@intentius/behold 0.15.0 → 0.17.0

package/AGENTS.md

@@ -171,6 +171,49 @@ and nothing else about the run is behold's to decide: a stream that dies leaves
 the playhead at the last settled step and says so, and a gate paints as pending
 only when chant's `gateState` query named it.
 
+### The executor contract (#165, #61)
+
+`.behold.json` may designate which forge deploys an environment:
+
+```json
+{ "executor": { "prod": { "forge": "github", "workflow": "deploy-prod.yml" } } }
+```
+
+It designates the committed WORKFLOW, not just the forge: two environments'
+generated pipelines carry identical job ids, so a picker cannot tell them
+apart, and a contract that names prod must not sit on a guess. For a
+designated env, `POST /api/apply` and a committed ApplyOp's `/api/ops/:name/run`
+answer `409 {code: "executor-forge"}`, auto-sync declines out loud, and the
+only deploy is `POST /api/ci/dispatch?env=<env>`, which runs the designated
+workflow through the operator's own `gh` and follows it on the dial. Any
+approval the workflow's environment requires is granted on the forge by a
+GitHub identity behold does not have; the dial links the run's page and offers
+nothing else. Fail-closed: a designation behold cannot honour (a typo'd forge,
+a missing or non-dispatchable workflow, a forge with no trigger here) disables
+Deploy for that env with the reason on `/api/project`'s `executor` block, and
+never falls back to running it here. `/api/project` reports `{forge, workflow,
+ok, reason?}` per designated env.
+
+Without a designation, dispatch picks the committed workflow named for the env
+(`chant-components-<env>`, chant ≥ 0.54.0); on the older job-overlap match it
+refuses a tie rather than letting directory order choose, and a workflow named
+for another env never stands in. `just e2e-ci-github` proves the contract
+against the real forge (example-ci + `.github/workflows/behold-e2e-dispatch.yml`),
+including the `lost` verdict, which `BEHOLD_CI_FOLLOW_TIMEOUT_MS` and
+`BEHOLD_CI_POLL_FAIL_BUDGET` let a run force on purpose; a lost run is the one
+`POST /api/ci/readopt` re-follows.
+
+A dispatched run is followed honestly (#165 §6, PR #350): only GitHub's own
+`completed` + conclusion paints `ok`/`failed`; a poll-failure budget or the
+follow deadline promotes the run to `lost` (chips frozen at last-observed,
+the run possibly still live at its own page), never to a verdict. The adopted
+run id is persisted as one JSON per project under `~/.behold/ci-runs/` — the
+operator's machine-state, outside the project tree, so the Invariant below
+still names the whole in-project write surface. `GET /api/ci/run` reads the
+record; `POST /api/ci/readopt` (also attempted once at boot) re-follows an
+unconcluded run by its saved id, so a restart mid-deploy leaves the run a
+reader instead of nothing.
+
 ## The operating loop (a strip, a timeline, and a gate that is not the run gate)
 
 A project that declares a `ConvergeOp` gets an operator strip on the ops lens:
@@ -277,11 +320,13 @@ live here, with the enforceable ones enforced.
   it merges. A check that has merely settled is not a pass — read the lines.
   No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
   next onto what landed.
-- **The local gate** is `just check` (tsc, tests, build). `just test` keeps
-  the reporter's full output in `vitest.log`, because #334's one-shot
-  first-run failures kept losing the failing file's name — if the suite fails
-  once and passes on rerun, the log from the first run is the evidence; attach
-  it to #334.
+- **The local gate** is `just check` (tsc, tests, build). Every vitest run
+  also writes `.vitest-last.json` (the json reporter, PR #351), and `just
+  test` keeps the reporter's full output in `vitest.log` — both gitignored —
+  because #334's one-shot first-run failures kept losing the failing file's
+  name. If the suite fails once and passes on rerun, those two files from the
+  first run are the evidence; attach them to #334 (`jq '.testResults[] |
+  select(.status != "passed") | .name' .vitest-last.json` names the file).
 - **Releasing** is `just release`, after the version-bump PR merged: it tags
   `behold-v<version>`, pushes the tag (which is what runs `release.yml`), and
   waits for npm to show the version. It refuses in every state where a tag

package/README.md

@@ -8,8 +8,8 @@ drift — then act through delegated, gated Ops.
 gets you to a running graph without reading anything else first.
 
 Where Argo CD shows one cluster's tree, behold shows the mixed-substrate estate:
-cloud drift on AWS, supply-chain drift on GitHub Actions, artifact presence on Helm —
-each substrate's own kind of truth, in one picture.
+cloud drift on AWS, supply-chain drift on GitHub Actions, artifact presence and
+render provenance on Helm — each substrate's own kind of truth, in one picture.
 
 ```
 chant source ──build/lint──▶ graph IR ──behold──▶ live graph + drift + (delegated) actions
@@ -354,6 +354,38 @@ render and the graph loads with no tier selected — the default for any project
 that doesn't opt in. There's no other tier config surface (not
 `chant.config.ts`, not an env var behold guesses the name of).
 
+### Deploy executors — `executor`
+
+The same file can designate which forge deploys an environment (#165):
+
+```json
+{
+  "executor": {
+    "prod": { "forge": "github", "workflow": "deploy-prod.yml" }
+  }
+}
+```
+
+It names the committed **workflow**, not just the forge, because two
+environments' generated pipelines carry identical job ids and a picker cannot
+tell them apart. For a designated environment the Deploy button dispatches that
+workflow through your own `gh` login and follows the run on the dial; a local
+apply, a committed ApplyOp for that environment, and auto-sync are all refused
+(`409 executor-forge`), and rollback is withheld. Any approval the workflow's
+GitHub environment requires is granted on GitHub, by your identity there — the
+dial links the run's page and offers nothing else, because behold holds no
+identity that could clear a forge gate. A designation behold cannot honour (a
+typo'd forge, a missing workflow, one without `workflow_dispatch`) disables
+Deploy for that environment with the reason, and never falls back to running
+it on your machine. The workflow is read from the `.github/workflows` of the
+repository the project belongs to, so a project that is one directory of a
+monorepo works as-is.
+
+A dispatched run's id is kept under `~/.behold/ci-runs/` — the operator's own
+state, outside the project — so a behold restarted mid-deploy re-adopts the run
+and keeps following it. A follow whose stream dies is reported as `lost`, never
+as a verdict; `just e2e-ci-github` proves the whole contract against GitHub.
+
 ### The hand-layout sidecar — `.behold/layout.json`
 
 dagre places your nodes; you can move them. Drag a card, resize a containment