@intentius/behold 0.30.2 → 0.32.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 +791 -16
- package/README.md +78 -23
- package/THIRD_PARTY.md +6 -5
- package/demos.json +14 -9
- package/dist/cli.js +51926 -20221
- package/example-carve/README.md +19 -23
- package/example-carve/app/package.json +1 -1
- package/example-carve/app/src/carved.ts +3 -3
- package/example-carve/carve-report.json +1 -1
- package/example-carve/{legacy-tf → tf-root}/terraform.tfstate +1 -1
- package/example-choudoufu-estate/README.md +7 -0
- package/example-choudoufu-estate/chant.workspace.json +1 -1
- package/example-choudoufu-estate/scripts/choudoufu-down.sh +2 -1
- package/example-choudoufu-estate/scripts/choudoufu-up.sh +10 -3
- package/example-terraform-estate/README.md +32 -5
- package/example-terraform-estate/chant.workspace.json +1 -1
- package/example-terraform-estate/recorded/adoption/platform.json +72 -0
- package/example-terraform-estate/recorded/adoption/prod.json +224 -0
- package/example-three-cloud/README.md +111 -18
- package/example-three-cloud/aws/Pulumi.yaml +15 -0
- package/example-three-cloud/aws/index.ts +174 -0
- package/example-three-cloud/aws/package-lock.json +2725 -0
- package/example-three-cloud/aws/package.json +14 -0
- package/example-three-cloud/aws/tsconfig.json +17 -0
- package/example-three-cloud/azure/main.tf +48 -0
- package/example-three-cloud/azure/site.tf +104 -0
- package/example-three-cloud/chant.config.json +9 -0
- package/example-three-cloud/chant.workspace.json +30 -4
- package/example-three-cloud/dns/chant.config.ts +26 -1
- package/example-three-cloud/dns/src/records.component.ts +32 -6
- package/example-three-cloud/package-lock.json +48 -27
- package/example-three-cloud/package.json +8 -6
- package/example-three-cloud/scripts/emulators-up.sh +28 -1
- package/example-three-cloud/scripts/front-door.ts +679 -86
- package/package.json +26 -8
- package/schemas/graph/v1/graph.schema.json +140 -0
- package/web/adopt-pulumi.js +114 -0
- package/web/adopt-pulumi.test.js +28 -0
- package/web/adopt.js +203 -0
- package/web/adopt.test.js +27 -0
- package/web/app.js +367 -14
- package/web/boot-motion.js +6 -0
- package/web/carve-steps.js +1 -1
- package/web/carve-steps.test.js +2 -2
- package/web/change-set-overlay.js +12 -5
- package/web/change-set-overlay.test.js +22 -0
- package/web/cut-around.d.ts +30 -0
- package/web/cut-around.js +138 -0
- package/web/drift-stream.js +241 -0
- package/web/drift-stream.test.js +146 -0
- package/web/edge-weight.d.ts +8 -2
- package/web/edge-weight.js +38 -4
- package/web/edge-weight.test.js +55 -1
- package/web/graph-query.js +180 -0
- package/web/graph-query.test.js +49 -0
- package/web/graph.html +107 -0
- package/web/index-diff.js +109 -0
- package/web/index-diff.test.js +39 -0
- package/web/index.html +45 -20
- package/web/kiosk-ask-tips.js +15 -5
- package/web/kiosk-ask-tips.test.js +14 -1
- package/web/kiosk-estate-scene.js +72 -8
- package/web/kiosk-light-frame.js +1 -0
- package/web/kiosk-light.js +41 -3
- package/web/kiosk-member-kind.test.js +140 -0
- package/web/kiosk-popover.js +4 -1
- package/web/kiosk-side.js +296 -0
- package/web/kiosk-side.test.js +249 -0
- package/web/kiosk-watch.js +12 -0
- package/web/kiosk-watch.test.js +15 -1
- package/web/kiosk.html +47 -1
- package/web/kiosk.js +106 -7
- package/web/member-kind.js +31 -0
- package/web/neighbourhood.js +105 -0
- package/web/neighbourhood.test.js +131 -0
- package/web/outside-refs.js +515 -0
- package/web/outside-refs.test.js +249 -0
- package/web/template-apps.js +245 -0
- package/web/template-apps.test.js +252 -0
- package/web/templates.js +285 -0
- package/web/templates.test.js +155 -0
- package/web/terragucci-lifecycle.js +112 -62
- package/web/terragucci-lifecycle.test.js +29 -1
- package/web/terragucci-timeline.js +39 -2
- package/web/terragucci-timeline.test.js +42 -1
- package/web/theme-paint.js +14 -0
- package/example-three-cloud/aws/chant.config.ts +0 -8
- package/example-three-cloud/aws/site.component.ts +0 -13
- package/example-three-cloud/aws/src/site.ts +0 -27
- package/example-three-cloud/azure/chant.config.ts +0 -1
- package/example-three-cloud/azure/src/site.component.ts +0 -13
- package/example-three-cloud/azure/src/site.ts +0 -18
- /package/example-carve/{legacy-tf → tf-root}/cdn.tf +0 -0
- /package/example-carve/{legacy-tf → tf-root}/compute.tf +0 -0
- /package/example-carve/{legacy-tf → tf-root}/floci-override.tf.disabled +0 -0
- /package/example-carve/{legacy-tf → tf-root}/modules/cdn/main.tf +0 -0
- /package/example-carve/{legacy-tf → tf-root}/naming.tf +0 -0
- /package/example-carve/{legacy-tf → tf-root}/network.tf +0 -0
- /package/example-carve/{legacy-tf → tf-root}/observability.tf +0 -0
- /package/example-carve/{legacy-tf → tf-root}/outputs.tf +0 -0
- /package/example-carve/{legacy-tf → tf-root}/storage.tf +0 -0
- /package/example-carve/{legacy-tf → tf-root}/versions.tf +0 -0
package/AGENTS.md
CHANGED
|
@@ -21,7 +21,7 @@ apply creds.
|
|
|
21
21
|
A directory with a `chant.workspace.json` is a chant workspace (chant ≥ 0.81.0,
|
|
22
22
|
INTENTIUS/chant#2524). `behold serve <root>` serves it from chant's own member
|
|
23
23
|
list (`chant workspace ls --json`, read contract 1; any other contract is
|
|
24
|
-
refused), and reads each `chant`, `terraform` and `
|
|
24
|
+
refused), and reads each `chant`, `terraform`, `choudoufu` and `pulumi` member through
|
|
25
25
|
`chant workspace graph --member <name>`. A `choudoufu` member takes its block
|
|
26
26
|
graph from it (the estate's own edges, each block's `file` and `line`) and
|
|
27
27
|
joins it onto choudoufu's `live-check` roster, which still names the cards,
|
|
@@ -29,7 +29,15 @@ the rungs and the cross-estate references: chant's graph is one node per
|
|
|
29
29
|
block, ownership is per instance, and chant carries no rung or reference
|
|
30
30
|
(src/choudoufu-workspace.ts, #465). The ids are the roster's, as before, so a
|
|
31
31
|
saved layout keeps matching. behold's own lexicon read of a choudoufu
|
|
32
|
-
directory stays for a loose view only.
|
|
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
|
|
33
41
|
form chant composes. A member chant cannot read is drawn as one
|
|
34
42
|
`UnreadableMember` node carrying `attrs._unreadable: {code, message}` with
|
|
35
43
|
chant's reason code. An `other` member is listed on startup and in doctor and
|
|
@@ -37,6 +45,16 @@ draws nothing. A declaration with `members: []` (terragucci writes one for its
|
|
|
37
45
|
gates) declares nothing to draw, so serve, export and doctor read the
|
|
38
46
|
directory as they would without one, and say so (#489). `.behold.json`'s `members` are ignored beside a declaration;
|
|
39
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.
|
|
40
58
|
Several directories on the command line (`behold serve a b c`) stay the loose
|
|
41
59
|
view behold composes itself.
|
|
42
60
|
|
|
@@ -59,6 +77,52 @@ a scheduled read: it holds a slot in the read budget, has the read deadline,
|
|
|
59
77
|
and stops when the request does. `serve --hud <url>` (or `BEHOLD_HUD_URL`)
|
|
60
78
|
links a proposed decision to its review in hud.
|
|
61
79
|
|
|
80
|
+
## A folder with no declaration, read by its kinds' probes (behold#1079)
|
|
81
|
+
|
|
82
|
+
`chant workspace graph <dir> --discover` (INTENTIUS/chant#5095) finds the members
|
|
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.
|
|
92
|
+
|
|
93
|
+
src/discover-read.ts reads it through `src/workspace-reader.ts`, one chant call
|
|
94
|
+
per folder, and `readGraph` (src/read-graph.ts, signature unchanged) turns the
|
|
95
|
+
document into the `Workspace` a declaration would give. Each member then takes
|
|
96
|
+
its part of that one document (`discoveredVia`), so the estate code composes a
|
|
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
|
+
|
|
62
126
|
## Chant version floors (behold#691)
|
|
63
127
|
|
|
64
128
|
behold shells each project's own chant, so a read can reach a chant that
|
|
@@ -80,6 +144,75 @@ spawning the read. A new read adds its constant and entry in the issue that
|
|
|
80
144
|
adds the read, once the chant release is known, and reads through the read
|
|
81
145
|
contract (`src/workspace-reader.ts`), never chant's library.
|
|
82
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
|
+
|
|
83
216
|
## A pipeline's numbers, from Prometheus (behold#571)
|
|
84
217
|
|
|
85
218
|
`behold serve --prometheus <url>` (or `BEHOLD_PROMETHEUS_URL`) adds `GET
|
|
@@ -127,6 +260,78 @@ makes, `declaredReportUrl` in src/workspace.ts, floor
|
|
|
127
260
|
declaration included; the flag overrides it, and each answer's `urlFrom` says
|
|
128
261
|
`flag` or `declaration`. With neither, nothing changes.
|
|
129
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
|
+
|
|
130
335
|
## A plan job run locally (behold#685)
|
|
131
336
|
|
|
132
337
|
`POST /api/chant/ci/local` `{job: "plan", commit, pr, env?, base?, member?,
|
|
@@ -154,6 +359,64 @@ that holds for it: `ci run` gives the job a clean environment that keeps HOME,
|
|
|
154
359
|
so `serve --local`'s emulator env does not reach the job and the operator's
|
|
155
360
|
own credentials would. Cached-step marks wait on chant#4015.
|
|
156
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
|
+
|
|
157
420
|
## A terragucci estate, from its reports (#490)
|
|
158
421
|
|
|
159
422
|
`behold serve <repo> --terragucci <dir|s3://bucket/prefix|https://…>`
|
|
@@ -657,6 +920,101 @@ pending member becomes a real one only when its own read completes, and the
|
|
|
657
920
|
live pass a progressive request starts is the same one per member under the
|
|
658
921
|
same budget: a progressive load costs the estate no extra spawn.
|
|
659
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
|
+
|
|
660
1018
|
### What a read cost (#420, #421)
|
|
661
1019
|
|
|
662
1020
|
`GET /api/doctor` serves `diagnose()`, the same report `behold doctor` prints,
|
|
@@ -888,7 +1246,7 @@ would go.
|
|
|
888
1246
|
|
|
889
1247
|
### The walkthrough (`behold demo carve`, #254)
|
|
890
1248
|
|
|
891
|
-
`behold demo carve` copies a bundled
|
|
1249
|
+
`behold demo carve` copies a bundled mixed estate (a chant project
|
|
892
1250
|
beside a Terraform one), runs the advisor over the copy, and serves the same
|
|
893
1251
|
carve view plus a six-step stepper on the panel's Carve tab: advise → pick →
|
|
894
1252
|
emit → bridge → handoff → done.
|
|
@@ -1029,6 +1387,33 @@ GET /api/capabilities
|
|
|
1029
1387
|
"helpers":[...]}
|
|
1030
1388
|
```
|
|
1031
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
|
+
|
|
1032
1417
|
## Moving the person's open tab (#914)
|
|
1033
1418
|
|
|
1034
1419
|
`POST /api/view` changes what every open tab of this serve draws. It is a
|
|
@@ -1121,10 +1506,209 @@ remote does not take the LFS object, it refuses with the setup line and exits
|
|
|
1121
1506
|
1 before the branch moves; the local PNG is kept. `behold mcp`, `GET
|
|
1122
1507
|
/api/shot` and a `--public` serve never publish.
|
|
1123
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
|
+
|
|
1124
1708
|
## Over MCP: `behold mcp` (#916)
|
|
1125
1709
|
|
|
1126
1710
|
`behold mcp [project-dir] [--url <serve> | --port <n>]` is a stdio MCP server
|
|
1127
|
-
with
|
|
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
|
|
1128
1712
|
`capabilities` first (#926): it calls `GET /api/capabilities` and returns
|
|
1129
1713
|
chant's capability catalog, the read contract's `capabilities` document
|
|
1130
1714
|
(`chant search --capabilities --json`, INTENTIUS/chant#4375), byte for byte.
|
|
@@ -1142,6 +1726,24 @@ followed by a text block `{link, state, serve}`. They take `query`, `env`,
|
|
|
1142
1726
|
and `height`. The answers are chant's: behold passes chant's documents
|
|
1143
1727
|
through and computes none of its own.
|
|
1144
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
|
+
|
|
1145
1747
|
It finds the serve through `--url`/`--port`, then the per-user registry at
|
|
1146
1748
|
`<os.tmpdir()>/behold/serves/<pid>.json` (`{url, pid, projectDir, version,
|
|
1147
1749
|
startedAt}`, written by every serve at start, rewritten on a project switch,
|
|
@@ -1446,7 +2048,12 @@ or null where chant mapped none), `nodes` (`<member>/<id>` to the strongest
|
|
|
1446
2048
|
bucket and the actions on it), `counts`, `unchanged`, `gaps` (members that
|
|
1447
2049
|
failed to plan or have holes), `gate` (commit, run, `releaseDigest`) and
|
|
1448
2050
|
`planned` (a release gate's release and environment, chant#4045). An entry
|
|
1449
|
-
with no node is kept and listed in the Change set tab, never dropped.
|
|
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
|
|
1450
2057
|
(web/change-set-overlay.js) outlines each card in the drift legend's tokens
|
|
1451
2058
|
(managed for create, foreign for update or replace, degraded for delete or
|
|
1452
2059
|
forget) with a tag above it, never a fill; it is opened from the "change set"
|
|
@@ -1569,7 +2176,9 @@ document, so it is checked against chant's schema, vendored unchanged in
|
|
|
1569
2176
|
src/health-schema/ (chant PR #4193 at d727944c4) and validated with ajv, with
|
|
1570
2177
|
a hole's `reason` loosened to any string; a document the schema refuses is
|
|
1571
2178
|
refused whole. A project with no lexicon that reads health is `none`, not a
|
|
1572
|
-
failure. A member
|
|
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
|
|
1573
2182
|
every member is, the answer carries the refusal and `degraded`.
|
|
1574
2183
|
|
|
1575
2184
|
The answer is `nodes` (per id: `healthy`, `unhealthy` or `unknown` with
|
|
@@ -1597,13 +2206,41 @@ overlay gives that project's nodes.
|
|
|
1597
2206
|
|
|
1598
2207
|
`example-three-cloud` is a chant workspace (`dns`, `aws`, `azure`, `gcp`) on
|
|
1599
2208
|
floci, floci-az and floci-gcp; docs/src/content/docs/using/three-cloud.mdx is
|
|
1600
|
-
its page. `
|
|
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
|
|
1601
2238
|
emulators under chant's own container names, with the Docker socket, floci-az
|
|
1602
2239
|
running Container Apps unmocked), then serves with `--local --env local`.
|
|
1603
2240
|
`--local` on a workspace boots every chant member's emulators
|
|
1604
2241
|
(`emulatorDirs`/`emulatorsUp` in src/emulator.ts), not the first member's, and
|
|
1605
2242
|
tears down the same set. The `front-door` Op (`dns/ops/front-door.op.ts`)
|
|
1606
|
-
runs `scripts/front-door.ts`: apply all four, deactivate the Azure revision,
|
|
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,
|
|
1607
2244
|
wait for `azureCheck` to read unhealthy, then `behold export --open-env local
|
|
1608
2245
|
--open-zoom composites --note …`. `--note` (`settleNote` in src/export.ts) is
|
|
1609
2246
|
one line under 200 characters, written to the manifest as `note` and drawn at
|
|
@@ -1626,16 +2263,21 @@ behold made itself (both below).
|
|
|
1626
2263
|
The commands behold starts run with behold's own environment, so Deploy (`POST
|
|
1627
2264
|
/api/apply`, chant's local executor) applies with the credentials of whoever
|
|
1628
2265
|
started it. On a terragucci repo (a `terragucci.yml` in the served directory or
|
|
1629
|
-
above it, up to the git root) behold
|
|
1630
|
-
|
|
1631
|
-
|
|
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`
|
|
1632
2271
|
so the page offers no write, and auto-sync declines. The boundary is an
|
|
1633
2272
|
allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
|
|
1634
2273
|
any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
|
|
1635
2274
|
method and route, and that list holds only the exceptions below (the layout
|
|
1636
2275
|
cache, project open and reveal, demo open, refresh, and the four carve
|
|
1637
2276
|
steps), plus `POST /api/view`, which moves the open tabs and writes nothing
|
|
1638
|
-
(#914)
|
|
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
|
|
1639
2281
|
there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
|
|
1640
2282
|
app (`app.routes`, built plain, with a carve report and with `--terragucci`)
|
|
1641
2283
|
and asserts each one is allowlisted or answers 409, and that every allowlist
|
|
@@ -1679,6 +2321,76 @@ These are also the only writes a guarded product repo answers: terragucci
|
|
|
1679
2321
|
(`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
|
|
1680
2322
|
listed in `TERRAGUCCI_ALLOWED_WRITES`.
|
|
1681
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
|
+
|
|
1682
2394
|
`POST /api/layout` (#228) writes **one** file, and not in the served project:
|
|
1683
2395
|
the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
|
|
1684
2396
|
with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
|
|
@@ -1785,12 +2497,39 @@ changing it, the working rules that used to live in a handoff note and now
|
|
|
1785
2497
|
live here, with the enforceable ones enforced.
|
|
1786
2498
|
|
|
1787
2499
|
- **Branches and merges.** Work on a branch off `main` (an isolated worktree
|
|
1788
|
-
when more than one agent is active). `main` is protected by
|
|
1789
|
-
|
|
1790
|
-
|
|
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).
|
|
1791
2509
|
No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
|
|
1792
2510
|
next onto what landed.
|
|
1793
|
-
- **
|
|
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
|
|
1794
2533
|
also writes `.vitest-last.json` (the json reporter, PR #351), and `just
|
|
1795
2534
|
test` keeps the reporter's full output in `vitest.log`, both gitignored —
|
|
1796
2535
|
because #334's one-shot first-run failures kept losing the failing file's
|
|
@@ -2233,6 +2972,17 @@ same facts per card as JSON.
|
|
|
2233
2972
|
stays pending with no physical id, and chant carries its plan attributes
|
|
2234
2973
|
onto the declared node anyway (chant#4372). Its rows read `plan: create`,
|
|
2235
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.
|
|
2236
2986
|
- **choudoufu members read ownership and the plan through chant together**
|
|
2237
2987
|
(src/choudoufu-chant-read.ts, #924): src/choudoufu-plan.ts is gone, and a
|
|
2238
2988
|
re-check's `live-plan` is chant's, handed back to behold. See the choudoufu
|
|
@@ -2378,3 +3128,28 @@ strip either way: the DNS fan is 19564 x 400 upright and 900 x 10046 on its
|
|
|
2378
3128
|
side. A box under 4:1 is left exactly as it laid out. Measured: `terralith-4`
|
|
2379
3129
|
7660 x 5162 with 266 edges, waterpark 3536 x 3138 at detail 2 and 7142 x 6974
|
|
2380
3130
|
at detail 3 (from 4.2:1 and 15.1:1, the case #393's wrap did not answer).
|
|
3131
|
+
|
|
3132
|
+
## What live objects name outside the cluster (behold#1082)
|
|
3133
|
+
|
|
3134
|
+
`outsideRefs(objects, { graph })` in web/outside-refs.js is a pure function
|
|
3135
|
+
with no imports, so a browser bundle takes it whole. It turns Kubernetes
|
|
3136
|
+
objects as the API serves them into `{ cards, edges, notes }`: a cloud identity
|
|
3137
|
+
card for a ServiceAccount's `iam.gke.io/gcp-service-account`,
|
|
3138
|
+
`eks.amazonaws.com/role-arn` or `azure.workload.identity/client-id`
|
|
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.
|
|
3147
|
+
|
|
3148
|
+
Chant's live Kubernetes read masks every key matching /secret/i. An
|
|
3149
|
+
ExternalSecret's whole `spec.secretStoreRef` comes back as `<masked>`, so on a
|
|
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.
|