@intentius/behold 0.7.0 → 0.9.0

package/AGENTS.md

@@ -17,7 +17,7 @@ apply creds.
 ## Getting a server
 
 ```sh
-npx @intentius/behold serve <chant-project-dir> --port 4600   # or: preview / demo
+npx @intentius/behold serve <chant-project-dir> --port 4600   # or: preview / demo / doctor
 ```
 
 `behold demo` needs no project at all — it copies the bundled example and serves
@@ -25,10 +25,27 @@ it against a local emulator (Docker). A directory that is not a chant project
 gets a structured `{code: "no-project"}` error from `/api/graph`, not a blank
 graph.
 
+A running server offers the same catalog over HTTP (#268): `GET /api/demos`
+lists every bundled demo with `{name, description, requires, satisfiable,
+reason?, fetches, repo?, target, loaded}` — `satisfiable` is doctor's PATH probe
+for that demo's `requires`, and `fetches` marks the one kind of entry that
+reaches the network (a git demo is cloned). `POST /api/demos/open` with
+`{name}` loads it and switches the served project to it: the same copy/clone →
+install → setup the CLI runs, then an in-place switch. It takes a catalog
+**name** and never a path, so it cannot be aimed outside the install; it is
+preview-locked, and one load runs at a time (409 otherwise).
+
 ## The read loop
 
 0. **discover** — GET `/api` lists every route with a one-line description,
-   plus the server's version and a link back to this guide.
+   plus the server's version and a link back to this guide. Before the server
+   exists (or when a route answers with an error you'd have to guess at), run
+   `npx @intentius/behold doctor <dir> --json`: a read-only diagnosis of the
+   project's kind, its own chant install and version, declared lexicons, the
+   envs the picker will infer, the bound kube context versus the ambient one,
+   substrate readiness and committed Ops. Each check is
+   `{name, status: pass|warn|fail, detail, fix}`; the process exits non-zero
+   iff something failed. It starts no server and changes nothing.
 1. **observe** — GET `/api/graph` (JSON: `{ ir, svg, meta }`). The mixed graph
    of the project, every node with `id`/`kind`/`lexicon`/`attrs`/`sourceLoc`. Drift
    status, when present, is `attrs._status` (`good`=managed, `warn`=foreign,
@@ -43,6 +60,49 @@ graph.
 3. **inspect** — a node's `sourceLoc.file` is the typed source that declared it;
    edit there to change the estate (chant is the source of truth, not behold).
 
+## The carve loop (Terraform → chant, #230)
+
+`behold carve <report.json>` serves a `chant carve advise --json` peelability
+report instead of a chant project. Same SPA, same `/api/graph` shape; `attrs.
+_status` carries the band (`good` = carve now, `warn` = has boundary work,
+`neutral` = leave in Terraform) and `attrs` carries the score arithmetic
+(`score`, `arithmetic`, `inbound`, `outbound`, `tier`, `mapsTo`).
+`GET /api/carve` returns the raw report verbatim.
+
+To move a resource: confirm its band on `/api/carve`, then run chant's own
+`carve emit --state` and `carve bridge` in the project. `terraform state rm` and
+applying the generated survivor rewrites stay a human gate — behold has no
+endpoint that writes Terraform, and adding one would break the invariant below.
+
+### The walkthrough (`behold demo carve`, #254)
+
+`behold demo carve` copies a bundled half-migrated estate (a chant project
+beside a Terraform one), runs the advisor over the copy, and serves the same
+carve view plus a six-step stepper on the panel's Carve tab: advise → pick →
+emit → bridge → handoff → done.
+
+Two of those steps are POST routes, and they exist **only** in a demo copy:
+
+- `POST /api/carve/emit` — body `{select}`; runs `chant carve emit --state
+  --select <addr> --output <copy>/app/carveout` and then `chant lint` on the
+  result. Answers `{select, command, output, artifacts[], boundary, lint,
+  buildCaveat}`.
+- `POST /api/carve/bridge` — body `{select}`; runs `chant carve bridge`
+  **without** `--apply-rewrites`. Answers `{select, command, output, runbook,
+  proposals[]}`.
+
+`GET /api/project`'s `carve.demo` says whether they can act (`runnable`, plus a
+`reason` when not). `select` must name a resource the served report ranks;
+anything else is a 400. Outside a demo copy both routes answer 403
+`{code: "read-only"}`, and on an ordinary project serve they don't exist at all.
+
+The gate the Emit step reports is `chant lint`, not `chant build` — chant#1637
+means `build` fails on the emitted bucket. Don't read a lint pass as a build
+pass.
+
+There is still **no** endpoint that runs `terraform`. The handoff step hands
+back the runbook's commands as text.
+
 ## The act loop (delegated, never direct)
 
 behold does not apply. To change the estate:
@@ -62,3 +122,35 @@ and saga rollback. There is no behold endpoint that mutates the cloud.
 If a request would have behold write to a cloud or to source directly, it's wrong.
 behold shows truth and triggers Ops. Authority stays in the committed source and the
 executor.
+
+### The exceptions, and their exact size
+
+`POST /api/layout` (#228) writes **one** file in the served project:
+`.behold/layout.json` — the hand-layout sidecar, `{version, lenses: {<lens>:
+{<node id>: {dx,dy,dw,dh}}}}`. That is the whole of behold's write surface
+inside a project, and it does not weaken the invariant above:
+
+- It is **workspace metadata**, not estate truth. Deltas describe how *you* want
+  the picture arranged on top of dagre's layout; the graph underneath stays
+  chant's, and a delta for a node that left the estate is dropped on read.
+- It **never touches the cloud and never touches your source**. No `.ts`, no
+  `chant.config.ts`, no `.behold.json`. The path is `cfg.projectDir` + two
+  constants — nothing from the request reaches the filesystem.
+- It refuses politely when it shouldn't write: preview mode, a static-export
+  capture, a read-only project directory, an oversized or malformed body.
+- It is **per-user state**, unlike `.behold.json` (config, meant to be tracked).
+  Projects should gitignore `.behold/`.
+
+`GET /api/layout` reads it back; `GET /api/graph?layout=1` (and `/api/overlay`)
+render with the deltas baked into the SVG, which is how `behold export` and
+static snapshots honour a hand layout.
+
+The second exception is the carve walkthrough's two steps above (#254), and it
+is narrower still: they exist only when behold booted a `behold demo carve`
+copy, they write only into `<copy>/app/carveout/`, and the directory they write
+into is a scratch dir behold created inside a directory it copied for you a
+minute earlier. `carve bridge` runs without `--apply-rewrites`, so the demo's
+own Terraform is not edited either. The only request-derived value is `select`,
+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.

package/README.md

@@ -30,17 +30,33 @@ npx @intentius/behold demo            # copies the example to ./behold-demo, ins
 The copied project is yours: edit its source and watch the graph change live.
 There's a whole catalog — `behold demo --list` names the rest (`behold demo
 k8s` stands the same loop up on a throwaway k3d cluster: runtime Pods, field
-ownership). Every loaded demo lands in the panel's recents, so switching
-between them is the Scope tab.
+ownership; `behold demo argo-estate` needs nothing at all — a three-project
+Argo CD estate, declared only, so it runs where Docker doesn't; `behold demo
+carve` is the Terraform peel walkthrough, below). Every loaded demo lands in
+the panel's recents, so switching between them is the Scope tab.
+
+The catalog is in the panel too (#268): the Scope tab's switcher lists every
+bundled demo under your recents, one click to copy, install and serve it —
+demos whose prerequisites are missing stay visible, disabled, saying what to
+install, and one that would clone from the network says so on the button.
 
 Already have a chant project?
 
 ```sh
 cd my-chant-project
+npx @intentius/behold doctor          # will this project serve well? (read-only)
 npx @intentius/behold preview         # → http://localhost:4600, this project's graph
 npx @intentius/behold serve . --env prod --poll 30   # live drift overlay
 ```
 
+`behold doctor` is the first thing to run on a project behold hasn't seen: one
+line each for the project's kind, its own chant install and version, declared
+lexicons, the envs the picker will infer, the kube context chant binds versus
+your ambient one, substrate readiness and committed Ops — pass/warn/fail with
+a one-line fix. It starts nothing and changes nothing; it exits non-zero only
+when something would actually stop behold serving the project well, so CI can
+gate on it. `--json` for scripts and agents.
+
 Driving it from an agent or script? `GET /api` lists every JSON route;
 [AGENTS.md](./AGENTS.md) (shipped in the package) is the read/act contract.
 
@@ -256,6 +272,59 @@ behold shells the **project's own** chant (resolved from the project's
 `@intentius/chant ^0.18.1` or later for the live overlay (`graph --live` observed
 nothing before that fix).
 
+## Terraform carve-out: `behold carve <report.json>`
+
+`chant carve advise` ranks a Terraform estate by **peelability** — how cleanly
+each resource could be carved into native chant source. `behold carve` draws
+that ranking: one card per resource, three panels (carve now / boundary work /
+leave in Terraform) on the same `attrs._status` drift palette every other view
+uses, and the score arithmetic behind each rank in the inspect pane.
+
+```sh
+chant carve advise --from ./terraform --report carve.json
+behold carve carve.json                      # → http://localhost:4600
+curl localhost:4600/api/carve                # the raw report, for agents
+```
+
+behold parses no HCL and needs no Terraform tooling: the report **is** the
+contract. A file that isn't a peelability report is refused with a structured
+`{error, code: "carve-report", remedy}` — in the terminal, and from the routes —
+never a blank graph. See `docs/using/carve` and issue #230 for the roadmap
+(the post-emit diff, then Terraform as an estate member).
+
+### The walkthrough: `behold demo carve`
+
+```sh
+npx @intentius/behold demo carve      # no Docker, no cloud, no terraform binary
+```
+
+Copies a half-migrated estate — a small chant project beside a Terraform one,
+both describing the same AWS account — installs the chant it will shell, runs
+`chant carve advise` over the copy, and opens the banded graph with a six-step
+stepper on the panel's **Carve** tab:
+
+1. **Advise** — the bands, with what each one means.
+2. **Pick** — click a green card. The inspect pane shows the score arithmetic;
+   the step names the boundary the cut crosses.
+3. **Emit** — runs `chant carve emit --state --select <addr>` into
+   `app/carveout/` in the copy, then shows the emitted chant source and the
+   `chant lint` result.
+4. **Bridge** — runs `chant carve bridge` (never `--apply-rewrites`) and renders
+   the proposed data source, the rewired survivors and the patch.
+5. **Handoff** — the runbook's commands with copy buttons, and **not** a button:
+   `terraform state rm` and `terraform apply` change who owns a live resource,
+   so they stay yours to run. The panel says so.
+6. **Done** — the card is marked chant-owned at the observe position;
+   `terraform import` reverses all of it.
+
+The Emit step reports `chant lint`, not `chant build`: chant#1637 means `build`
+fails on the emitted bucket even though the advisor scored it 88, and the panel
+links the reason. `example-carve/README.md` has the estate's full story, the
+band table, and the offline/`--live` split.
+
+behold writes only into the demo copy it made — `app/carveout/`, and nothing
+else. Your Terraform is never edited; see AGENTS.md, "Invariant".
+
 ## Configuration — `.behold.json`
 
 An optional `.behold.json` in the served project's root is **behold's own**
@@ -284,6 +353,34 @@ 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).
 
+### The hand-layout sidecar — `.behold/layout.json`
+
+dagre places your nodes; you can move them. Drag a card, resize a containment
+box, and the offsets are remembered per project + lens — in `localStorage`
+first, and (when the served project is writable) in a `.behold/layout.json`
+sidecar beside it, so a layout is shareable, reviewable in a diff, and honoured
+by `behold export`:
+
+```json
+{ "version": 1, "lenses": { "components": { "src/api#Component": { "dx": 40, "dy": -25 } } } }
+```
+
+This is the **only** file behold writes inside a served project. It stores
+deltas, never absolute positions — the graph stays chant's and your layout sits
+on top of it — and a delta whose node has left the estate is dropped silently.
+`POST /api/layout` refuses politely in preview mode, during a static-export
+capture, on a read-only directory, and above its size caps. `↺ layout` in the
+graph clears the current lens on both tiers.
+
+**Gitignore it.** `.behold.json` (above) is config and belongs in the repo;
+`.behold/` is per-user state — one person's arrangement of the picture — so add
+it to the served project's `.gitignore` unless you actually want to share and
+review a layout:
+
+```gitignore
+.behold/
+```
+
 ## Layout
 
 ```
@@ -309,6 +406,40 @@ and paints it with `layoutIr` + `renderSvg` (`src/render.ts`); the SPA inlines t
 SVG and wires click-inspect by `data-node-id` against the IR. pinhole's layout is
 dagre — pure JS, no native dependency.
 
+Where an official mark exists, a node paints it instead of a generic glyph — a
+Deployment gets the Kubernetes wheel-and-helm heptagon, a Kustomization the
+Flux mark, a `Helm::Release` the Helm wheel. The corpus is vendored under
+`web/icons/` (30 kubernetes/community SVGs, 3 cncf/artwork marks for
+Flux/Argo/Helm, licensing in `THIRD_PARTY.md`) and mapped kind by kind in
+`src/icon-packs.ts`; a kind with no official icon falls through to pinhole's
+keyword heuristic rather than a wrong picture.
+
+dagre's layout is a good first draft, not a final one: drag a card to move
+it, grab a containment box's corner to resize it, and both survive a reload.
+What persists is a delta — `{dx,dy}` for a card, `{dw,dh}` for a box, never
+an absolute position — keyed by `behold.layout.<project>.<lens>`
+(`web/layout-store.js`), so the graph stays chant's and the arrangement on
+top of it is yours. `↺ layout` sits beside `⤢ fit` and shows up only once
+something on the current lens is hand-placed.
+
+Every JSON value the UI shows goes through one renderer (`web/json-view.js`):
+2-space pretty printed, objects and arrays collapsible (the first tier open,
+anything deeper or wider than a dozen entries folded), long strings truncated
+with an expander, and a `copy` on every node that yields that subtree's raw
+JSON. Enter or Space toggles the focused node. It paints with `--fg` and
+`--muted` and nothing else, so all 552 palettes keep it readable. That covers
+the inspect pane's declared attributes, observed live state, drift pairs and
+field ownership, the op log's JSON lines, and the payload behind an `/api`
+error card.
+
+Type splits by purpose: mono (system stacks — ui-monospace, SF Mono,
+Cascadia, JetBrains, IBM Plex) carries node ids, ARNs, statuses and counts;
+sans carries labels only. Colour comes from 552 Ghostty terminal palettes run
+through an OKLCH-derived token pipeline (`src/theme.ts`), so a theme switch
+re-derives the whole chrome, not just the graph — and a node whose drift
+status just changed pulses once in the colour it became, off under
+`prefers-reduced-motion`.
+
 ## Local development
 
 `just` lists everything. The core loop:

package/demos.json

@@ -19,13 +19,37 @@
     },
     {
       "name": "flux-estate",
-      "description": "A GitOps estate: a Flux control plane (GitRepository + Kustomizations) plus two app projects, served as one composed estate — cross-stack sourceRef edges, estate-wide drift, and the namespace-mismatch note on purpose (app-b uses targetNamespace). k3d + Flux, no cloud. scripts/estate-down.sh removes the cluster.",
+      "description": "A GitOps estate: a Flux control plane (GitRepository + Kustomizations) plus two app projects, served as one composed estate — cross-stack sourceRef edges, estate-wide drift, and the namespace join that reads app-b where the control plane's targetNamespace puts it. k3d + Flux, no cloud. scripts/estate-down.sh removes the cluster.",
       "source": "bundled",
       "dir": "example-flux-estate",
       "requires": ["docker", "k3d", "kubectl"],
       "setup": "bash scripts/estate-up.sh",
       "serve": { "env": "local", "dirs": ["control-plane", "app-a", "app-b"] }
     },
+    {
+      "name": "argo-estate",
+      "description": "The Argo CD mirror of flux-estate, declared only: an AppProject plus one Application per app project, served with the two apps as one composed estate — project edges from each Application to the AppProject it names, and each Application's destination namespace drawn as a box holding that app's objects. No cluster, no Argo install, no Docker.",
+      "source": "bundled",
+      "dir": "example-argo-estate",
+      "requires": [],
+      "serve": { "dirs": ["control-plane", "app-a", "app-b"] }
+    },
+    {
+      "name": "carve",
+      "description": "The peel walkthrough: a half-migrated estate — a chant project beside a Terraform one — scored by `chant carve advise`, then a six-step stepper that carves one S3 bucket across the line on camera (advise, pick, emit, bridge, handoff, done). Emit and bridge really run, into the demo copy; the destructive terraform commands stay yours to paste. No cloud, no Docker, no terraform binary.",
+      "source": "bundled",
+      "dir": "example-carve",
+      "requires": [],
+      "serve": {
+        "carve": {
+          "report": "carve-report.json",
+          "from": "legacy-tf",
+          "state": "legacy-tf/terraform.tfstate",
+          "project": "app",
+          "out": "app/carveout"
+        }
+      }
+    },
     {
       "name": "fountain",
       "description": "The mature estate: self-hosted fountain (a real app) on a throwaway k3d cluster — tiers (try the ha tier picker), seams, drift, runtime Pods. Clones INTENTIUS/fountain-ops; ~5 minutes, mostly image pulls. `just down` in the clone removes the cluster.",