@intentius/behold 0.22.0 → 0.24.0

package/AGENTS.md

@@ -8,7 +8,8 @@ apply creds.
 ## The division of labour
 
 - **behold** serves the live, mixed-substrate graph (and, later, the deployment-lanes
-  timeline). It reads; it never mutates.
+  timeline). It reads; every write it offers is a command it starts (an Op, a
+  `chant run`, a forge dispatch), and on a terragucci repo it starts none.
 - **chant's MCP** is where the real capabilities live. Prefer it over shelling.
   - Reads: `lifecycle-diff`, `lifecycle-snapshot`, `build`, `lint`.
   - Actions (delegated writes): `op-run` (start an `ApplyOp`/`ReconcileOp`),
@@ -19,18 +20,73 @@ apply creds.
 A directory with a `chant.workspace.json` is a chant workspace (chant ≥ 0.81.0,
 INTENTIUS/chant#2524). `behold serve <root>` serves it from chant's own member
 list (`chant workspace ls --json`, read contract 1; any other contract is
-refused), and reads each `chant` and `terraform` member through `chant
-workspace graph --member <name>`. A `choudoufu` member keeps behold's own
-reader, whose vocabulary (rungs, ownership, adoptable rows) chant's graph does
-not carry. Node ids are `<member>/<id>` with the declared member name, the same
+refused), and reads each `chant`, `terraform` and `choudoufu` member through
+`chant workspace graph --member <name>`. A `choudoufu` member takes its block
+graph from it (the estate's own edges, each block's `file` and `line`) and
+joins it onto choudoufu's `live-check` roster, which still names the cards,
+the rungs and the cross-estate references: chant's graph is one node per
+block, ownership is per instance, and chant carries no rung or reference
+(src/choudoufu-workspace.ts, #465). The ids are the roster's, as before, so a
+saved layout keeps matching. behold's own lexicon read of a choudoufu
+directory stays for a loose view only. Node ids are `<member>/<id>` with the declared member name, the same
 form chant composes. A member chant cannot read is drawn as one
 `UnreadableMember` node carrying `attrs._unreadable: {code, message}` with
 chant's reason code. An `other` member is listed on startup and in doctor and
-draws nothing. `.behold.json`'s `members` are ignored beside a declaration;
+draws nothing. A declaration with `members: []` (terragucci writes one for its
+gates) declares nothing to draw, so serve, export and doctor read the
+directory as they would without one, and say so (#489). `.behold.json`'s `members` are ignored beside a declaration;
 `behold doctor --fix` writes the declaration for an estate that has only them.
 Several directories on the command line (`behold serve a b c`) stay the loose
 view behold composes itself.
 
+Every workspace read goes through one module, `src/workspace-reader.ts`: one
+chant call per read, the document handed back as chant printed it, any
+contract but 1 refused. chant's reader conformance suite
+(`@intentius/chant/workspace/conformance`) runs against that module in `npm
+test` (`src/workspace-reader-conformance.test.ts`, #468), so a new workspace
+read is added to the reader and to the suite's `commands`, never shelled from
+somewhere else.
+
+`GET /api/workspace/why?member=<name>` or `?node=<member>/<id>` (#471) answers
+why a member or a card is the way it is, from `chant workspace graph --intent
+<region> --json` (chant 0.102.0 or newer writes its `why`): the decisions
+covering it in chant's order, the agent runs and the commits behind it, and the
+gaps chant names. The region is the member's declared directory or the node id,
+never a path from the caller. It takes seconds on a small workspace and tens of
+seconds on a large one, so the inspect pane reads it only on a click, and it is
+a scheduled read: it holds a slot in the read budget, has the read deadline,
+and stops when the request does. `serve --hud <url>` (or `BEHOLD_HUD_URL`)
+links a proposed decision to its review in hud.
+
+## A terragucci estate, from its reports (#490)
+
+`behold serve <repo> --terragucci <dir|s3://bucket/prefix|https://…>`
+(`--terragucci-project <host/path>` when the bucket holds several projects
+and none is the checkout's git remote) adds two reads, in
+`src/terragucci-view.ts`:
+
+- `GET /api/terragucci`: `{source, project, validation, read, reports, files,
+  estate?, roots[], cards{}, waiting[], unmatched}`. `roots[]` is every
+  Terraform root of the checkout with the newest `plan`, `drift` and `apply`
+  run that held it; a missing stage means no report holds that root, which is
+  not "no changes". `cards` maps a card id to its marks (`verdict: drift |
+  plan | wave`, terragucci's words, the instance addresses, the run). Nothing
+  sets `_status`: a report is never painted as live. `waiting[]` carries each
+  wave's roots, destroys, and the `command` a person runs. `estate` is
+  terragucci's own counts when the source has `estate.json`. A key such as a
+  run's `report` opens at `files` + the key. Refusals are `422 {code:
+  "terragucci-report"}`. `?fresh=1` skips the 30 s cache.
+- `GET /api/terragucci/file?key=<key>`: one report file from the source,
+  sandboxed.
+
+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; 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`.
+
 ## Getting a server
 
 ```sh
@@ -565,6 +621,25 @@ If a request would have behold write to a cloud or to source directly, it's wron
 behold shows truth and triggers Ops. Authority stays in the committed source and the
 executor.
 
+The commands behold starts run with behold's own environment, so Deploy (`POST
+/api/apply`, chant's local executor) applies with the credentials of whoever
+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. 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
 
 `POST /api/layout` (#228) writes **one** file in the served project:
@@ -607,6 +682,22 @@ and it must be an address the served report already ranks, the value that
 reaches the spawn's argv comes from a closed set read off disk. No cloud write,
 no Terraform mutation, no edit to anyone's chant source.
 
+`behold export --publish s3://<bucket>/<prefix>/views/<name>` (#491) is the
+one write to a cloud, and it is not a server route: an export, asked for it on
+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. `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.
+
 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,

package/README.md

@@ -145,6 +145,26 @@ Set the Worker name with `--name`, or edit `wrangler.jsonc`. Auth via
 Workers deploy). GitHub Pages, S3, nginx and Cloudflare Pages
 (`wrangler pages deploy .`) all work too.
 
+A bundle is made to be opened by other people, so it carries the picture and
+nothing about the machine that made it: no list of your recent projects, no
+user name, and every absolute path reduced to its directory's name. Each card
+of a Terraform root carries that root's whole source file (`attrs.source`);
+`--no-source` leaves it out.
+
+`--terragucci <src>` (with `--terragucci-project`, as for `serve`) captures the
+terragucci marks too, for the view terragucci's estate job can publish beside
+`estate.html`. The bundle's report links are relative to
+`<prefix>/views/behold/` (`--reports-base` changes that), so uploaded there they
+open the bucket's own report pages through the same presigned link or front
+door. An export asked for marks it cannot read fails rather than publishing a
+picture without them.
+
+`--publish s3://<bucket>/<prefix>/views/<name>` uploads the bundle there too,
+each file with its content type, signed with the AWS credentials in the
+environment (no SDK, no aws CLI needed). It writes only under a `views/<name>`
+directory, terragucci's reserved viewer prefix, so a bundle's `index.html`
+never lands on a page behold did not make.
+
 ## Try it: your first apply, no cloud account
 
 The bundled `example-writes` is one S3 bucket. `serve --local` boots *that
@@ -202,21 +222,33 @@ including the exact commands and what each state looks like over the API:
 
 ## Read-only core, delegated gated writes (the invariant)
 
-**behold never mutates anything itself.**
+**behold writes nothing to a cloud or to your source itself.** Every write it
+offers is a command it starts for you, run by a tool you already trust.
 
 - The vizes only read (`chant graph`, snapshots, Temporal history).
-- Actions don't mutate directly. Sync starts your `ApplyOp`; Adopt starts your
-  `ReconcileOp` (opens a PR a human merges). behold *triggers* Ops you committed,
-  running on your executor. It holds no apply creds.
-- Two write gestures, both human-confirmed: **Apply** (gate signal) and **Open PR**
-  (merge). Authority stays in your source and your worker, never in behold.
+- Sync starts your committed `ApplyOp`; Adopt starts your `ReconcileOp` (opens a
+  PR a human merges). Those run on your executor.
+- Deploy on a project with no committed ApplyOp runs `chant run <component>
+  --components` on chant's local executor, as a child of behold. That child has
+  behold's environment, so it applies with the credentials of whoever started
+  behold: to Deploy from behold, that environment needs write roles. Reads
+  alone need only read roles.
+- An env `.behold.json` designates to a forge is never applied from the laptop;
+  Deploy dispatches the forge's workflow through your `gh` instead.
+- `behold export --publish s3://…/views/<name>` uploads the bundle it just made.
+  It is the one write behold makes to a cloud, and only when an export is
+  asked for it.
+- A terragucci repo (a `terragucci.yml` in the served directory or above it) is
+  applied by its pipeline only. behold refuses every write there (Deploy, Op
+  runs, gate approvals, pipeline dispatch, rollback) with `409 terragucci` and
+  offers none of them on the page.
 
 ## Why a Node service (not an edge function)
 
 The live path (`chant graph --live --overlay`, `chant lifecycle plan`) shells
 `kubectl`/`aws`/`az`/the Temporal client and holds cloud creds. That needs a real
-process, so behold is a Node service you run where your creds live. Read-only means it only needs **read**
-roles (describe/list), so it's least-privilege to run.
+process, so behold is a Node service you run where your creds live. Viewing needs only **read**
+roles (describe/list); a Deploy from behold applies with whatever credentials its environment holds.
 
 ## Agent-drivable, on chant's MCP
 
@@ -359,10 +391,42 @@ workspace block keys them, so the two show the same set. Standalone, a gate's
 button says who chant will record (the user running behold) before the click.
 Every approve route refuses in preview mode.
 
+In a declared workspace, the inspect pane of a member's box or a card has a
+"why" section. "Read why" asks `chant workspace graph --intent <member dir or
+node id> --json` (chant 0.102.0 or newer in the workspace root) and shows the
+decisions covering it, in chant's order, with the agent runs and commits behind
+it. Nothing is read until the click: on chant's own repository one member takes
+about 30 s, a small workspace about 1 s. While it reads the section says
+"reading…" with a Stop button, and picking something else stops the read.
+Start behold with `--hud <url>` (or `BEHOLD_HUD_URL`) and a proposed decision
+links to its review in hud; otherwise it is named by id. Framed, the section is
+drawn the same, and clicks on the graph still go to the host.
+
 A host that already watches the workspace tells behold it changed with
 `POST /api/refresh?notify=1`, instead of running behold with `--poll` beside
 it. behold drops its cached reads and every open page re-pulls.
 
+## A terragucci estate, from its reports: `--terragucci`
+
+```sh
+npx @intentius/behold serve . --terragucci s3://acme-terragucci-reports   # or a synced dir, or an https address
+```
+
+In a [terragucci](https://intentius.io/terragucci/) repo, behold draws every
+root from the checkout and marks each card with what terragucci's newest runs
+found: the newest `tf-drift` and `tf-plan` report per root (one GET of
+`index.json`, then one of each run's `report.json`), and the waves waiting for
+an approval. Every mark is dated by its run and links its report and job
+("drift found 06:04 UTC, 4h ago"); none is a fill, and nothing is read from a
+cloud. Counts and waiting waves come from `estate.json` when the source has
+one, so behold agrees with terragucci's estate page and links it. A waiting
+wave offers `npx terragucci approve wave-<k> --plan <digest>` to copy; there is
+no approve button, and every behold write refuses on a terragucci repo.
+Documents are checked against terragucci's JSON Schemas when
+`@intentius/terragucci` is installed, structurally otherwise. Full page:
+docs `using/terragucci`. `example-terragucci-reports/` is a bucket for
+terragucci's own example, written by terragucci's code.
+
 ## Terraform carve-out: `behold carve <report.json>`
 
 `chant carve advise` ranks a Terraform estate by **peelability**: how cleanly

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 @cdktn/hcl2json (the refusal names the exact line). 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": [],
@@ -89,7 +89,7 @@
     },
     {
       "name": "choudoufu-estate",
-      "description": "A tag-owned estate: four choudoufu estates (an OpenTofu fork whose ownership is two AWS tags) served composed — the terralith applied to a scratch floci, three team estates whose declared resources are the monolith's (every card `owned by` it, dashed to its card), a cross-estate data-source edge, and a move plan whose `live-mv` lines you run by hand while behold previews with -dry-run and reads the receipt. A card's colour is ownership, not \"nothing changed\": attribute drift is a separate plan read, opt-in through ⌘K → \"Re-check live with plan\". Docker + choudoufu (0.16.0+, or a build from main) on PATH; provider download on first init. scripts/choudoufu-down.sh removes the container.",
+      "description": "A tag-owned estate: four choudoufu estates (an OpenTofu fork whose ownership is two AWS tags) served composed — the terralith applied to a scratch floci, three team estates whose declared resources are the monolith's (every card `owned by` it, dashed to its card), a cross-estate data-source edge, and a move plan whose `live-mv` lines you run by hand while behold previews with -dry-run and reads the receipt. A card's colour is ownership, not \"nothing changed\": attribute drift is a separate plan read, opt-in through ⌘K → \"Re-check live with plan\". Docker + choudoufu (0.16.0+, or a build from main) on PATH, and chant's terraform lexicon beside behold (it supplies the choudoufu kind; the copy is linked to it); provider download on first init. scripts/choudoufu-down.sh removes the container.",
       "source": "bundled",
       "dir": "example-choudoufu-estate",
       "requires": [