Skip to content

feat: add machine-readable run interface for herdr-board - #70

Merged
aorumbayev merged 4 commits into
mainfrom
feat/board-run-interface
Sep 26, 2026
Merged

aorumbayev merged 4 commits into
mainfrom
feat/board-run-interface

Conversation

@aorumbayev

Copy link
Copy Markdown
Owner

Adds hwf runs list --json, hwf runs get <uuid> --json, and hwf run <name> --detach --json so herdr-board can start and observe runs without reading history.db or importing HWF packages.

What changed

  • One JSON object per response with schema_version: 1 and stable error codes: invalid_request, history_unavailable, run_not_found, incompatible_history, launch_rejected. Failures exit 1.
  • History reads open SQLite read-only. They never create, migrate, or repair the database. A missing history.db is an empty list. A wrong user_version is incompatible_history.
  • ListRuns pages with a keyset cursor on (started_at desc, id desc), default 40, max 200. Console and runs browser keep page one at 40.
  • Summary gains heartbeat_at and a current_step object. Detail embeds Summary and carries JSON tags.
  • Launch payload gains requireHistory. A detached child exits before step 1 when history is unavailable or the claim is rejected, and the parent reports launch_rejected. Picker launches are unchanged.
  • --input parse errors no longer echo the raw value.
  • Docs: new ## Runs section in docs/reference.md, README command rows.

Acceptance

Covers the twelve acceptance tests from the brief: claim before UUID, list and get show the same state, restart safety, paging past 40 without loss or duplication, cursor stability when a newer run arrives, distinguishable empty, unavailable, incompatible, and missing results, malformed row warning, concurrent reads during a run, no input leak in any output, attached run and picker unchanged, help and docs.

Compatibility

Console and runs browser no longer rebuild an old-schema database on open. The next writer does. Summary.CurrentLabel is gone (never serialized before).

go tool verify passes.

@aorumbayev
aorumbayev force-pushed the feat/board-run-interface branch from 8f19e17 to 42418a3 Compare September 25, 2026 18:47
aorumbayev and others added 4 commits September 26, 2026 22:52
Add `hwf runs list --json`, `hwf runs get <uuid> --json`, and
`hwf run <name> --detach --json`. Every response is one JSON object with
schema_version 1 and stable error codes.

History reads open SQLite read-only and never create or migrate the
database. ListRuns pages with a keyset cursor on (started_at desc, id desc),
default 40, max 200. Summary gains heartbeat_at and a current_step object.
Detail embeds Summary and carries JSON tags.

The launch payload gains requireHistory so a detached child exits before
step 1 when history is unavailable or the claim is rejected. The parent
reports launch_rejected. Picker launches are unchanged.

--input parse errors no longer echo the raw value.
Stat history.db before the ACL checks so a read on a fresh install no
longer creates the state directory. Drop the query_only pragma that
duplicated mode=ro.

Rename ListResult.SchemaVersion to IncompatibleSchema so it does not read
like the response schema_version. Rename Detail.CurrentStep to ActiveStep
so it stops shadowing the embedded Summary.CurrentStep that serializes as
current_step.
@aorumbayev
aorumbayev force-pushed the feat/board-run-interface branch from 42418a3 to 0986e41 Compare September 26, 2026 19:57
@aorumbayev
aorumbayev marked this pull request as ready for review September 26, 2026 20:02
@aorumbayev
aorumbayev merged commit a529e01 into main Sep 26, 2026
2 checks passed
@aorumbayev
aorumbayev deleted the feat/board-run-interface branch September 26, 2026 20:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant