@intentius/behold 0.29.57 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/AGENTS.md +323 -26
  2. package/demos.json +1 -1
  3. package/dist/cli.js +5129 -2040
  4. package/example-choudoufu-estate/chant.workspace.json +1 -1
  5. package/example-terraform-estate/README.md +10 -10
  6. package/example-terraform-estate/chant.workspace.json +1 -1
  7. package/example-three-cloud/README.md +17 -9
  8. package/example-three-cloud/aws/chant.config.ts +1 -1
  9. package/example-three-cloud/aws/site.component.ts +13 -0
  10. package/example-three-cloud/azure/chant.config.ts +1 -1
  11. package/example-three-cloud/azure/src/site.component.ts +13 -0
  12. package/example-three-cloud/azure/src/site.ts +5 -7
  13. package/example-three-cloud/dns/chant.config.ts +1 -1
  14. package/example-three-cloud/dns/src/records.component.ts +14 -0
  15. package/example-three-cloud/dns/src/route53.ts +4 -5
  16. package/example-three-cloud/gcp/chant.config.ts +1 -1
  17. package/example-three-cloud/gcp/src/site.component.ts +13 -0
  18. package/example-three-cloud/gcp/src/site.ts +7 -7
  19. package/example-three-cloud/package-lock.json +19 -19
  20. package/example-three-cloud/package.json +4 -4
  21. package/example-three-cloud/scripts/front-door.ts +89 -15
  22. package/package.json +8 -9
  23. package/web/agent-move.js +60 -0
  24. package/web/agent-move.test.js +55 -0
  25. package/web/app.js +555 -76
  26. package/web/dots-lod.js +1 -1
  27. package/web/embed.d.ts +3 -0
  28. package/web/embed.js +5 -3
  29. package/web/embed.test.js +8 -0
  30. package/web/index.html +64 -9
  31. package/web/panel.js +28 -4
  32. package/web/release.js +6 -4
  33. package/web/release.test.js +2 -2
  34. package/web/search-view.d.ts +27 -0
  35. package/web/search-view.js +213 -0
  36. package/web/search-view.test.js +144 -0
  37. package/web/shot-frame.d.ts +5 -0
  38. package/web/shot-frame.js +116 -0
  39. package/web/shot-frame.test.js +90 -0
  40. package/web/themes.js +1 -1
  41. package/web/view-url.d.ts +18 -0
  42. package/web/view-url.js +153 -6
  43. package/web/view-url.test.js +72 -1
  44. package/example-three-cloud/azure/composites/container-app-site.ts +0 -77
  45. package/example-three-cloud/dns/composites/latency-entry.ts +0 -73
  46. package/example-three-cloud/gcp/composites/public-cloud-run.ts +0 -102
package/AGENTS.md CHANGED
@@ -526,7 +526,8 @@ preview-locked, and one load runs at a time (409 otherwise).
526
526
  `?env=`, `/api/overlay` is the live entity overlay; `/api/diff?env=` slices
527
527
  per-node observed state, drift and field ownership; `/api/reconcile?env=`
528
528
  summarizes the pending change set; `/api/substrates` reports substrate
529
- readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`run`/`pr`.
529
+ readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`run`/`pr`,
530
+ and `view` when an agent moves the tab (below).
530
531
  With `?components=1&env=`, each component node carries `_liveStatus` (the
531
532
  `chant components status` verdict) and, when the release ledger recorded
532
533
  one, `_release` — `{runId, forge, originSource, url?, gitSha, digest,
@@ -886,6 +887,248 @@ pass.
886
887
  There is still **no** endpoint that runs `terraform`. The handoff step hands
887
888
  back the runbook's commands as text.
888
889
 
890
+ ## A chant search query: `q` and `GET /api/search` (#913)
891
+
892
+ `q` is a view key holding a query in chant's search grammar. In a link
893
+ (`?q=...`), a `behold:view` message, `POST /api/view` and `behold shot`, it
894
+ draws the same way: the cards chant matched are lit, the cards and edges on
895
+ each match's path (chant's `paths[].hops`, and for a `cap:` term the hops
896
+ in `paths[].because[]` too, INTENTIUS/chant#4375) are drawn at full weight, and the
897
+ rest is dimmed, with nothing hidden. One line at the top left says the query,
898
+ the match count and chant's provenance line. A query with no matches dims
899
+ the whole graph, says "no matches" with the universe count, and outlines the
900
+ near-misses `--explain` names (hover one for the term it fails). A live read
901
+ that failed is said as a failure naming the lexicon, and its rows wear a
902
+ dashed ring. A query chant's grammar refuses lights and dims nothing and
903
+ shows chant's message and hint. A reload keeps `q`.
904
+
905
+ chant answers and behold draws. Every search goes through the workspace
906
+ reader (`src/workspace-reader.ts`, a fifth `BEHOLD_READS` entry held by
907
+ chant's reader conformance suite):
908
+
909
+ | Served | chant call |
910
+ |---|---|
911
+ | a declared workspace | `chant workspace search [flags] --json -- <q>` at the root (INTENTIUS/chant#4374). Ids are `<member>/<id>`, as `workspace graph` gives them. A member chant didn't search is named in a "not searched" line with chant's reason code, never shown as no matches |
912
+ | one chant project | `chant search [flags] --json -- <q>` in its directory |
913
+ | a bare Terraform folder | `chant workspace search` at a scratch workspace of one member (#925): `<tmpdir>/behold-tfws-<hash>`, whose `chant.workspace.json` declares one member of kind `chant`, named what the folder's box is named, at a link to the scratch project behold graphs the folder through. chant composes the `<member>/<id>` ids the cards carry; behold prefixes nothing. Nothing is written in the folder. The folder's box is named with a member name chant accepts (`^[a-z0-9][a-z0-9-]{0,39}$`, #927): a folder name that already is one is kept, any other is lowercased, with each run of other characters turned into `-`, and cut to 40 (`MyInfra` -> `myinfra`, `terraform_ec2` -> `terraform-ec2`), for the graph and the search alike. `code: "search-member-name"` is left only as a guard |
914
+ | a loose estate of several dirs | refused, `code: "search-estate"`: declare a workspace |
915
+
916
+ The mode follows the view: no `env` is the declared source, `env` is a live
917
+ read (`--live --env`), and `env` with `snapshot` replays a recorded snapshot
918
+ (`--snapshot <ref> --env`). `--explain` is always passed.
919
+
920
+ ```
921
+ GET /api/search?q=->kind:aws_kms_key&env=&snapshot=&show=
922
+ -> 200 {q, env, snapshot,
923
+ document: <chant's search document, unchanged>,
924
+ draw: {lit, onPath, edges, unobserved, nearMisses, provenance, failure, notSearched},
925
+ link}
926
+ ```
927
+
928
+ A query chant refuses answers 400 `code: "query"` with chant's hint as the
929
+ remedy (and the document). A chant below 0.124.46 answers 422
930
+ `code: "chant-too-old"` (`SEARCH_CONTRACT_CHANT_FLOOR` in
931
+ `src/chant-floors.ts`). A `--public` serve answers declared queries and
932
+ refuses `env` and `snapshot` (403).
933
+
934
+ `behold export --q "<query>"` (repeatable) captures each query's answer for
935
+ the source graph and every environment, so the bundle draws it with no
936
+ backend. The manifest lists `queries`; a link's `q` that wasn't captured is
937
+ named, with the captured ones, and lights nothing.
938
+
939
+ ### Groups and the plan: `countBy` and `plan` (#922)
940
+
941
+ Two more view keys, carried the same way as `q` (a link, `behold:view`,
942
+ `POST /api/view`, `behold shot --view`, the MCP tools, an export):
943
+
944
+ - `countBy=kind|module|attr:<name>` is chant's `--count-by`. The document is
945
+ chant's counts branch, verbatim: `countBy`, `groups[{group, count, ids}]`
946
+ and `total` (INTENTIUS/chant#4360; `ids` is INTENTIUS/chant#4382). The page
947
+ lights each group's cards from `ids`, outlines them in the group's colour,
948
+ labels the group's first drawn card `<group> · <count>`, and the top-left
949
+ line lists the groups and the total. `draw.counts` is `{by, total, groups}`.
950
+ With `countBy`, `q` may be empty: the whole graph is counted. A chant that
951
+ lists no ids per group lights nothing and the line says so. behold never
952
+ works out a node's group itself.
953
+ - `plan=1` is the plan read. The source graph's cards carry each stock
954
+ Terraform root's plan facts (`/api/graph?plan=1`, #910) on every load, and
955
+ `q` is answered at the plan depth: `CHANT_TERRAFORM_OBSERVE=plan` in the
956
+ environment of that one chant call, with `--live --env <env>`
957
+ (INTENTIUS/chant#4358). A bare Terraform folder needs no env (the plan
958
+ read's placeholder `behold-plan` is used); a chant project or workspace
959
+ needs one (422 `code: "plan-env"`). `plan` with `snapshot` is refused,
960
+ naming both: a 400 on the route, both keys in `refused` on a link or
961
+ `POST /api/view`. A `--public` serve refuses it (403). It runs
962
+ `terraform plan -lock=false` in each root: nothing is changed, but every
963
+ resource is read.
964
+
965
+ ```
966
+ GET /api/search?q=kind:aws_&countBy=module
967
+ GET /api/search?q=attr:planAction=replace&plan=1&show=planActions,planReplacePaths,planActionReason
968
+ ```
969
+
970
+ `behold export --count-by <g>` captures each `--q` grouped too (with no
971
+ `--q`, the whole graph's groups); `behold export --plan` captures the plan
972
+ cards on the source graph and each `--q` at the plan depth.
973
+
974
+ A `cap:` term (INTENTIUS/chant#4375) asks a capability, such as
975
+ `cap:internet-reachable(22)`. Its route is in the path's `because`, one
976
+ entry per capability the match relied on, each with the hops that proved it,
977
+ and `draw.edges` and `draw.onPath` include them (#926). A hop that ends on a
978
+ node inside a resource, `<id>#<attr>[n]` (a security group's ingress rule),
979
+ is drawn on the resource's card.
980
+
981
+ ### The capability catalog: `GET /api/capabilities` (#926)
982
+
983
+ Read it before asking a `cap:` question. It answers chant's capabilities
984
+ document byte for byte (capabilities.schema.json, contract 1), read through
985
+ the workspace reader from the same target a search asks:
986
+ `chant workspace search --capabilities --json` at a declared workspace's
987
+ root, `chant search --capabilities --json` in one project or a Terraform
988
+ folder's scratch project. Each capability has its `name`, `meaning`,
989
+ `params`, the `search` term that asks it, the questions it `answers`, what
990
+ it leaves `notEvaluated`, its `rule`, and per lexicon whether it is
991
+ supplied. A chant below 0.124.46 answers 422 `code: "chant-too-old"`
992
+ (`CAPABILITIES_CHANT_FLOOR`). behold mcp's `capabilities` tool returns the
993
+ same text.
994
+
995
+ ```
996
+ GET /api/capabilities
997
+ -> 200 {"$schema":".../capabilities/v1/capabilities.schema.json","contract":1,"chant":"0.124.46",
998
+ "capabilities":[{"name":"internet-facing","meaning":...,"search":"cap:internet-facing",...}],
999
+ "helpers":[...]}
1000
+ ```
1001
+
1002
+ ## Moving the person's open tab (#914)
1003
+
1004
+ `POST /api/view` changes what every open tab of this serve draws. It is a
1005
+ view change and writes nothing: no infrastructure, no project file, not
1006
+ `.behold/layout.json`, and nothing kept on the server.
1007
+
1008
+ ```
1009
+ POST /api/view
1010
+ {"view": {"q": "attr:internetFacing=true", "env": "prod", "snapshot": "latest", "zoom": "resources"},
1011
+ "by": "claude-code via behold mcp"}
1012
+ ```
1013
+
1014
+ `view` takes the URL's view keys (`member`, `zoom`, `env`, `tier`, `lens`,
1015
+ `node`, `radial`, `alike`, `gates`, `focus`, `run`, `pull`, and #922's
1016
+ `plan` (a boolean) and `countBy`) plus `q`, a
1017
+ question in chant's search grammar, and `snapshot`, a recorded lifecycle
1018
+ snapshot (`latest` or a ref) that needs an `env`. They are settled with the
1019
+ same checks a link's query gets (`web/view-url.js`: `viewFromObject`,
1020
+ `settleView`, `checkQuery`); an env the project doesn't declare, a `q` with a
1021
+ control character or over 2000 characters, or a key that isn't a view key is
1022
+ named in `refused` and the rest still moves. `at` is refused by name: in
1023
+ chant's read contract it is a git revision, so a snapshot is `snapshot`.
1024
+ behold does not parse `q`. The tab draws it through `GET /api/search`
1025
+ (below): the matches lit, the rest dimmed.
1026
+
1027
+ The answer is `200 {id, movedAt, sent, link, view, refused}`, where `sent` is
1028
+ the number of open tabs it reached and `link` opens the same view. With no
1029
+ tab open it is `409 {code: "no-tab", link}`: hand the person the link. A
1030
+ view with nothing that can be applied is `400 {code: "view", refused}`.
1031
+
1032
+ Each tab gets a `view` event `{id, movedAt, by, view}` on `/api/events`,
1033
+ moves, and shows "Moved by an agent: `<by>` asked `<q>` at <time> (request
1034
+ <id>)" with a Back button. An agent's move pushes a browser history entry, so
1035
+ the banner's Back and the browser's Back both return to the view from before
1036
+ it; up to 20 moves in a row stack this way. The person's own changes keep
1037
+ replacing the entry they are on. An embedded frame with a host (`embed=1&host=`)
1038
+ ignores the event, because its host owns its view (#476).
1039
+
1040
+ `by` is a label of at most 80 printable characters. Without one it is the
1041
+ request's User-Agent product token. Anyone who can reach the serve can send
1042
+ any name, so `by` says who the caller claims to be and is not authentication.
1043
+
1044
+ Refused: under `serve --public` (405 from the request guard, and 403 `code:
1045
+ "public"` in the route itself), and under every `behold preview`, with or
1046
+ without `--emulator` (403 `code: "preview"`). A terragucci or SQL Yodeler
1047
+ repo allows it, since it writes nothing. A static export has no server, so no
1048
+ route.
1049
+
1050
+ ## A picture of a view (#915)
1051
+
1052
+ `behold shot "<query>" [project-dir] -o out.png` and `GET /api/shot` take a
1053
+ PNG of a view and give the link to the same view. Both call `src/shot.ts`.
1054
+ The page is behold's own, loaded in a headless browser with
1055
+ `embed=1&bare=1&frame=matches`: it lights what the view asks for, dims the
1056
+ rest, frames the lit cards with the kiosk's arithmetic (`web/kiosk-shot.js`),
1057
+ draws one caption line (what was asked, from where, when), and sets
1058
+ `data-behold-shot` on `<html>` to `drawn`, `no-matches` or `failed`. Nothing
1059
+ is photographed until it does: a page that never reports ready within 60 s,
1060
+ or one that draws no cards, is refused and no file is written.
1061
+
1062
+ ```
1063
+ GET /api/shot?node=aws_vpc.main&env=prod&width=1600&height=1000
1064
+ -> 200 image/png, Behold-View-Link: http://127.0.0.1:4600/?env=prod&node=aws_vpc.main,
1065
+ Behold-Shot-State: drawn | no-matches | failed
1066
+ ```
1067
+
1068
+ The browser comes from `playwright-core`, an optional peer behold does not
1069
+ install: the system Chrome first, then Playwright's `chromium-headless-shell`.
1070
+ Without either the CLI exits 1 with the install line and the route answers
1071
+ 501 `code: "no-browser"`. `--env`/`env=` draws the env's live view, and
1072
+ `--snapshot <ref>`/`snapshot=` a recorded snapshot of it (`at` is a git
1073
+ revision and is not taken). The route answers bytes, never a path, and is
1074
+ refused on `serve --public` (403), since each shot starts a browser. The CLI
1075
+ uses the serve at `--url`, or starts behold's app for the project on a free
1076
+ loopback port and stops it after; without `-o` the PNG goes under the OS temp
1077
+ directory. Nothing is written in the served project.
1078
+
1079
+ A query's matches are lit and framed (#913). Without a query, a shot frames
1080
+ the view's own `node` or `focus` (`behold shot "" --view node=<id>`).
1081
+
1082
+ Publishing is opt-in per call (#923, `src/shot-publish.ts`): `--publish
1083
+ <remote>[/<branch>]` (branch default `behold-shots`) commits the PNG to that
1084
+ branch of the remote, in the repo `--publish-repo <dir>` names (default: the
1085
+ current directory's), tracked with Git LFS (`*.png` in the branch's
1086
+ `.gitattributes`), pushes it, and prints the raw URL (at the commit, for
1087
+ GitHub and GitLab) after the view link. It is git plumbing on a private index:
1088
+ no checkout's tree, index or HEAD changes, and the branch checked out in the
1089
+ repo or the project, or its upstream, is refused. Without git-lfs, or when the
1090
+ remote does not take the LFS object, it refuses with the setup line and exits
1091
+ 1 before the branch moves; the local PNG is kept. `behold mcp`, `GET
1092
+ /api/shot` and a `--public` serve never publish.
1093
+
1094
+ ## Over MCP: `behold mcp` (#916)
1095
+
1096
+ `behold mcp [project-dir] [--url <serve> | --port <n>]` is a stdio MCP server
1097
+ with four tools, all clients of a running serve's HTTP API. An agent reads
1098
+ `capabilities` first (#926): it calls `GET /api/capabilities` and returns
1099
+ chant's capability catalog, the read contract's `capabilities` document
1100
+ (`chant search --capabilities --json`, INTENTIUS/chant#4375), byte for byte.
1101
+ It names each capability a `cap:` term asks, what it means, its parameters,
1102
+ the search term, the questions it answers, what it does not evaluate, its
1103
+ rule and which lexicons supply it, and it takes no arguments. `ask` calls
1104
+ `GET /api/search` and returns chant's search document verbatim, with `link`
1105
+ and `drawn: false` added after its own fields (a test holds it byte for byte
1106
+ to what chant prints); it takes `query`, `env`, `snapshot` and `show`, and
1107
+ never moves the tab. `show` calls
1108
+ `POST /api/view` (its `by` is the MCP client's name plus "via behold mcp"),
1109
+ and `shot` calls `GET /api/shot` and returns the PNG as MCP `image` content
1110
+ followed by a text block `{link, state, serve}`. They take `query`, `env`,
1111
+ `snapshot`, `member`, `zoom`, `focus` and `node`; `shot` also takes `width`
1112
+ and `height`. The answers are chant's: behold passes chant's documents
1113
+ through and computes none of its own.
1114
+
1115
+ It finds the serve through `--url`/`--port`, then the per-user registry at
1116
+ `<os.tmpdir()>/behold/serves/<pid>.json` (`{url, pid, projectDir, version,
1117
+ startedAt}`, written by every serve at start, rewritten on a project switch,
1118
+ removed at exit, a dead pid ignored; `BEHOLD_SERVES_DIR` moves it), then
1119
+ `http://127.0.0.1:4600`. It confirms the serve through `GET /api/project`.
1120
+ `show` refuses a serve of another project, naming both, and refuses with the
1121
+ serve command when none runs. `capabilities`, `ask` and `shot` with no serve of the project
1122
+ start behold in their own process for the call (`src/shot-cli.ts`), and the
1123
+ answer comes from the same route.
1124
+
1125
+ Arguments are checked against each tool's schema (`additionalProperties:
1126
+ false`), a credential-named one is refused by name, and a refusal is an
1127
+ `isError` result carrying the route's `{error, code, remedy}`. The server
1128
+ refuses to start with a tool whose name holds a write word (deploy, apply,
1129
+ approve, run, op, rollback, write and kin), and a call to an unlisted tool is
1130
+ refused with the same words.
1131
+
889
1132
  ## The act loop (delegated, never direct)
890
1133
 
891
1134
  behold does not apply. To change the estate:
@@ -1344,7 +1587,8 @@ allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
1344
1587
  any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
1345
1588
  method and route, and that list holds only the exceptions below (the layout
1346
1589
  sidecar, project open and reveal, demo open, refresh, and the four carve
1347
- steps). A new write route is refused on a terragucci repo until it is added
1590
+ steps), plus `POST /api/view`, which moves the open tabs and writes nothing
1591
+ (#914). A new write route is refused on a terragucci repo until it is added
1348
1592
  there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
1349
1593
  app (`app.routes`, built plain, with a carve report and with `--terragucci`)
1350
1594
  and asserts each one is allowlisted or answers 409, and that every allowlist
@@ -1652,7 +1896,7 @@ its own graph and overlay counts as it runs.
1652
1896
  | `terralith-1` | `terralith-gen` at scale 1 plus the `estate.chdf.hcl` sidecar it omits, applied by choudoufu from nothing: 79 cards, all 79 bound | docker, choudoufu, go |
1653
1897
  | `terralith-4` | the same at scale 4: 301 cards, all 301 bound. The estate behold is sized against | the same |
1654
1898
  | `terralith-4-adopt` | scale 4 again, but STOCK terraform applies it first, so nothing wears a marker: 301 cards — 85 UNOWNED, 84 bound by derived identity alone, 132 neutral. One `choudoufu live-import` line, which the up script prints and you run, and all 301 read bound | docker, choudoufu, go, terraform |
1655
- | `waterpark` | `../waterpark/access` in place as a bare Terraform directory (#384): five roots as boxes, 58 cards, 49 edges, nothing written under the estate | `@intentius/chant-lexicon-terraform` + `@cdktn/hcl2json` beside behold — optional peers behold declares and does not install |
1899
+ | `waterpark` | `../waterpark/access` in place as a bare Terraform directory (#384): five roots as boxes, 58 cards, 49 edges, nothing written under the estate | `@intentius/chant-lexicon-terraform` + `@cdktn/hcl2json` beside behold, dependencies of behold since #909 |
1656
1900
 
1657
1901
  **The scratch, by name and port.** Each emulator is the entry's own, booted by
1658
1902
  its up script and removed by the `scripts/down.sh` that script wrote into the
@@ -1716,8 +1960,9 @@ A Terraform estate reaches behold through chant.
1716
1960
  `@intentius/chant-lexicon-terraform` reads the HCL an estate already has and
1717
1961
  emits one entity per block, so **a Terraform estate is a chant project whose
1718
1962
  only lexicon is a reader** and `chant graph --format ir` serves it like any
1719
- other. behold parses no HCL and ships no HCL parser, the same posture
1720
- `src/carve-lens.ts` states for the carve report (#378).
1963
+ other. behold parses no HCL itself, the same posture `src/carve-lens.ts`
1964
+ states for the carve report (#378). The parser chant uses is installed with
1965
+ behold since #909, below.
1721
1966
 
1722
1967
  Three passes turn what arrives into a picture (`src/terraform-lens.ts`), in this
1723
1968
  order, guarded on the IR carrying terraform entities so every other estate gets
@@ -1780,17 +2025,24 @@ points chant at it. The Invariant's one in-project write stays
1780
2025
  across a read. Three decisions, each a trade #384 left open and each measured on
1781
2026
  water park's `access/` before it was taken:
1782
2027
 
1783
- 1. **The lexicon is opt-in.** chant resolves the lexicon from the config file's
1784
- own location, so the generated project has to see it, and making it a
1785
- dependency would put `@cdktn/hcl2json`, a ~1.8 MB wasm blob, in the install
1786
- of every user who serves a chant project. `@intentius/chant-lexicon-terraform`
1787
- and `@cdktn/hcl2json` are therefore **optional peers**: declared in
1788
- package.json (the only place their versions are named, the refusal reads
1789
- them from there), never installed by behold, probed at serve and doctor time,
1790
- and refused with the one install line and where behold looked. The same gate
1791
- `behold demo` puts on a binary it does not ship. The lexicon's own chant peer
1792
- is what moved behold's `@intentius/chant` floor to `^0.61.0`: chant 0.54
1793
- loads no published version of it (`applyLineage is not a function`).
2028
+ 1. **The reader ships with behold, and is still probed.** chant resolves the
2029
+ lexicon from the config file's own location, so the generated project has to
2030
+ see it, and chant core (not the lexicon) imports `@cdktn/hcl2json` from its
2031
+ own real path; neither package declares the parser. #384 made both optional
2032
+ peers to keep a ~1.8 MB wasm blob out of chant-only installs. #909 reversed
2033
+ that so `npx @intentius/behold serve .` on a folder of `.tf` files is one
2034
+ command: `@intentius/chant-lexicon-terraform` and `@cdktn/hcl2json` are
2035
+ **dependencies** in package.json (the only place their versions are named;
2036
+ the refusal reads them from there). The maintainer accepted the cost on #909:
2037
+ +8.3 MB on a 195 MB install, six packages. The lexicon's range starts at
2038
+ behold's chant floor so its chant peer dedupes against behold's chant, and
2039
+ npm hoists both beside chant, which is where the scratch project's
2040
+ `node_modules` symlink and chant's parser import look. They are still probed
2041
+ at serve and doctor time and refused with the one install line and where
2042
+ behold looked, because an install that pruned them reaches a chant that
2043
+ warns, exits 0 and prints an empty graph. The lexicon's own chant peer is
2044
+ what moved behold's `@intentius/chant` floor to `^0.61.0`: chant 0.54 loads
2045
+ no published version of it (`applyLineage is not a function`).
1794
2046
  2. **Roots are discovered, and the skips are reported.** A root is a directory
1795
2047
  with a `.tf` declaring a line-start `terraform {` or `provider "` block
1796
2048
  beside a `resource`, `data` or `module` block, a regex probe at the depth
@@ -1843,21 +2095,36 @@ tag, path or mutability was changed out of band still carries its markers, so
1843
2095
  it is still bound, and it is still green.
1844
2096
 
1845
2097
  The other half of the terminal's answer ("would a plan change anything?") is
1846
- a **separate, opt-in read**: `choudoufu plan -input=false -out=<tmp>` then
1847
- `choudoufu show -json <tmp>`, whose `resource_changes[].change.{actions,before,
1848
- after}` name the attributes and both their values. (`choudoufu plan -json` is
1849
- NOT this: on 0.16.0 it prints choudoufu's own ownership document, the same
1850
- shape as `live-plan -json`, with no attribute values in it at all. The
1851
- measurement is in src/choudoufu-plan.ts's header.) The plan file is written to
1852
- a scratch directory of behold's own and removed after rather than inside the served
1853
- member, which would be a write into someone's source.
2098
+ a **separate, opt-in read**, and since #924 it goes through chant together with
2099
+ the ownership it is about (src/choudoufu-chant-read.ts): one `chant graph
2100
+ --live` over the member's `chdf` reader project at the plan depth
2101
+ (`CHANT_TERRAFORM_OBSERVE=plan`, INTENTIUS/chant#4371). chant runs `choudoufu
2102
+ live-plan -json` for ownership, then `choudoufu plan -input=false -lock=false
2103
+ -out=<its tmp>` and `show -json` for the attributes, and puts `planChanges`
2104
+ (live value `before`, declared value `after`) on each bound block. With
2105
+ `CHANT_TERRAFORM_LIVE_PLAN_DIR` set to a directory behold made under the OS
2106
+ temp directory (INTENTIUS/chant#4383), chant also hands back the `live-plan`
2107
+ document its verdicts came from, and behold paints ownership from that, so a
2108
+ re-check runs ONE `live-plan` per member and the plan sits on the same
2109
+ verdicts as the card. Nothing is written in the served member (chant writes
2110
+ its plan file and the handed document outside it, INTENTIUS/chant#4379).
2111
+ (`choudoufu plan -json` is not this read: on 0.16.0 it prints choudoufu's own
2112
+ ownership document with no attribute values in it at all, measured in #404.)
2113
+ On a live root drift IS the planned `update`: choudoufu rebuilds prior state
2114
+ from the account, so chant's `planDrift` is empty there and is not read. A
2115
+ path chant finds flagged sensitive on either side is `(sensitive)` on both,
2116
+ and so is every copy of a flagged string (`tags_all`): a choudoufu plan flags
2117
+ a sensitive variable's value on `after` only, with the old secret unflagged in
2118
+ `before`. Floor: `CHOUDOUFU_PLAN_CHANT_FLOOR` (0.124.46); below it, or with no
2119
+ terraform lexicon, a re-check paints from behold's own `live-plan` and reads
2120
+ no plan.
1854
2121
 
1855
2122
  It is opt-in because it costs differently: the ownership read is answered out
1856
2123
  of the tagging index and is flat in the estate's size, while `plan` refreshes
1857
2124
  every resource, one provider read per card, 301 of them on `terralith-4`. So:
1858
2125
 
1859
2126
  - **Never on an ordinary overlay read.** `GET /api/overlay?plan=1` and
1860
- `GET /api/diff?plan=1` are the only things that spawn one, and the palette's
2127
+ `GET /api/diff?plan=1` are the only things that read one, and the palette's
1861
2128
  **"Re-check live with plan (attribute drift)"** row is the only thing in the
1862
2129
  SPA that sends the flag. The cheap **"Re-check live (refresh drift)"** row is
1863
2130
  deliberately left alone — it is `POST /api/refresh`, a primary-only re-observe
@@ -1865,7 +2132,7 @@ every resource, one provider read per card, 301 of them on `terralith-4`. So:
1865
2132
  - **Cached under the member's source stamp**, the same key half `memberIr`
1866
2133
  uses. A read that did NOT ask is served that stored answer, so a reload after
1867
2134
  a refresh keeps showing the drift without paying for a second pass; a read
1868
- that DID ask always re-plans, because "re-check" means re-check.
2135
+ that DID ask always re-reads both halves, because "re-check" means re-check.
1869
2136
  - **The ownership verdict stays the card's colour.** A bound card that drifted
1870
2137
  is still painted bound and still counted `bound`; it gains `attrs._planDrift`
1871
2138
  and wears a dashed `--degraded` edge plus a `~ n attributes` corner glyph
@@ -1877,6 +2144,36 @@ every resource, one provider read per card, 301 of them on `terralith-4`. So:
1877
2144
  drifted: n}`. The two are different answers — "nobody looked" versus "looked,
1878
2145
  nothing drifted", and the legend prints a count only for the second.
1879
2146
 
2147
+ ### A stock Terraform root's plan comes from chant (#910)
2148
+
2149
+ `GET /api/graph?plan=1` (palette: **"Read the plan on the Terraform roots"**)
2150
+ reads each stock Terraform member's roots at chant's plan depth
2151
+ (INTENTIUS/chant#4358): behold's own chant over the member's scratch project,
2152
+ `CHANT_TERRAFORM_OBSERVE=plan chant graph . --live --overlay --env behold-plan
2153
+ --format ir --detail 3` (src/terraform-plan.ts). The plan runs with
2154
+ `-lock=false`, its file under the OS temp directory. Each resource or data card
2155
+ gains `attrs._plan` (`source`, `action`, `reason`, `replacePaths`,
2156
+ `forcedFrom`, `afterUnknown`, `changes`, `drift`), and the card's rows lead with
2157
+ `plan`, `forced by`, `from` and `read`. `GET /api/terraform/plan` answers the
2158
+ same facts per card as JSON.
2159
+
2160
+ - **Which read answered is per root**, parsed from chant's notes: `plan`,
2161
+ `state` (the plan failed, for missing credentials or a provider error) or
2162
+ `none` (declared only). A card in a root that fell back says `plan: not read`
2163
+ and which read answered. Never "no changes" unless the plan said `no-op`.
2164
+ - **Sensitive values arrive redacted** by chant, at any depth and every copy;
2165
+ behold copies plan facts only, never a block's other attributes.
2166
+ - **Floor**: `TERRAFORM_PLAN_CHANT_FLOOR` (0.124.46) for behold's chant and the
2167
+ lexicon; below it the read is refused with the upgrade line.
2168
+ - **A planned create has a card**: it reads absent at the plan depth, so it
2169
+ stays pending with no physical id, and chant carries its plan attributes
2170
+ onto the declared node anyway (chant#4372). Its rows read `plan: create`,
2171
+ `unknown: N until apply`, `read: plan`.
2172
+ - **choudoufu members read ownership and the plan through chant together**
2173
+ (src/choudoufu-chant-read.ts, #924): src/choudoufu-plan.ts is gone, and a
2174
+ re-check's `live-plan` is chant's, handed back to behold. See the choudoufu
2175
+ section above.
2176
+
1880
2177
  ### A lexicon behold draws but cannot aim (#430)
1881
2178
 
1882
2179
  `behold doctor`'s **targets** line. `SUBSTRATE_TARGET_VARS` (src/targets.ts)
package/demos.json CHANGED
@@ -65,7 +65,7 @@
65
65
  },
66
66
  {
67
67
  "name": "terraform-estate",
68
- "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.124.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.",
68
+ "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). Reads through chant's terraform lexicon (@intentius/chant-lexicon-terraform) and @cdktn/hcl2json, both installed with behold since #909 (an install that pruned them refuses with the line that puts them back); 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.",
69
69
  "source": "bundled",
70
70
  "dir": "example-terraform-estate",
71
71
  "requires": [],