@intentius/behold 0.23.0 → 0.25.0

package/AGENTS.md

@@ -78,14 +78,101 @@ 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
-check otherwise) and the join is `src/terragucci-overlay.ts` (root path to
+check otherwise; the package is looked up on every read and the compiled
+schemas cached by its path and files' mtimes, #500) and the join is `src/terragucci-overlay.ts` (root path to
 `attrs.root`, instance address to block path). An S3 source shells the
 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
@@ -626,9 +713,18 @@ started it. On a terragucci repo (a `terragucci.yml` in the served directory or
 above it, up to the git root) behold starts nothing: every POST that deploys,
 approves or starts a run answers `409` with `code: "terragucci"` and names the
 pipeline (`src/terragucci-repo.ts`, #489), `/api/project` carries `terragucci`
-so the page offers no write, and auto-sync declines. A new POST route goes in
-`TERRAGUCCI_REFUSED_WRITES` or in the test's list of routes that write nothing
-outside behold; `src/terragucci-repo.test.ts` fails until it is in one.
+so the page offers no write, and auto-sync declines. The boundary is an
+allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
+any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
+method and route, and that list holds only the exceptions below (the layout
+sidecar, project open and reveal, demo open, refresh, and the four carve
+steps). A new write route is refused on a terragucci repo until it is added
+there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
+app (`app.routes`, built plain, with a carve report and with `--terragucci`)
+and asserts each one is allowlisted or answers 409, and that every allowlist
+entry is a registered route. `TERRAGUCCI_REFUSED_WRITES` only words the
+refusal for known routes. The remedy names `npx terragucci approve wave-<k>
+--plan <digest>`, the digest from the wave's gate card.
 
 ### The exceptions, and their exact size
 
@@ -678,7 +774,29 @@ the command line, uploads the bundle it just wrote, signed with the AWS
 credentials in the environment (src/s3-object.ts). `publishTarget` refuses
 any destination that is not a `views/<name>` directory, terragucci's reserved
 viewer prefix, so the bundle's `index.html` can never land on a page behold did
-not make.
+not make. `publishBundle` (src/export.ts, #500) uploads every other file
+first, then `manifest.json`, then `index.html`. Snapshot names carry the first
+16 hex digits of their SHA-256 (`CONTENT_ADDRESSED`) and go up with
+`Cache-Control: public, max-age=31536000, immutable`; everything else gets
+`no-cache`. It GETs the previous `manifest.json` under the prefix before
+uploading (no list call) and, after `index.html`, deletes the
+`snapshots/<name>` files that manifest named and this export did not write.
+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

package/demos.json

@@ -65,7 +65,7 @@
     },
     {
       "name": "terraform-estate",
-      "description": "A multi-root Terraform estate, declared only: two roots applied separately (envs/prod and platform) plus the shared module both are built on — 37 cards boxed by root, module calls expanded into their own contents, and the two look-alike versions.tf files told apart. Shows what behold does NOT infer as clearly as what it draws: platform declares the KMS key and prod reads it back by alias, and no edge is drawn between them, because both ends carry the same unresolved interpolation (#381). Needs chant's terraform lexicon beside behold, which behold does not install: npm install --no-save @intentius/chant-lexicon-terraform@^0.102.0 @cdktn/hcl2json@^0.24.0 (without them the demo refuses with that line); the copy is linked to the lexicon behold resolved, since chant reads a workspace's pinned kinds from beside the workspace. No cloud, no Docker, no terraform binary.",
+      "description": "A multi-root Terraform estate, declared only: two roots applied separately (envs/prod and platform) plus the shared module both are built on — 37 cards boxed by root, module calls expanded into their own contents, and the two look-alike versions.tf files told apart. Shows what behold does NOT infer as clearly as what it draws: platform declares the KMS key and prod reads it back by alias, and no edge is drawn between them, because both ends carry the same unresolved interpolation (#381). Needs chant's terraform lexicon beside behold, which behold does not install: npm install --no-save @intentius/chant-lexicon-terraform@^0.121.0 @cdktn/hcl2json@^0.24.0 (without them the demo refuses with that line); the copy is linked to the lexicon behold resolved, since chant reads a workspace's pinned kinds from beside the workspace. No cloud, no Docker, no terraform binary.",
       "source": "bundled",
       "dir": "example-terraform-estate",
       "requires": [],