@intentius/behold 0.32.0 → 0.33.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.
- package/AGENTS.md +64 -3133
- package/README.md +17 -6
- package/dist/chant-KLLNQOCK.js +117 -0
- package/dist/choudoufu-chant-read-MJ6DK23L.js +36 -0
- package/dist/chunk-26K6QLVB.js +157 -0
- package/dist/chunk-4IETG5U7.js +267 -0
- package/dist/chunk-7DQDWJI5.js +46 -0
- package/dist/chunk-ANJ33KX4.js +78 -0
- package/dist/chunk-C7OMVDI5.js +124 -0
- package/dist/chunk-GG3SLEYM.js +30297 -0
- package/dist/chunk-GMCRBXPQ.js +15578 -0
- package/dist/chunk-IMX6PXXA.js +1019 -0
- package/dist/chunk-JHLNY324.js +232 -0
- package/dist/chunk-JJPU2DXX.js +54 -0
- package/dist/chunk-KUHU6T4P.js +2820 -0
- package/dist/chunk-OY4EF7ZO.js +5651 -0
- package/dist/chunk-XKWCGNT2.js +8139 -0
- package/dist/chunk-YO233FHU.js +136 -0
- package/dist/cli.js +859 -77499
- package/dist/config-XKQQ4ORG.js +69 -0
- package/dist/config-run-4IMSAYPX.js +418 -0
- package/dist/declaration-5NE7H5UD.js +6867 -0
- package/dist/index.js +99 -0
- package/dist/main-4PGA5RJS.js +2509 -0
- package/dist/mcp-W2CHVEPI.js +753 -0
- package/dist/object-store-H77QSRIZ.js +1033 -0
- package/dist/src-54PT4UC5.js +1189 -0
- package/dist/tree-W23HE2EZ.js +17 -0
- package/example-choudoufu-estate/chant.workspace.json +1 -1
- package/example-terraform-estate/README.md +2 -2
- package/example-terraform-estate/chant.workspace.json +1 -1
- package/example-three-cloud/chant.workspace.json +2 -2
- package/example-three-cloud/package-lock.json +32 -515
- package/example-three-cloud/package.json +5 -5
- package/package.json +18 -16
package/AGENTS.md
CHANGED
|
@@ -1,3155 +1,86 @@
|
|
|
1
|
-
#
|
|
1
|
+
# behold for agents
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
gated** writes. As an agent you drive it the same way a human does, and the
|
|
5
|
-
mutating capabilities are chant's MCP Op tools, not behold's, so nothing here holds
|
|
6
|
-
apply creds.
|
|
3
|
+
Working in the INTENTIUS workspace, `../agents/shared.md` applies too.
|
|
7
4
|
|
|
8
|
-
|
|
5
|
+
behold is a read-only control plane over a chant estate. It draws the live,
|
|
6
|
+
mixed-substrate graph and starts delegated, gated commands; it never holds
|
|
7
|
+
apply credentials. This file ships in the npm package and `GET /api` links to
|
|
8
|
+
it, so the first half is for agents driving a running behold and the second
|
|
9
|
+
for agents changing this repo. Route and feature detail lives in
|
|
10
|
+
docs/src/content/docs/using/ (agents.mdx first) and in `GET /api`, not here.
|
|
9
11
|
|
|
10
|
-
|
|
11
|
-
timeline). It reads; every write it offers is a command it starts (an Op, a
|
|
12
|
-
`chant run`, a forge dispatch), and on a terragucci or SQL Yodeler repo it
|
|
13
|
-
starts none.
|
|
14
|
-
- **chant's MCP** is where the real capabilities live. Prefer it over shelling.
|
|
15
|
-
- Reads: `lifecycle-diff`, `lifecycle-snapshot`, `build`, `lint`.
|
|
16
|
-
- Actions (delegated writes): `op-run` (start an `ApplyOp`/`ReconcileOp`),
|
|
17
|
-
`op-signal` (approve a gate), `op-status` / `op-report` (watch it).
|
|
12
|
+
## Driving a running behold
|
|
18
13
|
|
|
19
|
-
|
|
14
|
+
- Before a server exists, or when a route errors: `npx @intentius/behold doctor <dir> --json`. Read-only, exits non-zero if a check failed, each check carries a `fix`.
|
|
15
|
+
- Start one with `npx @intentius/behold serve <dir> --port 4600`. `GET /api` lists the routes with a one-line description each.
|
|
16
|
+
- Read with `GET /api/graph` (`{ir, svg, meta}`) and `GET /api/overlay?env=<env>`, the live entity overlay. Each node's `sourceLoc.file` is the source that declared it. A failed precondition answers `{code, error, remedy}`; branch on `code`.
|
|
17
|
+
- To change the estate, edit that chant source or run a committed Op through chant's MCP (`op-run`, `op-signal`, `op-status`). behold's own mutating routes only start Ops the project committed; none writes a cloud or Terraform directly, and none should be added.
|
|
20
18
|
|
|
21
|
-
|
|
22
|
-
INTENTIUS/chant#2524). `behold serve <root>` serves it from chant's own member
|
|
23
|
-
list (`chant workspace ls --json`, read contract 1; any other contract is
|
|
24
|
-
refused), and reads each `chant`, `terraform`, `choudoufu` and `pulumi` member through
|
|
25
|
-
`chant workspace graph --member <name>`. A `choudoufu` member takes its block
|
|
26
|
-
graph from it (the estate's own edges, each block's `file` and `line`) and
|
|
27
|
-
joins it onto choudoufu's `live-check` roster, which still names the cards,
|
|
28
|
-
the rungs and the cross-estate references: chant's graph is one node per
|
|
29
|
-
block, ownership is per instance, and chant carries no rung or reference
|
|
30
|
-
(src/choudoufu-workspace.ts, #465). The ids are the roster's, as before, so a
|
|
31
|
-
saved layout keeps matching. behold's own lexicon read of a choudoufu
|
|
32
|
-
directory stays for a loose view only. A `pulumi` member (#994) is read through
|
|
33
|
-
the same `workspace graph --member` and nothing else: chant reads the `pulumi
|
|
34
|
-
stack export` checked in beside its Pulumi.yaml as stack-export.json, so its
|
|
35
|
-
cards are the export's resources, edged by `parent` and `dependencies`. behold
|
|
36
|
-
has no reader of its own for the kind, keys on the kind string and not on the
|
|
37
|
-
lexicon that supplies it, and sends it no live read: chant has none, so the
|
|
38
|
-
overlay draws it neutral with `_unobserved` saying so (`pulumiWorkspaceVia`,
|
|
39
|
-
src/workspace.ts; the fixture is e2e/fixtures/pulumi-workspace, the e2e
|
|
40
|
-
`just e2e-pulumi-workspace` and src/pulumi-member.test.ts). Node ids are `<member>/<id>` with the declared member name, the same
|
|
41
|
-
form chant composes. A member chant cannot read is drawn as one
|
|
42
|
-
`UnreadableMember` node carrying `attrs._unreadable: {code, message}` with
|
|
43
|
-
chant's reason code. An `other` member is listed on startup and in doctor and
|
|
44
|
-
draws nothing. A declaration with `members: []` (terragucci writes one for its
|
|
45
|
-
gates) declares nothing to draw, so serve, export and doctor read the
|
|
46
|
-
directory as they would without one, and say so (#489). `.behold.json`'s `members` are ignored beside a declaration;
|
|
47
|
-
`behold doctor --fix` writes the declaration for an estate that has only them.
|
|
48
|
-
A `kustomize`, `argo-app`, `flux-kustomization`, `helm-chart` or `cloudformation`
|
|
49
|
-
member is read the same way (#1056), and the detail tier of a read is passed on
|
|
50
|
-
as `--detail` (chant 0.124.35, `WORKSPACE_DETAIL_CHANT_FLOOR`). The kinds come
|
|
51
|
-
from the k8s, helm and aws lexicons the workspace pins (chant 0.124.49,
|
|
52
|
-
`WORKSPACE_KINDS_CHANT_FLOOR`). At chant's default detail a k8s node carries only
|
|
53
|
-
`apiVersion` and `kind`; the Argo and Flux path edges of src/estate-edges.ts need
|
|
54
|
-
`spec`, which comes at detail 3. A lens, `up`, `down` and a namespace stay on the
|
|
55
|
-
member's own `chant graph`. A kustomize member needs `kustomize` or `kubectl` on
|
|
56
|
-
PATH and a helm-chart member needs `helm`. The fixture is
|
|
57
|
-
e2e/fixtures/k8s-workspace and the test src/k8s-member.test.ts.
|
|
58
|
-
Several directories on the command line (`behold serve a b c`) stay the loose
|
|
59
|
-
view behold composes itself.
|
|
19
|
+
## Changing behold
|
|
60
20
|
|
|
61
|
-
|
|
62
|
-
chant call per read, the document handed back as chant printed it, any
|
|
63
|
-
contract but 1 refused. chant's reader conformance suite
|
|
64
|
-
(`@intentius/chant/workspace/conformance`) runs against that module in `npm
|
|
65
|
-
test` (`src/workspace-reader-conformance.test.ts`, #468), so a new workspace
|
|
66
|
-
read is added to the reader and to the suite's `commands`, never shelled from
|
|
67
|
-
somewhere else.
|
|
21
|
+
### The write boundary
|
|
68
22
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
a scheduled read: it holds a slot in the read budget, has the read deadline,
|
|
77
|
-
and stops when the request does. `serve --hud <url>` (or `BEHOLD_HUD_URL`)
|
|
78
|
-
links a proposed decision to its review in hud.
|
|
23
|
+
behold writes nothing in a served project. Its own state (hand layout,
|
|
24
|
+
per-user settings, CI run ids, the serve registry) goes in the user's cache,
|
|
25
|
+
home or temp directory, keyed by project. The only exceptions are
|
|
26
|
+
`behold doctor --fix` writing `chant.workspace.json`, the carve demo steps
|
|
27
|
+
writing inside the demo copy behold made, and `behold export --publish`.
|
|
28
|
+
There is deliberately no `/api/carve/apply` and no `/api/choudoufu/mv`;
|
|
29
|
+
route tests assert they stay absent.
|
|
79
30
|
|
|
80
|
-
|
|
31
|
+
On a terragucci repo (`terragucci.yml`) or SQL Yodeler repo
|
|
32
|
+
(`yodel.config.ts`), every non-GET route answers 409 unless it is listed in
|
|
33
|
+
`TERRAGUCCI_ALLOWED_WRITES` (src/terragucci-repo.ts). A new write route is
|
|
34
|
+
refused there until you add it; src/terragucci-repo.test.ts walks every route.
|
|
81
35
|
|
|
82
|
-
|
|
83
|
-
of a directory that has no `chant.workspace.json`: the kinds' probes claim
|
|
84
|
-
directories, a directory a local `module` source calls or that sits inside
|
|
85
|
-
another member is not a member of its own, and two kinds claiming one directory
|
|
86
|
-
at the same precedence is a tie that is not read. The document is a contract 1
|
|
87
|
-
graph with one more field, `discovered[]`, one entry per claimed directory
|
|
88
|
-
(`dir`, `member`, `kind`, `source`, `probe`, `outcome`, `claims`, `note`).
|
|
89
|
-
Member names are the lowercased path with runs of characters a name cannot
|
|
90
|
-
hold turned to `-`, and `.` is `root`, so node ids and `member=` links in a
|
|
91
|
-
discovered folder carry those names, not the folder's name.
|
|
36
|
+
### Reading chant
|
|
92
37
|
|
|
93
|
-
src/
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
discovered folder exactly as it composes a declared workspace, including an
|
|
98
|
-
unreadable member drawn as a box with chant's reason. The note names each tied
|
|
99
|
-
directory and counts the directories left out as modules or inside a member.
|
|
100
|
-
A list of one path is read as that folder, which is how the server hands it
|
|
101
|
-
over; `behold serve`, `behold shot` and the server treat a folder this applies
|
|
102
|
-
to as an estate (`discoverAppliesToList`). The overlay, search and the other
|
|
103
|
-
per-member reads still go to the folder as they did.
|
|
104
|
-
|
|
105
|
-
The floor is `WORKSPACE_DISCOVER_CHANT_FLOOR`, 0.124.98 (src/chant-floors.ts):
|
|
106
|
-
chant#5095 is on chant's main after the 0.124.97 freeze. Below it, or when the
|
|
107
|
-
chant's version is unknown, nothing here runs and a folder is read as before.
|
|
108
|
-
`CHANT_RELEASE` (src/chant-release.ts) is not moved by this: that is a
|
|
109
|
-
maintainer step once 0.124.98 is on npm.
|
|
110
|
-
|
|
111
|
-
Which folders go through it is a measured choice, not "all of them". On the
|
|
112
|
-
`infra/` tree of a Kubernetes project checkout (52 Terraform roots, 2
|
|
113
|
-
CloudFormation templates, 1 manifests directory), behold's own Terraform reader
|
|
114
|
-
takes 3.5 s cold and 72 ms on a reread, because one chant reads one generated
|
|
115
|
-
project naming every root. `--discover` runs a reader per member: 44 s cold,
|
|
116
|
-
6.8 s on chant's member cache, 55 members. So the default (`auto`) discovers a
|
|
117
|
-
folder behold cannot draw (no member kind claims it: Kubernetes, Helm) or draws
|
|
118
|
-
only half of (a Terraform or choudoufu folder that also holds Kubernetes or
|
|
119
|
-
Helm files), and leaves a Terraform or choudoufu folder with none on its own
|
|
120
|
-
reader. A chant project is never discovered. `BEHOLD_DISCOVER=always|never|auto`
|
|
121
|
-
overrides it. Because the Terraform scratch project (`behold-tf-*`) stays the
|
|
122
|
-
reader for those folders, and the plan read, choudoufu, behaviour and search
|
|
123
|
-
(`behold-tfws-*`) write it too, `writeTerraformScratchProject` and its tests
|
|
124
|
-
stay.
|
|
125
|
-
|
|
126
|
-
## Chant version floors (behold#691)
|
|
127
|
-
|
|
128
|
-
behold shells each project's own chant, so a read can reach a chant that
|
|
129
|
-
predates it. Every read has one floor, and every floor lives in
|
|
130
|
-
`src/chant-floors.ts`:
|
|
131
|
-
|
|
132
|
-
- one constant per read, named after the read (`WHY_CHANT_FLOOR`) and set to the
|
|
133
|
-
chant release that adds it;
|
|
134
|
-
- one entry in `CHANT_FLOORS` (the read in words, the floor, what adds it in
|
|
135
|
-
chant), which is what `behold doctor` lists with the project's chant version
|
|
136
|
-
and whether the floor is met;
|
|
137
|
-
- the code that makes the read checks the project's chant first (`floorMet`,
|
|
138
|
-
`floorRefusal`) and never sends the read to a chant that would reject it.
|
|
139
|
-
|
|
140
|
-
On an older chant the pane that needs the read shows `floorRefusal`'s words
|
|
141
|
-
(the read, the chant that adds it, the project's version) and the rest of
|
|
142
|
-
behold works. The why route does this: `GET /api/workspace/why` refuses before
|
|
143
|
-
spawning the read. A new read adds its constant and entry in the issue that
|
|
144
|
-
adds the read, once the chant release is known, and reads through the read
|
|
145
|
-
contract (`src/workspace-reader.ts`), never chant's library.
|
|
146
|
-
|
|
147
|
-
### The chant release behold follows (behold#1005)
|
|
148
|
-
|
|
149
|
-
`CHANT_RELEASE` in src/chant-release.ts, `{ version, released }`, names the
|
|
150
|
-
chant release behold's newest reads need. It says `{ version: "0.124.58",
|
|
151
|
-
released: true }`: chant 0.124.58 is on npm (0.124.54 was the first release with the
|
|
152
|
-
drift record and its stream, the adoption report, `member-outputs` and
|
|
153
|
-
`@intentius/chant-lexicon-pulumi`; 0.124.58 adds the self-service modules). `ADOPTION_REPORT_CHANT_FLOOR`,
|
|
154
|
-
`DRIFT_RECORD_CHANT_FLOOR`, `DRIFT_STREAM_CHANT_FLOOR` and
|
|
155
|
-
`LEDGER_ROOT_MEMBER_CHANT_FLOOR` are its `version`, which is chant's
|
|
156
|
-
`NEXT_RELEASE` (INTENTIUS/chant#4480) at the cut. scripts/chant-release.ts
|
|
157
|
-
writes the files the switch decides (src/chant-release-sync.ts lists them):
|
|
158
|
-
the exact terraform and pulumi lexicon pins of example-terraform-estate,
|
|
159
|
-
example-choudoufu-estate and e2e/fixtures/pulumi-workspace (the published
|
|
160
|
-
chant, `PUBLISHED_CHANT`, while unreleased, so a plain `npm ci` meets them,
|
|
161
|
-
and `version` once released, moving with the floors; behold#1015), the
|
|
162
|
-
three-cloud workspace's pins (by path while unreleased, by package and
|
|
163
|
-
version once released) and its package.json, and behold's own chant ranges,
|
|
164
|
-
the pulumi lexicon devDependency among them. src/chant-release.test.ts holds
|
|
165
|
-
them to the switch, and `npx tsx scripts/chant-release.ts --check` lists any
|
|
166
|
-
file out of step.
|
|
167
|
-
|
|
168
|
-
With the release out, behold imports what it once copied from chant:
|
|
169
|
-
src/drift-line.ts decodes with `@intentius/chant/drift-record` (keeping
|
|
170
|
-
behold#995's unknown-status rule on top), src/graph-db/types.ts, listing.ts
|
|
171
|
-
and mask.ts re-export chant's engine-facts, index-document, cloud-lister and
|
|
172
|
-
mask modules, the investigation templates come from
|
|
173
|
-
`@intentius/chant/capabilities/templates` with no stub, the index diff is
|
|
174
|
-
`@intentius/chant/lifecycle/index-diff`, and `behold index` calls chant's
|
|
175
|
-
`runCloudIndex` statically. src/value-match.ts stays until the pulumi
|
|
176
|
-
lexicon has a `referenceCatalog` (chant#4535's note on behold#1005).
|
|
177
|
-
|
|
178
|
-
## chant's reference catalog (behold#1080)
|
|
179
|
-
|
|
180
|
-
A declared workspace read by a chant at `REFERENCE_CATALOG_CHANT_FLOOR`
|
|
181
|
-
(0.124.98, the release that carries INTENTIUS/chant#5097; 0.124.97 is on npm
|
|
182
|
-
today) gets one more read: `chant workspace graph <root>` for the whole
|
|
183
|
-
workspace, at the tier the members are read at (src/reference-catalog.ts,
|
|
184
|
-
cached under the workspace's source stamp). A read of one member cannot see a
|
|
185
|
-
reference into another, so the per-member reads' `dangling` entries that carry
|
|
186
|
-
a `rule` are replaced by this read's, and its derived edges, `dangling[]`,
|
|
187
|
-
`ambiguous[]` and `catalog.rules` go on the composed IR (`ir.catalog`). The
|
|
188
|
-
floor is checked first; below it nothing is sent and the estate is composed as
|
|
189
|
-
before. `readGraph` does this, after behold's own edge passes and before the
|
|
190
|
-
cluster anchor.
|
|
191
|
-
|
|
192
|
-
src/catalog-draw.ts draws it, after the stacking (`graphView` and the estate
|
|
193
|
-
branch of `/api/graph` call `drawCatalog`). A catalog edge is weighed "joined"
|
|
194
|
-
(web/edge-weight.js, `isCatalogEdge`), apart from "inferred", and the weight
|
|
195
|
-
and the rule are stamped on the SVG's edge (`data-edge-weight`,
|
|
196
|
-
`data-edge-rule`) with inline strokes, so a static export keeps them. A
|
|
197
|
-
dangling reference whose rule is not containment is a dashed placeholder card
|
|
198
|
-
(kind of the `targetKind`, lexicon `behold`, `attrs._placeholder` the value, one
|
|
199
|
-
per member, kind and value), and an ambiguous one is a dotted edge to each
|
|
200
|
-
candidate with `viaAttr` "one of N". The picture ends with the key; the answer's
|
|
201
|
-
`meta.catalogLegend` has the same rows for the page, which hides the in-SVG one
|
|
202
|
-
and draws its own. The graph document keeps `rule`, the one field: chant's rule
|
|
203
|
-
id on a joined edge, and the reference's rule on the placeholder and ambiguous
|
|
204
|
-
edges.
|
|
205
|
-
|
|
206
|
-
The cluster anchor (src/cluster-anchor.ts) reads the join: a member whose
|
|
207
|
-
Applications name a cluster Secret that chant joins to one cluster resource
|
|
208
|
-
anchors its objects to that cluster only; a Secret with no match, two matches,
|
|
209
|
-
or a member that reaches several clusters anchors nothing and puts the reason
|
|
210
|
-
in the note (`ir.anchorNotes`). A member without a cluster Secret keeps the
|
|
211
|
-
guess. The fixtures are `chant workspace graph --discover --json` recorded
|
|
212
|
-
from a chant checkout at the catalog and its rules (e2e/fixtures/
|
|
213
|
-
reference-catalog), the tests src/catalog-draw.test.ts and
|
|
214
|
-
src/catalog-route.test.ts.
|
|
215
|
-
|
|
216
|
-
## A pipeline's numbers, from Prometheus (behold#571)
|
|
217
|
-
|
|
218
|
-
`behold serve --prometheus <url>` (or `BEHOLD_PROMETHEUS_URL`) adds `GET
|
|
219
|
-
/api/metrics?project=<owner>/<name>[&commit=<sha>]` (src/prometheus-metrics.ts).
|
|
220
|
-
behold asks a FIXED set of named queries over terragucci's gauges (each a
|
|
221
|
-
constant string, nothing from the request in it), shares one read for 30 s,
|
|
222
|
-
and picks the repo's series out of the answers: one commit's tf-apply waves
|
|
223
|
-
(the wave job's own time first, then each root's init, plan and apply
|
|
224
|
-
seconds and any state lock wait, in milliseconds below a second on the
|
|
225
|
-
kiosk, the time an approval held the wave at
|
|
226
|
-
its gate, the changes it applied, when it started waiting) and the DORA four,
|
|
227
|
-
from terragucci estate's gauges or its `dora.json` beside the reports. It
|
|
228
|
-
answers numbers, never a proxy, and a public serve keeps it (GET). Without
|
|
229
|
-
an address it answers 404. The kiosk's "Pipeline metrics" pane
|
|
230
|
-
(web/kiosk-metrics.js) shows only what it returns, and no pane when it
|
|
231
|
-
returns nothing for the repo.
|
|
232
|
-
|
|
233
|
-
## Runs from chant's run index (behold#815)
|
|
234
|
-
|
|
235
|
-
`behold serve --ci-report-url <url>` (or `BEHOLD_CI_REPORT_URL`) points the
|
|
236
|
-
kiosk's runs pane at chant's run index, `<url>/runs/index.json`
|
|
237
|
-
(ci-run-index/v1, floor `CI_RUN_INDEX_CHANT_FLOOR`, 0.124.31), instead of the
|
|
238
|
-
forge's runs (src/ci-run-index.ts). The text goes through
|
|
239
|
-
`ciRunIndexOf` in src/workspace-reader.ts (contract 1), then the floor against
|
|
240
|
-
the index's own `chant`, then the vendored schema
|
|
241
|
-
(src/ci-run-index-schema/, chant commit in `CI_RUN_INDEX_SCHEMA_SOURCE`) with
|
|
242
|
-
its `status` and `job` enums left out, since v1 adds to them. An entry the
|
|
243
|
-
schema refuses, or whose key is not `<pr>/<commit>[/<member>]`, is dropped and
|
|
244
|
-
listed in `skipped`. `GET /api/chant/ci/runs` answers the runs in demo.runs/v1
|
|
245
|
-
shape; `GET /api/chant/ci/runs/:runId` reads that entry's
|
|
246
|
-
`pr-<job>.events.jsonl` and `pr-<job>.json` under its key only and builds the
|
|
247
|
-
log with `demoRunOf` (src/chant-demo.ts). No events file is one step saying
|
|
248
|
-
so. An apply refused with `plan-changed`, `not-approved` or a wave's
|
|
249
|
-
equivalent exited 3 and is drawn waiting with "the plan moved or waits:
|
|
250
|
-
re-plan and re-approve". So is an apply whose entry has `exitCode: 3` and a
|
|
251
|
-
failure that isn't another refusal (#818; the field follows chant#4165, not
|
|
252
|
-
merged, and isn't in the vendored schema; absent reads as before). `signer` shows only when it is a string; runOrigin's
|
|
253
|
-
URL is the link, named by its host, never by `forge`. The page learns of it
|
|
254
|
-
from `<meta name="kiosk-runs" content="chant-ci">` (web/kiosk-source.js
|
|
255
|
-
`pageRuns`); only the runs pane switches, the cycle and approval panel read
|
|
256
|
-
as before. #818: without the flag, a served workspace's declared
|
|
257
|
-
`ci.reportUrl` (s3:// or file://, read from the `workspace ls` behold already
|
|
258
|
-
makes, `declaredReportUrl` in src/workspace.ts, floor
|
|
259
|
-
`CI_REPORT_URL_CHANT_FLOOR`, 0.124.32, chant#4160) is used, a memberless
|
|
260
|
-
declaration included; the flag overrides it, and each answer's `urlFrom` says
|
|
261
|
-
`flag` or `declaration`. With neither, nothing changes.
|
|
262
|
-
|
|
263
|
-
A member of another kind in an estate's components picture (#997): chant
|
|
264
|
-
writes its release ledger per component and a TerraformApplyOp writes no
|
|
265
|
-
release, so a `choudoufu` or `terraform` member is one card,
|
|
266
|
-
`<member>/<kind>` (lexicon `member-runs`, src/component-releases.ts), with
|
|
267
|
-
every resource of the member under it. Its `apply` and `_lastApply` are the
|
|
268
|
-
run index's newest `apply` entry for that member that passed (an entry with
|
|
269
|
-
no `member` is a run of the whole workspace and is not taken as one), and
|
|
270
|
-
its `since` and `_runSince` the newest entry after it, the member's or the
|
|
271
|
-
workspace's, when that did not pass. A card the index names nothing of says
|
|
272
|
-
`no runs recorded`, or `no run index read` when behold has no report URL;
|
|
273
|
-
behold never makes one up. The members are read through the same
|
|
274
|
-
`ciRunIndexOf` as the runs pane.
|
|
275
|
-
|
|
276
|
-
The same card lists the member's local applies (behold#1010,
|
|
277
|
-
src/member-local-applies.ts): the TerraformApplyOp runs that applied a root
|
|
278
|
-
in the member's directory, from `chant ledger runs --where
|
|
279
|
-
root_member=<member> --json` at the served workspace's root (chant#4482,
|
|
280
|
-
chant#4500), as `_localApplies` (newest first, at most five) and `local`, the
|
|
281
|
-
newest that passed. The read is sent only to a chant at
|
|
282
|
-
`LEDGER_ROOT_MEMBER_CHANT_FLOOR`, and a `runs` table whose `columns` lack
|
|
283
|
-
`root_member` reads as "this chant does not say", so the card keeps the run
|
|
284
|
-
index alone. A null `root_member` is unknown (chant#4508): such a run is on
|
|
285
|
-
no card, the declaring member's included, and the picture's note counts it
|
|
286
|
-
as an apply of an unknown root with its `labels.TerraformRoot`, read with
|
|
287
|
-
`--where labels.Apply=true`.
|
|
288
|
-
|
|
289
|
-
## Adopting a Pulumi stack into plunge (behold#999)
|
|
290
|
-
|
|
291
|
-
A `pulumi` member of a declared workspace is offered adoption into plunge,
|
|
292
|
-
the engine tier, through plunge's own `plunge stack adopt` (INTENTIUS/plunge#7,
|
|
293
|
-
P-L4). The Adopt tab and `GET /api/adopt` say what it gains (a record per
|
|
294
|
-
resource, marker tags, no stack lock, the checkpoint's IDs kept, a recorded
|
|
295
|
-
adoption that a re-run leaves alone, a back-out through `plunge stack export`
|
|
296
|
-
and `pulumi stack import`) and what it does not (plunge's refusals, bridged
|
|
297
|
-
types classed at the first run, record-only ownership for untaggable types).
|
|
298
|
-
|
|
299
|
-
- `GET /api/adopt/report?member=<name>[&stack=<name>]` runs `plunge stack
|
|
300
|
-
adopt --stack <s> --json --non-interactive` in the member's directory, with
|
|
301
|
-
`PULUMI_BACKEND_URL=plunge+<backend.url from Pulumi.yaml>`, no stdin and no
|
|
302
|
-
`--yes`. That is plunge's read-only stage, as one v1 JSON document
|
|
303
|
-
(INTENTIUS/plunge#17, plunge docs/plunge/ADOPT.md): every resource with its
|
|
304
|
-
fate (marker, record, pending, already-adopted), having written nothing.
|
|
305
|
-
Each resource gets its fate and why. When plunge refuses the adoption
|
|
306
|
-
(pending operations, a provider hiding the markers, an aws-native
|
|
307
|
-
create-only-tag type, foreign records), each refusal is listed with its
|
|
308
|
-
code and the URN it names. behold reads the JSON view only (behold#1007).
|
|
309
|
-
- `POST /api/adopt/start` `{member, stack?}` runs the same classification
|
|
310
|
-
through the runner's `track` and answers the confirm command, `cd <dir> &&
|
|
311
|
-
PULUMI_BACKEND_URL=<url> plunge stack adopt --stack <s> --yes`. A person
|
|
312
|
-
runs it. behold never passes `--yes` or `-y`, drops
|
|
313
|
-
`PULUMI_SKIP_CONFIRMATIONS` from the environment it hands plunge, and
|
|
314
|
-
refuses any other plunge argv before spawning (`assertClassificationOnly`,
|
|
315
|
-
src/pulumi-adoption.ts). After the confirm, point Pulumi.yaml's
|
|
316
|
-
`backend.url` at `plunge+<url>` so chant runs the member through plunge.
|
|
317
|
-
- The backend comes from the member's Pulumi.yaml only, never login state. A
|
|
318
|
-
`file://`, `s3://`, `gs://` or `azblob://` URL is a DIY backend; a
|
|
319
|
-
`plunge+` one is already plunge's. No URL, or a Pulumi Cloud URL, gets no
|
|
320
|
-
start, and the offer says why. The stack is read off the checked-in
|
|
321
|
-
`stack-export.json` URNs unless the request names one.
|
|
322
|
-
- A plunge without the `stack adopt --json` view is detected from its answer
|
|
323
|
-
(outcome `no-view`), not from a version, and refused with words naming
|
|
324
|
-
plunge 968b54748d, the commit that adds the view.
|
|
325
|
-
- The table is keyed on member kind (`ADOPTERS`, src/adoption.ts), the same
|
|
326
|
-
names the Terraform half uses on integration/choudoufu-engine.
|
|
327
|
-
`/api/adopt*` is refused in a public view, and the start goes through the
|
|
328
|
-
terragucci and SQL Yodeler write allowlist.
|
|
329
|
-
- Tests: src/pulumi-adoption.test.ts, web/adopt-pulumi.test.js, and the e2e
|
|
330
|
-
`just e2e-adopt-pulumi` (e2e/adopt-pulumi-e2e.sh with the stand-in
|
|
331
|
-
e2e/fixtures/adopt-pulumi/plunge), which asserts nothing is written before
|
|
332
|
-
a person runs the confirm line, even with `PULUMI_SKIP_CONFIRMATIONS=true`
|
|
333
|
-
in behold's environment.
|
|
334
|
-
|
|
335
|
-
## A plan job run locally (behold#685)
|
|
336
|
-
|
|
337
|
-
`POST /api/chant/ci/local` `{job: "plan", commit, pr, env?, base?, member?,
|
|
338
|
-
forge?}` starts `chant ci run plan --local --events-json --env <env> --base
|
|
339
|
-
<sha> --commit <sha> --pr <n> --forge <forge>` (src/ci-local-run.ts, floor
|
|
340
|
-
`CI_RUN_LOCAL_CHANT_FLOOR`, 0.124.32, chant#4161) in the workspace root or the
|
|
341
|
-
named member's declared directory. Each value is checked; the commit and base
|
|
342
|
-
are resolved by `git rev-parse` in the root, the base defaulting to where the
|
|
343
|
-
commit leaves the trunk, the forge to the one workflow directory present. It
|
|
344
|
-
runs through the runner's `track`, so it shares the one-command guard and the
|
|
345
|
-
now-line, and is refused like an Op run: preview `403`, a terragucci or SQL
|
|
346
|
-
Yodeler repo `409` (not allowlisted), `--public` `405` and its GETs `403`.
|
|
347
|
-
stdout lines cross `readRunLine`; stderr is the step output, filed under its
|
|
348
|
-
`[<phase>]`. `GET /api/chant/ci/local/:id` answers the run in demo.run/v1
|
|
349
|
-
(`from: "chant-ci-local"`) and `ci`, CI's run of the same job, commit and
|
|
350
|
-
member from the run index (`ciRunsRoutes`' lookup) when `--ci-report-url` is
|
|
351
|
-
set. The SSE `local-run` event names a run that moved. The page's **Local** tab
|
|
352
|
-
(web/local-run.js) draws both with kiosk-runs.js `renderRun`, and is not drawn
|
|
353
|
-
in a public view, an embed, a static export, preview or a guarded repo.
|
|
354
|
-
|
|
355
|
-
Apply is never started: `job: "apply"` answers `422 local-apply`.
|
|
356
|
-
`--local` does not make an apply safe (it still changes real infrastructure
|
|
357
|
-
and pushes release records and gate facts), and behold has no emulator notion
|
|
358
|
-
that holds for it: `ci run` gives the job a clean environment that keeps HOME,
|
|
359
|
-
so `serve --local`'s emulator env does not reach the job and the operator's
|
|
360
|
-
own credentials would. Cached-step marks wait on chant#4015.
|
|
361
|
-
|
|
362
|
-
## Adopting a Terraform root into choudoufu (behold#999)
|
|
363
|
-
|
|
364
|
-
A `terraform` member of a declared workspace is offered adoption into
|
|
365
|
-
choudoufu, the engine tier, through chant's `chant workspace promote <member>
|
|
366
|
-
--state <file>` (src/adoption.ts, floor `ADOPTION_REPORT_CHANT_FLOOR`, which
|
|
367
|
-
is `CHANT_RELEASE.version` in src/chant-release.ts until the chant release
|
|
368
|
-
carrying the report is cut; see "The coming chant release" below). The panel's
|
|
369
|
-
**Adopt** tab (web/adopt.js) shows, per member, what the engine tier gives
|
|
370
|
-
and what it does not, the command, and promote's report.
|
|
371
|
-
|
|
372
|
-
- `GET /api/adopt`: each adoptable member's offer `{member, kind, dir,
|
|
373
|
-
offered, engine, gains, limits, stateHint, state: {file, present},
|
|
374
|
-
command, approve, recorded, start: {offered, why?}}`. A `pulumi` member is
|
|
375
|
-
listed `offered: false` with `waits` (plunge P-L4, INTENTIUS/plunge#7):
|
|
376
|
-
`ADOPTERS` and `ADOPTION_WAITS` are keyed on member kind, and the Pulumi
|
|
377
|
-
half adds its adopter there.
|
|
378
|
-
- `GET /api/adopt/report?member=<name>[&state=<file>]`: promote's read-only
|
|
379
|
-
stage, `workspace promote <member> --state <abs> --dry-run --json`, through
|
|
380
|
-
the reader (`readPromoteReport`, `PROMOTE_REPORT_READ`). chant stages in a
|
|
381
|
-
throwaway worktree, runs `choudoufu live-check` and `live-import` without
|
|
382
|
-
`-approve`, records no gate and leaves the tree as it was. Its `adoption`
|
|
383
|
-
field (chant's `adoption-report.ts`, parsed from choudoufu's text) lists
|
|
384
|
-
every resource instance; behold gives each a `fate`: `claimed` (VERIFIED,
|
|
385
|
-
DRIFTED) or `left-out` (MISSING, UNTAGGABLE, UNADMITTED_TYPE), with a
|
|
386
|
-
`why` and choudoufu's `detail`. An unknown status is listed as `unknown`,
|
|
387
|
-
never dropped.
|
|
388
|
-
- `POST /api/adopt/start` `{member, state?}`: the delegated write. It starts
|
|
389
|
-
`workspace promote <member> --state <abs> --json` (never `--dry-run`,
|
|
390
|
-
never `-approve`) at the workspace root through the runner's `track`.
|
|
391
|
-
chant's gate decides: without an approval of the patch's digest promote
|
|
392
|
-
records a pending gate on `chant/lifecycle` and exits 3 (`gated`), and
|
|
393
|
-
nothing in the tree or the cloud is written; after `chant approve
|
|
394
|
-
workspace-promote <member> --plan <digest>`, the same start applies the
|
|
395
|
-
patch and runs `live-import -approve`. behold never approves here; the
|
|
396
|
-
approve line is shown to copy. `GET /api/adopt/runs/:id` answers one start
|
|
397
|
-
(`outcome`, `digest`, `words`, `approve`, `report`), the last 20 in memory;
|
|
398
|
-
the SSE `adopt-run` event names one that moved.
|
|
399
|
-
- The state file is a file name in the member's declared directory
|
|
400
|
-
(`terraform.tfstate` by default), never a path. A root on a remote backend
|
|
401
|
-
pulls one there under a name git ignores first, since promote refuses a
|
|
402
|
-
member with uncommitted changes.
|
|
403
|
-
|
|
404
|
-
Refusals: no declared workspace `404`, below the floor `409 chant-too-old`,
|
|
405
|
-
preview `403` for the start, a kind behold does not adopt `422 adopt-kind`,
|
|
406
|
-
no state file `422 adopt-state`, a second command while one runs `409 busy`.
|
|
407
|
-
A terragucci or SQL Yodeler repo refuses the start through the write
|
|
408
|
-
allowlist (`409`), and `--public` refuses every `/api/adopt` read (`403`)
|
|
409
|
-
and the start (`405`). The tab is not drawn in a public view, an embed, a
|
|
410
|
-
static export or a guarded repo.
|
|
411
|
-
|
|
412
|
-
`behold demo terraform-estate` serves `serve --adopt-recorded
|
|
413
|
-
recorded/adoption` (DemoServe `adoptRecorded`): one recorded `<member>.json`
|
|
414
|
-
per root in promote's shape, labelled recorded (`RECORDED_NOTE`), and no
|
|
415
|
-
start. `just e2e-adopt` (e2e/adopt-terraform-e2e.sh) runs the whole path over
|
|
416
|
-
a real chant and serve with choudoufu replaced by
|
|
417
|
-
e2e/fixtures/adopt/choudoufu, and asserts the report lists every resource
|
|
418
|
-
with its fate and that nothing is written before approval.
|
|
419
|
-
|
|
420
|
-
## A terragucci estate, from its reports (#490)
|
|
421
|
-
|
|
422
|
-
`behold serve <repo> --terragucci <dir|s3://bucket/prefix|https://…>`
|
|
423
|
-
(`--terragucci-project <host/path>` when the bucket holds several projects
|
|
424
|
-
and none is the checkout's git remote) adds two reads, in
|
|
425
|
-
`src/terragucci-view.ts`:
|
|
426
|
-
|
|
427
|
-
- `GET /api/terragucci`: `{source, project, validation, read, reports, files,
|
|
428
|
-
estate?, roots[], cards{}, waiting[], unmatched}`. `roots[]` is every
|
|
429
|
-
Terraform root of the checkout with the newest `plan`, `drift` and `apply`
|
|
430
|
-
run that held it; a missing stage means no report holds that root, which is
|
|
431
|
-
not "no changes". `cards` maps a card id to its marks (`verdict: drift |
|
|
432
|
-
plan | wave`, terragucci's words, the instance addresses, the run). Each
|
|
433
|
-
mark's `values` gives each changed attribute's `before` and `after`, or
|
|
434
|
-
`unknown: true` for a value known only after apply. A sensitive attribute
|
|
435
|
-
is never there, and a value longer than 300 characters of JSON is left out
|
|
436
|
-
with `long: true`. `applied` maps a card id to what its root's newest
|
|
437
|
-
applied wave wrote. The kiosk's popover reads both (behold#571). Nothing
|
|
438
|
-
sets `_status`: a report is never painted as live. `waiting[]` carries each
|
|
439
|
-
wave's roots, destroys, and the `command` a person runs. `estate` is
|
|
440
|
-
terragucci's own counts when the source has `estate.json`. A key such as a
|
|
441
|
-
run's `report` opens at `files` + the key. Refusals are `422 {code:
|
|
442
|
-
"terragucci-report"}`. `?fresh=1` skips the 30 s cache.
|
|
443
|
-
- `GET /api/terragucci/file?key=<key>`: one report file from the source,
|
|
444
|
-
sandboxed.
|
|
445
|
-
- `GET /api/terragucci/timeline?root=<path>&limit=<n>` (#506): terragucci's
|
|
446
|
-
audit record (`audit.jsonl` at the top of the prefix, one GET) as `{source,
|
|
447
|
-
project, validation, read, record: {key, present}, absent?, files, root?,
|
|
448
|
-
total, limit, entries[]}`, newest first, 200 by default and 1000 at most.
|
|
449
|
-
An entry is `{id, kind, at, who, what, wave?, digest, result, roots[], run:
|
|
450
|
-
{commit?, job_url?, run_id?, pull_request?, report?}, evidence, detail?}`;
|
|
451
|
-
`run.report` opens at `files` + the key. An approval takes the roots and
|
|
452
|
-
report of its wave's other entries (same gate and digest). No
|
|
453
|
-
`audit.jsonl` is `present: false` plus an `absent` sentence, never an
|
|
454
|
-
empty history; a bad line is the `422 terragucci-report` refusal naming it.
|
|
455
|
-
#523: an S3 403 on an optional read (`audit.jsonl` here, `run.json` for
|
|
456
|
-
`/api/terragucci/progress` and the estate's run views) is not a refusal:
|
|
457
|
-
the source throws `TerragucciDenied` (`src/terragucci-source.ts`), and the
|
|
458
|
-
answer carries `present: false`, `unreadable: true` and an `absent`
|
|
459
|
-
sentence naming the key and `s3:GetObject` (or `s3:ListBucket`). A 403 on
|
|
460
|
-
`index.json`, a report or `estate.json` still fails.
|
|
461
|
-
`src/terragucci-timeline.ts` holds the read and the check (terragucci's
|
|
462
|
-
`dist/audit.schema.json` when it resolves, structural otherwise). The SPA
|
|
463
|
-
draws it in the Terragucci tab and, filtered to the card's root, in the
|
|
464
|
-
inspect pane (`web/terragucci-timeline.js`); an export carries it as one
|
|
465
|
-
snapshot and does not fail on it.
|
|
466
|
-
- `GET /api/terragucci/lifecycle` (#505): the repo's `chant/lifecycle` lane,
|
|
467
|
-
`{branch, found, via, origin?, fetch: {ok, error?}, commit?: {sha,
|
|
468
|
-
committed}, read: {at}, approval?, gates[], locks[], note}`. `gates[]` is one
|
|
469
|
-
entry per wave gate (`wave-<k>`, chant op-waves' `<gate>-wave-<k>` or a
|
|
470
|
-
product's `<name>-wave-<k>`: `WAVE_GATE`, #521) in `_gates/tf-apply.jsonl` and
|
|
471
|
-
`_gates/tf-apply/applied.jsonl`, decided by chant's `decideGateApproval`
|
|
472
|
-
(`@intentius/chant/gate-decision`, #520) with spent approvals left out, on
|
|
473
|
-
lines parsed by chant's `parseGateLedger` and `parseAppliedGateLines`. The
|
|
474
|
-
states:
|
|
475
|
-
- `waiting`: no approval of the wave's digest counts; `command` is the
|
|
476
|
-
approve line (`--sign` under `sealed`), or `chant workspace points answer
|
|
477
|
-
<id>` when the pending fact carries `answer: {point, id}` (#521).
|
|
478
|
-
- `expired`: the pending fact's `expiresAt` passed with none.
|
|
479
|
-
- `refused`: an unspent approval stands for another digest
|
|
480
|
-
(`refused: {digest, by, at}`); no approve line.
|
|
481
|
-
- `approved`: an unspent approval of the digest counts, not applied yet.
|
|
482
|
-
- `applied` / `failed`: a wave applied under that approval, and how the
|
|
483
|
-
apply finished when terragucci recorded it. chant's op waves write no
|
|
484
|
-
`finished` line: then `applied.result` is absent and the page says
|
|
485
|
-
"applied (outcome not recorded)".
|
|
486
|
-
- `refused-by-policy` (#521): a denial on `_gates/policy-override.jsonl`
|
|
487
|
-
(chant's `recordedDenials`) newer than anything on the wave's gate, that
|
|
488
|
-
no override counts for (chant's `decideOverride`, with the overriders at
|
|
489
|
-
base: `.chant/overriders`, or terragucci's `policy.override`) and no run
|
|
490
|
-
applied an override of since. `denials[]` carries each run, its plan and
|
|
491
|
-
rules, and chant's `overrideCommand` line; no approve line. The wave is
|
|
492
|
-
the one the denial's pending fact names (`wave: {number, name, op}`,
|
|
493
|
-
typed on chant's `PendingGateRecord`, whose parser drops a wave of the
|
|
494
|
-
wrong shape, chant#3887), else, for a fact an older chant wrote, the one
|
|
495
|
-
whose pending fact lists the run.
|
|
496
|
-
- `held` (#521): a pending fact on another gate (any `_gates/<op>.jsonl`)
|
|
497
|
-
that names this op's wave (`wave: {number, name, op}`), with no approval
|
|
498
|
-
of its digest that counts under the mode the fact records. `heldOn: {op,
|
|
499
|
-
gate, digest, since, heldBy, description}`; `heldBy: {hook, moment,
|
|
500
|
-
target?}` is the hook that holds the wave (chant#3886), and the card
|
|
501
|
-
(`holderWords` in `web/terragucci-lifecycle.js`) names it from there,
|
|
502
|
-
or from `description` for a fact an older chant wrote. `command`
|
|
503
|
-
approves that gate (`chant approve <op> <gate> --plan`) or answers its
|
|
504
|
-
decision point. A hold fact that names no wave is not read as a hold.
|
|
505
|
-
Each entry also carries `digest`, `pending` (with `members` and
|
|
506
|
-
`neverOverMcp` when recorded, `description`, `url`, `answer`), `approval`
|
|
507
|
-
(by, at, `signed` when the seal has a signature, via (`review` for chant's
|
|
508
|
-
`review: {pr, head, approvers}` line), pr, head, reviewers, relayedBy, note), `uncounted` (an
|
|
509
|
-
approval of this digest the mode did not count, with chant's reason, such
|
|
510
|
-
as an unsealed one under `sealed`), `spent` (an approval of another digest
|
|
511
|
-
an apply used), `applied` (with `wave` and `review` when present), the kept
|
|
512
|
-
reports under `_gates/tf-apply/wave-<k>/`, and `command`. `approval` on the
|
|
513
|
-
answer is the rule read at base, the tip of origin's default branch fetched
|
|
514
|
-
depth 1 into the same cache (`refs/behold/base`): `mode` from
|
|
515
|
-
terragucci.yml's `approval:` key, else `sealed` when chant.workspace.json
|
|
516
|
-
lists `identity.gates`, else `ledger`, and the signers read with chant's
|
|
517
|
-
`gateSignersAt`. Each wave is decided under the approval mode its newest
|
|
518
|
-
pending fact records (`approvalMode`, `withRecordedModes`), else the mode at
|
|
519
|
-
base; the entry carries `approvalMode: {mode, from: "pending" | "base"}`,
|
|
520
|
-
and `approval.inferred` is set only when some wave's fact records none. A
|
|
521
|
-
gate `identity.gates` names at base is decided with `refuses` from chant's
|
|
522
|
-
`identityGateAdmissionAt`, which checks the seal against the signers at
|
|
523
|
-
base and, when the gate names a class, the role grants in
|
|
524
|
-
`.chant/trust.json` at base, whatever the mode; the entry carries
|
|
525
|
-
`identity: {class}`. A class a pinned package supplies is read by chant
|
|
526
|
-
from `./workspace-principals` (chant#3888): a path pin's file at base, a
|
|
527
|
-
package pin's from the package installed in the served checkout's
|
|
528
|
-
node_modules (behold passes the checkout as `packages`, since the bare
|
|
529
|
-
cache has none), at the pinned version. When that package is missing or
|
|
530
|
-
at another version, a gate naming a domain class or `human` refuses every
|
|
531
|
-
approval and chant's reason names the pin. Under `pr-review`, a spec's `headPlans` (the op-waves spec name)
|
|
532
|
-
has the newest 50 `_wave-plans/<name>/<head>.json` records read with
|
|
533
|
-
chant's `readHeadPlans` (`@intentius/chant/lifecycle/wave-plans`) through
|
|
534
|
-
`ledgerPort`, a `LedgerReadPort` over the fetched commit. The op, ledger paths, gate names, approve line and
|
|
535
|
-
mode reader are a `GateLaneSpec` (`TERRAGUCCI_LANE` is terragucci's), for
|
|
536
|
-
another product's lane: `opWavesLane(op, over?)` gives one with chant's
|
|
537
|
-
approve line, mode rule and overriders, and `readLifecycle(checkout, {spec})`
|
|
538
|
-
reads it. `terragucciApproveCommand` is the one approve line the reports,
|
|
539
|
-
the estate and the lane share, and `gatePolicyName` reads `on-destroy` as
|
|
540
|
-
`on-destructive` (terragucci#863). `locks[]` is
|
|
541
|
-
`_locks/tf-apply.json`, one per root (`pr, by, at, head, via?, stage?`).
|
|
542
|
-
Every gate and lock carries `source: {commit, committed, path}`, the newest
|
|
543
|
-
commit of the branch that changed its file. The branch is fetched from the
|
|
544
|
-
checkout's origin URL into `<tmpdir>/behold-lifecycle-<hash of the URL>`, a
|
|
545
|
-
bare repo behold owns (`assertScratch`), with the person's own git
|
|
546
|
-
credentials and no prompt; the checkout is never fetched into and no ref of
|
|
547
|
-
it moves. A failed fetch falls back to the checkout's own
|
|
548
|
-
`refs/remotes/origin/chant/lifecycle`, read-only (`via: "checkout-ref"`,
|
|
549
|
-
`fetch.error`); a remote without the branch is `found: false, via:
|
|
550
|
-
"fetch"`, not an error. 30 s cache, `?fresh=1` skips it. Reader:
|
|
551
|
-
`src/terragucci-lifecycle.ts`.
|
|
552
|
-
- `GET /api/lifecycle/history?op=<op>&gate=<gate>&limit=<n>` (#522): the
|
|
553
|
-
gate ledgers' history on `chant/lifecycle`, for any product, registered
|
|
554
|
-
whether or not `--terragucci` is given. Same bare cache and fallback as
|
|
555
|
-
the lifecycle lane; per `_gates/<op>.jsonl` it runs `git log -p
|
|
556
|
-
--unified=0 --no-renames` and hands the text to chant's
|
|
557
|
-
`gateLedgerLinesFromLog`, then all ledgers to `deriveGateAudit`
|
|
558
|
-
(`@intentius/chant/lifecycle/gate-audit`). behold parses no ledger line
|
|
559
|
-
itself. Answer: `{branch, source: "ledger", found, via, origin?, fetch,
|
|
560
|
-
commit?, read, ledgers[], op?, gate?, total, limit, entries[], gaps[],
|
|
561
|
-
note}`, newest first, 200 by default and 1000 at most. An entry is `{id,
|
|
562
|
-
kind, at, op, gate, wave?, digest?, actor?, seal?, note?, rules?, subject?,
|
|
563
|
-
source: {path, line?, commit, committer, committed, change}, audit}`;
|
|
564
|
-
`kind` is chant's (`approval-requested | approved | override-requested |
|
|
565
|
-
override-recorded | revoked`), `audit` is chant's whole entry. A revocation
|
|
566
|
-
is a line a commit removed, and its `actor` is that commit's author. The
|
|
567
|
-
ledger holds no applies, so `applied` and `override-spent` appear only in
|
|
568
|
-
a product's own record (terragucci's `audit.jsonl`). The Terragucci tab's
|
|
569
|
-
Timeline draws it under the audit record, labelled "ledger"; when the
|
|
570
|
-
source has no `audit.jsonl` the record's lane says so and the ledger is
|
|
571
|
-
the history. An export carries it as one snapshot. Reader:
|
|
572
|
-
`src/lifecycle-history.ts`.
|
|
573
|
-
- `GET /api/terragucci/events` (#505): SSE. While at least one page holds it
|
|
574
|
-
open, a timer (`--terragucci-poll <secs>`, default 30, 0 off) asks
|
|
575
|
-
whether `index.json` changed (`If-None-Match` with the last ETag for S3 and
|
|
576
|
-
http, mtime for a directory) and fetches `chant/lifecycle` again. Events:
|
|
577
|
-
`hello {pollSecs}`, `reports {at, tag}` (the page reads `/api/terragucci`
|
|
578
|
-
again), `lifecycle <the whole answer>` when the read differs from the last,
|
|
579
|
-
and `polled {at, reports, lifecycle}` after every tick. The last page
|
|
580
|
-
leaving stops the timer (`src/terragucci-poll.ts`). Neither route writes,
|
|
581
|
-
approves, locks or unlocks.
|
|
582
|
-
- `GET /api/terragucci/progress` (#511): a choudoufu wave's progress per
|
|
583
|
-
resource from the run view of the newest commit `index.json` names a
|
|
584
|
-
`tf-apply` run of (one GET of `index.json`, one of
|
|
585
|
-
`<project dir>/runs/<commit>/run.json`, the directory taken from the index
|
|
586
|
-
row's own path). `{source, kind, project, validation, read, run: {commit,
|
|
587
|
-
key, present, updated?, html?} | null, absent?, files, watching, waves[],
|
|
588
|
-
cards{}, unmatched[]}`. A wave is `{number, state, gate, read, counts,
|
|
589
|
-
resources[]}`, a resource `{root, address, action, status: done | in-flight
|
|
590
|
-
| waiting | not-applied, done_at?, card?}`. `cards` is keyed by the same ids
|
|
591
|
-
as `/api/terragucci`'s marks (root path to `attrs.root`, instance to block),
|
|
592
|
-
one entry per wave with the wave's records `read` time and the card's
|
|
593
|
-
status (not applied, else in flight, else waiting, else done). It is a
|
|
594
|
-
dated corner tag, never a fill. No `run.json` is `run.present: false` plus
|
|
595
|
-
an `absent` sentence. `watching` is true while a wave is applying or a
|
|
596
|
-
resource is in flight or waiting; only then does the poll ask whether that
|
|
597
|
-
`run.json` changed (`If-None-Match`, mtime for a directory) and push a
|
|
598
|
-
`progress` event with the whole answer, and `polled` carries `progress:
|
|
599
|
-
{asked, key?, changed?, error?}`. Checked against `dist/run.schema.json`
|
|
600
|
-
when `@intentius/terragucci` resolves, structurally otherwise; reader
|
|
601
|
-
`src/terragucci-progress.ts`, page `web/terragucci-progress.js`.
|
|
602
|
-
|
|
603
|
-
The reads are `src/terragucci-reports.ts` (index, each run's report, estate;
|
|
604
|
-
terragucci's JSON Schemas when `@intentius/terragucci` resolves, a structural
|
|
605
|
-
check otherwise; the package is looked up on every read and the compiled
|
|
606
|
-
schemas cached by its path and files' mtimes, #500) and the join is `src/terragucci-overlay.ts` (root path to
|
|
607
|
-
`attrs.root`, instance address to block path). An S3 source shells the
|
|
608
|
-
operator's `aws s3 cp <key> -`. There is no approve route, by design: hand the
|
|
609
|
-
operator `waiting[].command`.
|
|
610
|
-
|
|
611
|
-
A control repo (#509), one whose terragucci config has `projects:` and whose
|
|
612
|
-
checkout declares no Terraform root (`controlRepo` in
|
|
613
|
-
`src/terragucci-estate.ts`), gets one more read, and `/api/project` carries
|
|
614
|
-
`terragucciControl: {config, projects}`:
|
|
615
|
-
|
|
616
|
-
- `GET /api/terragucci/estate`: `{source, kind, config, validation: {estate,
|
|
617
|
-
run}, read, estate: {key, html, generated}, gets, projects[], edges[],
|
|
618
|
-
files}`. It reads `estate.json` and each project's newest run view,
|
|
619
|
-
`<project>/runs/<commit>/run.json`, one GET each (the commit is the
|
|
620
|
-
project's `run_view.commit`, else its `apply.commit`). A project is
|
|
621
|
-
`{project, status, index?, counts: {drifted, failed, waiting, dated},
|
|
622
|
-
waiting[], run? | missing? | refused?, checkout?, configured}`. Every
|
|
623
|
-
figure carries `dated: {key, at}`: estate.json's `generated`, or the run
|
|
624
|
-
view's `updated`. `waiting[].command` is the run view's approve line when it
|
|
625
|
-
holds that wave. `edges[]` is `{from, to, cross}`, `to` reading `from`'s
|
|
626
|
-
state; a cross edge matches a root's `external` read to another project's
|
|
627
|
-
root `state`, as terragucci's `estateGraph` does. A malformed run view is
|
|
628
|
-
`refused: {code: "terragucci-report"}` on its project only; a missing or
|
|
629
|
-
malformed `estate.json` is a 422. Not a control repo: 404 `code:
|
|
630
|
-
"terragucci-not-control"`. Run views are checked against
|
|
631
|
-
`@intentius/terragucci`'s `dist/run.schema.json` when it resolves, a
|
|
632
|
-
structural check otherwise. The page (`web/terragucci-estate.js`) draws it
|
|
633
|
-
in a layer over the graph area.
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
### The kiosk's prompt pane (#936)
|
|
637
|
-
|
|
638
|
-
A step of terragucci's `demo.json` may carry an `ask` (or `asks`, a list of
|
|
639
|
-
them played in order), and the file may carry `opening` and `closing` strings
|
|
640
|
-
(src/terragucci-demo.ts parses them; a field of the wrong type is null, and an
|
|
641
|
-
ask with none of a prompt, an action and a reply is dropped; a reply alone prints with no line of the person's, as an applied step's does). While a step has an ask,
|
|
642
|
-
the pane (`#k-ask`, web/kiosk-ask.js) takes the place of `#bar` and
|
|
643
|
-
`#k-caption` in Watch: a big monospace block at the foot of the screen. A
|
|
644
|
-
`prompt` is typed after `>` at 40 ms a character; an `action` shows at once
|
|
645
|
-
after a check mark; the `reply` prints after it, with `{roots}`, `{creates}`,
|
|
646
|
-
`{updates}`, `{deletes}` and `{error}` filled from the step's report (an
|
|
647
|
-
unknown token, or one without a value, is empty). The last three entries stay
|
|
648
|
-
above, faded. `opening` shows once at the scenario's first step
|
|
649
|
-
(`pull-request` or `planned`), `closing` at `applied`. While a job runs
|
|
650
|
-
(`pull-request`, `approved`, `merged`, `applying`, `resumed`) a status line
|
|
651
|
-
gives what is happening, the time since `started_at`, and `next`. With
|
|
652
|
-
`prefers-reduced-motion` everything shows at once. The pane's height is fixed
|
|
653
|
-
and replaces the caption in `captionRoomPx`, so it never covers the graph. A
|
|
654
|
-
step without an ask looks as it always did.
|
|
655
|
-
|
|
656
|
-
The pane tells the page through window events, each with detail
|
|
657
|
-
`{ ask, step, scenario }`: `behold:ask-start` before a beat is typed,
|
|
658
|
-
`behold:ask-done` when its reply has printed, and `behold:ask-clear` on a new
|
|
659
|
-
step with no ask. `{dependents}` is left to the lighting: it sets
|
|
660
|
-
`window.beholdAskTokens = { dependents: n }` on `behold:ask-start`, and the
|
|
661
|
-
reply reads it when it prints.
|
|
662
|
-
|
|
663
|
-
## Releases per environment, from the release ledger (#525)
|
|
664
|
-
|
|
665
|
-
`GET /api/lifecycle/releases[?fresh=1]` (src/lifecycle-releases.ts) reads
|
|
666
|
-
`<env>/releases.jsonl` on the served checkout's `chant/lifecycle` with chant's
|
|
667
|
-
own reader (`listReleaseEnvironments`, `readReleaseLedger`,
|
|
668
|
-
`latestPerComponent`, `recordsForDigest`). This one still imports
|
|
669
|
-
`@intentius/chant/lifecycle/release-ledger`: no read-contract command lists a
|
|
670
|
-
project's per-environment ledger outside a declared workspace (`workspace
|
|
671
|
-
status` needs a declaration, and `release list` lists cut releases, not the
|
|
672
|
-
`components release` records SQL Yodeler writes), so dropping the import would
|
|
673
|
-
blank the tab for every SQL Yodeler project. The trunk lane (#680) reads
|
|
674
|
-
releases through the contract only. The branch is fetched into the
|
|
675
|
-
same bare cache the terragucci lane uses (`fetchIntoCache` in
|
|
676
|
-
src/terragucci-lifecycle.ts). When that fetch fails, the checkout's
|
|
677
|
-
`refs/remotes/origin/chant/lifecycle` is fetched into a second cache of
|
|
678
|
-
behold's and read there (`via: "checkout-ref"`); the checkout is never
|
|
679
|
-
written. Reads are reused for 30s.
|
|
680
|
-
|
|
681
|
-
The answer: `environments` (wave order from `yodel-waves.json` when present,
|
|
682
|
-
`order: "waves"`, else by name), `components` (a tenant is
|
|
683
|
-
`<component>/<tenant>`, as SQL Yodeler records it), and `cells[]`, one per
|
|
684
|
-
component and environment that has a release: `digest`, `timestamp`,
|
|
685
|
-
`actor`, `approver?`, `gitSha`, `runId`, `runUrl?`, `source` (the newest
|
|
686
|
-
commit that changed that environment's ledger), and `differs: {from,
|
|
687
|
-
digest?, everHad}` when the environment before it holds another digest or
|
|
688
|
-
none. `/api/project` says `releaseLedger: true` for a checkout with a
|
|
689
|
-
`yodel.config.ts` or `yodel-waves.json`; the page then opens a Releases tab
|
|
690
|
-
(`web/releases.js`), and `behold export` captures the route as a snapshot.
|
|
691
|
-
|
|
692
|
-
## SQL Yodeler's report and drift, from files (#526)
|
|
693
|
-
|
|
694
|
-
`behold serve <dir> --yodel-report <file|dir>` adds `GET /api/yodel-report`
|
|
695
|
-
(`src/yodel-report.ts`). It reads one `yodel report --json` output and any
|
|
696
|
-
`yodel drift <env> --json` output in the same directory, written by the
|
|
697
|
-
person or their pipeline. behold never runs `yodel` and never connects to
|
|
698
|
-
the database.
|
|
699
|
-
|
|
700
|
-
- The answer is `{source, validation, report, environments[], drift[],
|
|
701
|
-
marks[], ignored[]}`. Each environment carries its applied migrations, the
|
|
702
|
-
rest with their state, its gaps and notes, dated by the report's
|
|
703
|
-
`generatedAt`. Each mark is one object a drift file names (`changed` or
|
|
704
|
-
`missing`), dated by the file's mtime (drift JSON has no time of its own)
|
|
705
|
-
and named by its file.
|
|
706
|
-
- Every file is checked against SQL Yodeler's schemas: from
|
|
707
|
-
`@intentius/sql-yodeler/schemas/` when the package resolves beside the
|
|
708
|
-
served project or behold, otherwise from the copy pinned in
|
|
709
|
-
`src/sql-yodeler-schemas/` (sql-yodeler 19ebbff). A file that fails is a
|
|
710
|
-
422 with `code: "yodel-report"` naming the file, and nothing is drawn.
|
|
711
|
-
Update the pinned copy by copying the three files from sql-yodeler's
|
|
712
|
-
`schemas/` and changing `PINNED_COMMIT`.
|
|
713
|
-
- The page (`web/yodel-report.js`) joins a mark to the card whose id is the
|
|
714
|
-
object's name, or ends in `/<name>` in a composed estate, and draws a
|
|
715
|
-
corner tag with its age; never a fill. Objects no card is are listed in
|
|
716
|
-
the SQL Yodeler tab, which also holds the environments and gaps.
|
|
717
|
-
- `audit[]` (#537) carries the report's audit entries with the report file
|
|
718
|
-
they came from. The tab lists them under their environment, each dated by
|
|
719
|
-
its own `at` and named by its source (a ledger's op and gate, or a history
|
|
720
|
-
table's row and run).
|
|
721
|
-
- `behold export --yodel-report <file|dir>` (#537) captures `/api/yodel-report`
|
|
722
|
-
as a snapshot, and a refusal fails the export, as `--terragucci` does. A
|
|
723
|
-
SQL Yodeler repo's export also captures `/api/sql-yodeler/lifecycle` and
|
|
724
|
-
`/api/lifecycle/history`, so the Pipeline lane draws in static mode,
|
|
725
|
-
without its Read again button.
|
|
726
|
-
|
|
727
|
-
## A SQL Yodeler project: kinds and a lifecycle lane (#524)
|
|
728
|
-
|
|
729
|
-
A SQL Yodeler project is a chant project with `lexicons: ["sql"]` and a
|
|
730
|
-
`yodel.config.ts` (#517's detection, `productRepo` in src/terragucci-repo.ts).
|
|
731
|
-
Its graph draws from `chant graph` as any project's does. src/sql-kinds.ts
|
|
732
|
-
registers a pinhole pack for the `sql` lexicon: a line glyph per
|
|
733
|
-
`Postgres::*` and `ClickHouse::*` kind, and cards that lead with the kind in
|
|
734
|
-
words and the qualified name. A `REFERENCES ${other}` foreign key is a `ref`
|
|
735
|
-
edge; e2e/fixtures/sql-yodeler-fk holds a project with one, and
|
|
736
|
-
src/sql-yodeler-lane.test.ts graphs it. `@intentius/chant-lexicon-sql` is a
|
|
737
|
-
devDependency for that test; from 0.124.13 its lint rules use chant's own
|
|
738
|
-
TypeScript (chant#3864), so they run beside behold's TypeScript 7.
|
|
739
|
-
|
|
740
|
-
`GET /api/sql-yodeler/lifecycle[?fresh=1]` (src/sql-yodeler-lane.ts) reads
|
|
741
|
-
`chant/lifecycle` with `readLifecycle` and a spec per op, sharing one fetch:
|
|
742
|
-
|
|
743
|
-
- `opWavesLane("yodel-apply")` for the apply pipeline's
|
|
744
|
-
`yodel-apply-wave-<k>` gates, with the mode at base from `yodel-waves.json`
|
|
745
|
-
when every wave names the same `approval`. When they differ (#537) the
|
|
746
|
-
rule carries `waves[]` and each wave is decided under its own mode
|
|
747
|
-
(`waveRule`; a gate decided so carries `mode`). Under `pr-review` a gate not
|
|
748
|
-
yet approved carries `headPlans[]`: the heads whose
|
|
749
|
-
`_wave-plans/yodel-apply/<head>.json` (chant's HeadPlans, newest 50 read)
|
|
750
|
-
name its digest.
|
|
751
|
-
- `migrateOpLane(env)` for each `migrate-<env>` op that `ops/` or
|
|
752
|
-
`yodel-waves.json` names: its one gate `approve-migrate-<env>`, drawn as
|
|
753
|
-
wave 1 of that op.
|
|
754
|
-
|
|
755
|
-
The answer is the lane's header (branch, via, commit, rule, note) with
|
|
756
|
-
`environments[]` in the order of applies (`yodel-waves.json`, then any
|
|
757
|
-
environment only `ops/` names), each with its wave (`k`, targets, gate
|
|
758
|
-
policy, approval) and `gates[]` (`kind: "wave" | "migrate"`, the GateEntry
|
|
759
|
-
of #520/#521). A waiting gate carries `npx yodel approve <env> --plan
|
|
760
|
-
<digest>` (`--sign` under sealed). Waves the spec does not name go in
|
|
761
|
-
`unplaced`. A served directory that is not SQL Yodeler gets 404 with
|
|
762
|
-
`code: "sql-yodeler"`. The page's Pipeline tab (`web/sql-yodeler-lane.js`)
|
|
763
|
-
draws it, with `/api/lifecycle/history` (#522) below. Reads are reused 30s.
|
|
764
|
-
|
|
765
|
-
A SQL Yodeler project that is a chant workspace member (#537) keeps its
|
|
766
|
-
records under `_members/<member>/` on `chant/lifecycle`. src/member-ledger.ts
|
|
767
|
-
asks chant's `resolveMemberLedger` (`@intentius/chant/lifecycle/member-ledger`)
|
|
768
|
-
for the prefix; the lane passes it as `GateLaneSpec.ledgerPrefix`, which
|
|
769
|
-
`readLifecycle` puts before every branch path, and `/api/lifecycle/releases`
|
|
770
|
-
hands it to chant's `listReleaseEnvironments` and `readReleaseLedger` as
|
|
771
|
-
`ledgerPrefix` (chant#3865), which list and read the environments under it. Both answers then carry
|
|
772
|
-
`member: { members, prefix, error? }`, and `yodel-waves.json` at base is read
|
|
773
|
-
in the project's own directory.
|
|
774
|
-
|
|
775
|
-
## Getting a server
|
|
776
|
-
|
|
777
|
-
```sh
|
|
778
|
-
npx @intentius/behold serve <chant-project-dir> --port 4600 # or: preview / demo / doctor
|
|
779
|
-
```
|
|
780
|
-
|
|
781
|
-
`behold demo` needs no project at all — it copies the bundled example and serves
|
|
782
|
-
it against a local emulator (Docker). A directory that is not a chant project
|
|
783
|
-
gets a structured `{code: "no-project"}` error from `/api/graph`, not a blank
|
|
784
|
-
graph.
|
|
785
|
-
|
|
786
|
-
In a checkout, `behold demo --list` prints a second block under the bundled
|
|
787
|
-
one: the eleven workbench entries from `workbench.json` (this repo's own
|
|
788
|
-
catalog of the internal estates behold is developed against), the same
|
|
789
|
-
`behold demo <entry>` load, `just example name="<entry>"` to serve one, and
|
|
790
|
-
"The workbench catalog" below for what each is and what it boots.
|
|
791
|
-
|
|
792
|
-
A running server offers the same catalog over HTTP (#268): `GET /api/demos`
|
|
793
|
-
lists every bundled demo with `{name, description, requires, satisfiable,
|
|
794
|
-
reason?, fetches, repo?, target, loaded}` — `satisfiable` is doctor's PATH probe
|
|
795
|
-
for that demo's `requires`, and `fetches` marks the one kind of entry that
|
|
796
|
-
reaches the network (a git demo is cloned). `POST /api/demos/open` with
|
|
797
|
-
`{name}` loads it and switches the served project to it: the same copy/clone →
|
|
798
|
-
install → setup the CLI runs, then an in-place switch. It takes a catalog
|
|
799
|
-
**name** and never a path, so it cannot be aimed outside the install; it is
|
|
800
|
-
preview-locked, and one load runs at a time (409 otherwise).
|
|
801
|
-
|
|
802
|
-
## The read loop
|
|
803
|
-
|
|
804
|
-
0. **discover.** GET `/api` lists every route with a one-line description,
|
|
805
|
-
plus the server's version and a link back to this guide. Before the server
|
|
806
|
-
exists (or when a route answers with an error you'd have to guess at), run
|
|
807
|
-
`npx @intentius/behold doctor <dir> --json`: a read-only diagnosis of the
|
|
808
|
-
project's kind, its own chant install and version, declared lexicons, the
|
|
809
|
-
envs the picker will infer, the bound kube context versus the ambient one,
|
|
810
|
-
substrate readiness and committed Ops. Each check is
|
|
811
|
-
`{name, status: pass|warn|fail, detail, fix}`; the process exits non-zero
|
|
812
|
-
iff something failed. It starts no server and changes nothing.
|
|
813
|
-
1. **observe.** GET `/api/graph` (JSON: `{ ir, svg, meta }`). The mixed graph
|
|
814
|
-
of the project, every node with `id`/`kind`/`lexicon`/`attrs`/`sourceLoc`. Drift
|
|
815
|
-
status, when present, is `attrs._status` (`good`=managed, `warn`=foreign,
|
|
816
|
-
`accent`=pending, `neutral`=unobserved, `runtime`=runtime child). With
|
|
817
|
-
`?env=`, `/api/overlay` is the live entity overlay; `/api/diff?env=` slices
|
|
818
|
-
per-node observed state, drift and field ownership; `/api/reconcile?env=`
|
|
819
|
-
summarizes the pending change set; `/api/substrates` reports substrate
|
|
820
|
-
readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`run`/`pr`,
|
|
821
|
-
and `view` when an agent moves the tab (below).
|
|
822
|
-
With `?components=1&env=`, each component node carries `_liveStatus` (the
|
|
823
|
-
`chant components status` verdict) and, when the release ledger recorded
|
|
824
|
-
one, `_release` — `{runId, forge, originSource, url?, gitSha, digest,
|
|
825
|
-
timestamp, actor, approver?}` (#165). `url` is present only when the record
|
|
826
|
-
itself carries an address (chant#2045); `originSource: "inferred"` means
|
|
827
|
-
behold read the id's spelling and nothing more, and a `forge: "unknown"` id
|
|
828
|
-
is never resolved to a link on behold's guess.
|
|
829
|
-
`?stacks=1` is the apply-order lens (#426): the cross-stack ordering chant
|
|
830
|
-
computes at synthesis and prints from `chant graph --stacks --json`, which
|
|
831
|
-
behold read nowhere and re-derived a subset of. One card per stack (a
|
|
832
|
-
lexicon partition), one box per wave, edges consumer to producer;
|
|
833
|
-
`meta.stacks` carries `order`, `waves` and `cycles` verbatim. It is
|
|
834
|
-
source-only (no env, no credentials, no substrate) and asks chant for the
|
|
835
|
-
project ROOT, not `graphPath`, because `runStackGraph` only sees
|
|
836
|
-
`ops/*.op.ts` from there (measured: `example-writes` answers `[aws,
|
|
837
|
-
temporal]` from `.` and `[aws]` from `src`). Single project only: an estate
|
|
838
|
-
is refused with `422 stacks-estate`, since `composeStacks` pools members
|
|
839
|
-
into one bucket per bare lexicon name and two members' `aws` stacks are not
|
|
840
|
-
one stack. A cycle is NOT a refusal — chant exits 1 with valid JSON and the
|
|
841
|
-
entangled stacks absent from `order`/`waves`, so they are drawn unwaved in
|
|
842
|
-
their own box and the note says so; nothing invents a wave number for a
|
|
843
|
-
stack chant could not order. `/api/project`'s `stacksCapable` gates the
|
|
844
|
-
stop. Note that `chant graph --stacks --json` is malformed today on two of
|
|
845
|
-
chant's own examples (an edge with no `from`, a `null` in `order` and in a
|
|
846
|
-
wave); `sanitizeStackGraph` treats `nodes` as the roster and drops anything
|
|
847
|
-
named nowhere else.
|
|
848
|
-
`?ops=1` is the ops lens: the project's declared Ops as a phase track, read
|
|
849
|
-
from each emitted `dist/ops/<name>/op.json`, with the current run painted
|
|
850
|
-
over it (`meta.run`, `meta.gate`); `/api/ops/<name>/status` reads that Op's
|
|
851
|
-
newest run status and pending gate (`chant run status <name>`; chant
|
|
852
|
-
removed `--temporal`, #459). A
|
|
853
|
-
`ConvergeOp` also gets one card per rule from its `convergeTick` step's
|
|
854
|
-
`args.rules` (`attrs._step: "rule"`), carrying `when` (chant's JSON predicate,
|
|
855
|
-
rendered as the condition it states), `then`, and the `why` chant requires of
|
|
856
|
-
every rule, verbatim. `then: run(<op>)` is an edge to that Op's first step
|
|
857
|
-
when the Op is in the rendered set, and `attrs.dangling` when it isn't.
|
|
858
|
-
`meta.operator` on that same lens names the ConvergeOps the project declares
|
|
859
|
-
(chant's own `searchAttributes.Converge === "true"`, read from op.json, no
|
|
860
|
-
subprocess), and `/api/operator/status` fills the strip in from
|
|
861
|
-
`chant operator status --json`.
|
|
862
|
-
2. **focus.** Narrow with chant graph options as query params: `?detail=0..3`,
|
|
863
|
-
`?components=1`, `?logical=1`, `?lens=blast:<id>&down=1`, `?lens=lexicon:aws`,
|
|
864
|
-
`?env=`, `?stack=`, `?tier=`, `?target=`, `?collapse=1`.
|
|
865
|
-
`?collapse=1` (#393) shuts every member box holding more than 40 cards: the
|
|
866
|
-
box is drawn as ONE card carrying the count it was badged with (`301
|
|
867
|
-
resources · 84 bound · 85 unowned · 132 neutral`, in the estate's own
|
|
868
|
-
words), ids namespaced `box:<member>`, and the returned IR is the collapsed
|
|
869
|
-
one so every count and note speaks about the picture on screen — except its
|
|
870
|
-
NOTE, which is written about the expanded estate plus one collapse clause
|
|
871
|
-
(#396): a shut box hides what the estate references rather than changing it.
|
|
872
|
-
⌘K → "Collapse large boxes" / "Expand all". Below the limit it changes
|
|
873
|
-
nothing. **The toggle costs no live read** (#396): a member's overlay
|
|
874
|
-
document is cached under its source stamp and the read's own options, the
|
|
875
|
-
same key half `memberIr` and #404's plan cache use, so collapse and expand
|
|
876
|
-
are re-renders of a document behold already holds. `src/overlay-ir.ts` is
|
|
877
|
-
that cache and its header is the stated exception to src/member-ir.ts's
|
|
878
|
-
"a live read is never cached"; it names everything that drops an entry —
|
|
879
|
-
`POST /api/refresh` ("Re-check live"), `GET /api/overlay?plan=1`
|
|
880
|
-
("Re-check live with plan", which re-checks both halves), the capture that
|
|
881
|
-
ends an Op run, and the member's source moving. A change made to the account
|
|
882
|
-
by something that is not behold is what the re-check rows are for.
|
|
883
|
-
3. **inspect.** A node's `sourceLoc.file` is the typed source that declared it;
|
|
884
|
-
edit there to change the estate (chant is the source of truth, not behold).
|
|
885
|
-
4. **find.** ⌘K also takes an ADDRESS (#393). Two characters in, the palette
|
|
886
|
-
matches the ids and addresses of the graph the page is currently showing and
|
|
887
|
-
offers up to twelve `node: <address>` rows, prefix matches first, each with
|
|
888
|
-
its member and kind on a second line (two members of one estate can declare
|
|
889
|
-
the same address). Enter takes the same path a click on the card does (the
|
|
890
|
-
inspect pane and the highlight) and pans the graph onto it: `revealNode` in
|
|
891
|
-
web/app.js drives the same viewBox the wheel, the drag and "⤢ fit" drive.
|
|
892
|
-
Nothing here fetches, so it works in a static export too.
|
|
893
|
-
|
|
894
|
-
### The picture arrives in pieces (#422)
|
|
895
|
-
|
|
896
|
-
`GET /api/overlay?progressive=1` answers at once with the estate composed from
|
|
897
|
-
every member's SOURCE, each node carrying `attrs._pendingRead`, and then
|
|
898
|
-
broadcasts one `member` SSE frame per member as its own live read settles —
|
|
899
|
-
`{member, statuses: {<composed id>: <status>}, unobserved?}`, or `{error}` if
|
|
900
|
-
the pass itself failed. `meta.mode` is `progressive` and `meta.pending` names
|
|
901
|
-
the members not yet read.
|
|
902
|
-
|
|
903
|
-
**Opt-in, and never the default.** `/api/overlay` without the flag is byte-for-
|
|
904
|
-
byte what it was: the blocking, complete live answer this guide's read loop
|
|
905
|
-
names, which is what an agent GETs and what `src/export.ts` captures into a
|
|
906
|
-
static bundle. A route that answered with members it had not read would hand an
|
|
907
|
-
agent a half-picture it could not know was half, and freeze a bundle with
|
|
908
|
-
members permanently still-reading.
|
|
909
|
-
|
|
910
|
-
**Pending is a third claim.** `_unobserved` is "behold looked and could not
|
|
911
|
-
see"; `neutral` is "the plan did not mention it"; `_pendingRead` is "the read
|
|
912
|
-
has not finished". It rides its own attr rather than a fifth `_status` because
|
|
913
|
-
a fifth `_status` is not paintable — pinhole's painter takes a closed set and
|
|
914
|
-
falls back to `neutral` for anything else, which is `unobserved`, the exact
|
|
915
|
-
wrong answer. The SPA draws it dashed and dimmed, never filled: the fill is the
|
|
916
|
-
status channel and a pending card has no status yet.
|
|
917
|
-
|
|
918
|
-
No live result is cached to build the first picture and none is reused. A
|
|
919
|
-
pending member becomes a real one only when its own read completes, and the
|
|
920
|
-
live pass a progressive request starts is the same one per member under the
|
|
921
|
-
same budget: a progressive load costs the estate no extra spawn.
|
|
922
|
-
|
|
923
|
-
### Drift, streamed card by card (#998)
|
|
924
|
-
|
|
925
|
-
`POST /api/workspace/drift/stream {member, addresses?}` (palette: **"Stream
|
|
926
|
-
drift card by card: <member>"**) runs `chant workspace drift --member <name>
|
|
927
|
-
--stream` at the workspace root and narrates it as `drift` frames on
|
|
928
|
-
`/api/events` (src/drift-stream.ts). The stream is chant's drift record in
|
|
929
|
-
NDJSON (chant#4451): one `drift-start` with the addresses it expects, one
|
|
930
|
-
`drift-record` per instance as its read finishes, one `drift-settle`. Each
|
|
931
|
-
line is decoded in `streamDrift` (src/workspace-reader.ts) by
|
|
932
|
-
src/drift-line.ts, which uses chant's own `decodeDriftLine` from
|
|
933
|
-
`@intentius/chant/drift-record` (behold#1005) and narrows its line to what a
|
|
934
|
-
card reads, and each record frame repaints only its own card. The
|
|
935
|
-
start is refused below `DRIFT_STREAM_CHANT_FLOOR` (409, the floor's refusal,
|
|
936
|
-
nothing spawned), unless `BEHOLD_DRIFT_CHANT` names the chant to run.
|
|
937
|
-
|
|
938
|
-
- **Per resource on a choudoufu member.** choudoufu's single-resource path
|
|
939
|
-
(`live-plan -resource`, choudoufu#2245) plans one resource and writes its
|
|
940
|
-
records when that plan ends, and there is no whole-estate stream. So behold
|
|
941
|
-
asks once per resource block (`--resource <addr>`, instance keys dropped,
|
|
942
|
-
data sources left out), one after another, from the card addresses the page
|
|
943
|
-
sends; the cards change colour resource by resource. Any other member is
|
|
944
|
-
asked once without `--resource`.
|
|
945
|
-
- **Reading is not a status.** Between a start and its settle, an expected
|
|
946
|
-
card that has not reported is `data-drift-reading`: dimmed and dashed, its
|
|
947
|
-
fill and `_status` unchanged. Only a record sets `_status`.
|
|
948
|
-
- **Not reached.** At settle, every expected address no record answered
|
|
949
|
-
becomes `not-observed` with reason `not-reached` (chant's fold rule), sent
|
|
950
|
-
as a record frame before the settle frame. A read that fails or prints a
|
|
951
|
-
line that does not decode is a `failed` frame: its cards stop reading and
|
|
952
|
-
keep the colour they had. A read that never started stops the run.
|
|
953
|
-
- **Colour** is `toneFor(record)`, #995's `(status, read)` table
|
|
954
|
-
(src/drift-tone.ts, below). A status or read outside it is neutral, and the
|
|
955
|
-
card carries `data-drift-unknown` and says so in its tooltip.
|
|
956
|
-
- One run at a time (`409 drift-streaming`); `{stop: true}` stops it.
|
|
957
|
-
`BEHOLD_DRIFT_CHANT` names the chant the read runs, for a chant built
|
|
958
|
-
ahead of the release that adds `workspace drift --stream`, and for
|
|
959
|
-
`just e2e-streamed-drift`'s fake (e2e/fixtures/fake-chant-drift); the
|
|
960
|
-
floor, `DRIFT_STREAM_CHANT_FLOOR`, is checked only against the root's own
|
|
961
|
-
chant, so it does not apply then.
|
|
962
|
-
|
|
963
|
-
### Colour from the drift record (#995)
|
|
964
|
-
|
|
965
|
-
Every card's live colour is one fixed table over chant's drift record
|
|
966
|
-
(chant#4451), keyed on the record's `status` and the `read` that answered,
|
|
967
|
-
and on nothing else: `DRIFT_TONE_TABLE` and `toneFor` in src/drift-tone.ts.
|
|
968
|
-
No engine is named there, so a Pulumi member (path 2, chant#4453) colours
|
|
969
|
-
through the same cells as the rest. The read limits the claim: an
|
|
970
|
-
`ownership` read's `in-sync` is green and labelled "bound (ownership only)"
|
|
971
|
-
(#404), a `state` read's `recorded` is neutral, and a state read that says
|
|
972
|
-
`in-sync` or `drifted` (a record chant refuses) is neutral and labelled. An
|
|
973
|
-
unknown status or read is neutral and labelled unknown, never a guessed
|
|
974
|
-
colour.
|
|
975
|
-
|
|
976
|
-
- **The drift document.** `chant workspace drift --member <name> [--read
|
|
977
|
-
<read>] [--resource <addr>] [--env <env>]` prints one member's drift
|
|
978
|
-
document (contract 1, `drift: "v1"`), read by the member's own engine. It is
|
|
979
|
-
`read("drift", driftArgs(ask))` on the workspace reader, the sixth
|
|
980
|
-
`BEHOLD_READS` entry, held by chant's conformance suite when that suite
|
|
981
|
-
lists `drift`. `paintWorkspaceDrift` (src/drift-overlay.ts) reads it per
|
|
982
|
-
member and paints `_status`, `_drift: {status, read, label, reason?,
|
|
983
|
-
engineCode?, fellBackFrom?, unknown?}` and `_unobserved` on each card.
|
|
984
|
-
`/api/overlay` on a declared workspace whose chant meets
|
|
985
|
-
`DRIFT_RECORD_CHANT_FLOOR` (`CHANT_RELEASE.version`, the release not cut yet) does this on
|
|
986
|
-
every read for the members with no live half of their own (`terraform`,
|
|
987
|
-
`pulumi`), and with `?drift=1` for `chant` and `choudoufu` members too, at
|
|
988
|
-
the cost of a second live read. `meta.driftRecord` lists each member's
|
|
989
|
-
painted and unplaced records and chant's error. With `?plan=1` a terraform
|
|
990
|
-
or choudoufu member is asked `--read plan`.
|
|
991
|
-
- **The reads behold still makes itself colour through the same table.** A
|
|
992
|
-
choudoufu member's `live-plan`/`live-ls` paint (src/choudoufu-live.ts
|
|
993
|
-
`verdictFor`) gives each address the status chant's adapter gives it
|
|
994
|
-
(`bound` in-sync, `unowned`/`adoptable` unclaimed, `ABSENT` pending, every
|
|
995
|
-
other omission not-observed, a listed item nothing declares undeclared) and
|
|
996
|
-
takes the table's tone, read `ownership`. A component status row's
|
|
997
|
-
reconciliation fallback (src/component-status.ts `reconciliationStatus`) is
|
|
998
|
-
chant's `componentStatusDriftRecords` mapping, read `live-read`.
|
|
999
|
-
- **UNOWNED, settled with chant.** An `UNOWNED` omission with no `unowned[]`
|
|
1000
|
-
row is `not-observed` (`read-failed`, `engineCode: "UNOWNED"`), as chant C1
|
|
1001
|
-
decided: neutral, not `warn`. With its `unowned[]` row it is `unclaimed`
|
|
1002
|
-
and `warn`, as before.
|
|
1003
|
-
- **Which read answered a root** is the IR's `rootReads` (chant#4452):
|
|
1004
|
-
`terraform.roots.<root>` with `depth`, `fellBackTo` and `reason`
|
|
1005
|
-
(src/terraform-plan.ts `planRootAnswers`, src/choudoufu-chant-read.ts
|
|
1006
|
-
`rootAnswerOf`). chant's note text is not parsed. A chant that puts no
|
|
1007
|
-
`rootReads` on the IR reports no root: a stock root's cards carry no plan
|
|
1008
|
-
answer, and a choudoufu re-check reads as live-plan alone.
|
|
1009
|
-
- **choudoufu card ids and chant node ids (the B3 follow-up).** behold keeps
|
|
1010
|
-
a choudoufu member's card ids, the roster's `<member>/<address>`, because
|
|
1011
|
-
saved layouts are keyed on them, while chant names the same blocks
|
|
1012
|
-
`<member>/<root>/<block path>`. One alias table, built from chant's graph
|
|
1013
|
-
of the member (`choudoufuCardAliases`, src/drift-overlay.ts), maps a chant
|
|
1014
|
-
node and an instance address onto the card (`cardIdFor`), and both the
|
|
1015
|
-
change-set overlay (src/change-set-overlay.ts) and drift records use it. A
|
|
1016
|
-
node the table does not know lands on no card and is listed.
|
|
1017
|
-
|
|
1018
|
-
### What a read cost (#420, #421)
|
|
1019
|
-
|
|
1020
|
-
`GET /api/doctor` serves `diagnose()`, the same report `behold doctor` prints,
|
|
1021
|
-
which until #421 only the CLI could ask for — with two extra blocks on it:
|
|
1022
|
-
|
|
1023
|
-
- `reads`, the ledger from `src/read-stats.ts`. Every scheduled chant read
|
|
1024
|
-
passes through `ReadScheduler`, so each one is filed there with its running
|
|
1025
|
-
time, its outcome, and which side of the source/live split it sits on. A bare
|
|
1026
|
-
`chant graph` is the member's own TypeScript evaluation; anything with
|
|
1027
|
-
`--live`/`--overlay`, and every other verb `isScheduledRead` allows, reaches
|
|
1028
|
-
past it. `shared` counts subscribers handed an in-flight spawn, work not
|
|
1029
|
-
done, never a run.
|
|
1030
|
-
- `cache`, `memberIrCacheStats()`.
|
|
1031
|
-
|
|
1032
|
-
`GET /api/doctor?reads=1` is the same two blocks WITHOUT the diagnosis, and it
|
|
1033
|
-
is what the SPA asks for. The split is the one #421 states: the full report is
|
|
1034
|
-
for a person diagnosing and the panel line is for a person waiting. It is also a
|
|
1035
|
-
cost split too: `diagnose()` probes docker, gh, helm and k3d through
|
|
1036
|
-
src/substrates.ts, whose `probe` has no timeout and no kill, and the SPA asks
|
|
1037
|
-
after every load settles. A static export asks for neither; `refreshReadCost`
|
|
1038
|
-
returns on `staticMode` rather than relying on the bundle's own 404.
|
|
1039
|
-
|
|
1040
|
-
`reads.inFlight` is `{running, queued}` off the scheduler itself. The ledger
|
|
1041
|
-
cannot answer it: a read still in flight has finished nothing, so it has filed
|
|
1042
|
-
nothing. "What is queued now" is what someone watching a slow read wants.
|
|
1043
|
-
|
|
1044
|
-
Three things to know before reading a number off it. `queuedMs` is contention
|
|
1045
|
-
**in the scheduler** (the HTTP-versus-poll-versus-capture competition #367
|
|
1046
|
-
bounded) rather than the whole of what a member waits: the estate fan-out bounds
|
|
1047
|
-
upstream through `mapPool` (src/estate.ts), so a three-member estate measured
|
|
1048
|
-
3033/3035/2218 ms of running time with `queuedMs` 0 against 5.2 s of wall clock.
|
|
1049
|
-
The gap is the upstream wait and #422 is where it gets measured.
|
|
1050
|
-
|
|
1051
|
-
`reads.unmeasured` counts the served members the ledger is BLIND to, and the
|
|
1052
|
-
panel line prints it rather than quietly excluding them. Only reads that pass
|
|
1053
|
-
`ReadScheduler` are filed, which is every chant read and therefore a terraform
|
|
1054
|
-
member too (its `via.read` shells `chant graph`, src/terraform-member.ts). A
|
|
1055
|
-
choudoufu member spawns its own binary through its own helper and is filed
|
|
1056
|
-
nowhere, so on a chant+choudoufu estate the slowest card may be one that never
|
|
1057
|
-
reached `recent` — "slowest 3s · 1 not measured" is the honest form of that, and
|
|
1058
|
-
an unqualified "slowest 3s" is not.
|
|
1059
|
-
|
|
1060
|
-
And preview mode keeps the totals but drops `recent`, whose samples are keyed by
|
|
1061
|
-
member directory.
|
|
1062
|
-
|
|
1063
|
-
The SPA asks once after each load settles and shows the answer on the loading
|
|
1064
|
-
scrim the *next* time one goes up (`web/read-cost.js`, `#loading-cost`): the
|
|
1065
|
-
slowest recent member, because an estate read finishes when its last member
|
|
1066
|
-
does, so a sum would report a number nobody waits for.
|
|
1067
|
-
|
|
1068
|
-
### The behaviour overlay (#398, M1 of #397)
|
|
1069
|
-
|
|
1070
|
-
What the estate costs and where it runs out of headroom, on `/api/overlay`
|
|
1071
|
-
only. **behold never calls a behavioural engine**, never holds its key, and
|
|
1072
|
-
produces no figure of its own — it renders what a chant lexicon handed it, the
|
|
1073
|
-
way it already renders drift and the carve score. The one arithmetic it does is
|
|
1074
|
-
addition, and the result is named `sum` so nobody can read it as a bill.
|
|
1075
|
-
|
|
1076
|
-
The contract's source of truth is the comment titled "The behaviour block,
|
|
1077
|
-
proposed" on INTENTIUS/behold#398 (chant#2356 is the writing half). Field names
|
|
1078
|
-
here match it exactly; `src/behaviour.ts` is the implementation and the
|
|
1079
|
-
validator.
|
|
1080
|
-
|
|
1081
|
-
Per entity, `attrs._behaviour` on the overlay IR node — the channel `_status`,
|
|
1082
|
-
`_release` and `_carve` already ride: `{at: {traffic}, cost: {perHour,
|
|
1083
|
-
currency}, headroom: {cpu?, latency?}, errorRate, resilience: {failure, verdict:
|
|
1084
|
-
survives|degrades|fails, note?}, rightSize?: {suggestion, reason?}, provenance:
|
|
1085
|
-
{engine, version, tolerance, basis: modeled|validated}}`. An entity nothing
|
|
1086
|
-
priced carries **no `_behaviour` key at all**, never a zeroed block, and a
|
|
1087
|
-
missing headroom axis is absent rather than 0. The block stays on the node and
|
|
1088
|
-
there is deliberately no top-level `behaviour: {}` map: the SPA already walks
|
|
1089
|
-
`ir.nodes` reading `attrs._status`, and a colour-by-cost mode is that same walk,
|
|
1090
|
-
with no join.
|
|
1091
|
-
|
|
1092
|
-
Two sources, in this order:
|
|
1093
|
-
|
|
1094
|
-
1. `attrs._behaviour` on the nodes, as `chant graph --live --overlay` painted
|
|
1095
|
-
them, with `meta._behaviour` beside them for the graph-level half.
|
|
1096
|
-
2. `behaviour.<env>.json` at a member's root — `{meta, entities: {<address>:
|
|
1097
|
-
block}}` — read **only** when no node of that member carries the attr and
|
|
1098
|
-
the member's read carried no `meta._behaviour` either (#402), and
|
|
1099
|
-
**only on the overlay** (`/api/graph` is the source graph; a prediction
|
|
1100
|
-
about a live account has no business on it). The file's keys are the
|
|
1101
|
-
member's own addresses; behold prefixes them to reach the composed id
|
|
1102
|
-
`<member>/<address>`.
|
|
1103
|
-
|
|
1104
|
-
`meta.behaviour` carries the graph-level half: `engine`, `version`, `at`, the
|
|
1105
|
-
engine's own `total` when it stated one, else behold's `sum` and the same per
|
|
1106
|
-
box under `boxes[<boxKey>]` (`{perHour, currency, priced, unpriced}`). Mixed
|
|
1107
|
-
currencies produce no sum and a diagnostic — behold converts no currency. A
|
|
1108
|
-
malformed block is dropped whole with its reason in `diagnostics`, never
|
|
1109
|
-
half-rendered. A member with neither source gets `{absent: "…"}` naming both
|
|
1110
|
-
places behold looked; that is an absence, not a refusal, because nothing was
|
|
1111
|
-
configured.
|
|
1112
|
-
|
|
1113
|
-
`meta.behaviour.refusal` is `{reason, remedy}` in the lexicon's own words,
|
|
1114
|
-
printed as it came, and it is present **instead of** everything above: a
|
|
1115
|
-
refusal emits no entity block at all and strips any that had arrived. The drift
|
|
1116
|
-
overlay is untouched either way: nothing in this pass reads or writes
|
|
1117
|
-
`_status`. `?logical=1` projects a different picture and carries no behaviour
|
|
1118
|
-
block in M1.
|
|
1119
|
-
|
|
1120
|
-
### Live versus declared (#402, M5)
|
|
1121
|
-
|
|
1122
|
-
With a traffic level, `/api/overlay` predicts each member twice and carries
|
|
1123
|
-
both figures and their difference. The level is `?traffic=` on the request,
|
|
1124
|
-
else the per-user settings' `{"behaviour": {"traffic": "100 rps, p50"}}` (src/user-settings.ts, #470), else none;
|
|
1125
|
-
with none nothing is asked for and the payload is exactly M1's. behold never
|
|
1126
|
-
defaults a level, because every figure is *at* one.
|
|
1127
|
-
|
|
1128
|
-
`meta.behaviour` gains `live`, `declared` (each `{perHour, currency, basis}`,
|
|
1129
|
-
where `basis` is `total` for a figure the engine stated and `sum` for behold
|
|
1130
|
-
adding the engine's per-entity figures) and `delta` (`{perHour, currency}`,
|
|
1131
|
-
live minus declared), plus the same three per member under `members[<name>]`.
|
|
1132
|
-
A delta is only ever like with like: one currency, and two totals or two sums.
|
|
1133
|
-
Anything else yields no delta and a line in `diagnostics` saying why. A node
|
|
1134
|
-
also carries the file's block under `attrs._behaviourDeclared`, including a
|
|
1135
|
-
node the account no longer holds, which has no `_behaviour` at all.
|
|
1136
|
-
|
|
1137
|
-
Who reads what is `src/behaviour-delta.ts`'s header. A chant member's live
|
|
1138
|
-
half is its own overlay read with `--traffic` added (sent only to a chant at
|
|
1139
|
-
0.75.0 or newer; an older one rejects the flag). A choudoufu member is not
|
|
1140
|
-
read by chant, so behold predicts it through a generated reader project with
|
|
1141
|
-
`binary: "choudoufu"` (the Terraform member's scratch project, under
|
|
1142
|
-
`behold-chdf-*`), which needs the optional terraform lexicon. A terraform
|
|
1143
|
-
member has no live half and so no delta.
|
|
1144
|
-
|
|
1145
|
-
The declared half goes through `memberIr` and is cached under the member's
|
|
1146
|
-
source stamp plus the traffic level. The live half goes through `overlayIr`
|
|
1147
|
-
and is dropped by whatever drops the overlay. With a level set, the
|
|
1148
|
-
`behaviour.<env>.json` documents are not read at all: a fixture's figures
|
|
1149
|
-
beside a real prediction would be two answers to one question.
|
|
1150
|
-
|
|
1151
|
-
`/api/graph?traffic=` (or the config default) paints the declared side alone
|
|
1152
|
-
as `attrs._behaviour` with `meta.behaviour.declared`. The file is the only
|
|
1153
|
-
estate that route has, so it carries no live half and no delta.
|
|
1154
|
-
|
|
1155
|
-
### Colour by drift, cost or headroom (#399, M2)
|
|
1156
|
-
|
|
1157
|
-
The SPA colours the graph by one of three modes. The mode is **client-side
|
|
1158
|
-
state** — `web/app.js`'s `colourMode`, persisted under `behold.colourBy` the way
|
|
1159
|
-
the theme is. It is deliberately NOT in `LENS_PARAMS`/`canonicalKey`: a lens
|
|
1160
|
-
param means "a different snapshot comes back", and a mode change changes no
|
|
1161
|
-
fetch at all. The block is already on every priced card, so a switch is a
|
|
1162
|
-
repaint of the SVG on screen.
|
|
1163
|
-
|
|
1164
|
-
`drift` keeps the categorical fill and #393's vocabulary legend, unchanged. The
|
|
1165
|
-
two behaviour modes replace the card's FILL only, so the drift bar underneath
|
|
1166
|
-
keeps saying what chant observed. `cost` is a sequential scale over
|
|
1167
|
-
`cost.perHour` between the estate's own min and max; `headroom` is absolute over
|
|
1168
|
-
0..1 and reads **the lower of the axes present**. An entity with no block draws
|
|
1169
|
-
the drift overlay's neutral (`pinTokensFor().neutralFill`) and is marked
|
|
1170
|
-
`data-unpriced`, never the zero end of the scale — "nothing priced this" and
|
|
1171
|
-
"this is free" are opposite claims.
|
|
1172
|
-
|
|
1173
|
-
Both ramps are derived from the active palette (`rampFor` in
|
|
1174
|
-
`web/behaviour-scale.js`), the way #229 derives the chrome: cost is a single hue
|
|
1175
|
-
off the accent walked in lightness away from the background — expensive is not a
|
|
1176
|
-
verdict behold gets to paint, and headroom rides the three status hues the
|
|
1177
|
-
drift overlay already anchors, degraded → foreign → managed.
|
|
1178
|
-
|
|
1179
|
-
One legend per mode, in the Model tab. The Scope tab carries a totals row per
|
|
1180
|
-
box and per estate for the active mode: `cost` quotes `meta.behaviour.boxes[key]`
|
|
1181
|
-
and `.sum`, or `meta.behaviour.total` when the ENGINE stated one (labelled
|
|
1182
|
-
"engine total"); `headroom` has no server-side aggregate, since no engine states one —
|
|
1183
|
-
so the SPA takes the scope's min and median itself and the row says "computed".
|
|
1184
|
-
Every row carries `n priced · m unpriced`. In drift mode there is no row.
|
|
1185
|
-
|
|
1186
|
-
Everything either mode decides is pure in `web/behaviour-scale.js`, with
|
|
1187
|
-
`web/behaviour-scale.test.js` beside it; the SPA owns the fetches and the SVG.
|
|
1188
|
-
|
|
1189
|
-
### Provenance on every figure, and the refusal (#401, M4)
|
|
1190
|
-
|
|
1191
|
-
Every figure the SPA shows, the totals rows, the legend, and the inspect pane's
|
|
1192
|
-
`behaviour` section — carries `{engine} {version} · {tolerance} · {basis}`
|
|
1193
|
-
beside it, never once per page. `modeled` is spelled out on hover as "modeled,
|
|
1194
|
-
not billed": #397's one prohibition is a prediction presented as a bill, and the
|
|
1195
|
-
badge is where that is prevented. Provenance is per ENTITY in #398's contract, so
|
|
1196
|
-
a badge over a set (a box, the estate) says `mixed` on any field the set
|
|
1197
|
-
disagrees on rather than picking one.
|
|
1198
|
-
|
|
1199
|
-
`meta.behaviour.refusal` disables both behaviour modes in the View tab and in
|
|
1200
|
-
⌘K (visibly, with the lexicon's reason and remedy as their tooltip) and prints
|
|
1201
|
-
those words verbatim where the legend would be. The drift overlay keeps
|
|
1202
|
-
rendering; it never depended on an engine. `meta.behaviour.absent` disables the
|
|
1203
|
-
same two modes with the absent line as their tooltip and prints **nothing**:
|
|
1204
|
-
nothing was configured, so nothing refused. `meta.behaviour.diagnostics` render
|
|
1205
|
-
in the Model tab under the legend.
|
|
1206
|
-
|
|
1207
|
-
## The carve loop (Terraform → chant, #230)
|
|
1208
|
-
|
|
1209
|
-
`behold carve <report.json>` serves a `chant carve advise --json` peelability
|
|
1210
|
-
report instead of a chant project. Same SPA, same `/api/graph` shape; `attrs.
|
|
1211
|
-
_status` carries the band (`good` = carve now, `warn` = has boundary work,
|
|
1212
|
-
`neutral` = leave in Terraform) and `attrs` carries the score arithmetic
|
|
1213
|
-
(`score`, `arithmetic`, `inbound`, `outbound`, `tier`, `mapsTo`).
|
|
1214
|
-
`GET /api/carve` returns the raw report verbatim.
|
|
1215
|
-
|
|
1216
|
-
To move a resource: confirm its band on `/api/carve`, then run chant's own
|
|
1217
|
-
`carve emit --state` and `carve bridge` in the project. `terraform state rm` and
|
|
1218
|
-
applying the generated survivor rewrites stay a human gate — behold has no
|
|
1219
|
-
endpoint that writes Terraform, and adding one would break the invariant below.
|
|
1220
|
-
|
|
1221
|
-
### Carve state, from chant's manifests (#230 M3)
|
|
1222
|
-
|
|
1223
|
-
chant ≥ 0.52.2 writes `<address>.carve.json` into `carve emit --output`; `carve
|
|
1224
|
-
bridge` and `carve apply` add their own records to the same file. behold reads
|
|
1225
|
-
those and never writes one, so the progression is on disk rather than in a
|
|
1226
|
-
session.
|
|
1227
|
-
|
|
1228
|
-
`GET /api/project`'s `carve.state` publishes it: `{manifests, progress:
|
|
1229
|
-
{applied, bridged, emitted, inFlight, total, label, detail}, states[], apply:
|
|
1230
|
-
{human, note}}`. Each entry carries `target`, `stage`
|
|
1231
|
-
(`emitted`/`bridged`/`applied`), `graduated`, `note` and a retypeable
|
|
1232
|
-
`applyCommand`. The same field appears on an ordinary `behold serve` whose
|
|
1233
|
-
project directory carries a carveout (no report and no demo needed) and is
|
|
1234
|
-
absent entirely when nothing has been carved.
|
|
1235
|
-
|
|
1236
|
-
In the graph, an `applied` address draws inside the chant member box (keeping
|
|
1237
|
-
its Terraform address as its node id) instead of in a band; `emitted` and
|
|
1238
|
-
`bridged` stay banded with `attrs._status: "accent"` and the stage in
|
|
1239
|
-
`attrs.carve`. Only `applied` means ownership moved.
|
|
1240
|
-
|
|
1241
|
-
**There is no `/api/carve/apply`.** `chant carve apply` graduates ownership;
|
|
1242
|
-
behold renders what the manifest records and echoes the command. Do not add the
|
|
1243
|
-
endpoint — src/carve-manifest.ts `APPLY_IS_HUMAN` is the statement of it, and
|
|
1244
|
-
src/carve-actions.ts and src/server.ts both carry the refusal where the route
|
|
1245
|
-
would go.
|
|
1246
|
-
|
|
1247
|
-
### The walkthrough (`behold demo carve`, #254)
|
|
1248
|
-
|
|
1249
|
-
`behold demo carve` copies a bundled mixed estate (a chant project
|
|
1250
|
-
beside a Terraform one), runs the advisor over the copy, and serves the same
|
|
1251
|
-
carve view plus a six-step stepper on the panel's Carve tab: advise → pick →
|
|
1252
|
-
emit → bridge → handoff → done.
|
|
1253
|
-
|
|
1254
|
-
Two of those steps are POST routes, and they exist **only** in a demo copy:
|
|
1255
|
-
|
|
1256
|
-
- `POST /api/carve/emit` — body `{select}`; runs `chant carve emit --state
|
|
1257
|
-
--select <addr> --output <copy>/app/carveout` and then `chant lint` on the
|
|
1258
|
-
result. Answers `{select, command, output, artifacts[], boundary, lint,
|
|
1259
|
-
buildCaveat}`.
|
|
1260
|
-
- `POST /api/carve/bridge` — body `{select}`; runs `chant carve bridge`
|
|
1261
|
-
**without** `--apply-rewrites`. Answers `{select, command, output, runbook,
|
|
1262
|
-
proposals[]}`.
|
|
1263
|
-
|
|
1264
|
-
`GET /api/project`'s `carve.demo` says whether they can act (`runnable`, plus a
|
|
1265
|
-
`reason` when not). `select` must name a resource the served report ranks;
|
|
1266
|
-
anything else is a 400. Outside a demo copy both routes answer 403
|
|
1267
|
-
`{code: "read-only"}`, and on an ordinary project serve they don't exist at all.
|
|
1268
|
-
|
|
1269
|
-
The gate the Emit step reports is `chant lint`, not `chant build` — chant#1637
|
|
1270
|
-
means `build` fails on the emitted bucket. Don't read a lint pass as a build
|
|
1271
|
-
pass.
|
|
1272
|
-
|
|
1273
|
-
There is still **no** endpoint that runs `terraform`. The handoff step hands
|
|
1274
|
-
back the runbook's commands as text.
|
|
1275
|
-
|
|
1276
|
-
## A chant search query: `q` and `GET /api/search` (#913)
|
|
1277
|
-
|
|
1278
|
-
`q` is a view key holding a query in chant's search grammar. In a link
|
|
1279
|
-
(`?q=...`), a `behold:view` message, `POST /api/view` and `behold shot`, it
|
|
1280
|
-
draws the same way: the cards chant matched are lit, the cards and edges on
|
|
1281
|
-
each match's path (chant's `paths[].hops`, and for a `cap:` term the hops
|
|
1282
|
-
in `paths[].because[]` too, INTENTIUS/chant#4375) are drawn at full weight, and the
|
|
1283
|
-
rest is dimmed, with nothing hidden. One line at the top left says the query,
|
|
1284
|
-
the match count and chant's provenance line. A query with no matches dims
|
|
1285
|
-
the whole graph, says "no matches" with the universe count, and outlines the
|
|
1286
|
-
near-misses `--explain` names (hover one for the term it fails). A live read
|
|
1287
|
-
that failed is said as a failure naming the lexicon, and its rows wear a
|
|
1288
|
-
dashed ring. A query chant's grammar refuses lights and dims nothing and
|
|
1289
|
-
shows chant's message and hint. A reload keeps `q`.
|
|
1290
|
-
|
|
1291
|
-
chant answers and behold draws. Every search goes through the workspace
|
|
1292
|
-
reader (`src/workspace-reader.ts`, a fifth `BEHOLD_READS` entry held by
|
|
1293
|
-
chant's reader conformance suite):
|
|
1294
|
-
|
|
1295
|
-
| Served | chant call |
|
|
1296
|
-
|---|---|
|
|
1297
|
-
| 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 |
|
|
1298
|
-
| one chant project | `chant search [flags] --json -- <q>` in its directory |
|
|
1299
|
-
| 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 |
|
|
1300
|
-
| a loose estate of several dirs | refused, `code: "search-estate"`: declare a workspace |
|
|
1301
|
-
|
|
1302
|
-
The mode follows the view: no `env` is the declared source, `env` is a live
|
|
1303
|
-
read (`--live --env`), and `env` with `snapshot` replays a recorded snapshot
|
|
1304
|
-
(`--snapshot <ref> --env`). `--explain` is always passed.
|
|
1305
|
-
|
|
1306
|
-
```
|
|
1307
|
-
GET /api/search?q=->kind:aws_kms_key&env=&snapshot=&show=
|
|
1308
|
-
-> 200 {q, env, snapshot,
|
|
1309
|
-
document: <chant's search document, unchanged>,
|
|
1310
|
-
draw: {lit, onPath, edges, unobserved, nearMisses, provenance, failure, notSearched},
|
|
1311
|
-
link}
|
|
1312
|
-
```
|
|
1313
|
-
|
|
1314
|
-
A query chant refuses answers 400 `code: "query"` with chant's hint as the
|
|
1315
|
-
remedy (and the document). A chant below 0.124.46 answers 422
|
|
1316
|
-
`code: "chant-too-old"` (`SEARCH_CONTRACT_CHANT_FLOOR` in
|
|
1317
|
-
`src/chant-floors.ts`). A `--public` serve answers declared queries and
|
|
1318
|
-
refuses `env` and `snapshot` (403).
|
|
1319
|
-
|
|
1320
|
-
`behold export --q "<query>"` (repeatable) captures each query's answer for
|
|
1321
|
-
the source graph and every environment, so the bundle draws it with no
|
|
1322
|
-
backend. The manifest lists `queries`; a link's `q` that wasn't captured is
|
|
1323
|
-
named, with the captured ones, and lights nothing.
|
|
1324
|
-
|
|
1325
|
-
### Groups and the plan: `countBy` and `plan` (#922)
|
|
1326
|
-
|
|
1327
|
-
Two more view keys, carried the same way as `q` (a link, `behold:view`,
|
|
1328
|
-
`POST /api/view`, `behold shot --view`, the MCP tools, an export):
|
|
1329
|
-
|
|
1330
|
-
- `countBy=kind|module|attr:<name>` is chant's `--count-by`. The document is
|
|
1331
|
-
chant's counts branch, verbatim: `countBy`, `groups[{group, count, ids}]`
|
|
1332
|
-
and `total` (INTENTIUS/chant#4360; `ids` is INTENTIUS/chant#4382). The page
|
|
1333
|
-
lights each group's cards from `ids`, outlines them in the group's colour,
|
|
1334
|
-
labels the group's first drawn card `<group> · <count>`, and the top-left
|
|
1335
|
-
line lists the groups and the total. `draw.counts` is `{by, total, groups}`.
|
|
1336
|
-
With `countBy`, `q` may be empty: the whole graph is counted. A chant that
|
|
1337
|
-
lists no ids per group lights nothing and the line says so. behold never
|
|
1338
|
-
works out a node's group itself.
|
|
1339
|
-
- `plan=1` is the plan read. The source graph's cards carry each stock
|
|
1340
|
-
Terraform root's plan facts (`/api/graph?plan=1`, #910) on every load, and
|
|
1341
|
-
`q` is answered at the plan depth: `CHANT_TERRAFORM_OBSERVE=plan` in the
|
|
1342
|
-
environment of that one chant call, with `--live --env <env>`
|
|
1343
|
-
(INTENTIUS/chant#4358). A bare Terraform folder needs no env (the plan
|
|
1344
|
-
read's placeholder `behold-plan` is used); a chant project or workspace
|
|
1345
|
-
needs one (422 `code: "plan-env"`). `plan` with `snapshot` is refused,
|
|
1346
|
-
naming both: a 400 on the route, both keys in `refused` on a link or
|
|
1347
|
-
`POST /api/view`. A `--public` serve refuses it (403). It runs
|
|
1348
|
-
`terraform plan -lock=false` in each root: nothing is changed, but every
|
|
1349
|
-
resource is read.
|
|
1350
|
-
|
|
1351
|
-
```
|
|
1352
|
-
GET /api/search?q=kind:aws_&countBy=module
|
|
1353
|
-
GET /api/search?q=attr:planAction=replace&plan=1&show=planActions,planReplacePaths,planActionReason
|
|
1354
|
-
```
|
|
1355
|
-
|
|
1356
|
-
`behold export --count-by <g>` captures each `--q` grouped too (with no
|
|
1357
|
-
`--q`, the whole graph's groups); `behold export --plan` captures the plan
|
|
1358
|
-
cards on the source graph and each `--q` at the plan depth.
|
|
1359
|
-
|
|
1360
|
-
A `cap:` term (INTENTIUS/chant#4375) asks a capability, such as
|
|
1361
|
-
`cap:internet-reachable(22)`. Its route is in the path's `because`, one
|
|
1362
|
-
entry per capability the match relied on, each with the hops that proved it,
|
|
1363
|
-
and `draw.edges` and `draw.onPath` include them (#926). A hop that ends on a
|
|
1364
|
-
node inside a resource, `<id>#<attr>[n]` (a security group's ingress rule),
|
|
1365
|
-
is drawn on the resource's card.
|
|
1366
|
-
|
|
1367
|
-
### The capability catalog: `GET /api/capabilities` (#926)
|
|
1368
|
-
|
|
1369
|
-
Read it before asking a `cap:` question. It answers chant's capabilities
|
|
1370
|
-
document byte for byte (capabilities.schema.json, contract 1), read through
|
|
1371
|
-
the workspace reader from the same target a search asks:
|
|
1372
|
-
`chant workspace search --capabilities --json` at a declared workspace's
|
|
1373
|
-
root, `chant search --capabilities --json` in one project or a Terraform
|
|
1374
|
-
folder's scratch project. Each capability has its `name`, `meaning`,
|
|
1375
|
-
`params`, the `search` term that asks it, the questions it `answers`, what
|
|
1376
|
-
it leaves `notEvaluated`, its `rule`, and per lexicon whether it is
|
|
1377
|
-
supplied. A chant below 0.124.46 answers 422 `code: "chant-too-old"`
|
|
1378
|
-
(`CAPABILITIES_CHANT_FLOOR`). behold mcp's `capabilities` tool returns the
|
|
1379
|
-
same text. behold keeps the document per checkout and commit, so a second
|
|
1380
|
-
read of an unmoved checkout runs no chant; a `--public` serve refuses the
|
|
1381
|
-
route with 403 (#978).
|
|
1382
|
-
|
|
1383
|
-
```
|
|
1384
|
-
GET /api/capabilities
|
|
1385
|
-
-> 200 {"$schema":".../capabilities/v1/capabilities.schema.json","contract":1,"chant":"0.124.46",
|
|
1386
|
-
"capabilities":[{"name":"internet-facing","meaning":...,"search":"cap:internet-facing",...}],
|
|
1387
|
-
"helpers":[...]}
|
|
1388
|
-
```
|
|
1389
|
-
|
|
1390
|
-
### The graph pane: Cypher and resolve-from-resource (behold#1027)
|
|
1391
|
-
|
|
1392
|
-
Every member's chant IR, every engine graph document (`choudoufu live-graph
|
|
1393
|
-
-json`, `plunge graph --json`, read from `engine-graph.json` beside a member
|
|
1394
|
-
or `.behold/graph/*.json`), every index version (the latest per scope in
|
|
1395
|
-
`.chant/store/index/`, `_index/` on `refs/chant/snapshots`, and behold's
|
|
1396
|
-
per-user index directory) and every cloud listing in one LadybugDB per
|
|
1397
|
-
session. Tables: `Resource` keyed `<member>/<id>` (or the source's scope
|
|
1398
|
-
key), `CloudId` with `KNOWN_AS` from each Resource, and `REF` with `grain`,
|
|
1399
|
-
`origin` (`derived` for an identity match, with its `rule`) and `ambiguous`.
|
|
1400
|
-
The database is behold's own file under `$XDG_DATA_HOME/behold/graph` and
|
|
1401
|
-
read-only once built; a query that writes is refused. Cypher needs the
|
|
1402
|
-
optional peer `@ladybugdb/core` and answers 503 `graph-peer-missing` with the
|
|
1403
|
-
install line without it; resolve, the template catalog and the path-pattern
|
|
1404
|
-
templates work without it. Every answer carries `sources`, each with
|
|
1405
|
-
`observedAt` (null for a declared source) and `readAt`. A `--public` serve
|
|
1406
|
-
refuses the pane. behold mcp's `ask` takes `cypher` or `resource` (with
|
|
1407
|
-
`template` and `inputs`) beside `query`. All GET.
|
|
1408
|
-
|
|
1409
|
-
```
|
|
1410
|
-
GET /api/graphdb sources, counts, notes, peer
|
|
1411
|
-
GET /api/graphdb/query?cypher=¶ms= {"columns","rows","keys","draw":{nodes,edges},"link","sources"}
|
|
1412
|
-
GET /api/graphdb/resolve?ref= {"candidates":[{key,matchedBy,...}],"templates":[...],"sources"}
|
|
1413
|
-
GET /api/graphdb/template?name=&node=&in.<input>=
|
|
1414
|
-
GET /graph the pane
|
|
1415
|
-
```
|
|
1416
|
-
|
|
1417
|
-
## Moving the person's open tab (#914)
|
|
1418
|
-
|
|
1419
|
-
`POST /api/view` changes what every open tab of this serve draws. It is a
|
|
1420
|
-
view change and writes nothing: no infrastructure, no project file, not
|
|
1421
|
-
the layout cache, and nothing kept on the server.
|
|
1422
|
-
|
|
1423
|
-
```
|
|
1424
|
-
POST /api/view
|
|
1425
|
-
{"view": {"q": "attr:internetFacing=true", "env": "prod", "snapshot": "latest", "zoom": "resources"},
|
|
1426
|
-
"by": "claude-code via behold mcp"}
|
|
1427
|
-
```
|
|
1428
|
-
|
|
1429
|
-
`view` takes the URL's view keys (`member`, `zoom`, `env`, `tier`, `lens`,
|
|
1430
|
-
`node`, `radial`, `alike`, `gates`, `focus`, `run`, `pull`, and #922's
|
|
1431
|
-
`plan` (a boolean) and `countBy`) plus `q`, a
|
|
1432
|
-
question in chant's search grammar, and `snapshot`, a recorded lifecycle
|
|
1433
|
-
snapshot (`latest` or a ref) that needs an `env`. They are settled with the
|
|
1434
|
-
same checks a link's query gets (`web/view-url.js`: `viewFromObject`,
|
|
1435
|
-
`settleView`, `checkQuery`); an env the project doesn't declare, a `q` with a
|
|
1436
|
-
control character or over 2000 characters, or a key that isn't a view key is
|
|
1437
|
-
named in `refused` and the rest still moves. `at` is refused by name: in
|
|
1438
|
-
chant's read contract it is a git revision, so a snapshot is `snapshot`.
|
|
1439
|
-
behold does not parse `q`. The tab draws it through `GET /api/search`
|
|
1440
|
-
(below): the matches lit, the rest dimmed.
|
|
1441
|
-
|
|
1442
|
-
The answer is `200 {id, movedAt, sent, link, view, refused}`, where `sent` is
|
|
1443
|
-
the number of open tabs it reached and `link` opens the same view. With no
|
|
1444
|
-
tab open it is `409 {code: "no-tab", link}`: hand the person the link. A
|
|
1445
|
-
view with nothing that can be applied is `400 {code: "view", refused}`.
|
|
1446
|
-
|
|
1447
|
-
Each tab gets a `view` event `{id, movedAt, by, view}` on `/api/events`,
|
|
1448
|
-
moves, and shows "Moved by an agent: `<by>` asked `<q>` at <time> (request
|
|
1449
|
-
<id>)" with a Back button. An agent's move pushes a browser history entry, so
|
|
1450
|
-
the banner's Back and the browser's Back both return to the view from before
|
|
1451
|
-
it; up to 20 moves in a row stack this way. The person's own changes keep
|
|
1452
|
-
replacing the entry they are on. An embedded frame with a host (`embed=1&host=`)
|
|
1453
|
-
ignores the event, because its host owns its view (#476).
|
|
1454
|
-
|
|
1455
|
-
`by` is a label of at most 80 printable characters. Without one it is the
|
|
1456
|
-
request's User-Agent product token. Anyone who can reach the serve can send
|
|
1457
|
-
any name, so `by` says who the caller claims to be and is not authentication.
|
|
1458
|
-
|
|
1459
|
-
Refused: under `serve --public` (405 from the request guard, and 403 `code:
|
|
1460
|
-
"public"` in the route itself), and under every `behold preview`, with or
|
|
1461
|
-
without `--emulator` (403 `code: "preview"`). A terragucci or SQL Yodeler
|
|
1462
|
-
repo allows it, since it writes nothing. A static export has no server, so no
|
|
1463
|
-
route.
|
|
1464
|
-
|
|
1465
|
-
## A picture of a view (#915)
|
|
1466
|
-
|
|
1467
|
-
`behold shot "<query>" [project-dir] -o out.png` and `GET /api/shot` take a
|
|
1468
|
-
PNG of a view and give the link to the same view. Both call `src/shot.ts`.
|
|
1469
|
-
The page is behold's own, loaded in a headless browser with
|
|
1470
|
-
`embed=1&bare=1&frame=matches`: it lights what the view asks for, dims the
|
|
1471
|
-
rest, frames the lit cards with the kiosk's arithmetic (`web/kiosk-shot.js`),
|
|
1472
|
-
draws one caption line (what was asked, from where, when), and sets
|
|
1473
|
-
`data-behold-shot` on `<html>` to `drawn`, `no-matches` or `failed`. Nothing
|
|
1474
|
-
is photographed until it does: a page that never reports ready within 60 s,
|
|
1475
|
-
or one that draws no cards, is refused and no file is written.
|
|
1476
|
-
|
|
1477
|
-
```
|
|
1478
|
-
GET /api/shot?node=aws_vpc.main&env=prod&width=1600&height=1000
|
|
1479
|
-
-> 200 image/png, Behold-View-Link: http://127.0.0.1:4600/?env=prod&node=aws_vpc.main,
|
|
1480
|
-
Behold-Shot-State: drawn | no-matches | failed
|
|
1481
|
-
```
|
|
1482
|
-
|
|
1483
|
-
The browser comes from `playwright-core`, an optional peer behold does not
|
|
1484
|
-
install: the system Chrome first, then Playwright's `chromium-headless-shell`.
|
|
1485
|
-
Without either the CLI exits 1 with the install line and the route answers
|
|
1486
|
-
501 `code: "no-browser"`. `--env`/`env=` draws the env's live view, and
|
|
1487
|
-
`--snapshot <ref>`/`snapshot=` a recorded snapshot of it (`at` is a git
|
|
1488
|
-
revision and is not taken). The route answers bytes, never a path, and is
|
|
1489
|
-
refused on `serve --public` (403), since each shot starts a browser. The CLI
|
|
1490
|
-
uses the serve at `--url`, or starts behold's app for the project on a free
|
|
1491
|
-
loopback port and stops it after; without `-o` the PNG goes under the OS temp
|
|
1492
|
-
directory. Nothing is written in the served project.
|
|
1493
|
-
|
|
1494
|
-
A query's matches are lit and framed (#913). Without a query, a shot frames
|
|
1495
|
-
the view's own `node` or `focus` (`behold shot "" --view node=<id>`).
|
|
1496
|
-
|
|
1497
|
-
Publishing is opt-in per call (#923, `src/shot-publish.ts`): `--publish
|
|
1498
|
-
<remote>[/<branch>]` (branch default `behold-shots`) commits the PNG to that
|
|
1499
|
-
branch of the remote, in the repo `--publish-repo <dir>` names (default: the
|
|
1500
|
-
current directory's), tracked with Git LFS (`*.png` in the branch's
|
|
1501
|
-
`.gitattributes`), pushes it, and prints the raw URL (at the commit, for
|
|
1502
|
-
GitHub and GitLab) after the view link. It is git plumbing on a private index:
|
|
1503
|
-
no checkout's tree, index or HEAD changes, and the branch checked out in the
|
|
1504
|
-
repo or the project, or its upstream, is refused. Without git-lfs, or when the
|
|
1505
|
-
remote does not take the LFS object, it refuses with the setup line and exits
|
|
1506
|
-
1 before the branch moves; the local PNG is kept. `behold mcp`, `GET
|
|
1507
|
-
/api/shot` and a `--public` serve never publish.
|
|
1508
|
-
|
|
1509
|
-
## The graph document: `behold-graph/1` (#1066)
|
|
1510
|
-
|
|
1511
|
-
A graph snapshot (`{ir, meta}`, what `/api/graph` answers and what every
|
|
1512
|
-
export snapshot holds) becomes a versioned document through
|
|
1513
|
-
`toDocument(snapshot, opts)` (`src/to-document.ts`). The types, the version
|
|
1514
|
-
string and `checkGraphDocument` are in `src/graph-document.ts`, which imports
|
|
1515
|
-
nothing, so a browser host can load it. The JSON Schema ships in the package
|
|
1516
|
-
at `schemas/graph/v1/graph.schema.json` and is published at
|
|
1517
|
-
https://intentius.io/behold/schemas/graph/v1/graph.schema.json (its `$id`,
|
|
1518
|
-
the same bytes from `docs/public/`; a test holds the two together).
|
|
1519
|
-
|
|
1520
|
-
```
|
|
1521
|
-
{schema: "behold-graph/1", generator: {behold, chant?}, origin: {dir, rev?},
|
|
1522
|
-
cut: {kind: "whole" | "around" | "changed", ...}, nodes[], edges[], groups[],
|
|
1523
|
-
notes[], layout?}
|
|
1524
|
-
node: {id, title, subtitle, kind, lexicon, box?, file?, line?, change?,
|
|
1525
|
-
status?, color?, mainstat?, secondarystat?, stackOf?, detail__member?,
|
|
1526
|
-
detail__root?, detail__namespace?, detail__release?, attrs}
|
|
1527
|
-
edge: {id, source, target, kind, inferred, rule?, via?}
|
|
1528
|
-
group: {id: "<kind>:<key>", title, kind: stack | wave | pipeline | container, parent?}
|
|
1529
|
-
note: {kind, text, short?, box?, count?}
|
|
1530
|
-
```
|
|
1531
|
-
|
|
1532
|
-
The node and edge field names are the ones Grafana's node graph panel takes,
|
|
1533
|
-
so the panel reads `nodes` and `edges` with no transform. `subtitle` is the
|
|
1534
|
-
tool (`k8s` reads `kubernetes`), `status` is `attrs._status`, `color` its
|
|
1535
|
-
pinhole bar colour, `mainstat` the drift record's words or the plan's action,
|
|
1536
|
-
`change` the plan's action unless it is `no-op` or `read`. `file` is relative
|
|
1537
|
-
to the repository root, and absent when behold cannot place it there; an
|
|
1538
|
-
absolute `sourceLoc` is dropped. An edge whose end the view does not draw is
|
|
1539
|
-
left out and counted in `notes` (`edges-left-out`), so every `source` and
|
|
1540
|
-
`target` names a node. Edge ids are `<source>-><target>:<kind>[:<via>]`, with
|
|
1541
|
-
`#2`, `#3` on repeats. `rule` names the join behind an inferred edge: chant's
|
|
1542
|
-
catalog rule (`origin: "derived"`), or `behold:<join>` from the `join` field
|
|
1543
|
-
each behold pass now sets beside `inferred: true` (`value-match`,
|
|
1544
|
-
`k8s-declared`, `estate-member`, `cluster-anchor`, `composite-deps`,
|
|
1545
|
-
`choudoufu-lexicon`, `choudoufu-estate`). `attrs.source` is left out unless
|
|
1546
|
-
`opts.source` asks for it.
|
|
1547
|
-
|
|
1548
|
-
`documentOptions({projectDir, projectDirs?, workspace?, behold, rev?})`
|
|
1549
|
-
(`src/graph-document-context.ts`) works out what the IR does not carry: the
|
|
1550
|
-
served directory relative to its repository (the nearest `.git` above it),
|
|
1551
|
-
each member's directory and Terraform roots, and a scrubber that rewrites this
|
|
1552
|
-
machine's paths to repository-relative ones, the home directory to `~` and
|
|
1553
|
-
the temporary directory to `$TMPDIR`. The same snapshot and options give
|
|
1554
|
-
byte-identical JSON. Within `behold-graph/1` fields are only added and a
|
|
1555
|
-
reader ignores what it does not know; `checkGraphDocument` refuses any other
|
|
1556
|
-
`behold-graph/<n>` by name.
|
|
1557
|
-
|
|
1558
|
-
## The graph from the command line: `behold graph` (#1058)
|
|
1559
|
-
|
|
1560
|
-
`behold graph [dir] [--json | --ir] [-o <file>] [--detail 0..3] [--source]
|
|
1561
|
-
[--every-card]` reads a directory and prints it, with no server, no browser
|
|
1562
|
-
and no write but the `-o` file (src/graph-cli.ts). `--json`, the default, is
|
|
1563
|
-
the `behold-graph/1` document; `--ir` is the unversioned `{ir, meta}` that
|
|
1564
|
-
`/api/graph` answers, without its SVG. `--mermaid [--forge gitlab|github|forgejo]`
|
|
1565
|
-
is a flowchart that fits that forge's character budget (below); `--svg` is
|
|
1566
|
-
reserved for its painter (#1061) and exits 2 until it applies. Exit 1 is a
|
|
1567
|
-
directory chant would not read (its refusal and remedy on stderr), exit 2 a
|
|
1568
|
-
usage error. No output holds an absolute path: both go through
|
|
1569
|
-
`documentOptions`' scrubber, and `attrs.source` is left out without
|
|
1570
|
-
`--source`.
|
|
1571
|
-
|
|
1572
|
-
The Mermaid writer (#1060) is `toMermaid(doc, { forge })` in
|
|
1573
|
-
src/graph-mermaid.ts, over a `behold-graph/1` document, so a cut applies first.
|
|
1574
|
-
Ids are `n<index>` and `g<index>` over the sorted ids, one label line per card,
|
|
1575
|
-
boxes as subgraphs, inferred edges dotted, labels quoted and escaped with
|
|
1576
|
-
Mermaid entity codes. A document with a plan's `change` or a cut's `seed` gets
|
|
1577
|
-
four `classDef` lines: added (`create`), changed (`update`, `replace`), removed
|
|
1578
|
-
(`delete`) and neighbour (a card in the cut that is neither a seed nor changed).
|
|
1579
|
-
Over the budget it drops neighbours first, then whole boxes (those with the
|
|
1580
|
-
fewest changed cards first), and ends with a `N cards not shown` card; it never
|
|
1581
|
-
returns text over the budget. The budgets are one table, `FORGE_BUDGETS` in
|
|
1582
|
-
src/mermaid-budgets.ts: gitlab 2,000 characters, github and forgejo 20,000 and
|
|
1583
|
-
250 edges, a whole comment under 60,000. Each row has `confirmed: false` until
|
|
1584
|
-
the live check (e2e/forge-limits, #1065) records the forge's real figures; that
|
|
1585
|
-
check's result is an edit to the row. `forgeComment` builds the comment body
|
|
1586
|
-
(marker, count line, fenced diagram) and posts the per-root table from
|
|
1587
|
-
`rootTable` instead when the diagram had to leave cards out or the comment
|
|
1588
|
-
would reach its limit; the action (#1062) and the MCP text fallback (#1073)
|
|
1589
|
-
use these.
|
|
1590
|
-
|
|
1591
|
-
The read is `graphView(dir, opts)` (src/graph-view.ts): `readGraph`, then the
|
|
1592
|
-
lenses `/api/graph` runs over an estate's source picture: the plan when
|
|
1593
|
-
`terraformPlan` is passed (the server's setting, as an argument), collapse,
|
|
1594
|
-
stacking alike cards (`--every-card` turns it off), and the note, joined by
|
|
1595
|
-
`viewNote`. The route calls `shapeEstate` and `viewNote` from the same module,
|
|
1596
|
-
and src/graph-view.test.ts holds the view equal to the route's answer. The
|
|
1597
|
-
logical and components lenses, the traffic prediction (it reads per-user
|
|
1598
|
-
settings) and the SVG stay in the route. An output format is one entry in
|
|
1599
|
-
`GRAPH_FORMATS` (src/graph-formats.ts); a cut is a function over the document
|
|
1600
|
-
that the CLI hands a format as `cut`.
|
|
1601
|
-
|
|
1602
|
-
### A bare cluster: `behold graph --context <name>` (#1083)
|
|
1603
|
-
|
|
1604
|
-
`behold graph --context <name> [--kubeconfig <file>] [--namespace a,b]
|
|
1605
|
-
[--types t,u] [--allow-exec-plugin]` draws the cluster a kubeconfig context
|
|
1606
|
-
points at, with no chant project and no directory (src/read-cluster.ts).
|
|
1607
|
-
`--kubeconfig` alone reads that file's current context; without it the file is
|
|
1608
|
-
the first path in `KUBECONFIG`, then `~/.kube/config`. There is no reader of
|
|
1609
|
-
behold's own. `readCluster` calls chant's `indexCloud` (the cloud lister
|
|
1610
|
-
`behold index kubernetes` runs: API discovery, then a paged LIST per kind, read
|
|
1611
|
-
allowlist only) with the `none` store, so no index version and no file is
|
|
1612
|
-
written, and hands the result to `readComposed` (src/read-graph.ts), the passes
|
|
1613
|
-
`readGraph` runs over a directory's estate. `readGraph` still reads no
|
|
1614
|
-
kubeconfig. Cards are boxed by namespace (cluster-scoped objects in `cluster`)
|
|
1615
|
-
and take the ids `<namespace>/<Kind>/<name>`; an edge to an object the read did
|
|
1616
|
-
not list is dropped and counted in the note. What the objects name outside the
|
|
1617
|
-
cluster (web/outside-refs.js, #1082) is added as cards in a box called Outside
|
|
1618
|
-
the cluster. `behold serve` does not take a context yet.
|
|
1619
|
-
|
|
1620
|
-
Credentials: a token, a token file or a client certificate. A user that
|
|
1621
|
-
authenticates through an exec plugin (the GKE, EKS and AKS tools write these)
|
|
1622
|
-
is refused with exit 2, naming the context, before chant is loaded and before
|
|
1623
|
-
any request. `--allow-exec-plugin` runs the plugin once (src/kube-exec.ts, the
|
|
1624
|
-
ExecCredential protocol, no terminal) and reads with the credential it prints.
|
|
1625
|
-
An `auth-provider` user is always refused. Whether the switch should be on by
|
|
1626
|
-
default is the maintainer's ruling and is open.
|
|
1627
|
-
|
|
1628
|
-
The live read masks every key matching /secret/i, which chant's typing then
|
|
1629
|
-
shows as `[REDACTED]`. On chant 0.124.58 an ExternalSecret's
|
|
1630
|
-
`spec.secretStoreRef` is masked whole, so its store and provider draw no card
|
|
1631
|
-
and the note says so (chant#5116 keeps such reference fields readable). An Argo
|
|
1632
|
-
CD cluster Secret's name and server are masked too, and chant#5116 decides
|
|
1633
|
-
whether they show. behold draws what the lister returns under either answer.
|
|
1634
|
-
`BEHOLD_K3D_TESTS=1 npx vitest run src/read-cluster-live.test.ts` runs the
|
|
1635
|
-
live test on a k3d cluster named `behold-read-cluster-<pid>`, deleted afterward
|
|
1636
|
-
unless `BEHOLD_K3D_KEEP=1`; `BEHOLD_EXPECT_5116=1` makes its reference test
|
|
1637
|
-
fail instead of skip.
|
|
1638
|
-
|
|
1639
|
-
The same command is the `behold-graph` bin of `@intentius/behold-graph`,
|
|
1640
|
-
built from this repo into packages/graph by `npm run build:graph` (part of
|
|
1641
|
-
`npm run build`). Its entry is src/graph-package.ts, which exports `readGraph`,
|
|
1642
|
-
`graphView`, the formats, `toDocument` and the document types. Its
|
|
1643
|
-
dependencies are packages/graph/budget.json's allowlist, at behold's own
|
|
1644
|
-
ranges and version (a test holds both). `npm run check:graph-package` (CI runs
|
|
1645
|
-
it after the build) packs it, installs the tarball into an empty directory,
|
|
1646
|
-
prints the installed size, and fails above the budget, on a dependency not on
|
|
1647
|
-
the allowlist, or when `npm ls --all` names hono, `@hono/node-server`, the MCP
|
|
1648
|
-
SDK or the Kubernetes client. The first measurement was 127 MB and 55
|
|
1649
|
-
packages, against 238 MB and 162 for behold; the budget is 140 MB and 60.
|
|
1650
|
-
Most of it is chant itself (73 MB) and the TypeScript compiler chant loads
|
|
1651
|
-
configs with (23 MB). Publishing the package is the maintainer's step.
|
|
1652
|
-
|
|
1653
|
-
## The single-file viewer (#1070)
|
|
1654
|
-
|
|
1655
|
-
`npm run build:viewer` (scripts/build-viewer.mts) writes
|
|
1656
|
-
`dist/behold-viewer/`: `index.html` (no inline script), `viewer.js` (a
|
|
1657
|
-
classic script), `viewer.mjs` (the same as an ES module), `viewer.css`, a
|
|
1658
|
-
stand-in `graph.js`, and `viewer.html` with the script and the styles
|
|
1659
|
-
inlined, for an MCP resource or an unzipped artifact. It draws a
|
|
1660
|
-
`behold-graph/1` document with the painter `/api/graph` uses: the document is
|
|
1661
|
-
turned back into the IR (src/viewer/document-ir.ts, a card's box walked up to
|
|
1662
|
-
its stack, pipeline, wave and container) and painted by `paintDocument`
|
|
1663
|
-
(src/viewer/paint.ts), with the same box badges. The source is src/viewer/.
|
|
1664
|
-
|
|
1665
|
-
The document comes, in this order, from a `behold:graph {document, icons?}`
|
|
1666
|
-
message, from `window.__BEHOLD_GRAPH__` (graph.js, the only form that works
|
|
1667
|
-
from `file://`), or from `?src=<same-origin path>`. Options come from the
|
|
1668
|
-
query string and from `window.__BEHOLD_VIEWER__`, the query winning:
|
|
1669
|
-
`theme` (light, dark, blueprint, aws; absent, `prefers-color-scheme`),
|
|
1670
|
-
`node`, `focus` (box keys or ids), `host` (the parent's origin), `transport`
|
|
1671
|
-
(post, vscode, mcp, none) and `src`. In: `behold:theme {theme?, vars?}` (CSS
|
|
1672
|
-
custom properties only) and `behold:view {node?, focus?}`. Out:
|
|
1673
|
-
`behold:ready`, then `behold:select {id, kind, file}` per pick.
|
|
1674
|
-
src/viewer/transport.ts has the three hosts: a parent page (`postMessage` to
|
|
1675
|
-
`host` only, and only its messages read), a VS Code webview
|
|
1676
|
-
(`acquireVsCodeApi`, called once), and an MCP Apps view (JSON-RPC:
|
|
1677
|
-
`ui/initialize`, the document from `ui/notifications/tool-result`'s
|
|
1678
|
-
`structuredContent`, the theme from the host context, a pick sent as
|
|
1679
|
-
`ui/update-model-context`). With no `transport`, a page with
|
|
1680
|
-
`acquireVsCodeApi` is VS Code, one with `host` is a parent page, and a
|
|
1681
|
-
framed page with neither is MCP Apps.
|
|
1682
|
-
|
|
1683
|
-
The layout runs in a Web Worker: the script starts itself as the worker,
|
|
1684
|
-
from its own URL or, inlined, from its own text, and paints on the page when
|
|
1685
|
-
no worker starts (index.html opened from `file://`). A document with no
|
|
1686
|
-
boxes above `FLAT_LIMIT` cards is refused with the reason, since one flat
|
|
1687
|
-
layout grows far faster than the card count. The page sets
|
|
1688
|
-
`data-behold-viewer` on `<html>` (`waiting`, `drawing`, `drawn`, `refused`)
|
|
1689
|
-
and `window.__BEHOLD_VIEWER_STATE__` (cards, where it laid out, time to first
|
|
1690
|
-
paint).
|
|
1691
|
-
|
|
1692
|
-
The vendored icon table is left out of the build: it is 544 KB of the 684 KB
|
|
1693
|
-
painter. A host hands over the icons its document uses, as
|
|
1694
|
-
`window.__BEHOLD_ICONS__` or the message's `icons`; `graphScript(doc)`
|
|
1695
|
-
(src/viewer/graph-script.ts) writes a graph.js with both, and
|
|
1696
|
-
`documentIcons(doc)` finds the icons by painting the document once with the
|
|
1697
|
-
full table (`recordIcons` in src/icon-packs.ts). Once a host supplies icons,
|
|
1698
|
-
an icon it did not supply falls through to pinhole's keyword glyph
|
|
1699
|
-
(`supplyIcons`). The build fails above 300 KB minified or 100 KB gzipped for
|
|
1700
|
-
`viewer.js` or `viewer.mjs`, above 1 MB for the directory, on any Node
|
|
1701
|
-
built-in in the bundle, and when `viewer.js` names `EventSource` or
|
|
1702
|
-
`WebSocket`. On pinhole 0.5.0 it fails on the four `node:` imports in
|
|
1703
|
-
pinhole's root (#1069), which pinhole 0.6.0 removes.
|
|
1704
|
-
src/viewer/viewer-browser.test.ts opens it in headless Chrome from `file://`
|
|
1705
|
-
and under `default-src 'none'; script-src 'self'; style-src 'self'
|
|
1706
|
-
'unsafe-inline'`, and skips while pinhole is 0.5.0.
|
|
1707
|
-
|
|
1708
|
-
## Over MCP: `behold mcp` (#916)
|
|
1709
|
-
|
|
1710
|
-
`behold mcp [project-dir] [--url <serve> | --port <n>]` is a stdio MCP server
|
|
1711
|
-
with five tools for an agent (and a sixth for a view), most of them clients of a running serve's HTTP API; `graph` (#1073, below) reads the directory itself. An agent reads
|
|
1712
|
-
`capabilities` first (#926): it calls `GET /api/capabilities` and returns
|
|
1713
|
-
chant's capability catalog, the read contract's `capabilities` document
|
|
1714
|
-
(`chant search --capabilities --json`, INTENTIUS/chant#4375), byte for byte.
|
|
1715
|
-
It names each capability a `cap:` term asks, what it means, its parameters,
|
|
1716
|
-
the search term, the questions it answers, what it does not evaluate, its
|
|
1717
|
-
rule and which lexicons supply it, and it takes no arguments. `ask` calls
|
|
1718
|
-
`GET /api/search` and returns chant's search document verbatim, with `link`
|
|
1719
|
-
and `drawn: false` added after its own fields (a test holds it byte for byte
|
|
1720
|
-
to what chant prints); it takes `query`, `env`, `snapshot` and `show`, and
|
|
1721
|
-
never moves the tab. `show` calls
|
|
1722
|
-
`POST /api/view` (its `by` is the MCP client's name plus "via behold mcp"),
|
|
1723
|
-
and `shot` calls `GET /api/shot` and returns the PNG as MCP `image` content
|
|
1724
|
-
followed by a text block `{link, state, serve}`. They take `query`, `env`,
|
|
1725
|
-
`snapshot`, `member`, `zoom`, `focus` and `node`; `shot` also takes `width`
|
|
1726
|
-
and `height`. The answers are chant's: behold passes chant's documents
|
|
1727
|
-
through and computes none of its own.
|
|
1728
|
-
|
|
1729
|
-
`graph` (#1073) draws the repository, or a cut of it, and takes `dir` (a folder
|
|
1730
|
-
inside the project), `around` (comma-separated card or box ids, or a box title
|
|
1731
|
-
or Terraform root as the roots table prints it), `changed` (`<base>..<head>`),
|
|
1732
|
-
`depth` and `direction`. It reads in this process with the calls `behold graph`
|
|
1733
|
-
makes (`src/mcp-graph.ts`) and answers in text for every host: the counts, the
|
|
1734
|
-
cut, a Mermaid block when it fits (`MCP_MERMAID_BUDGET`, nine thousand
|
|
1735
|
-
characters) or a table of roots when it does not, and a link to the running
|
|
1736
|
-
serve at the card or box asked for, else the line that starts one. The whole
|
|
1737
|
-
text stays under `TEXT_CHARS` (18,000), well under Claude Code's 10,000-token
|
|
1738
|
-
warning, and holds no document JSON. `_meta.ui.resourceUri` names
|
|
1739
|
-
`ui://behold/viewer` (MIME type `text/html;profile=mcp-app`, MCP Apps spec
|
|
1740
|
-
2026-01-26), which `resources/read` serves from `src/viewer-resource.ts`:
|
|
1741
|
-
`dist/behold-viewer/viewer.html` (#1070's `npm run build:viewer`) when it is in
|
|
1742
|
-
the package, else a page saying the view is not in this build. The view gets
|
|
1743
|
-
its document from `graph_document`, a tool with `_meta.ui.visibility: ["app"]`
|
|
1744
|
-
that takes `graph`'s arguments (`structuredContent.view` of a `graph` result
|
|
1745
|
-
is exactly those), so the cards never enter the model's context.
|
|
1746
|
-
|
|
1747
|
-
It finds the serve through `--url`/`--port`, then the per-user registry at
|
|
1748
|
-
`<os.tmpdir()>/behold/serves/<pid>.json` (`{url, pid, projectDir, version,
|
|
1749
|
-
startedAt}`, written by every serve at start, rewritten on a project switch,
|
|
1750
|
-
removed at exit, a dead pid ignored; `BEHOLD_SERVES_DIR` moves it), then
|
|
1751
|
-
`http://127.0.0.1:4600`. It confirms the serve through `GET /api/project`.
|
|
1752
|
-
`show` refuses a serve of another project, naming both, and refuses with the
|
|
1753
|
-
serve command when none runs. `capabilities`, `ask` and `shot` with no serve of the project
|
|
1754
|
-
start behold in their own process for the call (`src/shot-cli.ts`), and the
|
|
1755
|
-
answer comes from the same route.
|
|
1756
|
-
|
|
1757
|
-
Arguments are checked against each tool's schema (`additionalProperties:
|
|
1758
|
-
false`), a credential-named one is refused by name, and a refusal is an
|
|
1759
|
-
`isError` result carrying the route's `{error, code, remedy}`. The server
|
|
1760
|
-
refuses to start with a tool whose name holds a write word (deploy, apply,
|
|
1761
|
-
approve, run, op, rollback, write and kin), and a call to an unlisted tool is
|
|
1762
|
-
refused with the same words.
|
|
1763
|
-
|
|
1764
|
-
## The act loop (delegated, never direct)
|
|
1765
|
-
|
|
1766
|
-
behold does not apply. To change the estate:
|
|
1767
|
-
|
|
1768
|
-
1. Edit the chant `.ts` source (the node's `sourceLoc`), or
|
|
1769
|
-
2. Trigger a committed Op via chant's MCP:
|
|
1770
|
-
- `op-run <name>` — start the project's `ApplyOp` (code→cloud) or `ReconcileOp`
|
|
1771
|
-
(cloud→code PR).
|
|
1772
|
-
- `op-signal <name> <gate>` — approve a gate (e.g. a destructive apply).
|
|
1773
|
-
- `op-status <name>` — watch phases; `op-report <name>`, the run report.
|
|
1774
|
-
|
|
1775
|
-
Every mutation is a gated, durable Temporal workflow with a human-confirmable gate
|
|
1776
|
-
and saga rollback. There is no behold endpoint that mutates the cloud.
|
|
1777
|
-
|
|
1778
|
-
A run behold triggered is asked for chant's run events (#679, chant#4019:
|
|
1779
|
-
`chant run <op> --events-json`, `chant run <target> --components --env <env>
|
|
1780
|
-
--events-json`), so the ops lens and the dial show each step's start and settle,
|
|
1781
|
-
a skip with chant's reason, a cache hit, and the gate or decision point a run
|
|
1782
|
-
waits on, as they happen, and a pending gate renders as a card with an Approve
|
|
1783
|
-
button. That button is `op-signal`, the same delegated write, and nothing else
|
|
1784
|
-
about the run is behold's to decide: the verdict is the stream's own
|
|
1785
|
-
`run-settle`, a stream that ends without one leaves the playhead at the last
|
|
1786
|
-
settled step and says it was lost, and a gate paints as pending only when chant
|
|
1787
|
-
named it (`gate-waiting`, or `chant run status`).
|
|
1788
|
-
|
|
1789
|
-
`src/run-events.ts` is the one boundary every run line crosses. It validates
|
|
1790
|
-
each line against chant's `run-event.schema.json` (vendored in
|
|
1791
|
-
`src/run-event-schema/` from @intentius/chant 0.124.28, its source commit in
|
|
1792
|
-
`RUN_EVENT_SCHEMA_SOURCE`), since the line comes from the project's chant,
|
|
1793
|
-
not behold's, and refuses a line that fails it; it folds the stream into what
|
|
1794
|
-
the dial and the ops lens render. The event types are chant's own `RunEvent`
|
|
1795
|
-
and `RunEventBody`, imported as types only. `src/run-events-chant.test.ts`
|
|
1796
|
-
runs the whole path against a real chant when `BEHOLD_TEST_CHANT_BIN` is set.
|
|
1797
|
-
|
|
1798
|
-
A run behold did not start is followed when the status read names it: `chant
|
|
1799
|
-
run events <run> --json --follow` replays what chant kept on this host and tails
|
|
1800
|
-
it to `run-settle`. A run killed outright writes no settle, so a follow that is
|
|
1801
|
-
silent for `BEHOLD_RUN_EVENTS_IDLE_MS` (60 s) asks `chant run status` whether it
|
|
1802
|
-
still runs, and ends as lost when it does not or after
|
|
1803
|
-
`BEHOLD_RUN_EVENTS_MAX_IDLE_MS` (30 min) of silence. A steward run keeps no
|
|
1804
|
-
events here, and the playhead says so.
|
|
1805
|
-
|
|
1806
|
-
The read has a floor, `RUN_EVENTS_CHANT_FLOOR` (0.124.28). Below it behold
|
|
1807
|
-
starts runs with the older `--progress-json` (degraded mode: settled steps
|
|
1808
|
-
only, no skip reasons, cache hits or gate events, and no follow), translates
|
|
1809
|
-
those lines at the same boundary, and the dial and the playhead say they are
|
|
1810
|
-
degraded. A local pipeline run (gitlab-ci-local, a forgejo runner) is the one
|
|
1811
|
-
path that still reads a log, because chant does not run it; the dial labels it
|
|
1812
|
-
best-effort, and only its exit code is certain (src/ci-run.ts).
|
|
1813
|
-
|
|
1814
|
-
### The executor contract (#165, #61)
|
|
1815
|
-
|
|
1816
|
-
A member's `chant.config.ts` may designate which forge deploys an environment,
|
|
1817
|
-
on the environment's entry (#470):
|
|
1818
|
-
|
|
1819
|
-
```ts
|
|
1820
|
-
environments: [{ name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } }]
|
|
1821
|
-
```
|
|
1822
|
-
|
|
1823
|
-
behold reads it from `chant workspace graph --composites --json`
|
|
1824
|
-
(`components[].environments[].executor`, floor `EXECUTOR_CHANT_FLOOR` 0.124.47,
|
|
1825
|
-
src/executor.ts) through the workspace reader. It never reads `.behold.json`'s
|
|
1826
|
-
`executor` (retired; `behold doctor` warns), and never derives it from a
|
|
1827
|
-
`chant-components-<env>` workflow name (maintainer ruling, 2026-10-23). An older
|
|
1828
|
-
chant prints no `executor`, and no row means none declared. `reason.code`
|
|
1829
|
-
`executor-config-unreadable` stays designated and fails closed.
|
|
1830
|
-
|
|
1831
|
-
It designates the committed WORKFLOW, not just the forge: two environments'
|
|
1832
|
-
generated pipelines carry identical job ids, so a picker cannot tell them
|
|
1833
|
-
apart, and a contract that names prod must not sit on a guess. For a
|
|
1834
|
-
designated env, `POST /api/apply` and a committed ApplyOp's `/api/ops/:name/run`
|
|
1835
|
-
answer `409 {code: "executor-forge"}`, auto-sync declines out loud, and the
|
|
1836
|
-
only deploy is `POST /api/ci/dispatch?env=<env>`, which runs the designated
|
|
1837
|
-
workflow through the operator's own `gh` and follows it on the dial. Any
|
|
1838
|
-
approval the workflow's environment requires is granted on the forge by a
|
|
1839
|
-
GitHub identity behold does not have; the dial links the run's page and offers
|
|
1840
|
-
nothing else. Fail-closed: a designation behold cannot honour (a typo'd forge,
|
|
1841
|
-
a missing or non-dispatchable workflow, a forge with no trigger here) disables
|
|
1842
|
-
Deploy for that env with the reason on `/api/project`'s `executor` block, and
|
|
1843
|
-
never falls back to running it here. `/api/project` reports `{forge, workflow,
|
|
1844
|
-
ok, reason?}` per designated env.
|
|
1845
|
-
|
|
1846
|
-
Without a designation, dispatch picks the committed workflow named for the env
|
|
1847
|
-
(`chant-components-<env>`, chant ≥ 0.54.0); on the older job-overlap match it
|
|
1848
|
-
refuses a tie rather than letting directory order choose, and a workflow named
|
|
1849
|
-
for another env never stands in. `just e2e-ci-github` proves the contract
|
|
1850
|
-
against the real forge (example-ci + `.github/workflows/behold-e2e-dispatch.yml`),
|
|
1851
|
-
including the `lost` verdict, which `BEHOLD_CI_FOLLOW_TIMEOUT_MS` and
|
|
1852
|
-
`BEHOLD_CI_POLL_FAIL_BUDGET` let a run force on purpose; a lost run is the one
|
|
1853
|
-
`POST /api/ci/readopt` re-follows. The same e2e dispatches into an environment
|
|
1854
|
-
with a required reviewer (`behold-e2e-gated`): the run holds at `waiting`, the
|
|
1855
|
-
progress state carries `waiting: true` and the run's `url`, the now-line says
|
|
1856
|
-
the approval is granted on the forge, and a cancellation lands as `failed`.
|
|
1857
|
-
|
|
1858
|
-
A dispatched run is followed honestly (#165 §6, PR #350): only GitHub's own
|
|
1859
|
-
`completed` + conclusion paints `ok`/`failed`; a poll-failure budget or the
|
|
1860
|
-
follow deadline promotes the run to `lost` (chips frozen at last-observed,
|
|
1861
|
-
the run possibly still live at its own page), never to a verdict. The adopted
|
|
1862
|
-
run id is persisted as one JSON per project under `~/.behold/ci-runs/`, the
|
|
1863
|
-
operator's machine-state, outside the project tree, so behold still writes
|
|
1864
|
-
nothing in a served project (the Invariant below). `GET /api/ci/run` reads the
|
|
1865
|
-
record; `POST /api/ci/readopt` (also attempted once at boot) re-follows an
|
|
1866
|
-
unconcluded run by its saved id, so a restart mid-deploy leaves the run a
|
|
1867
|
-
reader instead of nothing.
|
|
1868
|
-
|
|
1869
|
-
## The operating loop (a strip, a timeline, and a gate that is not the run gate)
|
|
1870
|
-
|
|
1871
|
-
A project that declares a `ConvergeOp` gets an operator strip on the ops lens:
|
|
1872
|
-
per loop, the last tick's own log line (verbatim, with its instant), the lease,
|
|
1873
|
-
and how many gates are pending. **One** tick — `chant operator status` keeps only
|
|
1874
|
-
`records.at(-1)`, so the strip is never a timeline, and it says so.
|
|
1875
|
-
|
|
1876
|
-
The timeline is its own read: `GET /api/operator/log` → `chant operator log
|
|
1877
|
-
--json` (chant#2029), the tick records and the gate resolutions against them
|
|
1878
|
-
merged oldest-first. It lives in a panel that grows from the strip, and two rules
|
|
1879
|
-
hold it there. It is **pulled**, on the click that opens it and never on a timer.
|
|
1880
|
-
And it is **bounded** — `--limit` on every invocation, 50 by default and 200 at
|
|
1881
|
-
most, `--since` when asked, because the ledger grows one line per tick forever;
|
|
1882
|
-
the answer reports the window it used, so a full one can't read as the end of
|
|
1883
|
-
history. The route checks the project's chant version *before* it spawns: below
|
|
1884
|
-
0.53.1, `chant operator log` resolves to `chant operator`, the tick daemon, and
|
|
1885
|
-
behold reading a history must never become behold running an operator.
|
|
1886
|
-
|
|
1887
|
-
Since chant 0.53.1 (chant#2027) a tick record carries an `id` and the
|
|
1888
|
-
per-component verdicts it derived, and both ride through to
|
|
1889
|
-
`[].lastTick.{id,components}`. The strip line names the tick (truncated), and
|
|
1890
|
-
the verdicts join onto the component DAG by component name, the same key the
|
|
1891
|
-
live `chant components status` read is joined by. They join **under** that read:
|
|
1892
|
-
a tick only ever feeds the last tier of `componentStatusColor` (the
|
|
1893
|
-
reconciliation verdict), only on a node the live read left unpainted, and only
|
|
1894
|
-
while the tick is younger than fifteen of chant's own operator rounds. Past
|
|
1895
|
-
that it is named on the node, dated, and painted nothing: a graph fill has
|
|
1896
|
-
nowhere to put "as of an hour ago". A chant older than 0.53.1 sends neither
|
|
1897
|
-
field and every one of these paths is a no-op.
|
|
1898
|
-
|
|
1899
|
-
Two gate cards exist and they are **different acts**:
|
|
1900
|
-
|
|
1901
|
-
- The **run gate** — `POST /api/ops/:name/signal/:gate` → `chant run approve
|
|
1902
|
-
<op> <gate>` (chant#2121 renamed `chant run signal`, #459). Records the
|
|
1903
|
-
resolution; a runtime that parks a run is woken, and the local one reads it
|
|
1904
|
-
when the Op runs again (behold runs `chant run <op> --events-json`, which
|
|
1905
|
-
says `gate-waiting`, settles `gated` and exits 3).
|
|
1906
|
-
- The **converge gate** — `POST /api/operator/approve/:op/:gate` →
|
|
1907
|
-
`chant approve <op> <gate>`. **Records a fact and unblocks nothing.** chant's
|
|
1908
|
-
gate ledger says it outright: the local executor still refuses a gated op,
|
|
1909
|
-
resolution or not. The next tick reads the fact. The card says this in its
|
|
1910
|
-
body, and the toast after the click says "recorded; the next tick acts on it".
|
|
1911
|
-
|
|
1912
|
-
A gate fact carries its address since chant#2028, on both halves, and the card
|
|
1913
|
-
links it under chant's own words — `approve at: <url>`. The field is optional by
|
|
1914
|
-
design (a local tick with no PR behind it has none) and never synthesized, so a
|
|
1915
|
-
fact without one renders no link and no placeholder for one, and a url behold
|
|
1916
|
-
would not put behind an `href` reads as no address at all.
|
|
1917
|
-
|
|
1918
|
-
A gate someone already resolved simply leaves `pendingGates`, the status read
|
|
1919
|
-
carries no `resolvedBy`/`when`, so the strip shows no resolved-by line rather
|
|
1920
|
-
than attributing an approval to nobody. The timeline is where resolutions are
|
|
1921
|
-
named, because there they are records rather than an inference.
|
|
1922
|
-
|
|
1923
|
-
An `OperatorStack` (chant#1940) declares the loop as a k8s estate, so it already
|
|
1924
|
-
appears in the entity graph. behold names it there, the Namespace as the loop's
|
|
1925
|
-
home, each CronJob as a converge tick — off chant's own
|
|
1926
|
-
`app.kubernetes.io/component: converge-tick` labels, never a naming convention.
|
|
1927
|
-
|
|
1928
|
-
## Who an approval is recorded as (#690)
|
|
1929
|
-
|
|
1930
|
-
chant never signs a person in (ws-052); the surface that does passes the person
|
|
1931
|
-
to chant as `--actor` (ws-080). behold has no login, so `src/approver.ts` names
|
|
1932
|
-
the person for each request, in this order:
|
|
1933
|
-
|
|
1934
|
-
- `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, the per-user settings'
|
|
1935
|
-
`approver.header`): behold sits behind a proxy that signed the person in
|
|
1936
|
-
through the forge or OIDC, and the header names them. A bare login is an
|
|
1937
|
-
account on `--identity-forge` (github unless set). A request without the
|
|
1938
|
-
header approves nothing (`403 no-identity`). Refused at startup with a
|
|
1939
|
-
`--host` other than loopback, since anyone reaching the port could send it.
|
|
1940
|
-
- `--as <principal>` (BEHOLD_APPROVER, the per-user settings' `approver.as`): one
|
|
1941
|
-
person runs behold and names themselves, `github:<login>` or a principal the
|
|
1942
|
-
signers file lists.
|
|
1943
|
-
- Neither: chant's own fallback (GITHUB_ACTOR, GITLAB_USER_LOGIN, USER), and
|
|
1944
|
-
behold passes no `--actor`.
|
|
1945
|
-
|
|
1946
|
-
Without a trusted header, a request carrying a usual proxy identity header
|
|
1947
|
-
(`PROXY_IDENTITY_HEADERS`, such as `X-Forwarded-User`) is refused with `403
|
|
1948
|
-
identity-header` on every approve route, rather than recorded as someone else.
|
|
1949
|
-
Every approve route (`/api/workspace/gates/approve`, the converge gate's
|
|
1950
|
-
`/api/operator/approve`, the run gate's `/api/ops/:name/signal`) adds
|
|
1951
|
-
`--actor` (`--approver` on `chant run approve`) and `--note "approved in
|
|
1952
|
-
behold"`. chant's ledger has no channel for a surface (its `origin` is `cli`,
|
|
1953
|
-
`mcp` or `acp`), so the note is where behold is named. A workspace gate that
|
|
1954
|
-
status marks `signed` is approved with `--sign <key>` when behold holds the
|
|
1955
|
-
person's key (`--signing-key` beside `--as`, or the per-user settings'
|
|
1956
|
-
`approver.keys` by principal) and refused `422 signed` with the line to run
|
|
1957
|
-
otherwise. The key path never reaches a page: `GET /api/workspace/gates`
|
|
1958
|
-
carries `approverIdentity: {principal, source, forge, signs}`, or `approver:
|
|
1959
|
-
null` and `approverRefusal`. `src/approver-chant.test.ts` runs the whole path
|
|
1960
|
-
against chant with a throwaway key and workspace.
|
|
1961
|
-
|
|
1962
|
-
## The trunk lane (#680)
|
|
1963
|
-
|
|
1964
|
-
`GET /api/workspace/lane` (src/trunk-lane.ts) answers "what is in flight and
|
|
1965
|
-
where is it?" for a served workspace, read through the reader on every request
|
|
1966
|
-
and kept nowhere:
|
|
1967
|
-
|
|
1968
|
-
- `chant ci list --json` at the root: the trunk's commits within ci.green's
|
|
1969
|
-
window, each `green`, `revoked` or `undecided`, with its phases and runs
|
|
1970
|
-
and its work items (`work`, chant#4029). It reads local tags only, so a
|
|
1971
|
-
commit that failed without ever being green reads `undecided`.
|
|
1972
|
-
- `chant workspace status <env> --json` once per environment, in the order the
|
|
1973
|
-
members' `promotionOrder` gives (merged in member order): the gates with
|
|
1974
|
-
`env` equal to that environment, with `gitSha`, `runId` and `changeSet`, and
|
|
1975
|
-
the deploy records.
|
|
1976
|
-
- `chant release list --json` in each member whose promotion order is not
|
|
1977
|
-
empty: the releases, each with its commit and the environments that run it.
|
|
1978
|
-
|
|
1979
|
-
The answer: `trunk` (or `trunkRefusal`), `commits[]` with `where` (`runs` or
|
|
1980
|
-
`waits` per environment), `environments[]` with `releases`, `deploys` (records
|
|
1981
|
-
no release covers) and `waiting` (each gate with `commitState`),
|
|
1982
|
-
`order` (`promotion`, or `env` when no member declares one), `releaseRefusals`,
|
|
1983
|
-
and the gate strip's approver fields. Gates with no environment stay in the
|
|
1984
|
-
gate strip. The three reads are `ci list` and `release list` through
|
|
1985
|
-
`readTrunk` on the reader (they are contract 1 documents outside `chant
|
|
1986
|
-
workspace`) and `status` through `read`; each has its floor in
|
|
1987
|
-
src/chant-floors.ts (0.124.28), and the route refuses a chant below any of them
|
|
1988
|
-
before spawning. The panel's Trunk tab (web/trunk-lane.js) reads it when opened
|
|
1989
|
-
and approves through `POST /api/workspace/gates/approve`.
|
|
1990
|
-
|
|
1991
|
-
The release column (#692) sits between the commits and the environments:
|
|
1992
|
-
`releases[]`, every release `release list` names, newest first, each with its
|
|
1993
|
-
`commit`, `label` and digest, its newest `cut` (who, when, and chant's
|
|
1994
|
-
`signatureCheck`), `runs` (environments in promotion order, with components),
|
|
1995
|
-
`waits` (a release gate that binds it, or a gate of its member reached at its
|
|
1996
|
-
commit; `pending`, or `superseded`), and `next`, the environment its member's
|
|
1997
|
-
promotion order names after the last one that runs it (null in the last one,
|
|
1998
|
-
and for a revoked release, which chant never promotes). Each commit carries
|
|
1999
|
-
`cuts`, the releases cut from it.
|
|
2000
|
-
|
|
2001
|
-
`configOnly` is true when a release carries artifact digests and they equal
|
|
2002
|
-
its previous release's. The previous release is the one of the same member
|
|
2003
|
-
cut from the nearest older commit: releases are ordered by their commit's
|
|
2004
|
-
place in the trunk list (first-parent, newest first), a commit older than the
|
|
2005
|
-
list after every listed one, and ties (one commit, or commits outside the
|
|
2006
|
-
list) by `release list`'s order, newest cut first. That is how `release cut`
|
|
2007
|
-
reuses an unchanged artifact's digest. It is null for the oldest release and
|
|
2008
|
-
for a release with no artifact digests (a member with no components).
|
|
2009
|
-
|
|
2010
|
-
The revoked fields ship in chant 0.124.29 (`RELEASE_COLUMN_CHANT_FLOOR`,
|
|
2011
|
-
chant#4033, chant#4043): `revoked` on a `release list` release (the
|
|
2012
|
-
ci/revoked tag, with `rollback`, the lines status gives for each component
|
|
2013
|
-
running it), `superseded` on each environment (release gates chant reads as
|
|
2014
|
-
superseded, never approvable), `rollback` on an environment's releases, and
|
|
2015
|
-
`release` and `rollback` on a deploy record. `releaseColumn: {full, floor}`
|
|
2016
|
-
says whether they were read. Below the floor nothing is refused: the column
|
|
2017
|
-
comes from `release list` alone with no revoked mark, and the tab says which
|
|
2018
|
-
chant would add it.
|
|
2019
|
-
|
|
2020
|
-
A mixed environment (#731): from chant 0.124.29
|
|
2021
|
-
(`MIXED_ENVIRONMENT_CHANT_FLOOR`, chant#4035, chant#4072) status gives an
|
|
2022
|
-
environment `mixed` when its components run different releases, or a
|
|
2023
|
-
promote, rollback or redeploy left one `failed` or `gated` (its
|
|
2024
|
-
`outcomes.jsonl` on chant/lifecycle). Each environment carries `mixed[]`, one
|
|
2025
|
-
per member: `components` (each with its recorded `release`, `state` and the
|
|
2026
|
-
`attempt` that left it unsettled), `redeploy` lines and the `rollback` line,
|
|
2027
|
-
as chant wrote them. The tab heads the environment `(mixed)` and shows the
|
|
2028
|
-
lines to copy, run in the member's directory; behold runs none of them.
|
|
2029
|
-
`mixedEnvironments: {read, floor}` says whether it was read; below the floor
|
|
2030
|
-
`mixed` is empty and the lane is drawn as before.
|
|
2031
|
-
|
|
2032
|
-
The fixtures in `src/__fixtures__/trunk-lane/` are recorded from chant main
|
|
2033
|
-
in the workspace `src/trunk-lane-fixture.ts` makes (staging carries a deploy
|
|
2034
|
-
outcome: v3's promote deployed api and failed on web), and
|
|
2035
|
-
`src/trunk-lane-chant.test.ts` reads the same workspace through a real chant
|
|
2036
|
-
when `BEHOLD_TEST_CHANT_BIN` names one.
|
|
2037
|
-
|
|
2038
|
-
## A gate's change set on the graph (#681)
|
|
2039
|
-
|
|
2040
|
-
`GET /api/workspace/change-set?gate=<member>/<op>/<gate>&env=<env>`
|
|
2041
|
-
(src/change-set-overlay.ts) reads the gate from `chant workspace status <env>
|
|
2042
|
-
--json`, never from the page, and the change set it binds (`changeSet`,
|
|
2043
|
-
chant#4022) from `chant change-set show <digest> --member <member> --json`
|
|
2044
|
-
(`readChangeSet` on the reader, floor `CHANGE_SET_SHOW_CHANT_FLOOR`,
|
|
2045
|
-
0.124.28). The answer is that document keyed by graph node: `entries` (those
|
|
2046
|
-
that change something, each with `bucket` create, change or delete and `node`,
|
|
2047
|
-
or null where chant mapped none), `nodes` (`<member>/<id>` to the strongest
|
|
2048
|
-
bucket and the actions on it), `counts`, `unchanged`, `gaps` (members that
|
|
2049
|
-
failed to plan or have holes), `gate` (commit, run, `releaseDigest`) and
|
|
2050
|
-
`planned` (a release gate's release and environment, chant#4045). An entry
|
|
2051
|
-
with no node is kept and listed in the Change set tab, never dropped. An entry
|
|
2052
|
-
for one instance of a counted block (#996) is put on the instance's node,
|
|
2053
|
-
`<blockNode>[k]`, with `block` naming the block, whether chant mapped it to the
|
|
2054
|
-
block node (before chant#4454) or the instance node; the block's node carries
|
|
2055
|
-
the rollup (`instances`), so its card is outlined when the instance cards are
|
|
2056
|
-
not drawn. The page
|
|
2057
|
-
(web/change-set-overlay.js) outlines each card in the drift legend's tokens
|
|
2058
|
-
(managed for create, foreign for update or replace, degraded for delete or
|
|
2059
|
-
forget) with a tag above it, never a fill; it is opened from the "change set"
|
|
2060
|
-
link on a Trunk tab gate card and turned off from its tab. A public view
|
|
2061
|
-
refuses the route, as it refuses the lane.
|
|
2062
|
-
|
|
2063
|
-
## Feature flags on the graph (#683)
|
|
2064
|
-
|
|
2065
|
-
`GET /api/workspace/flags` (src/feature-flags.ts) reads each member's
|
|
2066
|
-
`featureFlags` from `chant workspace status <env> --json` (chant#4024, floor
|
|
2067
|
-
`FEATURE_FLAGS_CHANT_FLOOR`, 0.124.29): per flag its `param`, `owner`, `work`
|
|
2068
|
-
with its state, `values` per environment and `stale`, the stale-flag lint's
|
|
2069
|
-
verdict (WSP118). It reads status in each environment of the promotion order
|
|
2070
|
-
for the waiting gates, and for each gate of a flagged member with a stored
|
|
2071
|
-
change set, `chant change-set show`, keeping the entries whose attribute
|
|
2072
|
-
`param:<param>` moves the flag's parameter (`waiting`, with before, after and
|
|
2073
|
-
the node chant mapped, which is null for a release's `chant:component`
|
|
2074
|
-
entry). chant names no graph node that reads a build parameter, so a flag
|
|
2075
|
-
marks every card of its member (`nodes: "member"`); behold infers no finer
|
|
2076
|
-
mapping. behold writes no flag record and has no flag write route: a waiting
|
|
2077
|
-
flip opens #681's change-set overlay for its gate, and otherwise `turnOn`
|
|
2078
|
-
carries the lines a person runs (`chant workspace records amend <id> --kind
|
|
2079
|
-
<kind> --set -` with the new values, then `git commit` of the record). The
|
|
2080
|
-
page (web/feature-flags.js) is the Flags tab and a tag under each flagged
|
|
2081
|
-
card in the environment the tab picks. Below the floor the route answers the
|
|
2082
|
-
refusal and `degraded`, and the graph draws no marks. A public view refuses
|
|
2083
|
-
the route. `src/feature-flags-chant.test.ts` reads the workspace
|
|
2084
|
-
`src/feature-flags-fixture.ts` makes through a real chant when
|
|
2085
|
-
`BEHOLD_TEST_CHANT_BIN` names one.
|
|
2086
|
-
## The why chain (#682)
|
|
2087
|
-
|
|
2088
|
-
From chant 0.124.29 the intent document `GET /api/workspace/why` reads carries
|
|
2089
|
-
`trace` (chant#4023): for each commit chant walked, the work items its
|
|
2090
|
-
`Chant-Record` or `Chant-Lease` trailer names (judged linked, unlinked, wrong
|
|
2091
|
-
or merge), the work items whose window it fell in (listed apart, never a
|
|
2092
|
-
link), its ci tag, the release cut from it or containing it, that release's
|
|
2093
|
-
gate resolutions (who, channel, when, the plan and the change set stored
|
|
2094
|
-
under it) and its deploys per environment. Every link names its source
|
|
2095
|
-
record (`source: {ref, field, value}`: a commit, a tag ref, a work record's
|
|
2096
|
-
file, or `chant/lifecycle:<path>`), and the pane gives each as the `git show`
|
|
2097
|
-
line that opens it, with a copy button. A link chant found nothing for is
|
|
2098
|
-
drawn as missing, with chant's reason where it gives one, and `trace.reasons`
|
|
2099
|
-
(`ledger-unreadable`, `declaration-invalid`) as partial-read notices. behold
|
|
2100
|
-
adds each commit's subject and each work item's title from the same
|
|
2101
|
-
document's `nodes` and joins nothing: a commit names its release and deploys
|
|
2102
|
-
by id in the same trace. A release gate's change set is shown as `chant
|
|
2103
|
-
change-set show <digest> --member <member>`, since the overlay (#681) opens
|
|
2104
|
-
only a gate still waiting.
|
|
2105
|
-
|
|
2106
|
-
The floor is `WHY_TRACE_CHANT_FLOOR` (0.124.29, read "why chain"). Below it
|
|
2107
|
-
nothing is refused: the answer has `trace: null` and `chain: {full: false,
|
|
2108
|
-
floor, note}`, and the pane shows the decisions, runs and commits it always
|
|
2109
|
-
did with the note. `src/why-trace-schema/intent.schema.json` is chant's
|
|
2110
|
-
intent schema at 5d33a48e7; `src/__fixtures__/why-trace/` was recorded from
|
|
2111
|
-
chant main at that commit in the workspace `src/why-trace-fixture.ts` makes,
|
|
2112
|
-
and `src/why-trace-chant.test.ts` reads the same workspace through a real
|
|
2113
|
-
chant when `BEHOLD_TEST_CHANT_BIN` names one.
|
|
2114
|
-
|
|
2115
|
-
## Collision marks (#684)
|
|
2116
|
-
|
|
2117
|
-
`GET /api/workspace/collisions` (src/collision-marks.ts) reads `overlap` from
|
|
2118
|
-
`chant workspace status <env> --json` (chant#4025, floor `OVERLAP_CHANT_FLOOR`,
|
|
2119
|
-
0.124.29): the in-flight work items with a linked commit, and each pair of
|
|
2120
|
-
them that changed one file or that a waiting gate's change set reaches at one
|
|
2121
|
-
entry. An entry names its graph node (`<member>/<id>`), and that node is what
|
|
2122
|
-
the graph marks (`nodes`, each with the items colliding there and the entries
|
|
2123
|
-
behind it). Files two items both changed have no node, and neither does an
|
|
2124
|
-
entry chant mapped to none: both go in a side list (`files`, `unplaced`).
|
|
2125
|
-
`items` holds every in-flight item with `with`, the items it collides with
|
|
2126
|
-
(empty for most). `overlap` absent is an older chant (`no-overlap`), and
|
|
2127
|
-
`null` is no work kind declared or a failed read (`overlap-unavailable`); both
|
|
2128
|
-
are refusals worded apart. One status read, through the read contract. behold
|
|
2129
|
-
records, locks and refuses nothing. The page (web/collision-marks.js) is the
|
|
2130
|
-
Collisions tab, a dashed ring and a tag under each marked card, and the
|
|
2131
|
-
filter, "Show only colliding work": it hides every card that is not a marked
|
|
2132
|
-
node and every edge with an unmarked end, and lists only the items that
|
|
2133
|
-
collide. Below the floor the route answers the refusal and `degraded`, and
|
|
2134
|
-
the graph draws no marks. A public view refuses the route.
|
|
2135
|
-
`src/collision-marks-chant.test.ts` reads the workspace
|
|
2136
|
-
`src/collision-fixture.ts` makes through a real chant when
|
|
2137
|
-
`BEHOLD_TEST_CHANT_BIN` names one. `status.schema.json` in
|
|
2138
|
-
src/trunk-lane-schemas/ is chant main at e9c996e93.
|
|
2139
|
-
|
|
2140
|
-
## Open decision points beside their gates (#472)
|
|
2141
|
-
|
|
2142
|
-
The approvals inbox is arugula's rail (arugula-salad/arugula#621); behold
|
|
2143
|
-
draws open decision points and answers none. `GET /api/workspace/points`
|
|
2144
|
-
(src/decision-points.ts) reads `chant workspace points --open --json` through
|
|
2145
|
-
the reader's `readPoints` (floor `DECISION_POINTS_CHANT_FLOOR`, 0.107.0, the
|
|
2146
|
-
chant where a gate can ask a point, chant#3170). chant's conformance suite
|
|
2147
|
-
does not list `points`, so the read is not in `BEHOLD_READS`; the reader test
|
|
2148
|
-
holds every other module to not naming it. Each open question carries its
|
|
2149
|
-
point's question, who may answer (the quorum's count and roles), a model's
|
|
2150
|
-
proposal when there is one, and chant's `points answer` line. A gate that
|
|
2151
|
-
asks a point carries `answer` in `workspace status` (the open question's id,
|
|
2152
|
-
its point and path), and its `approve` is that same `points answer` line. The
|
|
2153
|
-
gate strip (web/decision-points.js, web/workspace-gates.js) puts a question
|
|
2154
|
-
on the card of the gate whose `answer.id` names it and gives a question no
|
|
2155
|
-
waiting gate names a card of its own, naming the gate from its
|
|
2156
|
-
`gate:<op>/<gate>@<env>` subject when a gate asked it. Such a gate gets no
|
|
2157
|
-
approve button, framed or not, and `POST /api/workspace/gates/approve`
|
|
2158
|
-
refuses it with `422 decision-point`. Standalone, a point card shows the line
|
|
2159
|
-
as text to copy; framed, it says to answer in the host's rail. There is no
|
|
2160
|
-
write route. Below the floor the route answers the refusal and `degraded`,
|
|
2161
|
-
and the strip says which chant adds points. A public view refuses the route.
|
|
2162
|
-
`src/decision-points-chant.test.ts` reads the workspace
|
|
2163
|
-
`src/decision-points-fixture.ts` makes through a real chant when
|
|
2164
|
-
`BEHOLD_TEST_CHANT_BIN` names one; src/__fixtures__/decision-points/ is
|
|
2165
|
-
chant 0.124.31's output for it.
|
|
2166
|
-
|
|
2167
|
-
## Runtime health and rotation (#825)
|
|
2168
|
-
|
|
2169
|
-
`GET /api/health?env=<env>` (src/health-overlay.ts) reads `chant lifecycle
|
|
2170
|
-
health <env> --json` (chant#4177, floor `HEALTH_CHANT_FLOOR`, 0.124.33, read
|
|
2171
|
-
"runtime health") once per chant project: the served project, or each chant
|
|
2172
|
-
member of a workspace or an estate in its own directory with its own chant,
|
|
2173
|
-
ids composed `<member>/<id>`. The read is the reader's `readHealth`
|
|
2174
|
-
(src/workspace-reader.ts). Its document is `chant-health/v1`, not a contract 1
|
|
2175
|
-
document, so it is checked against chant's schema, vendored unchanged in
|
|
2176
|
-
src/health-schema/ (chant PR #4193 at d727944c4) and validated with ajv, with
|
|
2177
|
-
a hole's `reason` loosened to any string; a document the schema refuses is
|
|
2178
|
-
refused whole. A project with no lexicon that reads health is `none`, not a
|
|
2179
|
-
failure. A member of another kind (#997) is listed as `none` without a
|
|
2180
|
-
spawn: the read builds a chant project and it has none. A member below the
|
|
2181
|
-
floor is refused before anything is spawned; when
|
|
2182
|
-
every member is, the answer carries the refusal and `degraded`.
|
|
2183
|
-
|
|
2184
|
-
The answer is `nodes` (per id: `healthy`, `unhealthy` or `unknown` with
|
|
2185
|
-
chant's `detail`, `observedAt` and `checkedAt`; `unobserved` with chant's
|
|
2186
|
-
`reason`; or `absent`), `rotation`, `members` and `counts`. Rotation is
|
|
2187
|
-
behold's (src/runtime-health.ts, `rotationOf`): a Route 53 record whose
|
|
2188
|
-
`HealthCheckId` edge (or `$ref` attribute) names a declared check is out of
|
|
2189
|
-
rotation only when that check is unhealthy, in rotation when it is healthy,
|
|
2190
|
-
and `inRotation: null` with the reason in words otherwise. The edges come
|
|
2191
|
-
from each member's cached source graph (`memberIr` at detail 2). The answer
|
|
2192
|
-
is cached per environment for 30 s, `?fresh=1` reads again, and `POST
|
|
2193
|
-
/api/refresh` drops it. A public view refuses the route (it reads the live
|
|
2194
|
-
estate with behold's credentials), and `behold export` captures it once per
|
|
2195
|
-
environment. The page (web/health-marks.js) draws a tag under each card, a
|
|
2196
|
-
solid ring on an unhealthy one and a dashed ring on a hole, dims a record out
|
|
2197
|
-
of rotation with its edges, counts the states in the Model tab and shows the
|
|
2198
|
-
detail in the inspect pane. It never changes a card's fill.
|
|
2199
|
-
`src/__fixtures__/health/` was recorded from chant main at cd9a90716 against
|
|
2200
|
-
a floci whose health checks probe (lex00/floci#259); src/runtime-health.test.ts
|
|
2201
|
-
names each file's provenance. A multi-stack document (a project that declares
|
|
2202
|
-
`stacks`) is keyed `<member>/<stack>::<name>` (#824), the ids chant's live
|
|
2203
|
-
overlay gives that project's nodes.
|
|
2204
|
-
|
|
2205
|
-
## The three-cloud demo (#824)
|
|
2206
|
-
|
|
2207
|
-
`example-three-cloud` is a chant workspace (`dns`, `aws`, `azure`, `gcp`) on
|
|
2208
|
-
floci, floci-az and floci-gcp; docs/src/content/docs/using/three-cloud.mdx is
|
|
2209
|
-
its page. `azure` is a choudoufu estate (`azure/*.tf`, choudoufu#2246), so the
|
|
2210
|
-
demo requires choudoufu, `--local` boots no emulator for it (the setup starts
|
|
2211
|
-
floci-az, with TLS), and the root's `chant.config.json` names it as the
|
|
2212
|
-
terraform lexicon's `azure` root. `aws` is a Pulumi program on plunge
|
|
2213
|
-
(behold#1000: `aws/index.ts`, kind `pulumi`, `Pulumi.yaml` naming the
|
|
2214
|
-
`plunge+file://./.plunge` backend), so the demo requires plunge too
|
|
2215
|
-
(PLUNGE_BIN counts, as CHOUDOUFU_BIN does). `scripts/front-door.ts plan --out <file>`
|
|
2216
|
-
(`npm run change-set`) composes one change set, a part per engine: chant
|
|
2217
|
-
parts for dns and gcp, azure's choudoufu part from `choudoufuPlanSet`, and
|
|
2218
|
-
aws's pulumi part from `plunge preview` (`previewPulumiMember`);
|
|
2219
|
-
e2e/three-cloud-change-set-e2e.sh asserts it. `apply --change-set <file>`
|
|
2220
|
-
plans again and refuses the whole set, exit 3, when any part moved
|
|
2221
|
-
(.front-door/apply-verdict.json names each), and `oob-edit <member>` makes
|
|
2222
|
-
one out-of-band edit per member for the live run;
|
|
2223
|
-
e2e/multi-engine-demo-e2e.sh asserts the composed graph, a colour change per
|
|
2224
|
-
engine and the refusal, with a fake plunge and recorded drift streams. dns
|
|
2225
|
-
reads azure's `azureEndpoint` and aws's `awsEndpoint` through chant
|
|
2226
|
-
(chant#4455): dns/src/records.component.ts has `memberOutputsComponent("azure")`,
|
|
2227
|
-
`memberOutputsComponent("aws")` and a records step whose cfn-deploy inputs
|
|
2228
|
-
are `stackOutput("azure", "azureEndpoint")` and `stackOutput("aws",
|
|
2229
|
-
"awsEndpoint")`, and dns lists `terraform` (with `terraform.roots.azure` at
|
|
2230
|
-
`../azure`, which is the change signal) and `pulumi`. `member-outputs` and
|
|
2231
|
-
the pulumi lexicon are in chant 0.124.54 and newer, and the example depends on 0.124.58, and
|
|
2232
|
-
the workspace pins both lexicons by package at that version
|
|
2233
|
-
(`CHANT_RELEASE`, src/chant-release.ts); behold's own code does not import
|
|
2234
|
-
them, so there is no floor. scripts/front-door.ts loads the pulumi lexicon only for
|
|
2235
|
-
the aws plan, so `npm ci` in the example runs every other subcommand. The e2e's second half runs
|
|
2236
|
-
`chant components pr-plan --member dns` over a change to azure/ and asserts
|
|
2237
|
-
dns's records step names azure under its unresolved inputs. `behold demo three-cloud` runs `scripts/emulators-up.sh` (the
|
|
2238
|
-
emulators under chant's own container names, with the Docker socket, floci-az
|
|
2239
|
-
running Container Apps unmocked), then serves with `--local --env local`.
|
|
2240
|
-
`--local` on a workspace boots every chant member's emulators
|
|
2241
|
-
(`emulatorDirs`/`emulatorsUp` in src/emulator.ts), not the first member's, and
|
|
2242
|
-
tears down the same set. The `front-door` Op (`dns/ops/front-door.op.ts`)
|
|
2243
|
-
runs `scripts/front-door.ts`: apply all four (aws with `plunge up`, then `plunge stack export` into aws/stack-export.json, the export chant draws the member from), deactivate the Azure revision,
|
|
2244
|
-
wait for `azureCheck` to read unhealthy, then `behold export --open-env local
|
|
2245
|
-
--open-zoom composites --note …`. `--note` (`settleNote` in src/export.ts) is
|
|
2246
|
-
one line under 200 characters, written to the manifest as `note` and drawn at
|
|
2247
|
-
the foot of a static page by web/export-note.js, backticked spans as code.
|
|
2248
|
-
|
|
2249
|
-
## Invariant
|
|
2250
|
-
|
|
2251
|
-
If a request would have behold write to a cloud or to source directly, it's wrong.
|
|
2252
|
-
behold shows truth and triggers Ops. Authority stays in the committed source and the
|
|
2253
|
-
executor.
|
|
2254
|
-
|
|
2255
|
-
behold writes nothing in a served project (#469, ruled 2026-10-23). What it
|
|
2256
|
-
keeps for itself (the hand layout, the per-user settings, dispatched CI run
|
|
2257
|
-
ids, recents, the serve registry) lives in the user's own home, cache or temp directory, keyed by the
|
|
2258
|
-
project, never in the tree. The only files behold puts in a project are the
|
|
2259
|
-
ones a person asks for by name: `behold doctor --fix` writing
|
|
2260
|
-
`chant.workspace.json`, and the carve walkthrough writing into the demo copy
|
|
2261
|
-
behold made itself (both below).
|
|
2262
|
-
|
|
2263
|
-
The commands behold starts run with behold's own environment, so Deploy (`POST
|
|
2264
|
-
/api/apply`, chant's local executor) applies with the credentials of whoever
|
|
2265
|
-
started it. On a terragucci repo (a `terragucci.yml` in the served directory or
|
|
2266
|
-
above it, up to the git root) behold deploys, approves and applies nothing,
|
|
2267
|
-
and the only things it starts are terragucci's own request, rollout and
|
|
2268
|
-
action workflows (below):
|
|
2269
|
-
every other POST that deploys, approves or starts a run answers `409` with
|
|
2270
|
-
`code: "terragucci"` and names the pipeline (`src/terragucci-repo.ts`, #489), `/api/project` carries `terragucci`
|
|
2271
|
-
so the page offers no write, and auto-sync declines. The boundary is an
|
|
2272
|
-
allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
|
|
2273
|
-
any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
|
|
2274
|
-
method and route, and that list holds only the exceptions below (the layout
|
|
2275
|
-
cache, project open and reveal, demo open, refresh, and the four carve
|
|
2276
|
-
steps), plus `POST /api/view`, which moves the open tabs and writes nothing
|
|
2277
|
-
(#914), `POST /api/templates/request`, which dispatches terragucci's
|
|
2278
|
-
request workflow (behold#1035), `POST /api/templates/upgrade`, which
|
|
2279
|
-
dispatches its rollout workflow (behold#1036), and `POST
|
|
2280
|
-
/api/templates/action`, which dispatches its action workflow (behold#1037). A new write route is refused on a terragucci repo until it is added
|
|
2281
|
-
there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
|
|
2282
|
-
app (`app.routes`, built plain, with a carve report and with `--terragucci`)
|
|
2283
|
-
and asserts each one is allowlisted or answers 409, and that every allowlist
|
|
2284
|
-
entry is a registered route. `TERRAGUCCI_REFUSED_WRITES` only words the
|
|
2285
|
-
refusal for known routes. The remedy names `npx terragucci approve wave-<k>
|
|
2286
|
-
--plan <digest>`, the digest from the wave's gate card.
|
|
2287
|
-
|
|
2288
|
-
A SQL Yodeler repo (a `yodel.config.ts` in the served directory or above it,
|
|
2289
|
-
up to the git root) is guarded the same way (#517): the same allowlist, the
|
|
2290
|
-
same refused routes, auto-sync declined, and `/api/project` carries
|
|
2291
|
-
`sqlYodeler` so the page offers no write. The refusal is `409` with `code:
|
|
2292
|
-
"sql-yodeler"`, and its remedy names `npx yodel approve <env> --plan <digest>`
|
|
2293
|
-
(with `--sign` when the environment's gate is sealed) and `yodel apply <env>`
|
|
2294
|
-
in the project's pipeline. `productRepo()` in `src/terragucci-repo.ts` looks
|
|
2295
|
-
for terragucci's config along the whole walk first, so a yodel project nested
|
|
2296
|
-
inside a terragucci repo is refused as terragucci.
|
|
2297
|
-
|
|
2298
|
-
Op discovery (`src/ops.ts`) reads a gate from `signalName: "<name>"` or from
|
|
2299
|
-
`gate("<name>", ...)`, the form chant's op builder and SQL Yodeler write, so
|
|
2300
|
-
a gated Op is never listed or run as ungated on any repo (#517).
|
|
2301
|
-
|
|
2302
|
-
A policy denial is never approved from behold (#519, `src/policy-override.ts`).
|
|
2303
|
-
`GET /api/workspace/gates` gives a gate of op `policy-override` an `override`
|
|
2304
|
-
field `{subject, rules, plan, digest, state, spentAt, product, command,
|
|
2305
|
-
source}`: the rules and denied plan come from `chant/lifecycle:_gates/
|
|
2306
|
-
policy-override.jsonl` (read with `git show`, the local branch then
|
|
2307
|
-
`origin/chant/lifecycle`), `state` is `waiting`, `overridden` (status says an
|
|
2308
|
-
override counts) or `spent` (a line in `_gates/policy-override/applied.jsonl`
|
|
2309
|
-
for its digest), and `command` is the product's (`npx terragucci override`,
|
|
2310
|
-
`npx yodel override`) or chant's `chant approve policy-override <subject>
|
|
2311
|
-
--rule <id> --reason "<why>" --plan <digest>`. The card shows that command and
|
|
2312
|
-
no button, and `POST /api/workspace/gates/approve` answers such a gate `422`
|
|
2313
|
-
with `code: "override"`. The ledger lines are parsed by chant's
|
|
2314
|
-
`@intentius/chant/override-gate` (`recordedDenials`, `parseAppliedOverrides`,
|
|
2315
|
-
`overrideCommand`) and `parseGateLedger`, and the product is `productRepo()`
|
|
2316
|
-
from `src/terragucci-repo.ts` (#537).
|
|
2317
|
-
|
|
2318
|
-
### The exceptions, and their exact size
|
|
2319
|
-
|
|
2320
|
-
These are also the only writes a guarded product repo answers: terragucci
|
|
2321
|
-
(`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
|
|
2322
|
-
listed in `TERRAGUCCI_ALLOWED_WRITES`.
|
|
2323
|
-
|
|
2324
|
-
`POST /api/templates/request` (behold#1035, `src/templates.ts`),
|
|
2325
|
-
`POST /api/templates/upgrade` (behold#1036) and `POST /api/templates/action`
|
|
2326
|
-
(behold#1037) are the three starts on a terragucci repo, and they write
|
|
2327
|
-
nothing anywhere. The request is described first. It is on the
|
|
2328
|
-
allowlist, and because the list also guards SQL Yodeler repos the handler
|
|
2329
|
-
refuses on its own (`409`, the product's refusal or `code: "no-templates"`)
|
|
2330
|
-
unless the served repo is terragucci and its terragucci.yml sets
|
|
2331
|
-
`templates`. It checks the request against what the repo's own
|
|
2332
|
-
`terragucci templates list --json` printed (`GET /api/templates` answers that
|
|
2333
|
-
output byte for byte) and against chant's template-request/v1 (`@intentius/chant/template-request`), then dispatches
|
|
2334
|
-
the committed `terragucci-request.yml` with the inputs `template`, `version`,
|
|
2335
|
-
`name` and `inputs`, plus `claimed_by` (the person behold says filled the
|
|
2336
|
-
form) only when that workflow declares the input. On GitHub the dispatch and
|
|
2337
|
-
every read go through the operator's `gh` (`dispatchWorkflow`,
|
|
2338
|
-
`pullRequestOn` in src/gh-run.ts); on Forgejo through the HTTP API with the
|
|
2339
|
-
operator's `FORGEJO_TOKEN` (src/forgejo-api.ts), sent only to the origin's
|
|
2340
|
-
host and never stored or shown. GitLab has no request workflow and answers
|
|
2341
|
-
`422 request-forge` with the `npx terragucci request` line to run. behold
|
|
2342
|
-
never runs `terragucci request`, never shells out to plan or apply, and holds
|
|
2343
|
-
no apply credential: the run in CI opens the pull request with the repo's own
|
|
2344
|
-
token, its actor is the requester the forge vouches for, and the pull request
|
|
2345
|
-
is planned and reviewed like any other (ruling A of INTENTIUS/chant#4642). The
|
|
2346
|
-
follow runs in the runner's single slot, and `GET /api/templates/requests/:id`
|
|
2347
|
-
answers the run's end and the pull request's number and URL. `--public`
|
|
2348
|
-
refuses both reads (`403`) and the post (`405`).
|
|
2349
|
-
|
|
2350
|
-
With `app` in the body (behold#1036) the request asks for an add-on in that
|
|
2351
|
-
app's root. The template must be an add-on template (else `422 wrong-kind`),
|
|
2352
|
-
the app must be one the repo's own `terragucci templates apps --json` lists
|
|
2353
|
-
(`GET /api/templates/apps` answers that output byte for byte), else `422
|
|
2354
|
-
not-an-app`, and the add-on's name must not be a module the app's root already
|
|
2355
|
-
has (`422 addon-exists`). The dispatch adds the `app` input, and the branch is
|
|
2356
|
-
`request/<template>/<app>/<addon>`.
|
|
2357
|
-
|
|
2358
|
-
`POST /api/templates/upgrade` takes `{app, version?}`. It reads the apps again
|
|
2359
|
-
and takes the module and version from terragucci, never from the caller: the
|
|
2360
|
-
app's `template` and its `upgrade` (`422 not-an-app`, `422 no-upgrade` when
|
|
2361
|
-
`upgrade` is null, `409 stale-upgrade` when `version` is not it). It refuses
|
|
2362
|
-
on its own like the request, then dispatches the committed
|
|
2363
|
-
`terragucci-rollout.yml` with `module` and `version` only (`409
|
|
2364
|
-
no-rollout-workflow` when it is not committed, `409 terragucci-too-old` when
|
|
2365
|
-
it takes neither input), through the same `gh` and Forgejo paths and the same
|
|
2366
|
-
runner slot. A person starts it; terragucci's existing rollout opens one pull
|
|
2367
|
-
request per wave, and each wave is planned, reviewed and applied by the
|
|
2368
|
-
pipeline (ruling D). GitLab's rollout job takes no dispatch inputs, so GitLab
|
|
2369
|
-
answers `422 request-forge` with the `npx terragucci rollout` line. `--public`
|
|
2370
|
-
refuses the apps read (`403`) and the post (`405`).
|
|
2371
|
-
|
|
2372
|
-
`POST /api/templates/action` takes `{root, address}`. It reads the apps again,
|
|
2373
|
-
and the address must be one terragucci lists in that root's `actions` (`422
|
|
2374
|
-
not-an-app` for a root no app has, `422 unknown-action` otherwise); nothing
|
|
2375
|
-
starts before that. A root whose engine has no action invocation (terragucci.yml's
|
|
2376
|
-
`binary`, the repo's `.opentofu-version`, or `.tofu` files in the root, as
|
|
2377
|
-
terragucci detects it) answers `422 action-engine` naming OpenTofu or
|
|
2378
|
-
choudoufu (ruling E), and `/api/project` carries `terragucciActionRefusal` so
|
|
2379
|
-
the buttons say so. It refuses on its own like the request, then dispatches the
|
|
2380
|
-
committed `terragucci-action.yml` with `root` and `address` only (`409
|
|
2381
|
-
no-action-workflow` when it is not committed, which terragucci does only for
|
|
2382
|
-
Terraform roots; `409 terragucci-too-old` when it takes neither input), through
|
|
2383
|
-
the same `gh` and Forgejo paths and the same runner slot. The run asks chant's
|
|
2384
|
-
gated request (op `tf-action`, gate `<root>:<address>`) and waits for a person
|
|
2385
|
-
other than the requester to run `terragucci approve action <root> --plan
|
|
2386
|
-
<digest>`; behold approves nothing and never runs the action. The lifecycle
|
|
2387
|
-
lane reads `_gates/tf-action.jsonl` and `_gates/tf-action/applied.jsonl` into
|
|
2388
|
-
`actions` (`src/terragucci-lifecycle.ts`), apart from the waves: a waiting
|
|
2389
|
-
gate carries that approve line, the requester's own approval is listed as one
|
|
2390
|
-
that does not count, and an applied one carries the run's `ok` or `failed`.
|
|
2391
|
-
GitLab answers `422 request-forge` with the `npx terragucci action` line.
|
|
2392
|
-
`--public` refuses the post (`405`).
|
|
2393
|
-
|
|
2394
|
-
`POST /api/layout` (#228) writes **one** file, and not in the served project:
|
|
2395
|
-
the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
|
|
2396
|
-
with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
|
|
2397
|
-
`$XDG_CACHE_HOME` or `~/.cache`), `<key>` the first 32 hex characters of the
|
|
2398
|
-
sha256 of the project directory's realpath, and `BEHOLD_CACHE_DIR` replacing
|
|
2399
|
-
`<user cache>/behold`. The file is `{version, projectDir, lenses: {<lens>:
|
|
2400
|
-
{<node id>: {dx,dy,dw,dh}}}}`, mode 0600 in a 0700 directory (src/layout.ts):
|
|
2401
|
-
|
|
2402
|
-
- It is **one operator's view**, not estate truth. Deltas describe how *you*
|
|
2403
|
-
want the picture arranged on top of dagre's layout; the graph underneath
|
|
2404
|
-
stays chant's, and a delta for a node that left the estate is dropped on read.
|
|
2405
|
-
- It **never touches the cloud, your source or the project**. The path is a
|
|
2406
|
-
hash of `cfg.projectDir` + constants; nothing from the request reaches the
|
|
2407
|
-
filesystem.
|
|
2408
|
-
- It refuses politely when it shouldn't write: preview mode, a static-export
|
|
2409
|
-
capture, a cache directory that isn't writable, an oversized or malformed body.
|
|
2410
|
-
- A project served before #469 may carry `.behold/layout.json`. When the cache
|
|
2411
|
-
has no file for the project, that file is read once and copied into the
|
|
2412
|
-
cache; it is never written, moved or deleted. Clearing the last lens keeps
|
|
2413
|
-
an empty cache file, so the old one is not read back in.
|
|
2414
|
-
|
|
2415
|
-
The per-user settings (#470, src/user-settings.ts) sit beside it at
|
|
2416
|
-
`<user cache>/behold/settings/<key>.json`, same key, same modes: the operator's
|
|
2417
|
-
`approver` block and `behaviour.traffic`, which are not facts about the estate.
|
|
2418
|
-
No route writes them. When the cache has none for a project with a
|
|
2419
|
-
`.behold.json`, that file's two blocks are read once and copied in (key paths
|
|
2420
|
-
made absolute against the project), and a copy is kept even when neither
|
|
2421
|
-
block is there, so `.behold.json` is not read for them again. It is never
|
|
2422
|
-
written, moved or deleted. The tier axis is not a setting: it is the
|
|
2423
|
-
project's `chant.config.ts` `buildParams` entry with a string `enum`
|
|
2424
|
-
(src/project.ts `readTierParam`), read per request through `detectProject`
|
|
2425
|
-
and passed to `chant graph` as `--param`.
|
|
2426
|
-
|
|
2427
|
-
`GET /api/layout` reads it back; `GET /api/graph?layout=1` (and `/api/overlay`)
|
|
2428
|
-
render with the deltas baked into the SVG, which is how `behold export` and
|
|
2429
|
-
static snapshots honour a hand layout.
|
|
2430
|
-
|
|
2431
|
-
A declared workspace (#464) keys the layout by the workspace root, the
|
|
2432
|
-
directory holding `chant.workspace.json`, rather than by its first member.
|
|
2433
|
-
|
|
2434
|
-
`behold doctor --fix` (#464, ws-015) is the third exception, and it runs only
|
|
2435
|
-
when you type the flag: for an estate root whose members are listed in
|
|
2436
|
-
`.behold.json`, it writes `chant.workspace.json` in that root (never over an
|
|
2437
|
-
existing one) and copies the first member's saved layout to the root's cache
|
|
2438
|
-
entry with its node ids rewritten. It then runs `chant workspace check`. The
|
|
2439
|
-
first member's layout and `.behold.json` are left as they were.
|
|
2440
|
-
|
|
2441
|
-
The fourth exception is the carve walkthrough's two steps above (#254), and it
|
|
2442
|
-
is narrower still: they exist only when behold booted a `behold demo carve`
|
|
2443
|
-
copy, they write only into `<copy>/app/carveout/`, and the directory they write
|
|
2444
|
-
into is a scratch dir behold created inside a directory it copied for you a
|
|
2445
|
-
minute earlier. `carve bridge` runs without `--apply-rewrites`, so the demo's
|
|
2446
|
-
own Terraform is not edited either. The only request-derived value is `select`,
|
|
2447
|
-
and it must be an address the served report already ranks, the value that
|
|
2448
|
-
reaches the spawn's argv comes from a closed set read off disk. No cloud write,
|
|
2449
|
-
no Terraform mutation, no edit to anyone's chant source.
|
|
2450
|
-
|
|
2451
|
-
`behold export --publish s3://<bucket>/<prefix>/views/<name>` (#491) is the
|
|
2452
|
-
one write to a cloud, and it is not a server route: an export, asked for it on
|
|
2453
|
-
the command line, uploads the bundle it just wrote, signed with the AWS
|
|
2454
|
-
credentials in the environment (src/s3-object.ts). `publishTarget` refuses
|
|
2455
|
-
any destination that is not a `views/<name>` directory, terragucci's reserved
|
|
2456
|
-
viewer prefix, so the bundle's `index.html` can never land on a page behold did
|
|
2457
|
-
not make. `publishBundle` (src/export.ts, #500) uploads every other file
|
|
2458
|
-
first, then `manifest.json`, then `index.html`. Snapshot names carry the first
|
|
2459
|
-
16 hex digits of their SHA-256 (`CONTENT_ADDRESSED`) and go up with
|
|
2460
|
-
`Cache-Control: public, max-age=31536000, immutable`; everything else gets
|
|
2461
|
-
`no-cache`. It GETs the previous `manifest.json` under the prefix before
|
|
2462
|
-
uploading (no list call) and, after `index.html`, deletes the
|
|
2463
|
-
`snapshots/<name>` files that manifest named and this export did not write.
|
|
2464
|
-
Nothing outside the prefix is deleted. A refused delete stops the sweep with
|
|
2465
|
-
a warning naming `s3:DeleteObject`, and the publish still succeeds.
|
|
2466
|
-
|
|
2467
|
-
Since #510 the bundle goes to `<prefix>/<commit>/` (the checkout's HEAD, or
|
|
2468
|
-
`--commit`), with publishBundle's order and sweep one level down, and
|
|
2469
|
-
`src/publish-snapshots.ts` then writes, in order, `history.json` (newest
|
|
2470
|
-
first, `{commit, at, project, generated}`, one GET of the old one),
|
|
2471
|
-
`latest.json` (`{commit}`) and the root `index.html`, a no-cache page that
|
|
2472
|
-
opens `<latest>/index.html`, so old links keep working. `--keep <n>` (30)
|
|
2473
|
-
drops older commits from `history.json` and then deletes their files as each
|
|
2474
|
-
commit's `manifest.json` lists them (`files`, which runExport now writes,
|
|
2475
|
-
plus `keyToFile`), best effort with the same `s3:DeleteObject` warning. A
|
|
2476
|
-
view from before the layout keeps its files; only its `index.html` is
|
|
2477
|
-
replaced. With `--publish` the default `--reports-base` is `../../../`. The
|
|
2478
|
-
view's history picker (`web/history-picker.js`) reads `../history.json` and
|
|
2479
|
-
only navigates.
|
|
2480
|
-
|
|
2481
|
-
A choudoufu estate member (#366) adds no exception. A move there is one tag
|
|
2482
|
-
write through choudoufu's own `live-mv`, and behold never makes it: `GET
|
|
2483
|
-
/api/choudoufu/split` (also answered as `/api/choudoufu/moves`, its name before
|
|
2484
|
-
the split rename) reads a plan (`split.json`, or the workbench's `carve.json`)
|
|
2485
|
-
from inside a served member,
|
|
2486
|
-
previews each move with choudoufu's `live-mv -json -dry-run` (the only spelling
|
|
2487
|
-
of `live-mv` in the tree, src/choudoufu-moves.ts `dryRunArgs`, asserted by
|
|
2488
|
-
test), hands the lines back with copy buttons, and `?receipt=1` reads the
|
|
2489
|
-
listing after a person ran them. **There is no `/api/choudoufu/mv`**, and
|
|
2490
|
-
src/choudoufu-route.test.ts asserts it stays absent, for the same reason
|
|
2491
|
-
`/api/carve/apply` does not exist.
|
|
2492
|
-
|
|
2493
|
-
## Changing behold (for agents working on this repo)
|
|
2494
|
-
|
|
2495
|
-
The sections above are about driving a running behold. This one is about
|
|
2496
|
-
changing it, the working rules that used to live in a handoff note and now
|
|
2497
|
-
live here, with the enforceable ones enforced.
|
|
2498
|
-
|
|
2499
|
-
- **Branches and merges.** Work on a branch off `main` (an isolated worktree
|
|
2500
|
-
when more than one agent is active). `main` is protected by ruleset
|
|
2501
|
-
22042490, which requires a PR and a green `check` job in `ci.yml` of
|
|
2502
|
-
everyone but the repository admin role. That role bypasses it
|
|
2503
|
-
(`bypass_mode: always`, behold#1006, as chant and choudoufu have), so an
|
|
2504
|
-
admin may push a tested integration branch's merge to `main` directly;
|
|
2505
|
-
every other change arrives as a PR and merges once the check is green. A
|
|
2506
|
-
check that has merely settled is not a pass — read the lines. The
|
|
2507
|
-
ruleset's name still reads "every change is a PR with a green ci check";
|
|
2508
|
-
renaming it is a settings change for the maintainer (behold#1018).
|
|
2509
|
-
No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
|
|
2510
|
-
next onto what landed.
|
|
2511
|
-
- **Emulator e2e scripts** take their container names, ports and images
|
|
2512
|
-
from the environment and run under `e2e/lib/safe-env.sh`, which keeps real
|
|
2513
|
-
cloud credentials out of reach and fails on a real-cloud rejection in the
|
|
2514
|
-
log; e2e/README.md has the variables (behold#1032).
|
|
2515
|
-
- The painter bundles for a browser (#1069). `src/render.ts` and what it
|
|
2516
|
-
imports take no Node built-in: `npm run check:browser-bundle` bundles it
|
|
2517
|
-
with esbuild for `--platform=browser`, fails naming the import chain to any
|
|
2518
|
-
`node:` import, and prints the minified and gzipped sizes; CI runs it. A
|
|
2519
|
-
constant or card rule the painter needs from a module that reads disk or
|
|
2520
|
-
spawns lives in a module of its own (src/card-marks.ts,
|
|
2521
|
-
src/choudoufu-card.ts, src/carve-state.ts) and is re-exported from the old
|
|
2522
|
-
one. The icons come from src/icons.generated.ts: after a vendor script
|
|
2523
|
-
changes `web/icons`, run `npm run generate:icons` (`npm run check:icons`
|
|
2524
|
-
and src/generate-icons.test.ts fail until you do).
|
|
2525
|
-
- **The local gate** is `just check` (tsc, tests, build). The tests never read
|
|
2526
|
-
the caller's environment (behold#1013): src/test-env.ts, vitest's setup
|
|
2527
|
-
file, removes CHOUDOUFU_BIN, PLUNGE_BIN and the other variables behold
|
|
2528
|
-
reads to pick a binary or a service, and vitest.config.ts points
|
|
2529
|
-
PULUMI_BACKEND_URL at an empty `file://` directory made for the run, with
|
|
2530
|
-
PULUMI_SKIP_UPDATE_CHECK=true, so no pulumi or plunge a test starts sees
|
|
2531
|
-
the machine's login. A test that needs one of them sets it and puts back
|
|
2532
|
-
what was there. Every vitest run
|
|
2533
|
-
also writes `.vitest-last.json` (the json reporter, PR #351), and `just
|
|
2534
|
-
test` keeps the reporter's full output in `vitest.log`, both gitignored —
|
|
2535
|
-
because #334's one-shot first-run failures kept losing the failing file's
|
|
2536
|
-
name. If the suite fails once and passes on rerun, those two files from the
|
|
2537
|
-
first run are the evidence; attach them to #334 (`jq '.testResults[] |
|
|
2538
|
-
select(.status != "passed") | .name' .vitest-last.json` names the file).
|
|
2539
|
-
- **Releasing** is `just release`, after the version-bump PR merged: it tags
|
|
2540
|
-
`behold-v<version>`, pushes the tag (which is what runs `release.yml`), and
|
|
2541
|
-
waits for npm to show the version. It refuses in every state where a tag
|
|
2542
|
-
push would be wrong. Never re-push a `behold-v*` tag by hand: a tag push
|
|
2543
|
-
re-fires publish. Tags absent from origin (behold-v0.10.0, 0.10.1) stay
|
|
2544
|
-
absent for that reason.
|
|
2545
|
-
- **Scratch infrastructure** is governed by `src/scratch.ts`, asserted by
|
|
2546
|
-
`scratch.test.ts` across every boot site: anything behold boots is named
|
|
2547
|
-
`behold-*`, refuses if the name is taken, tears down only what it created,
|
|
2548
|
-
and never binds the shared emulator ports. The protected names — `floci*`,
|
|
2549
|
-
`chant-floci*`, the kubemicrovm and fountain k3d clusters, :4566 — are
|
|
2550
|
-
listed there, not in prose. A new boot site calls `assertScratch` before
|
|
2551
|
-
its spawn and gets a row in the test.
|
|
2552
|
-
- **The write boundary** is the Invariant section above. Apply is never a
|
|
2553
|
-
button; `/api/carve/apply` does not exist and the route test asserts it
|
|
2554
|
-
stays that way.
|
|
2555
|
-
- **chant's working rules** (its single-lane checkout, its release path) are
|
|
2556
|
-
chant's and live in chant's repo, not here.
|
|
38
|
+
- Every chant read goes through src/workspace-reader.ts. chant's reader conformance suite runs against it in `npm test` (src/workspace-reader-conformance.test.ts). Do not shell chant from elsewhere or import chant's library for something a read-contract command answers.
|
|
39
|
+
- behold runs the project's own chant, which may be older. Each read gets one floor in src/chant-floors.ts: a `<READ>_CHANT_FLOOR` constant, an entry in `CHANT_FLOORS` (what doctor prints), and a `floorMet`/`floorRefusal` check before spawning.
|
|
40
|
+
- When the chant behold follows changes, edit `CHANT_RELEASE` in src/chant-release.ts and run `npx tsx scripts/chant-release.ts`; `--check` lists files out of step.
|
|
41
|
+
- behold computes nothing chant answers. It parses no HCL, invents no edges, and paints an unknown status or read as neutral with a label, never a guessed colour.
|
|
2557
42
|
|
|
2558
43
|
### Adding a member kind
|
|
2559
44
|
|
|
2560
|
-
|
|
2561
|
-
|
|
2562
|
-
|
|
2563
|
-
|
|
2564
|
-
|
|
2565
|
-
|
|
2566
|
-
|
|
2567
|
-
|
|
2568
|
-
takes the `estate.chdf.hcl` sidecar, choudoufu's leading form, OR a `live {`
|
|
2569
|
-
block in a root *.tf, #387); `via.tool` stamps the binary and
|
|
2570
|
-
version that would answer, which is the version half of `memberIr`'s
|
|
2571
|
-
cache key; `via.read` is the one uncached read, source or live per `opts`.
|
|
2572
|
-
The module imports nothing from the read path at runtime (src/chant.ts
|
|
2573
|
-
imports src/project.ts, which imports it); a kind's `via` closes over its
|
|
2574
|
-
own tool module.
|
|
2575
|
-
Add the word to `MEMBER_KINDS`. A word in the vocabulary that no row
|
|
2576
|
-
registers is a doctor fail with the reason, never silently chant.
|
|
2577
|
-
2. Nothing in `src/estate.ts`: `composeEstate`, `composeEstateOverlay` and
|
|
2578
|
-
`estateNamespaceScopes` already dispatch through `memberKindOf(dir)`.
|
|
2579
|
-
The two routes that render an estate — `/api/graph`'s estate branch and
|
|
2580
|
-
`/api/overlay`'s — run the same passes in the same order and must not
|
|
2581
|
-
fork per kind; a kind's differences live inside its `read` or its `passes`.
|
|
2582
|
-
|
|
2583
|
-
`passes` (#427) is the render-time half, and it exists because the read-time
|
|
2584
|
-
one could not hold it: the Terraform kind's third pass takes the request's
|
|
2585
|
-
zoom, so it cannot run where the reader runs. `applyMemberPasses(ir,
|
|
2586
|
-
{detail})` is the one call the six render sites make, and `memberPassNote(run,
|
|
2587
|
-
dirs)` the line they return, each kind handed only the served dirs that are
|
|
2588
|
-
its own, so a route never names a kind. Three rules a `passes` holds. It
|
|
2589
|
-
mutates IN PLACE, because the existing passes do and their callers depend on
|
|
2590
|
-
it. It self-guards on the IR's own CONTENT and never on the served members'
|
|
2591
|
-
kinds. A chant project may declare a kind's lexicon; a chant project
|
|
2592
|
-
declaring `terraform` is what `src/terraform-route.test.ts`'s first block
|
|
2593
|
-
serves, and `memberKindOf` says `chant` there, so membership dispatch would
|
|
2594
|
-
silently stop rendering it. And a run is carried forward, never re-run: a
|
|
2595
|
-
pass that already elided its cards returns an empty elision the second time,
|
|
2596
|
-
which drops the note on every composed estate. A test that re-registers a
|
|
2597
|
-
kind to stub its reader spreads the real spec (`{ ...terraformSpec, via: … }`)
|
|
2598
|
-
or it drops the passes with it.
|
|
2599
|
-
3. A `registerPack({ lexicon, iconFor, fields })` in `src/render.ts`, or the
|
|
2600
|
-
kind's cards lead with the alphabetically first two short attrs. A `fields`
|
|
2601
|
-
function takes the box the card is drawn in as its second argument, so a
|
|
2602
|
-
row the box already carries can be left off (#393 item 9,
|
|
2603
|
-
`src/card-face.ts`).
|
|
2604
|
-
4. A row in `statusVocabulary` (`src/status-vocabulary.ts`) when the kind has
|
|
2605
|
-
its own words for the four overlay colours — choudoufu's `bound` is not
|
|
2606
|
-
chant's `managed`, and a legend that says `managed` over a card carrying no
|
|
2607
|
-
marker is a claim behold has no right to make. The colours never move; only
|
|
2608
|
-
the naming does, and an estate of several kinds keeps chant's words and says
|
|
2609
|
-
so in the legend's tooltip.
|
|
2610
|
-
5. A `DoctorCheck` line when the kind needs a tool on PATH or a per-member
|
|
2611
|
-
precondition (a version floor checked before the spawn, the way
|
|
2612
|
-
`carveStatusReader` does; a PATH probe the way `src/demos.ts` does).
|
|
2613
|
-
6. Tests: the probe and the object form in `src/project.test.ts`; dispatch
|
|
2614
|
-
in `src/estate.test.ts`'s "#368" block, which registers a fake kind and
|
|
2615
|
-
asserts chant members still go through exactly the calls they did, and its
|
|
2616
|
-
"#427" block for the render passes; the
|
|
2617
|
-
kind's own reader off recorded documents in `src/__fixtures__/`, with
|
|
2618
|
-
provenance in prose above the load.
|
|
2619
|
-
|
|
2620
|
-
`.behold.json` names a kind as `{ "dir": "x", "kind": "<kind>" }`; a bare
|
|
2621
|
-
string is `chant`. Anything behold boots for a kind goes through
|
|
2622
|
-
`assertScratch` first.
|
|
2623
|
-
|
|
2624
|
-
**What the first screen owes a non-chant member (#393).** Three chant-shaped
|
|
2625
|
-
things used to be offered to every member whatever it was, and a new kind gets
|
|
2626
|
-
all three answered for free:
|
|
2627
|
-
|
|
2628
|
-
- `/api/project` publishes `memberKinds`, the served members' kinds, in
|
|
2629
|
-
composition order. The SPA opens on the `resources` zoom when none of them is
|
|
2630
|
-
`chant`, because `components` is a projection of a chant project's own
|
|
2631
|
-
component DAG and a member without one opens on "the components lens doesn't
|
|
2632
|
-
apply to a composed estate yet". #182's zero-node fallback still covers a
|
|
2633
|
-
chant project that declares no components.
|
|
2634
|
-
- `/api/project` publishes `runtimeCapable`, and the palette and the View tab
|
|
2635
|
-
offer `zoom: runtime` only then. The tier below the declaration boundary is
|
|
2636
|
-
the owner-referenced children chant stamps `runtimeOwner` on, and only a
|
|
2637
|
-
Kubernetes read has an owner chain to resolve — `RUNTIME_LEXICONS` in
|
|
2638
|
-
`src/server.ts` is the one word (`k8s`), read off the members' DECLARED
|
|
2639
|
-
lexicons so the stop exists or not before anyone picks it.
|
|
2640
|
-
- A chant-only facet answers emptily rather than 500ing for a non-chant
|
|
2641
|
-
primary: `/api/resources` returns `{byComponent: {}}`, the shape carve mode
|
|
2642
|
-
already returns and the SPA already reads as "no resource facet here".
|
|
2643
|
-
|
|
2644
|
-
A kind that grows components, or a substrate with an owner chain, changes those
|
|
2645
|
-
answers where they are decided rather than per kind in a route.
|
|
2646
|
-
|
|
2647
|
-
### The workbench catalog
|
|
2648
|
-
|
|
2649
|
-
`demos.json` is the catalog that ships. `workbench.json`, read beside it and
|
|
2650
|
-
deliberately absent from package.json's `files`, is the catalog of internal
|
|
2651
|
-
estates this checkout is developed against (#386, #388). Four rules, and
|
|
2652
|
-
src/demos.ts holds them:
|
|
2653
|
-
|
|
2654
|
-
1. A third source, `local`, and a second file. A local entry's `path` is
|
|
2655
|
-
relative to the directory of the catalog file that named it, the intentius
|
|
2656
|
-
checkouts are siblings, so the workbench writes `../choudoufu`,
|
|
2657
|
-
`../waterpark`, `../chant`, and the file stays committed and reproducible.
|
|
2658
|
-
An entry whose path is not checked out is unsatisfiable exactly as a
|
|
2659
|
-
missing binary is: `--list` and `/api/demos` say so, CI stays clean.
|
|
2660
|
-
`BEHOLD_WORKBENCH=<file>` names a catalog elsewhere; a workbench name that
|
|
2661
|
-
collides with a bundled one is dropped with a stderr line.
|
|
2662
|
-
2. In place or copied, said explicitly. `inPlace: true` serves `path` where it
|
|
2663
|
-
sits; the default copies to `behold-demos/<name>` with the bundled filter.
|
|
2664
|
-
Anything whose setup writes into the tree — `init`, `apply`, a rendered
|
|
2665
|
-
generator — is copied or generated into the target, never run in a
|
|
2666
|
-
checkout, which is how #366's "behold never runs `choudoufu init` in a
|
|
2667
|
-
served project" survives. An `inPlace` entry with a `setup` says so in its
|
|
2668
|
-
description.
|
|
2669
|
-
3. A generator is a source. An entry with no `path` at all renders its estate
|
|
2670
|
-
into an empty target through its own `setup`, which runs with cwd = the
|
|
2671
|
-
target and two extra variables: `BEHOLD_WORKBENCH_DIR` (the catalog file's
|
|
2672
|
-
directory, so a script can reach `../choudoufu`) and `BEHOLD_DEMO_NAME`.
|
|
2673
|
-
The up script writes the matching down script into the target, the way the
|
|
2674
|
-
bundled choudoufu demo ships `scripts/choudoufu-down.sh`.
|
|
2675
|
-
4. `CHOUDOUFU_BIN`. `choudoufuBinary()` (src/choudoufu-member.ts) names the
|
|
2676
|
-
binary and every spawn, the doctor probe and the demo requirement check go
|
|
2677
|
-
through it; the doctor line prints which binary answered. Workbench scripts
|
|
2678
|
-
spell the same fallback, `${CHOUDOUFU_BIN:-choudoufu}`.
|
|
2679
|
-
|
|
2680
|
-
`just example name="<entry>"` serves one. Scratch discipline is unchanged: an
|
|
2681
|
-
emulator a workbench entry boots is `behold-wb-<entry>` on its own port, and
|
|
2682
|
-
the up scripts (`workbench/<entry>/up.sh`, helpers in `workbench/lib/`) assert
|
|
2683
|
-
the `behold-wb-` prefix and the not-4566 rule themselves, in bash, because they
|
|
2684
|
-
are the boot site. Each writes the matching `scripts/down.sh` into its target.
|
|
2685
|
-
|
|
2686
|
-
**The eleven entries**, in catalog order. The counts are measured, not
|
|
2687
|
-
estimated — every entry the e2e below can reach on a developer machine prints
|
|
2688
|
-
its own graph and overlay counts as it runs.
|
|
2689
|
-
|
|
2690
|
-
| entry | what it serves | needs |
|
|
2691
|
-
|---|---|---|
|
|
2692
|
-
| `chant-getting-started` | chant's own getting-started example from `../chant`, in place: the source graph, 8 nodes, no substrate. The one-second answer to "did I break plain chant reading?" | that example's own `node_modules`, nothing is installed in your chant tree |
|
|
2693
|
-
| `chant-local-cloud-trio` | chant's local-cloud-trio, in place: one project declaring across aws, azure and gcp, 8 nodes and 2 edges of source | the same |
|
|
2694
|
-
| `fountain-ops` | `../fountain-ops` in place with `--env local`, the mature estate on your working checkout | docker, k3d, kubectl, jq, just. **The one entry whose setup runs in your working copy**: the checkout's own `just up`, a five-minute k3d cluster, and it switches your kubectl context. `just down` there removes it; behold never does |
|
|
2695
|
-
| `choudoufu-workbench` | the live-mv workbench's four estates copied out of `../choudoufu`, composed with `--env live`: 42 cards — 24 bound, the 12 team cards reading `owned by tlmig-sample-monolith`, 6 neutral | docker, choudoufu |
|
|
2696
|
-
| `choudoufu-cohort-s3` | `estate-gen`'s `s3` cohort rendered into the target, a sidecar-declared estate (#387): 6 cards, all neutral, because the apply stops where floci answers S3 Control tag reads on a hostname that does not resolve | docker, choudoufu, go, terraform |
|
|
2697
|
-
| `choudoufu-cohort-iam-ecr` | the same for `iam-ecr`, the one cohort floci implements end to end: 6 cards, all 6 bound | the same |
|
|
2698
|
-
| `choudoufu-cohort-ec2-networking` | the same for `ec2-networking`: 49 cards, the widest roster, all neutral (floci refuses a transit gateway call and the apply stops) | the same |
|
|
2699
|
-
| `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 |
|
|
2700
|
-
| `terralith-4` | the same at scale 4: 301 cards, all 301 bound. The estate behold is sized against | the same |
|
|
2701
|
-
| `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 |
|
|
2702
|
-
| `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 |
|
|
2703
|
-
|
|
2704
|
-
**The scratch, by name and port.** Each emulator is the entry's own, booted by
|
|
2705
|
-
its up script and removed by the `scripts/down.sh` that script wrote into the
|
|
2706
|
-
target rather than by pattern.
|
|
2707
|
-
|
|
2708
|
-
| entry | container | host port |
|
|
2709
|
-
|---|---|---|
|
|
2710
|
-
| `choudoufu-workbench` | `behold-wb-choudoufu-workbench` | 4651 |
|
|
2711
|
-
| `choudoufu-cohort-s3` | `behold-wb-choudoufu-cohort-s3` | 4652 |
|
|
2712
|
-
| `choudoufu-cohort-iam-ecr` | `behold-wb-choudoufu-cohort-iam-ecr` | 4653 |
|
|
2713
|
-
| `choudoufu-cohort-ec2-networking` | `behold-wb-choudoufu-cohort-ec2-networking` | 4654 |
|
|
2714
|
-
| `terralith-1` | `behold-wb-terralith-1` | 4655 |
|
|
2715
|
-
| `terralith-4` | `behold-wb-terralith-4` | 4656 |
|
|
2716
|
-
| `terralith-4-adopt` | `behold-wb-terralith-4-adopt` | 4657 |
|
|
2717
|
-
| `chant-*`, `waterpark` | none (source reads, no substrate |) |
|
|
2718
|
-
| `fountain-ops` | the k3d cluster `fountain-local`, which is the checkout's, not behold's | — |
|
|
2719
|
-
|
|
2720
|
-
The port is the floci's host binding and the entry's `serve.spawnEnv`
|
|
2721
|
-
`AWS_ENDPOINT_URL` at once, so the estate's own applies and the choudoufu
|
|
2722
|
-
behold spawns talk to the same emulator.
|
|
2723
|
-
|
|
2724
|
-
**The e2e** is `just e2e-workbench` (`e2e/workbench-e2e.sh`, #391): every entry
|
|
2725
|
-
loaded through `behold demo <entry> <tmp target> --port <p>` on its own port
|
|
2726
|
-
from 4720 up, `/api/graph` asserted to carry nodes and a live entry's
|
|
2727
|
-
`/api/overlay?env=live` to answer with its bound/unowned/neutral split, timings
|
|
2728
|
-
per entry; eight entries and 553s on the machine this was written on.
|
|
2729
|
-
|
|
2730
|
-
Time is asserted, not only printed (#423). Each entry carries a ceiling at
|
|
2731
|
-
roughly twice its own measured value, and the run carries one too, because
|
|
2732
|
-
#419's whole subject was a number nobody was watching: the ratio could not
|
|
2733
|
-
regress silently and the duration could. The measured figures the ceilings come
|
|
2734
|
-
from are in the script beside them; `BEHOLD_E2E_SECS_<entry>` and
|
|
2735
|
-
`BEHOLD_E2E_RUN_SECS` override. A live entry also asserts #422's shape: the
|
|
2736
|
-
progressive overlay answers with every member marked pending and does so before
|
|
2737
|
-
the blocking read returns, so the estate cannot quietly regress to
|
|
2738
|
-
all-or-nothing. Where the blocking read is already sub-second there is nothing
|
|
2739
|
-
to beat, and the run reports the two numbers rather than claiming a pass.
|
|
2740
|
-
|
|
2741
|
-
`terralith-4-adopt` is asserted twice — 85 UNOWNED, then the
|
|
2742
|
-
`live-import` line the up script printed, run by the script itself in the
|
|
2743
|
-
target the way a person would, then 301 bound, because that write is the
|
|
2744
|
-
person's, never behold's (#372). `waterpark` is checked for an untouched
|
|
2745
|
-
checkout afterwards. `missingRequirements` decides what runs: a missing binary,
|
|
2746
|
-
an unchecked-out sibling, an uninstalled chant example or the absent Terraform
|
|
2747
|
-
lexicon each print `skip: <entry>: needs …`, so in CI every entry skips and the
|
|
2748
|
-
run exits 0. `fountain-ops` is skipped by name everywhere, for the reason in
|
|
2749
|
-
the table. A `behold-wb-*` container left standing at the end fails the run.
|
|
2750
|
-
|
|
2751
|
-
The seeded catalog (#389) found one thing missing in src/: a LONE choudoufu
|
|
2752
|
-
estate (every generated entry is one) served the no-project card, because the
|
|
2753
|
-
single-project read is `chant graph <dir>` and such a directory has no lexicon
|
|
2754
|
-
for it to read. `servesAsEstate` (src/member-kind.ts) is the predicate that
|
|
2755
|
-
routes one directory of a non-chant kind through the estate compose path, where
|
|
2756
|
-
the member's own kind reads it. One member composes exactly as four do, ids
|
|
2757
|
-
namespaced under the member's short name, so the graph, the pane and the morph
|
|
2758
|
-
agree on what a node is called.
|
|
2759
|
-
|
|
2760
|
-
### Rendering a Terraform estate
|
|
2761
|
-
|
|
2762
|
-
A Terraform estate reaches behold through chant.
|
|
2763
|
-
`@intentius/chant-lexicon-terraform` reads the HCL an estate already has and
|
|
2764
|
-
emits one entity per block, so **a Terraform estate is a chant project whose
|
|
2765
|
-
only lexicon is a reader** and `chant graph --format ir` serves it like any
|
|
2766
|
-
other. behold parses no HCL itself, the same posture `src/carve-lens.ts`
|
|
2767
|
-
states for the carve report (#378). The parser chant uses is installed with
|
|
2768
|
-
behold since #909, below.
|
|
2769
|
-
|
|
2770
|
-
Three passes turn what arrives into a picture (`src/terraform-lens.ts`), in this
|
|
2771
|
-
order, guarded on the IR carrying terraform entities so every other estate gets
|
|
2772
|
-
the identical object back:
|
|
2773
|
-
|
|
2774
|
-
1. **`normalizeTerraformNodes`.** A node's `kind` arrives as the entity class
|
|
2775
|
-
(`Terraform::Resource`), not the resource type, so every card would be titled
|
|
2776
|
-
and iconed the same. The type moves out of `attrs.address` into `kind` and
|
|
2777
|
-
the block class lands in `attrs.block`. That is the shape a carve node
|
|
2778
|
-
already has, which is why one presentation pack serves both.
|
|
2779
|
-
2. **`groupTerraformByRoot`.** Roots are a Terraform project's only grouping.
|
|
2780
|
-
It retires itself when chant#2266 groups upstream. A node sits in exactly one
|
|
2781
|
-
box, so a box every node has left is dropped rather than drawn empty (#393):
|
|
2782
|
-
a served directory arrives composed, `composeStacks` boxes the whole member,
|
|
2783
|
-
and the root boxes then take those same nodes, which is what put an empty
|
|
2784
|
-
box named `access` on water park's canvas. What the member box was there to
|
|
2785
|
-
say moves into the root box's title, which is `<member>/<root>` whenever the
|
|
2786
|
-
estate holds more than one member and the bare root name when it does not
|
|
2787
|
-
(two members with a root apiece named `prod` would otherwise merge silently).
|
|
2788
|
-
3. **`filterTerraformCards`.** What is a card, below.
|
|
2789
|
-
|
|
2790
|
-
**What is a card (#382).** Measured on a real estate: 247 nodes for 43
|
|
2791
|
-
resources, four fifths of it not infrastructure.
|
|
2792
|
-
|
|
2793
|
-
| tier | blocks | why |
|
|
2794
|
-
|---|---|---|
|
|
2795
|
-
| default (detail 0-2) | `resource`, `data`, `module` | the estate: what is declared, what it reads, what it composes |
|
|
2796
|
-
| attributes (detail 3) | + `output`, `variable` | its interface — real, but a second question |
|
|
2797
|
-
| never | `terraform`, `provider`, `locals` | settings, not estate |
|
|
2798
|
-
|
|
2799
|
-
Nothing is dropped silently: `terraformElisionNote` says what is not drawn and
|
|
2800
|
-
where to see it, the way `edgelessNote` says why a view has no edges.
|
|
2801
|
-
|
|
2802
|
-
**The note, at every zoom and in a 260px strip (#393).** The roots note and the
|
|
2803
|
-
elision note are built by one function in `/api/graph` and returned by all three
|
|
2804
|
-
of its branches, the logical lens included — it was the lens that most needed
|
|
2805
|
-
the line and the only one that dropped it. Both routes send `note` and, when
|
|
2806
|
-
there is a shorter true form, `noteShort` (`5 roots · 2 skipped · 189 blocks not
|
|
2807
|
-
drawn`). The strip shows the short one with the long one on its tooltip, and the
|
|
2808
|
-
panel's Model tab prints it whole. The server writes both: the SPA does not
|
|
2809
|
-
author notes, and truncating this one on a sentence boundary would keep the list
|
|
2810
|
-
of root names and drop the counts.
|
|
2811
|
-
|
|
2812
|
-
**Do not invent edges.** They arrive from chant or not at all: the fixtures here
|
|
2813
|
-
were recorded when a Terraform IR carried none, and lexicon 0.61.0 (chant#2265,
|
|
2814
|
-
which resolves a block's `"${…}"` references) draws 390 over water park's five
|
|
2815
|
-
roots with no change on this side. The one relationship that looked derivable
|
|
2816
|
-
without it (a cross-root read by name) was measured and refused (#381): both
|
|
2817
|
-
ends carry the same unresolved interpolation, so a match would be a coincidence
|
|
2818
|
-
of variable naming. A data source says what it reads as a row instead.
|
|
2819
|
-
|
|
2820
|
-
**Serving a directory that declares nothing (#384).** Every estate this lane
|
|
2821
|
-
exists to draw is a directory of `.tf` files and nothing else, and #378 chose
|
|
2822
|
-
not to ask one for a `chant.config.ts` of its own — INTENTIUS/waterpark#88 was
|
|
2823
|
-
withdrawn because the estate is more useful untouched. So `behold serve
|
|
2824
|
-
<terraform-dir>` generates the reader config itself, outside the estate, and
|
|
2825
|
-
points chant at it. behold writes nothing in a served project (the
|
|
2826
|
-
Invariant), nothing is written under the served directory, and
|
|
2827
|
-
`src/terraform-member.test.ts` asserts the estate's source stamp is unchanged
|
|
2828
|
-
across a read. Three decisions, each a trade #384 left open and each measured on
|
|
2829
|
-
water park's `access/` before it was taken:
|
|
2830
|
-
|
|
2831
|
-
1. **The reader ships with behold, and is still probed.** chant resolves the
|
|
2832
|
-
lexicon from the config file's own location, so the generated project has to
|
|
2833
|
-
see it, and chant core (not the lexicon) imports `@cdktn/hcl2json` from its
|
|
2834
|
-
own real path; neither package declares the parser. #384 made both optional
|
|
2835
|
-
peers to keep a ~1.8 MB wasm blob out of chant-only installs. #909 reversed
|
|
2836
|
-
that so `npx @intentius/behold serve .` on a folder of `.tf` files is one
|
|
2837
|
-
command: `@intentius/chant-lexicon-terraform` and `@cdktn/hcl2json` are
|
|
2838
|
-
**dependencies** in package.json (the only place their versions are named;
|
|
2839
|
-
the refusal reads them from there). The maintainer accepted the cost on #909:
|
|
2840
|
-
+8.3 MB on a 195 MB install, six packages. The lexicon's range starts at
|
|
2841
|
-
behold's chant floor so its chant peer dedupes against behold's chant, and
|
|
2842
|
-
npm hoists both beside chant, which is where the scratch project's
|
|
2843
|
-
`node_modules` symlink and chant's parser import look. They are still probed
|
|
2844
|
-
at serve and doctor time and refused with the one install line and where
|
|
2845
|
-
behold looked, because an install that pruned them reaches a chant that
|
|
2846
|
-
warns, exits 0 and prints an empty graph. The lexicon's own chant peer is
|
|
2847
|
-
what moved behold's `@intentius/chant` floor to `^0.61.0`: chant 0.54 loads
|
|
2848
|
-
no published version of it (`applyLineage is not a function`).
|
|
2849
|
-
2. **Roots are discovered, and the skips are reported.** A root is a directory
|
|
2850
|
-
with a `.tf` declaring a line-start `terraform {` or `provider "` block
|
|
2851
|
-
beside a `resource`, `data` or `module` block, a regex probe at the depth
|
|
2852
|
-
the choudoufu probe uses, no HCL parsed. #384 proposed the first half alone
|
|
2853
|
-
("what a root has and a called module does not") and the estate refuted it:
|
|
2854
|
-
water park's `modules/persona` is a shared module called by three roots and
|
|
2855
|
-
its `versions.tf` is `baseline`'s byte for byte. So two exclusions stand
|
|
2856
|
-
beside the probe, a directory under a `modules/` segment (Terraform's own
|
|
2857
|
-
standard module structure; the roots that call it draw its blocks already)
|
|
2858
|
-
and one with nothing to draw (`access/backends` is two backend fragments) —
|
|
2859
|
-
and both are named in the graph's note with their reason, the way
|
|
2860
|
-
`terraformElisionNote` names what a zoom left out. Measured on `access/`:
|
|
2861
|
-
five roots (`envs/prod`, `identity`, `github`, `baseline`,
|
|
2862
|
-
`satellites/waterpark-runner`), two skipped, `envs/dev` neither drawn nor
|
|
2863
|
-
reported because it holds only a README.
|
|
2864
|
-
3. **A `terraform` member kind, after chant and choudoufu.** #378 said there is
|
|
2865
|
-
no such kind and meant it about *reading*: behold parses no HCL and the
|
|
2866
|
-
render goes through chant. A kind whose `read` shells `chant graph` against a
|
|
2867
|
-
generated config is a scaffold, not a second reader, and it inherits the
|
|
2868
|
-
probe, the cache stamp, the doctor line and estate composition (#368) for
|
|
2869
|
-
free, so a Terraform root composes in an estate beside a chant project and a
|
|
2870
|
-
choudoufu estate at no extra cost. `src/terraform-member.ts` is the whole of
|
|
2871
|
-
it; `detectProjectShape` answers a directory that is its own member with
|
|
2872
|
-
`membersFrom: "probe"`, which is what retired #384's `no chant.config.ts
|
|
2873
|
-
here` dead end.
|
|
2874
|
-
|
|
2875
|
-
The scratch project is `<tmpdir>/behold-tf-<hash of the estate path>`:
|
|
2876
|
-
`behold-*` and cleared through `assertScratch` (src/scratch.ts), one directory
|
|
2877
|
-
per estate reused across runs, asserted to be outside the estate before a byte
|
|
2878
|
-
is written. It holds the generated `chant.config.ts`, a `package.json` that
|
|
2879
|
-
declares it an ES module (chant's compiled CLI, 0.124.14 on, otherwise reads a
|
|
2880
|
-
config tsx compiled as CommonJS as `{default: config}` and finds no lexicon:
|
|
2881
|
-
INTENTIUS/chant#3897), and two symlinks —
|
|
2882
|
-
`node_modules` to behold's own, which is how the config resolves the lexicon,
|
|
2883
|
-
and `estate` to the served directory, which is how each root's `dir` is spelled.
|
|
2884
|
-
The second is not decoration: the lexicon sets a root's module boundary to the
|
|
2885
|
-
root's own directory when its `dir` resolves outside the project root, so
|
|
2886
|
-
absolute paths cost every `../modules/x` call the estate makes — 72 nodes and 6
|
|
2887
|
-
resources on water park, against 247 and 43 through the symlink. Nothing in the
|
|
2888
|
-
answer mentions the scratch path (a terraform entity carries `attrs.file`
|
|
2889
|
-
relative to its root, and no `sourceLoc`).
|
|
2890
|
-
|
|
2891
|
-
### A choudoufu member's overlay is ownership; attribute drift is the plan (#404)
|
|
2892
|
-
|
|
2893
|
-
**Read a green choudoufu card as "this is ours", never as "nothing changed".**
|
|
2894
|
-
The overlay is composed from `live-ls -json` and `live-plan -json`, and those
|
|
2895
|
-
two documents answer one question — bound, unowned, omitted, or invisible to
|
|
2896
|
-
the listing. Neither of them ever compares an attribute VALUE. A resource whose
|
|
2897
|
-
tag, path or mutability was changed out of band still carries its markers, so
|
|
2898
|
-
it is still bound, and it is still green.
|
|
2899
|
-
|
|
2900
|
-
The other half of the terminal's answer ("would a plan change anything?") is
|
|
2901
|
-
a **separate, opt-in read**, and since #924 it goes through chant together with
|
|
2902
|
-
the ownership it is about (src/choudoufu-chant-read.ts): one `chant graph
|
|
2903
|
-
--live` over the member's `chdf` reader project at the plan depth
|
|
2904
|
-
(`CHANT_TERRAFORM_OBSERVE=plan`, INTENTIUS/chant#4371). chant runs `choudoufu
|
|
2905
|
-
live-plan -json` for ownership, then `choudoufu plan -input=false -lock=false
|
|
2906
|
-
-out=<its tmp>` and `show -json` for the attributes, and puts `planChanges`
|
|
2907
|
-
(live value `before`, declared value `after`) on each bound block. With
|
|
2908
|
-
`CHANT_TERRAFORM_LIVE_PLAN_DIR` set to a directory behold made under the OS
|
|
2909
|
-
temp directory (INTENTIUS/chant#4383), chant also hands back the `live-plan`
|
|
2910
|
-
document its verdicts came from, and behold paints ownership from that, so a
|
|
2911
|
-
re-check runs ONE `live-plan` per member and the plan sits on the same
|
|
2912
|
-
verdicts as the card. Nothing is written in the served member (chant writes
|
|
2913
|
-
its plan file and the handed document outside it, INTENTIUS/chant#4379).
|
|
2914
|
-
(`choudoufu plan -json` is not this read: on 0.16.0 it prints choudoufu's own
|
|
2915
|
-
ownership document with no attribute values in it at all, measured in #404.)
|
|
2916
|
-
On a live root drift IS the planned `update`: choudoufu rebuilds prior state
|
|
2917
|
-
from the account, so chant's `planDrift` is empty there and is not read. A
|
|
2918
|
-
path chant finds flagged sensitive on either side is `(sensitive)` on both,
|
|
2919
|
-
and so is every copy of a flagged string (`tags_all`): a choudoufu plan flags
|
|
2920
|
-
a sensitive variable's value on `after` only, with the old secret unflagged in
|
|
2921
|
-
`before`. Floor: `CHOUDOUFU_PLAN_CHANT_FLOOR` (0.124.46); below it, or with no
|
|
2922
|
-
terraform lexicon, a re-check paints from behold's own `live-plan` and reads
|
|
2923
|
-
no plan.
|
|
2924
|
-
|
|
2925
|
-
It is opt-in because it costs differently: the ownership read is answered out
|
|
2926
|
-
of the tagging index and is flat in the estate's size, while `plan` refreshes
|
|
2927
|
-
every resource, one provider read per card, 301 of them on `terralith-4`. So:
|
|
2928
|
-
|
|
2929
|
-
- **Never on an ordinary overlay read.** `GET /api/overlay?plan=1` and
|
|
2930
|
-
`GET /api/diff?plan=1` are the only things that read one, and the palette's
|
|
2931
|
-
**"Re-check live with plan (attribute drift)"** row is the only thing in the
|
|
2932
|
-
SPA that sends the flag. The cheap **"Re-check live (refresh drift)"** row is
|
|
2933
|
-
deliberately left alone — it is `POST /api/refresh`, a primary-only re-observe
|
|
2934
|
-
that captures a lanes frame and never composes the estate.
|
|
2935
|
-
- **Cached under the member's source stamp**, the same key half `memberIr`
|
|
2936
|
-
uses. A read that did NOT ask is served that stored answer, so a reload after
|
|
2937
|
-
a refresh keeps showing the drift without paying for a second pass; a read
|
|
2938
|
-
that DID ask always re-reads both halves, because "re-check" means re-check.
|
|
2939
|
-
- **The ownership verdict stays the card's colour.** A bound card that drifted
|
|
2940
|
-
is still painted bound and still counted `bound`; it gains `attrs._planDrift`
|
|
2941
|
-
and wears a dashed `--degraded` edge plus a `~ n attributes` corner glyph
|
|
2942
|
-
(web/app.js `markDriftedCards`, the same post-render stamp as the carve and
|
|
2943
|
-
operator marks). A card that is not bound is never marked: an unowned
|
|
2944
|
-
object's planned `create` is an ownership fact the overlay already paints,
|
|
2945
|
-
and `planDrift` drops creates for that reason.
|
|
2946
|
-
- **`/api/overlay`'s meta carries `drift`**: `{read: false}` or `{read: true,
|
|
2947
|
-
drifted: n}`. The two are different answers — "nobody looked" versus "looked,
|
|
2948
|
-
nothing drifted", and the legend prints a count only for the second.
|
|
2949
|
-
|
|
2950
|
-
### A stock Terraform root's plan comes from chant (#910)
|
|
2951
|
-
|
|
2952
|
-
`GET /api/graph?plan=1` (palette: **"Read the plan on the Terraform roots"**)
|
|
2953
|
-
reads each stock Terraform member's roots at chant's plan depth
|
|
2954
|
-
(INTENTIUS/chant#4358): behold's own chant over the member's scratch project,
|
|
2955
|
-
`CHANT_TERRAFORM_OBSERVE=plan chant graph . --live --overlay --env behold-plan
|
|
2956
|
-
--format ir --detail 3` (src/terraform-plan.ts). The plan runs with
|
|
2957
|
-
`-lock=false`, its file under the OS temp directory. Each resource or data card
|
|
2958
|
-
gains `attrs._plan` (`source`, `action`, `reason`, `replacePaths`,
|
|
2959
|
-
`forcedFrom`, `afterUnknown`, `changes`, `drift`), and the card's rows lead with
|
|
2960
|
-
`plan`, `forced by`, `from` and `read`. `GET /api/terraform/plan` answers the
|
|
2961
|
-
same facts per card as JSON.
|
|
2962
|
-
|
|
2963
|
-
- **Which read answered is per root**, parsed from chant's notes: `plan`,
|
|
2964
|
-
`state` (the plan failed, for missing credentials or a provider error) or
|
|
2965
|
-
`none` (declared only). A card in a root that fell back says `plan: not read`
|
|
2966
|
-
and which read answered. Never "no changes" unless the plan said `no-op`.
|
|
2967
|
-
- **Sensitive values arrive redacted** by chant, at any depth and every copy;
|
|
2968
|
-
behold copies plan facts only, never a block's other attributes.
|
|
2969
|
-
- **Floor**: `TERRAFORM_PLAN_CHANT_FLOOR` (0.124.46) for behold's chant and the
|
|
2970
|
-
lexicon; below it the read is refused with the upgrade line.
|
|
2971
|
-
- **A planned create has a card**: it reads absent at the plan depth, so it
|
|
2972
|
-
stays pending with no physical id, and chant carries its plan attributes
|
|
2973
|
-
onto the declared node anyway (chant#4372). Its rows read `plan: create`,
|
|
2974
|
-
`unknown: N until apply`, `read: plan`.
|
|
2975
|
-
- **A `count`/`for_each` block draws a card per instance** (#996,
|
|
2976
|
-
src/instance-cards.ts). The id is the block's node id and the key as
|
|
2977
|
-
Terraform prints it, `app/aws_s3_bucket.logs[0]`, `<member>/` in front on an
|
|
2978
|
-
estate, the same rule chant's graph uses for its instance nodes
|
|
2979
|
-
(INTENTIUS/chant#4454). Until chant emits them, behold derives them from the
|
|
2980
|
-
plan's per-instance rows (`planActions` by instance address, each change and
|
|
2981
|
-
drift row's `instance`), so each card has its own action, changes and drift.
|
|
2982
|
-
An instance node chant draws is kept and only painted. The block card stays
|
|
2983
|
-
as the rollup: chant's aggregate `_plan`, `attrs._instances` and an
|
|
2984
|
-
`instances` row. A key under a module instance (`module.a[0]...[1]`) stays
|
|
2985
|
-
in the rollup. A choudoufu member's roster is per instance already.
|
|
2986
|
-
- **choudoufu members read ownership and the plan through chant together**
|
|
2987
|
-
(src/choudoufu-chant-read.ts, #924): src/choudoufu-plan.ts is gone, and a
|
|
2988
|
-
re-check's `live-plan` is chant's, handed back to behold. See the choudoufu
|
|
2989
|
-
section above.
|
|
2990
|
-
|
|
2991
|
-
### A lexicon behold draws but cannot aim (#430)
|
|
2992
|
-
|
|
2993
|
-
`behold doctor`'s **targets** line. `SUBSTRATE_TARGET_VARS` (src/targets.ts)
|
|
2994
|
-
names four lexicons against the nine behold draws, deliberately — it withholds
|
|
2995
|
-
one until chant can actually be pointed at an emulator for it. That module also
|
|
2996
|
-
names the cost: a landed chant change leaves a stale omission "until someone
|
|
2997
|
-
notices", which happened once (#125) and left behold showing a floci-gcp pill it
|
|
2998
|
-
could not aim a read at. This is the line someone reads instead.
|
|
2999
|
-
|
|
3000
|
-
`NO_AMBIENT_TARGET` (same module) is what stops it being noise: k8s and temporal
|
|
3001
|
-
are not withheld, they are finished — they bind from `chant.config` rather than
|
|
3002
|
-
an ambient variable, so there is nothing to override and nothing for a picker.
|
|
3003
|
-
Those report as settled, not as a gap.
|
|
3004
|
-
|
|
3005
|
-
What the line CANNOT say, stated because the gap is the point: the honest
|
|
3006
|
-
question is "chant can route this and behold does not list it", and behold
|
|
3007
|
-
cannot ask it. Since chant 0.61 the endpoint variable is declared by the LEXICON
|
|
3008
|
-
PLUGIN (`endpointEnvVarsFor`), not by a table in core, and behold installs no
|
|
3009
|
-
lexicon plugins; the served project does. No chant CLI reports them either
|
|
3010
|
-
(`lifecycle whoami --json` answers identity and says nothing about endpoints).
|
|
3011
|
-
So the check warns on the weaker question it can answer and says it may be
|
|
3012
|
-
over-reporting. The real fix is upstream, and #430 records the ask.
|
|
3013
|
-
|
|
3014
|
-
### A card with no live half is not an unobserved one (#429)
|
|
3015
|
-
|
|
3016
|
-
pinhole's painter takes a closed `_status` set and falls back to `neutral` for
|
|
3017
|
-
anything else, `undefined` included. So on a mixed overlay a member with no live
|
|
3018
|
-
half, a Terraform root, whose `live`/`overlay`/`env` are stripped in
|
|
3019
|
-
src/terraform-member.ts — painted exactly like a card behold looked at and could
|
|
3020
|
-
not see, while the legend counted only the latter. Measured on
|
|
3021
|
-
`serve example-writes example-terraform-estate --env prod`: 37 Terraform cards
|
|
3022
|
-
carrying no `_status`, 2 chant cards carrying `neutral`, one fill between them.
|
|
3023
|
-
|
|
3024
|
-
Those cards now carry `data-no-live` and the legend gives them their own row.
|
|
3025
|
-
Named rather than folded into `unobserved`, because "I looked and could not see"
|
|
3026
|
-
and "there is nothing here to look at" are different claims, the same argument
|
|
3027
|
-
#399 makes for an unpriced card, and the same answer: mark it, do not merely
|
|
3028
|
-
colour it. The mark is overlay-only; on the source graph no card has a status
|
|
3029
|
-
and marking every one of them would say nothing.
|
|
3030
|
-
|
|
3031
|
-
This is presentation, not vocabulary. `statusVocabulary` gets no terraform row:
|
|
3032
|
-
there is no status to name. See #429 for the measurement that established it.
|
|
3033
|
-
|
|
3034
|
-
### An adoptable row is painted like an unowned one, plus its evidence (#413)
|
|
3035
|
-
|
|
3036
|
-
A `NEEDS_DISCOVERY` omission paired with an `adoptable[]` row at the same
|
|
3037
|
-
address paints `warn` with `ownership: "foreign"`, the same verdict the UNOWNED
|
|
3038
|
-
branch gives and for the same reason: the live object carries no marker for
|
|
3039
|
-
this estate. On its own, `NEEDS_DISCOVERY` stays neutral — the declaration
|
|
3040
|
-
names no identity, and with nothing found that is a "could not answer" rather
|
|
3041
|
-
than an action.
|
|
3042
|
-
|
|
3043
|
-
The card leads with `attrs.adopt`, which is choudoufu's own `adopt_command`
|
|
3044
|
-
here rather than the marker pair an unowned row carries. `adoptLine`'s
|
|
3045
|
-
composed-command branch had no real caller until this. behold composes no
|
|
3046
|
-
command of its own: the API that writes a tag differs per resource type.
|
|
3047
|
-
|
|
3048
|
-
`attrs.matchedOn` is the difference in kind. An unowned row needs no evidence
|
|
3049
|
-
because the identity IS the match; here choudoufu asserts that a live object is
|
|
3050
|
-
a declaration because their identity-bearing arguments agree, and a person
|
|
3051
|
-
about to stamp two tags onto somebody's resource is owed the list.
|
|
3052
|
-
|
|
3053
|
-
`web/app.js` renders both through the one copyable row, and its tooltip says
|
|
3054
|
-
whether the line is a command or a pair of tags.
|
|
3055
|
-
|
|
3056
|
-
### The adoption sweep is off unless a serve asks (#412)
|
|
3057
|
-
|
|
3058
|
-
`live-plan -json` carries `adoptable[]` (live resources the estate-wide sweep
|
|
3059
|
-
matched to a declared instance by content) and `swept` (the types it listed in
|
|
3060
|
-
full). Both are empty on a run that did not ask the account-inventory question,
|
|
3061
|
-
and behold does not ask by default.
|
|
3062
|
-
|
|
3063
|
-
The opt-in is `TOFU_LIVE_COLLECT_UNCLAIMED=1` (`ADOPTION_SWEEP_VAR`,
|
|
3064
|
-
src/choudoufu-live.ts), carried through `serve.spawnEnv`, the seam
|
|
3065
|
-
`setChoudoufuSpawnEnv` already feeds every choudoufu spawn. The env var rather
|
|
3066
|
-
than `-adoption-only`, because that flag suppresses the resource diff the
|
|
3067
|
-
overlay needs. Off by default because the sweep is bounded by the ACCOUNT rather
|
|
3068
|
-
than the estate, and behold polls. `0` means no, which is choudoufu's own
|
|
3069
|
-
spelling, not a truthiness test.
|
|
3070
|
-
|
|
3071
|
-
**Content matching is a closed per-type table**, and that is what decides
|
|
3072
|
-
whether a declaration can ever produce an `adoptable[]` row. `matchTable`
|
|
3073
|
-
(choudoufu's internal/live/foreign/classify.go) lists eleven types against the
|
|
3074
|
-
identity-bearing arguments a match may use — `aws_vpc` on `cidr_block`,
|
|
3075
|
-
`aws_security_group`/`aws_lb`/`aws_sns_topic` and friends on `name`,
|
|
3076
|
-
`aws_subnet` on `cidr_block` + `availability_zone`, `aws_acm_certificate` on
|
|
3077
|
-
`domain_name`. A type absent from it, in the table's own words, "can never
|
|
3078
|
-
produce a bind candidate". `aws_iam_role` is absent, which is why #412's first
|
|
3079
|
-
attempt measured a shape that cannot match rather than a gap. A resource with a
|
|
3080
|
-
`count`/`for_each` key is skipped too, so a fixture wants a scalar.
|
|
45
|
+
src/member-kind.ts is the one table (`registerMemberKind`, `MEMBER_KINDS`).
|
|
46
|
+
A probe is sync, read-only and runs no code. Routes never branch on kind:
|
|
47
|
+
differences live in the kind's `via.read` or `passes`. A `passes` function
|
|
48
|
+
mutates in place, guards on the IR's content rather than the served kinds,
|
|
49
|
+
and must not re-run. A test that stubs a kind's reader spreads the real spec
|
|
50
|
+
or it loses the passes. Add a pack in src/render.ts, a row in
|
|
51
|
+
src/status-vocabulary.ts if the kind has its own words, a doctor check if it
|
|
52
|
+
needs a binary, and tests in src/project.test.ts and src/estate.test.ts.
|
|
3081
53
|
|
|
3082
|
-
|
|
3083
|
-
recorded off floci: one scalar `aws_vpc` declaring a static `cidr_block`, its
|
|
3084
|
-
unmarked live twin created out of band, and the run asked with the opt-in. It
|
|
3085
|
-
carries the pairing M2 is about, a `NEEDS_DISCOVERY` omission and an
|
|
3086
|
-
`adoptable[]` row at the same address — plus `matched[]` naming what was
|
|
3087
|
-
compared and choudoufu's own `adopt_command`.
|
|
54
|
+
### Scratch infrastructure
|
|
3088
55
|
|
|
3089
|
-
|
|
56
|
+
Anything behold boots goes through `assertScratch` (src/scratch.ts): named
|
|
57
|
+
`behold-*`, refuses a taken name, tears down only what it created, never
|
|
58
|
+
binds :4566. Protected names are listed in `PROTECTED_INFRA`. A new boot site
|
|
59
|
+
gets a row in src/scratch.test.ts.
|
|
3090
60
|
|
|
3091
|
-
|
|
3092
|
-
second list is *cross-estate by construction* — data sources filtered on
|
|
3093
|
-
another estate's marker tags. So a 301-resource terralith of roles, policies
|
|
3094
|
-
and attachments drew no edge at all and the graph asserted "nothing in this
|
|
3095
|
-
estate references anything else", which is false about every one of them.
|
|
61
|
+
### Tests and checks
|
|
3096
62
|
|
|
3097
|
-
The
|
|
3098
|
-
|
|
3099
|
-
|
|
3100
|
-
|
|
3101
|
-
|
|
3102
|
-
|
|
3103
|
-
argument for each. In short: the lexicon names *blocks* in a path of module
|
|
3104
|
-
*calls* (`estate/module.team_pod/aws_iam_role.pod_role`) and choudoufu names
|
|
3105
|
-
*instances* in a path of module *instances*
|
|
3106
|
-
(`module.team_pod["pod-a"].aws_iam_role.pod_role[0]`), so one lexicon edge is a
|
|
3107
|
-
product — kept inside one module instance (Terraform's scoping, not a guess),
|
|
3108
|
-
joined key to key when both ends expand over the same keys (266 true edges on
|
|
3109
|
-
`terralith-4` against 666 of which ~400 would be false), landing on a module
|
|
3110
|
-
call's whole interior, and dropped whole when either end is a `var`, a
|
|
3111
|
-
`locals` or anything else the roster declares no card for.
|
|
63
|
+
- The local gate is `just check` (tsc, tests, build). The docs site has its own: `npm run build` in docs/ lints the agent prompts and checks every link.
|
|
64
|
+
- src/test-env.ts strips CHOUDOUFU_BIN, PLUNGE_BIN and similar from the test environment. A test that needs one sets it and restores it.
|
|
65
|
+
- Tests against a real chant run only when `BEHOLD_TEST_CHANT_BIN` is set; k3d tests only with `BEHOLD_K3D_TESTS=1`.
|
|
66
|
+
- src/render.ts and its imports must bundle for the browser, so no `node:` imports (`npm run check:browser-bundle` names the chain). After `web/icons` changes, run `npm run generate:icons`.
|
|
67
|
+
- src/graph-package.ts (built to dist/index.js, used by the action and the VS Code extension) stays free of hono, the MCP SDK and the Kubernetes client; src/read-graph-imports.test.ts holds it. The Kubernetes client is an optional peer, loaded by dynamic import.
|
|
68
|
+
- e2e scripts run under e2e/lib/safe-env.sh, which keeps real cloud credentials out; e2e/README.md lists the variables.
|
|
3112
69
|
|
|
3113
|
-
|
|
3114
|
-
`policy_arn`), so the card says what made the reference. **Without the
|
|
3115
|
-
lexicon there are no edges and the note says so** — carrying the terraform
|
|
3116
|
-
kind's own install line rather than the sentence behold has no reader to
|
|
3117
|
-
assert, and the lexicon's version is in the member's cache stamp, so
|
|
3118
|
-
installing it invalidates the edgeless IR rather than serving it forever.
|
|
70
|
+
### Merging
|
|
3119
71
|
|
|
3120
|
-
|
|
3121
|
-
|
|
3122
|
-
|
|
3123
|
-
|
|
3124
|
-
a box's components into shelves and resizes the box around them, re-laying each
|
|
3125
|
-
component on its own first (inside a cluster dagre interleaves them: a six-card
|
|
3126
|
-
cluster's bounding box spanned 46598 units) and wrapping a component that is a
|
|
3127
|
-
strip either way: the DNS fan is 19564 x 400 upright and 900 x 10046 on its
|
|
3128
|
-
side. A box under 4:1 is left exactly as it laid out. Measured: `terralith-4`
|
|
3129
|
-
7660 x 5162 with 266 edges, waterpark 3536 x 3138 at detail 2 and 7142 x 6974
|
|
3130
|
-
at detail 3 (from 4.2:1 and 15.1:1, the case #393's wrap did not answer).
|
|
72
|
+
No merge queue yet: open the pull request with the local gate passing and
|
|
73
|
+
stop; the orchestrator merges. Pull requests merge one at a time, in order,
|
|
74
|
+
each rebased onto what landed; no `gh pr merge --auto`. A repository admin
|
|
75
|
+
may push a tested integration branch's merge to `main` directly.
|
|
3131
76
|
|
|
3132
|
-
|
|
77
|
+
### Workbench and release
|
|
3133
78
|
|
|
3134
|
-
|
|
3135
|
-
|
|
3136
|
-
|
|
3137
|
-
|
|
3138
|
-
|
|
3139
|
-
annotation, a store card and a provider card (GCP Secret Manager, AWS Secrets
|
|
3140
|
-
Manager or Parameter Store, Vault, with the `remoteRef.key` values) for an
|
|
3141
|
-
ExternalSecret, and a source card for an Argo CD Application's `spec.source`
|
|
3142
|
-
and `spec.sources[]` or a Flux Kustomization's `sourceRef` and `path`. It reads
|
|
3143
|
-
the field paths chant#5098 and chant#5099 read, so a placeholder and a derived
|
|
3144
|
-
edge agree. A card's id is made from what it names, so two objects naming one
|
|
3145
|
-
thing share it, and a target the `graph` already holds gets no card and no
|
|
3146
|
-
edge. A field it cannot read goes in `notes`, never dropped.
|
|
79
|
+
workbench.json lists internal estates used for development; `just example
|
|
80
|
+
<entry>` serves one. Paths are siblings (`../chant`, `../choudoufu`); a
|
|
81
|
+
missing sibling just marks the entry unsatisfiable. `fountain-ops` runs its
|
|
82
|
+
setup in your working checkout and switches your kubectl context, so avoid it
|
|
83
|
+
unless asked.
|
|
3147
84
|
|
|
3148
|
-
|
|
3149
|
-
|
|
3150
|
-
live read that ExternalSecret has no store card and its keys stay off the
|
|
3151
|
-
provider card; its note carries `waitsOn: "INTENTIUS/chant#5116"`. The
|
|
3152
|
-
ServiceAccount, provider and source cards work on a live read today.
|
|
3153
|
-
src/outside-refs-live.test.ts reads a scratch k3d cluster through chant's
|
|
3154
|
-
lister to show it (BEHOLD_K3D_TESTS=1; the cluster is `behold-outside-refs-<pid>`,
|
|
3155
|
-
created and deleted by the test). Fixtures are in web/outside-refs.test.js.
|
|
85
|
+
`just release` tags `behold-v<version>` after the version-bump PR is in.
|
|
86
|
+
A tag push publishes, so never push a `behold-v*` tag by hand.
|