@intentius/behold 0.24.0 → 0.25.0

package/AGENTS.md

@@ -78,6 +78,68 @@ and none is the checkout's git remote) adds two reads, in
   "terragucci-report"}`. `?fresh=1` skips the 30 s cache.
 - `GET /api/terragucci/file?key=<key>`: one report file from the source,
   sandboxed.
+- `GET /api/terragucci/timeline?root=<path>&limit=<n>` (#506): terragucci's
+  audit record (`audit.jsonl` at the top of the prefix, one GET) as `{source,
+  project, validation, read, record: {key, present}, absent?, files, root?,
+  total, limit, entries[]}`, newest first, 200 by default and 1000 at most.
+  An entry is `{id, kind, at, who, what, wave?, digest, result, roots[], run:
+  {commit?, job_url?, run_id?, pull_request?, report?}, evidence, detail?}`;
+  `run.report` opens at `files` + the key. An approval takes the roots and
+  report of its wave's other entries (same gate and digest). No
+  `audit.jsonl` is `present: false` plus an `absent` sentence, never an
+  empty history; a bad line is the `422 terragucci-report` refusal naming it.
+  `src/terragucci-timeline.ts` holds the read and the check (terragucci's
+  `dist/audit.schema.json` when it resolves, structural otherwise). The SPA
+  draws it in the Terragucci tab and, filtered to the card's root, in the
+  inspect pane (`web/terragucci-timeline.js`); an export carries it as one
+  snapshot and does not fail on it.
+- `GET /api/terragucci/lifecycle` (#505): the repo's `chant/lifecycle` lane,
+  `{branch, found, via, origin?, fetch: {ok, error?}, commit?: {sha,
+  committed}, read: {at}, gates[], locks[], note}`. `gates[]` is one entry per
+  `wave-<k>` in `_gates/tf-apply.jsonl` and `_gates/tf-apply/applied.jsonl`:
+  `state` (`waiting | expired | approved | applied | failed`), `digest`,
+  `pending`, `approval` (by, at, signed), `applied`, the kept reports under
+  `_gates/tf-apply/wave-<k>/`, and `command` when it waits. `locks[]` is
+  `_locks/tf-apply.json`, one per root (`pr, by, at, head, via?, stage?`).
+  Every gate and lock carries `source: {commit, committed, path}`, the newest
+  commit of the branch that changed its file. The branch is fetched from the
+  checkout's origin URL into `<tmpdir>/behold-lifecycle-<hash of the URL>`, a
+  bare repo behold owns (`assertScratch`), with the person's own git
+  credentials and no prompt; the checkout is never fetched into and no ref of
+  it moves. A failed fetch falls back to the checkout's own
+  `refs/remotes/origin/chant/lifecycle`, read-only (`via: "checkout-ref"`,
+  `fetch.error`); a remote without the branch is `found: false, via:
+  "fetch"`, not an error. 30 s cache, `?fresh=1` skips it. Reader:
+  `src/terragucci-lifecycle.ts`.
+- `GET /api/terragucci/events` (#505): SSE. While at least one page holds it
+  open, a timer (`--terragucci-poll <secs>`, default 30, 0 off) asks
+  whether `index.json` changed (`If-None-Match` with the last ETag for S3 and
+  http, mtime for a directory) and fetches `chant/lifecycle` again. Events:
+  `hello {pollSecs}`, `reports {at, tag}` (the page reads `/api/terragucci`
+  again), `lifecycle <the whole answer>` when the read differs from the last,
+  and `polled {at, reports, lifecycle}` after every tick. The last page
+  leaving stops the timer (`src/terragucci-poll.ts`). Neither route writes,
+  approves, locks or unlocks.
+- `GET /api/terragucci/progress` (#511): a choudoufu wave's progress per
+  resource from the run view of the newest commit `index.json` names a
+  `tf-apply` run of (one GET of `index.json`, one of
+  `<project dir>/runs/<commit>/run.json`, the directory taken from the index
+  row's own path). `{source, kind, project, validation, read, run: {commit,
+  key, present, updated?, html?} | null, absent?, files, watching, waves[],
+  cards{}, unmatched[]}`. A wave is `{number, state, gate, read, counts,
+  resources[]}`, a resource `{root, address, action, status: done | in-flight
+  | waiting | not-applied, done_at?, card?}`. `cards` is keyed by the same ids
+  as `/api/terragucci`'s marks (root path to `attrs.root`, instance to block),
+  one entry per wave with the wave's records `read` time and the card's
+  status (not applied, else in flight, else waiting, else done). It is a
+  dated corner tag, never a fill. No `run.json` is `run.present: false` plus
+  an `absent` sentence. `watching` is true while a wave is applying or a
+  resource is in flight or waiting; only then does the poll ask whether that
+  `run.json` changed (`If-None-Match`, mtime for a directory) and push a
+  `progress` event with the whole answer, and `polled` carries `progress:
+  {asked, key?, changed?, error?}`. Checked against `dist/run.schema.json`
+  when `@intentius/terragucci` resolves, structurally otherwise; reader
+  `src/terragucci-progress.ts`, page `web/terragucci-progress.js`.
 
 The reads are `src/terragucci-reports.ts` (index, each run's report, estate;
 terragucci's JSON Schemas when `@intentius/terragucci` resolves, a structural
@@ -87,6 +149,30 @@ schemas cached by its path and files' mtimes, #500) and the join is `src/terragu
 operator's `aws s3 cp <key> -`. There is no approve route, by design: hand the
 operator `waiting[].command`.
 
+A control repo (#509), one whose terragucci config has `projects:` and whose
+checkout declares no Terraform root (`controlRepo` in
+`src/terragucci-estate.ts`), gets one more read, and `/api/project` carries
+`terragucciControl: {config, projects}`:
+
+- `GET /api/terragucci/estate`: `{source, kind, config, validation: {estate,
+  run}, read, estate: {key, html, generated}, gets, projects[], edges[],
+  files}`. It reads `estate.json` and each project's newest run view,
+  `<project>/runs/<commit>/run.json`, one GET each (the commit is the
+  project's `run_view.commit`, else its `apply.commit`). A project is
+  `{project, status, index?, counts: {drifted, failed, waiting, dated},
+  waiting[], run? | missing? | refused?, checkout?, configured}`. Every
+  figure carries `dated: {key, at}`: estate.json's `generated`, or the run
+  view's `updated`. `waiting[].command` is the run view's approve line when it
+  holds that wave. `edges[]` is `{from, to, cross}`, `to` reading `from`'s
+  state; a cross edge matches a root's `external` read to another project's
+  root `state`, as terragucci's `estateGraph` does. A malformed run view is
+  `refused: {code: "terragucci-report"}` on its project only; a missing or
+  malformed `estate.json` is a 422. Not a control repo: 404 `code:
+  "terragucci-not-control"`. Run views are checked against
+  `@intentius/terragucci`'s `dist/run.schema.json` when it resolves, a
+  structural check otherwise. The page (`web/terragucci-estate.js`) draws it
+  in a layer over the graph area.
+
 ## Getting a server
 
 ```sh
@@ -698,6 +784,20 @@ uploading (no list call) and, after `index.html`, deletes the
 Nothing outside the prefix is deleted. A refused delete stops the sweep with
 a warning naming `s3:DeleteObject`, and the publish still succeeds.
 
+Since #510 the bundle goes to `<prefix>/<commit>/` (the checkout's HEAD, or
+`--commit`), with publishBundle's order and sweep one level down, and
+`src/publish-snapshots.ts` then writes, in order, `history.json` (newest
+first, `{commit, at, project, generated}`, one GET of the old one),
+`latest.json` (`{commit}`) and the root `index.html`, a no-cache page that
+opens `<latest>/index.html`, so old links keep working. `--keep <n>` (30)
+drops older commits from `history.json` and then deletes their files as each
+commit's `manifest.json` lists them (`files`, which runExport now writes,
+plus `keyToFile`), best effort with the same `s3:DeleteObject` warning. A
+view from before the layout keeps its files; only its `index.html` is
+replaced. With `--publish` the default `--reports-base` is `../../../`. The
+view's history picker (`web/history-picker.js`) reads `../history.json` and
+only navigates.
+
 A choudoufu estate member (#366) adds no exception. A move there is one tag
 write through choudoufu's own `live-mv`, and behold never makes it: `GET
 /api/choudoufu/moves` reads a plan (`carve.json`) from inside a served member,