feat: behold demo carve — the recordable carve walkthrough, offline tier (#254)

[lex00]

Part 2 of #254 (M1.5 of #230): one command from npm to the peel walkthrough. Builds on #258's carve lens, #262's estate, #264's JSON view, #257's sidecar write boundary and #268's demo catalog.

npx @intentius/behold demo carve     # no Docker, no cloud, no terraform binary

What ships

behold demo carve — a demos.json entry (requires: []) that copies example-carve through #268's shared loader, npm-installs the chant every step will shell (app/), installs @cdktf/hcl2json into the copy's root node_modules (chant lazy-loads the HCL parser with a bare import resolved from its own install upward, so that is where it resolves — not beside the .tf files), and runs chant carve advise --report over the copy. A boot that fails any of that serves the committed carve-report.json and puts the reason on the statusbar, the terminal and the Carve tab. A blank graph is the one outcome that never happens.

The stepper — a Carve tab mounted at runtime (panel.js's new addPanelTab), so no other project grows a dead tab. Six steps on the deploy dial's own track, gated by real data dependencies rather than by wizard etiquette:

step	what it does
Advise	band legend with the report's own counts, and where the runs will write
Pick	a graph click is the pick; inspect shows the arithmetic, the step names the cut
Emit	POST /api/carve/emit → carve emit --state --select <addr> + chant lint; renders the emitted source, chant's boundary report (via json-view) and the lint verdict
Bridge	POST /api/carve/bridge → carve bridge, never --apply-rewrites; renders the data source, the rewired survivors and the patch
Handoff	the runbook's commands with copy buttons, and a paragraph on why it is not a button
Done	a ✓ carved → chant marker on the card + the end card

A finished run deliberately does not advance: the result is the step, and skipping past it would hide the thing the run was for. A new pick drops the previous runs — showing one resource's emitted source under another's name is the one way this panel could actively lie.

Honesty in the Pick step, both ways. With a chant#1636 report (the one committed on main now has the lists) it names the survivor the cut would strand and what bridging it costs. With a counts-only report — which is still what a real behold demo carve regenerates, since example-carve/app pins chant 0.44.4 — it reports the counts, names the cut from the breakdown, and says plainly that the survivors are not in this report. "None" and "not reported" stay different claims, and both paths are covered by tests.

chant lint, not chant build (chant#1637) — carve emit folds the bucket's versioning/public-access-block sub-resources into the carve set without carrying them as native props, so build fails two AWS policy rules on source the advisor scored 88. The Emit panel carries a "why lint and not build?" note; README, example-carve/README.md and the docs page say it too.

The write boundary (src/carve-actions.ts)

behold's second write, narrower than the first:

• The two routes exist only in carve mode and act only when this server booted a demo copy. A plain behold carve report.json shows the same six steps with the runs greyed out and a reason; an ordinary project serve doesn't register them at all (404).
• One directory is written: <copy>/app/carveout. It sits inside the chant project on purpose — the emitted source imports @intentius/chant-lexicon-aws and Node resolves that from the file's own directory upward, so a sibling carveout/ would fail chant lint on an install problem rather than on the source.
• The only value off the wire is select, and it must be an address the served report already ranks. The element that reaches the spawn's argv comes from a closed set read off disk, which is a stronger claim than any regex.
• carve bridge never gets --apply-rewrites. Verified by diffing the copy's legacy-tf/ after a full run: identical.
• Same conservative shape as feat: the layout sidecar — a hand layout that leaves the browser (#228) #257: JSON body only, caps, structured {error, code, remedy} refusals. AGENTS.md now states both exceptions and their exact size.

Meeting #268

The walkthrough is runnable anywhere but is not a project to switch into — carve mode claims /api/graph and /api/project at app creation, so a running server cannot become one. The catalog row stays visible, marked switchable: false, with the command that works on its face; POST /api/demos/open refuses it before the copy and install rather than after.

Tests

• src/carve-actions.test.ts — the actions against a fake project-local chant installed into a temp demo copy: the argv built, the --output directory created before chant's --report needs it (real chant writes the report first, verified against 0.44.4), the artifact read-back, path shortening, and a bin that exits non-zero if it ever sees --apply-rewrites. Plus the route guards: 404 off carve mode, 403 outside a demo, 400 on an unranked select, 415/413 on the body.
• web/carve-steps.test.js — the stepper's pure half: the gates, completed vs "walked past", cutSummary's two claims (including the fallback to the IR node's own counts), runbookCommands (drops annotations, keeps trailing comments, dedupes the runbook's two terraform plans), and lintVerdict counting warnings off chant's summary line rather than a column number.
• smoke/ui-smoke.mjs — a second stub in carve mode serving the real committed report through the real lens, with the two POSTs canned, so the six steps are deterministic in CI with no chant and no npm install. 30 new checks drive the whole walk headlessly.
• src/demos-route.test.ts / web/demos.test.js — the unswitchable catalog row and its early refusal.
• just check green (979 tests), npm run smoke:ui green.

Also driven end to end in a browser against a real behold demo carve — real chant 0.44.4, real emit, real lint, real bridge — which is how the auto-advance, the marker's position (measured, not read off attributes chant doesn't stamp) and a /api/resources 500 on every carve-mode boot were all found.

Deferred

• The Floci --live tier (carve walkthrough: behold demo carve — the recordable peel-advise → carve experience (#230 M1.5) #254's second comment): scratch Floci in Docker, terraform apply the estate into it, lifecycle diff --live after Emit, a real terraform plan showing no destroy on camera. A follow-up.
• The morph. The carved card is marked in place; it does not yet slide out of the Terraform boundary into the chant project beside last month's carves. The Done step names this rather than implying it is done.
• Edge highlights in the graph — the lens draws boundary edges when the report carries them, and the committed fixture now does; a regenerated one won't until example-carve/app's pinned chant is bumped past chant#1636. The stepper reads both.
• Estate framing. feat: behold carve <report.json> — the Terraform peelability report as a graph (#252) #258's carve mode is single-view: carveRoutes claims /api/graph and /api/project wholesale, and there is no seam for composing the report view with a chant member's graph. So this ships the honest minimum — the carve view with the walkthrough's demo context on it — and leaves serving the report inside an estate frame to the follow-up that adds the seam.

#254 stays open for the live tier and the morph.

🤖 Generated with Claude Code