@intentius/behold 0.30.1 → 0.31.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 +475 -16
- package/README.md +25 -19
- package/demos.json +14 -9
- package/dist/cli.js +54900 -26771
- 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-terralith/README.md +1 -1
- 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 +13 -6
- 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 +614 -19
- 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/drift-stream.js +241 -0
- package/web/drift-stream.test.js +146 -0
- package/web/edge-weight.d.ts +1 -1
- package/web/edge-weight.js +5 -1
- package/web/edge-weight.test.js +19 -0
- package/web/embed.js +2 -2
- package/web/event-help-modal.js +18 -12
- package/web/event-help-modal.test.js +28 -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 +55 -0
- package/web/kiosk-ask-layout.js +85 -0
- package/web/kiosk-ask-layout.test.js +83 -0
- package/web/kiosk-ask-tips.js +477 -0
- package/web/kiosk-ask-tips.test.js +372 -0
- package/web/kiosk-ask.js +774 -0
- package/web/kiosk-ask.test.js +593 -0
- package/web/kiosk-banner.js +108 -0
- package/web/kiosk-banner.test.js +72 -0
- package/web/kiosk-center-cards.test.js +110 -0
- package/web/kiosk-estate-scene.js +267 -0
- package/web/kiosk-estate-scene.test.js +21 -0
- package/web/kiosk-event-help.js +4 -1
- package/web/kiosk-graph-pane.js +63 -0
- package/web/kiosk-graph-pane.test.js +105 -0
- package/web/kiosk-light-frame.js +197 -0
- package/web/kiosk-light.js +547 -0
- package/web/kiosk-light.test.js +297 -0
- package/web/kiosk-member-kind.test.js +140 -0
- package/web/kiosk-metrics.js +7 -4
- package/web/kiosk-modal-sticky.test.js +2 -1
- package/web/kiosk-popover.js +4 -1
- package/web/kiosk-refit.test.js +81 -0
- package/web/kiosk-reset.js +49 -0
- package/web/kiosk-reset.test.js +11 -0
- package/web/kiosk-shot.js +40 -2
- package/web/kiosk-shot.test.js +23 -1
- package/web/kiosk-side.js +296 -0
- package/web/kiosk-side.test.js +249 -0
- package/web/kiosk-vendor.js +85 -7
- package/web/kiosk-vendor.test.js +9 -9
- package/web/kiosk-watch.js +20 -4
- package/web/kiosk-watch.test.js +15 -1
- package/web/kiosk.html +153 -1
- package/web/kiosk.js +252 -27
- package/web/kiosk.test.js +25 -1
- package/web/member-kind.js +31 -0
- package/web/small-stage.test.js +4 -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-change.js +30 -13
- 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/tool-mark.js +4 -4
- package/web/tool-mark.test.js +1 -1
- package/web/vendors/atmos.svg +1 -0
- package/web/vendors/chant.svg +1 -0
- package/web/vendors/choudoufu.svg +1 -0
- package/web/vendors/terragrunt.svg +9 -0
- package/web/vendors/terragucci.svg +1 -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/web/vendors/choudoufu-128.png +0 -0
- package/web/vendors/choudoufu-64.png +0 -0
- /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
|
|
@@ -80,6 +88,37 @@ spawning the read. A new read adds its constant and entry in the issue that
|
|
|
80
88
|
adds the read, once the chant release is known, and reads through the read
|
|
81
89
|
contract (`src/workspace-reader.ts`), never chant's library.
|
|
82
90
|
|
|
91
|
+
### The chant release behold follows (behold#1005)
|
|
92
|
+
|
|
93
|
+
`CHANT_RELEASE` in src/chant-release.ts, `{ version, released }`, names the
|
|
94
|
+
chant release behold's newest reads need. It says `{ version: "0.124.58",
|
|
95
|
+
released: true }`: chant 0.124.58 is on npm (0.124.54 was the first release with the
|
|
96
|
+
drift record and its stream, the adoption report, `member-outputs` and
|
|
97
|
+
`@intentius/chant-lexicon-pulumi`; 0.124.58 adds the self-service modules). `ADOPTION_REPORT_CHANT_FLOOR`,
|
|
98
|
+
`DRIFT_RECORD_CHANT_FLOOR`, `DRIFT_STREAM_CHANT_FLOOR` and
|
|
99
|
+
`LEDGER_ROOT_MEMBER_CHANT_FLOOR` are its `version`, which is chant's
|
|
100
|
+
`NEXT_RELEASE` (INTENTIUS/chant#4480) at the cut. scripts/chant-release.ts
|
|
101
|
+
writes the files the switch decides (src/chant-release-sync.ts lists them):
|
|
102
|
+
the exact terraform and pulumi lexicon pins of example-terraform-estate,
|
|
103
|
+
example-choudoufu-estate and e2e/fixtures/pulumi-workspace (the published
|
|
104
|
+
chant, `PUBLISHED_CHANT`, while unreleased, so a plain `npm ci` meets them,
|
|
105
|
+
and `version` once released, moving with the floors; behold#1015), the
|
|
106
|
+
three-cloud workspace's pins (by path while unreleased, by package and
|
|
107
|
+
version once released) and its package.json, and behold's own chant ranges,
|
|
108
|
+
the pulumi lexicon devDependency among them. src/chant-release.test.ts holds
|
|
109
|
+
them to the switch, and `npx tsx scripts/chant-release.ts --check` lists any
|
|
110
|
+
file out of step.
|
|
111
|
+
|
|
112
|
+
With the release out, behold imports what it once copied from chant:
|
|
113
|
+
src/drift-line.ts decodes with `@intentius/chant/drift-record` (keeping
|
|
114
|
+
behold#995's unknown-status rule on top), src/graph-db/types.ts, listing.ts
|
|
115
|
+
and mask.ts re-export chant's engine-facts, index-document, cloud-lister and
|
|
116
|
+
mask modules, the investigation templates come from
|
|
117
|
+
`@intentius/chant/capabilities/templates` with no stub, the index diff is
|
|
118
|
+
`@intentius/chant/lifecycle/index-diff`, and `behold index` calls chant's
|
|
119
|
+
`runCloudIndex` statically. src/value-match.ts stays until the pulumi
|
|
120
|
+
lexicon has a `referenceCatalog` (chant#4535's note on behold#1005).
|
|
121
|
+
|
|
83
122
|
## A pipeline's numbers, from Prometheus (behold#571)
|
|
84
123
|
|
|
85
124
|
`behold serve --prometheus <url>` (or `BEHOLD_PROMETHEUS_URL`) adds `GET
|
|
@@ -127,6 +166,78 @@ makes, `declaredReportUrl` in src/workspace.ts, floor
|
|
|
127
166
|
declaration included; the flag overrides it, and each answer's `urlFrom` says
|
|
128
167
|
`flag` or `declaration`. With neither, nothing changes.
|
|
129
168
|
|
|
169
|
+
A member of another kind in an estate's components picture (#997): chant
|
|
170
|
+
writes its release ledger per component and a TerraformApplyOp writes no
|
|
171
|
+
release, so a `choudoufu` or `terraform` member is one card,
|
|
172
|
+
`<member>/<kind>` (lexicon `member-runs`, src/component-releases.ts), with
|
|
173
|
+
every resource of the member under it. Its `apply` and `_lastApply` are the
|
|
174
|
+
run index's newest `apply` entry for that member that passed (an entry with
|
|
175
|
+
no `member` is a run of the whole workspace and is not taken as one), and
|
|
176
|
+
its `since` and `_runSince` the newest entry after it, the member's or the
|
|
177
|
+
workspace's, when that did not pass. A card the index names nothing of says
|
|
178
|
+
`no runs recorded`, or `no run index read` when behold has no report URL;
|
|
179
|
+
behold never makes one up. The members are read through the same
|
|
180
|
+
`ciRunIndexOf` as the runs pane.
|
|
181
|
+
|
|
182
|
+
The same card lists the member's local applies (behold#1010,
|
|
183
|
+
src/member-local-applies.ts): the TerraformApplyOp runs that applied a root
|
|
184
|
+
in the member's directory, from `chant ledger runs --where
|
|
185
|
+
root_member=<member> --json` at the served workspace's root (chant#4482,
|
|
186
|
+
chant#4500), as `_localApplies` (newest first, at most five) and `local`, the
|
|
187
|
+
newest that passed. The read is sent only to a chant at
|
|
188
|
+
`LEDGER_ROOT_MEMBER_CHANT_FLOOR`, and a `runs` table whose `columns` lack
|
|
189
|
+
`root_member` reads as "this chant does not say", so the card keeps the run
|
|
190
|
+
index alone. A null `root_member` is unknown (chant#4508): such a run is on
|
|
191
|
+
no card, the declaring member's included, and the picture's note counts it
|
|
192
|
+
as an apply of an unknown root with its `labels.TerraformRoot`, read with
|
|
193
|
+
`--where labels.Apply=true`.
|
|
194
|
+
|
|
195
|
+
## Adopting a Pulumi stack into plunge (behold#999)
|
|
196
|
+
|
|
197
|
+
A `pulumi` member of a declared workspace is offered adoption into plunge,
|
|
198
|
+
the engine tier, through plunge's own `plunge stack adopt` (INTENTIUS/plunge#7,
|
|
199
|
+
P-L4). The Adopt tab and `GET /api/adopt` say what it gains (a record per
|
|
200
|
+
resource, marker tags, no stack lock, the checkpoint's IDs kept, a recorded
|
|
201
|
+
adoption that a re-run leaves alone, a back-out through `plunge stack export`
|
|
202
|
+
and `pulumi stack import`) and what it does not (plunge's refusals, bridged
|
|
203
|
+
types classed at the first run, record-only ownership for untaggable types).
|
|
204
|
+
|
|
205
|
+
- `GET /api/adopt/report?member=<name>[&stack=<name>]` runs `plunge stack
|
|
206
|
+
adopt --stack <s> --json --non-interactive` in the member's directory, with
|
|
207
|
+
`PULUMI_BACKEND_URL=plunge+<backend.url from Pulumi.yaml>`, no stdin and no
|
|
208
|
+
`--yes`. That is plunge's read-only stage, as one v1 JSON document
|
|
209
|
+
(INTENTIUS/plunge#17, plunge docs/plunge/ADOPT.md): every resource with its
|
|
210
|
+
fate (marker, record, pending, already-adopted), having written nothing.
|
|
211
|
+
Each resource gets its fate and why. When plunge refuses the adoption
|
|
212
|
+
(pending operations, a provider hiding the markers, an aws-native
|
|
213
|
+
create-only-tag type, foreign records), each refusal is listed with its
|
|
214
|
+
code and the URN it names. behold reads the JSON view only (behold#1007).
|
|
215
|
+
- `POST /api/adopt/start` `{member, stack?}` runs the same classification
|
|
216
|
+
through the runner's `track` and answers the confirm command, `cd <dir> &&
|
|
217
|
+
PULUMI_BACKEND_URL=<url> plunge stack adopt --stack <s> --yes`. A person
|
|
218
|
+
runs it. behold never passes `--yes` or `-y`, drops
|
|
219
|
+
`PULUMI_SKIP_CONFIRMATIONS` from the environment it hands plunge, and
|
|
220
|
+
refuses any other plunge argv before spawning (`assertClassificationOnly`,
|
|
221
|
+
src/pulumi-adoption.ts). After the confirm, point Pulumi.yaml's
|
|
222
|
+
`backend.url` at `plunge+<url>` so chant runs the member through plunge.
|
|
223
|
+
- The backend comes from the member's Pulumi.yaml only, never login state. A
|
|
224
|
+
`file://`, `s3://`, `gs://` or `azblob://` URL is a DIY backend; a
|
|
225
|
+
`plunge+` one is already plunge's. No URL, or a Pulumi Cloud URL, gets no
|
|
226
|
+
start, and the offer says why. The stack is read off the checked-in
|
|
227
|
+
`stack-export.json` URNs unless the request names one.
|
|
228
|
+
- A plunge without the `stack adopt --json` view is detected from its answer
|
|
229
|
+
(outcome `no-view`), not from a version, and refused with words naming
|
|
230
|
+
plunge 968b54748d, the commit that adds the view.
|
|
231
|
+
- The table is keyed on member kind (`ADOPTERS`, src/adoption.ts), the same
|
|
232
|
+
names the Terraform half uses on integration/choudoufu-engine.
|
|
233
|
+
`/api/adopt*` is refused in a public view, and the start goes through the
|
|
234
|
+
terragucci and SQL Yodeler write allowlist.
|
|
235
|
+
- Tests: src/pulumi-adoption.test.ts, web/adopt-pulumi.test.js, and the e2e
|
|
236
|
+
`just e2e-adopt-pulumi` (e2e/adopt-pulumi-e2e.sh with the stand-in
|
|
237
|
+
e2e/fixtures/adopt-pulumi/plunge), which asserts nothing is written before
|
|
238
|
+
a person runs the confirm line, even with `PULUMI_SKIP_CONFIRMATIONS=true`
|
|
239
|
+
in behold's environment.
|
|
240
|
+
|
|
130
241
|
## A plan job run locally (behold#685)
|
|
131
242
|
|
|
132
243
|
`POST /api/chant/ci/local` `{job: "plan", commit, pr, env?, base?, member?,
|
|
@@ -154,6 +265,64 @@ that holds for it: `ci run` gives the job a clean environment that keeps HOME,
|
|
|
154
265
|
so `serve --local`'s emulator env does not reach the job and the operator's
|
|
155
266
|
own credentials would. Cached-step marks wait on chant#4015.
|
|
156
267
|
|
|
268
|
+
## Adopting a Terraform root into choudoufu (behold#999)
|
|
269
|
+
|
|
270
|
+
A `terraform` member of a declared workspace is offered adoption into
|
|
271
|
+
choudoufu, the engine tier, through chant's `chant workspace promote <member>
|
|
272
|
+
--state <file>` (src/adoption.ts, floor `ADOPTION_REPORT_CHANT_FLOOR`, which
|
|
273
|
+
is `CHANT_RELEASE.version` in src/chant-release.ts until the chant release
|
|
274
|
+
carrying the report is cut; see "The coming chant release" below). The panel's
|
|
275
|
+
**Adopt** tab (web/adopt.js) shows, per member, what the engine tier gives
|
|
276
|
+
and what it does not, the command, and promote's report.
|
|
277
|
+
|
|
278
|
+
- `GET /api/adopt`: each adoptable member's offer `{member, kind, dir,
|
|
279
|
+
offered, engine, gains, limits, stateHint, state: {file, present},
|
|
280
|
+
command, approve, recorded, start: {offered, why?}}`. A `pulumi` member is
|
|
281
|
+
listed `offered: false` with `waits` (plunge P-L4, INTENTIUS/plunge#7):
|
|
282
|
+
`ADOPTERS` and `ADOPTION_WAITS` are keyed on member kind, and the Pulumi
|
|
283
|
+
half adds its adopter there.
|
|
284
|
+
- `GET /api/adopt/report?member=<name>[&state=<file>]`: promote's read-only
|
|
285
|
+
stage, `workspace promote <member> --state <abs> --dry-run --json`, through
|
|
286
|
+
the reader (`readPromoteReport`, `PROMOTE_REPORT_READ`). chant stages in a
|
|
287
|
+
throwaway worktree, runs `choudoufu live-check` and `live-import` without
|
|
288
|
+
`-approve`, records no gate and leaves the tree as it was. Its `adoption`
|
|
289
|
+
field (chant's `adoption-report.ts`, parsed from choudoufu's text) lists
|
|
290
|
+
every resource instance; behold gives each a `fate`: `claimed` (VERIFIED,
|
|
291
|
+
DRIFTED) or `left-out` (MISSING, UNTAGGABLE, UNADMITTED_TYPE), with a
|
|
292
|
+
`why` and choudoufu's `detail`. An unknown status is listed as `unknown`,
|
|
293
|
+
never dropped.
|
|
294
|
+
- `POST /api/adopt/start` `{member, state?}`: the delegated write. It starts
|
|
295
|
+
`workspace promote <member> --state <abs> --json` (never `--dry-run`,
|
|
296
|
+
never `-approve`) at the workspace root through the runner's `track`.
|
|
297
|
+
chant's gate decides: without an approval of the patch's digest promote
|
|
298
|
+
records a pending gate on `chant/lifecycle` and exits 3 (`gated`), and
|
|
299
|
+
nothing in the tree or the cloud is written; after `chant approve
|
|
300
|
+
workspace-promote <member> --plan <digest>`, the same start applies the
|
|
301
|
+
patch and runs `live-import -approve`. behold never approves here; the
|
|
302
|
+
approve line is shown to copy. `GET /api/adopt/runs/:id` answers one start
|
|
303
|
+
(`outcome`, `digest`, `words`, `approve`, `report`), the last 20 in memory;
|
|
304
|
+
the SSE `adopt-run` event names one that moved.
|
|
305
|
+
- The state file is a file name in the member's declared directory
|
|
306
|
+
(`terraform.tfstate` by default), never a path. A root on a remote backend
|
|
307
|
+
pulls one there under a name git ignores first, since promote refuses a
|
|
308
|
+
member with uncommitted changes.
|
|
309
|
+
|
|
310
|
+
Refusals: no declared workspace `404`, below the floor `409 chant-too-old`,
|
|
311
|
+
preview `403` for the start, a kind behold does not adopt `422 adopt-kind`,
|
|
312
|
+
no state file `422 adopt-state`, a second command while one runs `409 busy`.
|
|
313
|
+
A terragucci or SQL Yodeler repo refuses the start through the write
|
|
314
|
+
allowlist (`409`), and `--public` refuses every `/api/adopt` read (`403`)
|
|
315
|
+
and the start (`405`). The tab is not drawn in a public view, an embed, a
|
|
316
|
+
static export or a guarded repo.
|
|
317
|
+
|
|
318
|
+
`behold demo terraform-estate` serves `serve --adopt-recorded
|
|
319
|
+
recorded/adoption` (DemoServe `adoptRecorded`): one recorded `<member>.json`
|
|
320
|
+
per root in promote's shape, labelled recorded (`RECORDED_NOTE`), and no
|
|
321
|
+
start. `just e2e-adopt` (e2e/adopt-terraform-e2e.sh) runs the whole path over
|
|
322
|
+
a real chant and serve with choudoufu replaced by
|
|
323
|
+
e2e/fixtures/adopt/choudoufu, and asserts the report lists every resource
|
|
324
|
+
with its fate and that nothing is written before approval.
|
|
325
|
+
|
|
157
326
|
## A terragucci estate, from its reports (#490)
|
|
158
327
|
|
|
159
328
|
`behold serve <repo> --terragucci <dir|s3://bucket/prefix|https://…>`
|
|
@@ -369,6 +538,34 @@ checkout declares no Terraform root (`controlRepo` in
|
|
|
369
538
|
structural check otherwise. The page (`web/terragucci-estate.js`) draws it
|
|
370
539
|
in a layer over the graph area.
|
|
371
540
|
|
|
541
|
+
|
|
542
|
+
### The kiosk's prompt pane (#936)
|
|
543
|
+
|
|
544
|
+
A step of terragucci's `demo.json` may carry an `ask` (or `asks`, a list of
|
|
545
|
+
them played in order), and the file may carry `opening` and `closing` strings
|
|
546
|
+
(src/terragucci-demo.ts parses them; a field of the wrong type is null, and an
|
|
547
|
+
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,
|
|
548
|
+
the pane (`#k-ask`, web/kiosk-ask.js) takes the place of `#bar` and
|
|
549
|
+
`#k-caption` in Watch: a big monospace block at the foot of the screen. A
|
|
550
|
+
`prompt` is typed after `>` at 40 ms a character; an `action` shows at once
|
|
551
|
+
after a check mark; the `reply` prints after it, with `{roots}`, `{creates}`,
|
|
552
|
+
`{updates}`, `{deletes}` and `{error}` filled from the step's report (an
|
|
553
|
+
unknown token, or one without a value, is empty). The last three entries stay
|
|
554
|
+
above, faded. `opening` shows once at the scenario's first step
|
|
555
|
+
(`pull-request` or `planned`), `closing` at `applied`. While a job runs
|
|
556
|
+
(`pull-request`, `approved`, `merged`, `applying`, `resumed`) a status line
|
|
557
|
+
gives what is happening, the time since `started_at`, and `next`. With
|
|
558
|
+
`prefers-reduced-motion` everything shows at once. The pane's height is fixed
|
|
559
|
+
and replaces the caption in `captionRoomPx`, so it never covers the graph. A
|
|
560
|
+
step without an ask looks as it always did.
|
|
561
|
+
|
|
562
|
+
The pane tells the page through window events, each with detail
|
|
563
|
+
`{ ask, step, scenario }`: `behold:ask-start` before a beat is typed,
|
|
564
|
+
`behold:ask-done` when its reply has printed, and `behold:ask-clear` on a new
|
|
565
|
+
step with no ask. `{dependents}` is left to the lighting: it sets
|
|
566
|
+
`window.beholdAskTokens = { dependents: n }` on `behold:ask-start`, and the
|
|
567
|
+
reply reads it when it prints.
|
|
568
|
+
|
|
372
569
|
## Releases per environment, from the release ledger (#525)
|
|
373
570
|
|
|
374
571
|
`GET /api/lifecycle/releases[?fresh=1]` (src/lifecycle-releases.ts) reads
|
|
@@ -629,6 +826,101 @@ pending member becomes a real one only when its own read completes, and the
|
|
|
629
826
|
live pass a progressive request starts is the same one per member under the
|
|
630
827
|
same budget: a progressive load costs the estate no extra spawn.
|
|
631
828
|
|
|
829
|
+
### Drift, streamed card by card (#998)
|
|
830
|
+
|
|
831
|
+
`POST /api/workspace/drift/stream {member, addresses?}` (palette: **"Stream
|
|
832
|
+
drift card by card: <member>"**) runs `chant workspace drift --member <name>
|
|
833
|
+
--stream` at the workspace root and narrates it as `drift` frames on
|
|
834
|
+
`/api/events` (src/drift-stream.ts). The stream is chant's drift record in
|
|
835
|
+
NDJSON (chant#4451): one `drift-start` with the addresses it expects, one
|
|
836
|
+
`drift-record` per instance as its read finishes, one `drift-settle`. Each
|
|
837
|
+
line is decoded in `streamDrift` (src/workspace-reader.ts) by
|
|
838
|
+
src/drift-line.ts, which uses chant's own `decodeDriftLine` from
|
|
839
|
+
`@intentius/chant/drift-record` (behold#1005) and narrows its line to what a
|
|
840
|
+
card reads, and each record frame repaints only its own card. The
|
|
841
|
+
start is refused below `DRIFT_STREAM_CHANT_FLOOR` (409, the floor's refusal,
|
|
842
|
+
nothing spawned), unless `BEHOLD_DRIFT_CHANT` names the chant to run.
|
|
843
|
+
|
|
844
|
+
- **Per resource on a choudoufu member.** choudoufu's single-resource path
|
|
845
|
+
(`live-plan -resource`, choudoufu#2245) plans one resource and writes its
|
|
846
|
+
records when that plan ends, and there is no whole-estate stream. So behold
|
|
847
|
+
asks once per resource block (`--resource <addr>`, instance keys dropped,
|
|
848
|
+
data sources left out), one after another, from the card addresses the page
|
|
849
|
+
sends; the cards change colour resource by resource. Any other member is
|
|
850
|
+
asked once without `--resource`.
|
|
851
|
+
- **Reading is not a status.** Between a start and its settle, an expected
|
|
852
|
+
card that has not reported is `data-drift-reading`: dimmed and dashed, its
|
|
853
|
+
fill and `_status` unchanged. Only a record sets `_status`.
|
|
854
|
+
- **Not reached.** At settle, every expected address no record answered
|
|
855
|
+
becomes `not-observed` with reason `not-reached` (chant's fold rule), sent
|
|
856
|
+
as a record frame before the settle frame. A read that fails or prints a
|
|
857
|
+
line that does not decode is a `failed` frame: its cards stop reading and
|
|
858
|
+
keep the colour they had. A read that never started stops the run.
|
|
859
|
+
- **Colour** is `toneFor(record)`, #995's `(status, read)` table
|
|
860
|
+
(src/drift-tone.ts, below). A status or read outside it is neutral, and the
|
|
861
|
+
card carries `data-drift-unknown` and says so in its tooltip.
|
|
862
|
+
- One run at a time (`409 drift-streaming`); `{stop: true}` stops it.
|
|
863
|
+
`BEHOLD_DRIFT_CHANT` names the chant the read runs, for a chant built
|
|
864
|
+
ahead of the release that adds `workspace drift --stream`, and for
|
|
865
|
+
`just e2e-streamed-drift`'s fake (e2e/fixtures/fake-chant-drift); the
|
|
866
|
+
floor, `DRIFT_STREAM_CHANT_FLOOR`, is checked only against the root's own
|
|
867
|
+
chant, so it does not apply then.
|
|
868
|
+
|
|
869
|
+
### Colour from the drift record (#995)
|
|
870
|
+
|
|
871
|
+
Every card's live colour is one fixed table over chant's drift record
|
|
872
|
+
(chant#4451), keyed on the record's `status` and the `read` that answered,
|
|
873
|
+
and on nothing else: `DRIFT_TONE_TABLE` and `toneFor` in src/drift-tone.ts.
|
|
874
|
+
No engine is named there, so a Pulumi member (path 2, chant#4453) colours
|
|
875
|
+
through the same cells as the rest. The read limits the claim: an
|
|
876
|
+
`ownership` read's `in-sync` is green and labelled "bound (ownership only)"
|
|
877
|
+
(#404), a `state` read's `recorded` is neutral, and a state read that says
|
|
878
|
+
`in-sync` or `drifted` (a record chant refuses) is neutral and labelled. An
|
|
879
|
+
unknown status or read is neutral and labelled unknown, never a guessed
|
|
880
|
+
colour.
|
|
881
|
+
|
|
882
|
+
- **The drift document.** `chant workspace drift --member <name> [--read
|
|
883
|
+
<read>] [--resource <addr>] [--env <env>]` prints one member's drift
|
|
884
|
+
document (contract 1, `drift: "v1"`), read by the member's own engine. It is
|
|
885
|
+
`read("drift", driftArgs(ask))` on the workspace reader, the sixth
|
|
886
|
+
`BEHOLD_READS` entry, held by chant's conformance suite when that suite
|
|
887
|
+
lists `drift`. `paintWorkspaceDrift` (src/drift-overlay.ts) reads it per
|
|
888
|
+
member and paints `_status`, `_drift: {status, read, label, reason?,
|
|
889
|
+
engineCode?, fellBackFrom?, unknown?}` and `_unobserved` on each card.
|
|
890
|
+
`/api/overlay` on a declared workspace whose chant meets
|
|
891
|
+
`DRIFT_RECORD_CHANT_FLOOR` (`CHANT_RELEASE.version`, the release not cut yet) does this on
|
|
892
|
+
every read for the members with no live half of their own (`terraform`,
|
|
893
|
+
`pulumi`), and with `?drift=1` for `chant` and `choudoufu` members too, at
|
|
894
|
+
the cost of a second live read. `meta.driftRecord` lists each member's
|
|
895
|
+
painted and unplaced records and chant's error. With `?plan=1` a terraform
|
|
896
|
+
or choudoufu member is asked `--read plan`.
|
|
897
|
+
- **The reads behold still makes itself colour through the same table.** A
|
|
898
|
+
choudoufu member's `live-plan`/`live-ls` paint (src/choudoufu-live.ts
|
|
899
|
+
`verdictFor`) gives each address the status chant's adapter gives it
|
|
900
|
+
(`bound` in-sync, `unowned`/`adoptable` unclaimed, `ABSENT` pending, every
|
|
901
|
+
other omission not-observed, a listed item nothing declares undeclared) and
|
|
902
|
+
takes the table's tone, read `ownership`. A component status row's
|
|
903
|
+
reconciliation fallback (src/component-status.ts `reconciliationStatus`) is
|
|
904
|
+
chant's `componentStatusDriftRecords` mapping, read `live-read`.
|
|
905
|
+
- **UNOWNED, settled with chant.** An `UNOWNED` omission with no `unowned[]`
|
|
906
|
+
row is `not-observed` (`read-failed`, `engineCode: "UNOWNED"`), as chant C1
|
|
907
|
+
decided: neutral, not `warn`. With its `unowned[]` row it is `unclaimed`
|
|
908
|
+
and `warn`, as before.
|
|
909
|
+
- **Which read answered a root** is the IR's `rootReads` (chant#4452):
|
|
910
|
+
`terraform.roots.<root>` with `depth`, `fellBackTo` and `reason`
|
|
911
|
+
(src/terraform-plan.ts `planRootAnswers`, src/choudoufu-chant-read.ts
|
|
912
|
+
`rootAnswerOf`). chant's note text is not parsed. A chant that puts no
|
|
913
|
+
`rootReads` on the IR reports no root: a stock root's cards carry no plan
|
|
914
|
+
answer, and a choudoufu re-check reads as live-plan alone.
|
|
915
|
+
- **choudoufu card ids and chant node ids (the B3 follow-up).** behold keeps
|
|
916
|
+
a choudoufu member's card ids, the roster's `<member>/<address>`, because
|
|
917
|
+
saved layouts are keyed on them, while chant names the same blocks
|
|
918
|
+
`<member>/<root>/<block path>`. One alias table, built from chant's graph
|
|
919
|
+
of the member (`choudoufuCardAliases`, src/drift-overlay.ts), maps a chant
|
|
920
|
+
node and an instance address onto the card (`cardIdFor`), and both the
|
|
921
|
+
change-set overlay (src/change-set-overlay.ts) and drift records use it. A
|
|
922
|
+
node the table does not know lands on no card and is listed.
|
|
923
|
+
|
|
632
924
|
### What a read cost (#420, #421)
|
|
633
925
|
|
|
634
926
|
`GET /api/doctor` serves `diagnose()`, the same report `behold doctor` prints,
|
|
@@ -860,7 +1152,7 @@ would go.
|
|
|
860
1152
|
|
|
861
1153
|
### The walkthrough (`behold demo carve`, #254)
|
|
862
1154
|
|
|
863
|
-
`behold demo carve` copies a bundled
|
|
1155
|
+
`behold demo carve` copies a bundled mixed estate (a chant project
|
|
864
1156
|
beside a Terraform one), runs the advisor over the copy, and serves the same
|
|
865
1157
|
carve view plus a six-step stepper on the panel's Carve tab: advise → pick →
|
|
866
1158
|
emit → bridge → handoff → done.
|
|
@@ -990,7 +1282,9 @@ folder's scratch project. Each capability has its `name`, `meaning`,
|
|
|
990
1282
|
it leaves `notEvaluated`, its `rule`, and per lexicon whether it is
|
|
991
1283
|
supplied. A chant below 0.124.46 answers 422 `code: "chant-too-old"`
|
|
992
1284
|
(`CAPABILITIES_CHANT_FLOOR`). behold mcp's `capabilities` tool returns the
|
|
993
|
-
same text.
|
|
1285
|
+
same text. behold keeps the document per checkout and commit, so a second
|
|
1286
|
+
read of an unmoved checkout runs no chant; a `--public` serve refuses the
|
|
1287
|
+
route with 403 (#978).
|
|
994
1288
|
|
|
995
1289
|
```
|
|
996
1290
|
GET /api/capabilities
|
|
@@ -999,6 +1293,33 @@ GET /api/capabilities
|
|
|
999
1293
|
"helpers":[...]}
|
|
1000
1294
|
```
|
|
1001
1295
|
|
|
1296
|
+
### The graph pane: Cypher and resolve-from-resource (behold#1027)
|
|
1297
|
+
|
|
1298
|
+
Every member's chant IR, every engine graph document (`choudoufu live-graph
|
|
1299
|
+
-json`, `plunge graph --json`, read from `engine-graph.json` beside a member
|
|
1300
|
+
or `.behold/graph/*.json`), every index version (the latest per scope in
|
|
1301
|
+
`.chant/store/index/`, `_index/` on `refs/chant/snapshots`, and behold's
|
|
1302
|
+
per-user index directory) and every cloud listing in one LadybugDB per
|
|
1303
|
+
session. Tables: `Resource` keyed `<member>/<id>` (or the source's scope
|
|
1304
|
+
key), `CloudId` with `KNOWN_AS` from each Resource, and `REF` with `grain`,
|
|
1305
|
+
`origin` (`derived` for an identity match, with its `rule`) and `ambiguous`.
|
|
1306
|
+
The database is behold's own file under `$XDG_DATA_HOME/behold/graph` and
|
|
1307
|
+
read-only once built; a query that writes is refused. Cypher needs the
|
|
1308
|
+
optional peer `@ladybugdb/core` and answers 503 `graph-peer-missing` with the
|
|
1309
|
+
install line without it; resolve, the template catalog and the path-pattern
|
|
1310
|
+
templates work without it. Every answer carries `sources`, each with
|
|
1311
|
+
`observedAt` (null for a declared source) and `readAt`. A `--public` serve
|
|
1312
|
+
refuses the pane. behold mcp's `ask` takes `cypher` or `resource` (with
|
|
1313
|
+
`template` and `inputs`) beside `query`. All GET.
|
|
1314
|
+
|
|
1315
|
+
```
|
|
1316
|
+
GET /api/graphdb sources, counts, notes, peer
|
|
1317
|
+
GET /api/graphdb/query?cypher=¶ms= {"columns","rows","keys","draw":{nodes,edges},"link","sources"}
|
|
1318
|
+
GET /api/graphdb/resolve?ref= {"candidates":[{key,matchedBy,...}],"templates":[...],"sources"}
|
|
1319
|
+
GET /api/graphdb/template?name=&node=&in.<input>=
|
|
1320
|
+
GET /graph the pane
|
|
1321
|
+
```
|
|
1322
|
+
|
|
1002
1323
|
## Moving the person's open tab (#914)
|
|
1003
1324
|
|
|
1004
1325
|
`POST /api/view` changes what every open tab of this serve draws. It is a
|
|
@@ -1416,7 +1737,12 @@ or null where chant mapped none), `nodes` (`<member>/<id>` to the strongest
|
|
|
1416
1737
|
bucket and the actions on it), `counts`, `unchanged`, `gaps` (members that
|
|
1417
1738
|
failed to plan or have holes), `gate` (commit, run, `releaseDigest`) and
|
|
1418
1739
|
`planned` (a release gate's release and environment, chant#4045). An entry
|
|
1419
|
-
with no node is kept and listed in the Change set tab, never dropped.
|
|
1740
|
+
with no node is kept and listed in the Change set tab, never dropped. An entry
|
|
1741
|
+
for one instance of a counted block (#996) is put on the instance's node,
|
|
1742
|
+
`<blockNode>[k]`, with `block` naming the block, whether chant mapped it to the
|
|
1743
|
+
block node (before chant#4454) or the instance node; the block's node carries
|
|
1744
|
+
the rollup (`instances`), so its card is outlined when the instance cards are
|
|
1745
|
+
not drawn. The page
|
|
1420
1746
|
(web/change-set-overlay.js) outlines each card in the drift legend's tokens
|
|
1421
1747
|
(managed for create, foreign for update or replace, degraded for delete or
|
|
1422
1748
|
forget) with a tag above it, never a fill; it is opened from the "change set"
|
|
@@ -1539,7 +1865,9 @@ document, so it is checked against chant's schema, vendored unchanged in
|
|
|
1539
1865
|
src/health-schema/ (chant PR #4193 at d727944c4) and validated with ajv, with
|
|
1540
1866
|
a hole's `reason` loosened to any string; a document the schema refuses is
|
|
1541
1867
|
refused whole. A project with no lexicon that reads health is `none`, not a
|
|
1542
|
-
failure. A member
|
|
1868
|
+
failure. A member of another kind (#997) is listed as `none` without a
|
|
1869
|
+
spawn: the read builds a chant project and it has none. A member below the
|
|
1870
|
+
floor is refused before anything is spawned; when
|
|
1543
1871
|
every member is, the answer carries the refusal and `degraded`.
|
|
1544
1872
|
|
|
1545
1873
|
The answer is `nodes` (per id: `healthy`, `unhealthy` or `unknown` with
|
|
@@ -1567,13 +1895,41 @@ overlay gives that project's nodes.
|
|
|
1567
1895
|
|
|
1568
1896
|
`example-three-cloud` is a chant workspace (`dns`, `aws`, `azure`, `gcp`) on
|
|
1569
1897
|
floci, floci-az and floci-gcp; docs/src/content/docs/using/three-cloud.mdx is
|
|
1570
|
-
its page. `
|
|
1898
|
+
its page. `azure` is a choudoufu estate (`azure/*.tf`, choudoufu#2246), so the
|
|
1899
|
+
demo requires choudoufu, `--local` boots no emulator for it (the setup starts
|
|
1900
|
+
floci-az, with TLS), and the root's `chant.config.json` names it as the
|
|
1901
|
+
terraform lexicon's `azure` root. `aws` is a Pulumi program on plunge
|
|
1902
|
+
(behold#1000: `aws/index.ts`, kind `pulumi`, `Pulumi.yaml` naming the
|
|
1903
|
+
`plunge+file://./.plunge` backend), so the demo requires plunge too
|
|
1904
|
+
(PLUNGE_BIN counts, as CHOUDOUFU_BIN does). `scripts/front-door.ts plan --out <file>`
|
|
1905
|
+
(`npm run change-set`) composes one change set, a part per engine: chant
|
|
1906
|
+
parts for dns and gcp, azure's choudoufu part from `choudoufuPlanSet`, and
|
|
1907
|
+
aws's pulumi part from `plunge preview` (`previewPulumiMember`);
|
|
1908
|
+
e2e/three-cloud-change-set-e2e.sh asserts it. `apply --change-set <file>`
|
|
1909
|
+
plans again and refuses the whole set, exit 3, when any part moved
|
|
1910
|
+
(.front-door/apply-verdict.json names each), and `oob-edit <member>` makes
|
|
1911
|
+
one out-of-band edit per member for the live run;
|
|
1912
|
+
e2e/multi-engine-demo-e2e.sh asserts the composed graph, a colour change per
|
|
1913
|
+
engine and the refusal, with a fake plunge and recorded drift streams. dns
|
|
1914
|
+
reads azure's `azureEndpoint` and aws's `awsEndpoint` through chant
|
|
1915
|
+
(chant#4455): dns/src/records.component.ts has `memberOutputsComponent("azure")`,
|
|
1916
|
+
`memberOutputsComponent("aws")` and a records step whose cfn-deploy inputs
|
|
1917
|
+
are `stackOutput("azure", "azureEndpoint")` and `stackOutput("aws",
|
|
1918
|
+
"awsEndpoint")`, and dns lists `terraform` (with `terraform.roots.azure` at
|
|
1919
|
+
`../azure`, which is the change signal) and `pulumi`. `member-outputs` and
|
|
1920
|
+
the pulumi lexicon are in chant 0.124.54 and newer, and the example depends on 0.124.58, and
|
|
1921
|
+
the workspace pins both lexicons by package at that version
|
|
1922
|
+
(`CHANT_RELEASE`, src/chant-release.ts); behold's own code does not import
|
|
1923
|
+
them, so there is no floor. scripts/front-door.ts loads the pulumi lexicon only for
|
|
1924
|
+
the aws plan, so `npm ci` in the example runs every other subcommand. The e2e's second half runs
|
|
1925
|
+
`chant components pr-plan --member dns` over a change to azure/ and asserts
|
|
1926
|
+
dns's records step names azure under its unresolved inputs. `behold demo three-cloud` runs `scripts/emulators-up.sh` (the
|
|
1571
1927
|
emulators under chant's own container names, with the Docker socket, floci-az
|
|
1572
1928
|
running Container Apps unmocked), then serves with `--local --env local`.
|
|
1573
1929
|
`--local` on a workspace boots every chant member's emulators
|
|
1574
1930
|
(`emulatorDirs`/`emulatorsUp` in src/emulator.ts), not the first member's, and
|
|
1575
1931
|
tears down the same set. The `front-door` Op (`dns/ops/front-door.op.ts`)
|
|
1576
|
-
runs `scripts/front-door.ts`: apply all four, deactivate the Azure revision,
|
|
1932
|
+
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,
|
|
1577
1933
|
wait for `azureCheck` to read unhealthy, then `behold export --open-env local
|
|
1578
1934
|
--open-zoom composites --note …`. `--note` (`settleNote` in src/export.ts) is
|
|
1579
1935
|
one line under 200 characters, written to the manifest as `note` and drawn at
|
|
@@ -1596,16 +1952,21 @@ behold made itself (both below).
|
|
|
1596
1952
|
The commands behold starts run with behold's own environment, so Deploy (`POST
|
|
1597
1953
|
/api/apply`, chant's local executor) applies with the credentials of whoever
|
|
1598
1954
|
started it. On a terragucci repo (a `terragucci.yml` in the served directory or
|
|
1599
|
-
above it, up to the git root) behold
|
|
1600
|
-
|
|
1601
|
-
|
|
1955
|
+
above it, up to the git root) behold deploys, approves and applies nothing,
|
|
1956
|
+
and the only things it starts are terragucci's own request, rollout and
|
|
1957
|
+
action workflows (below):
|
|
1958
|
+
every other POST that deploys, approves or starts a run answers `409` with
|
|
1959
|
+
`code: "terragucci"` and names the pipeline (`src/terragucci-repo.ts`, #489), `/api/project` carries `terragucci`
|
|
1602
1960
|
so the page offers no write, and auto-sync declines. The boundary is an
|
|
1603
1961
|
allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
|
|
1604
1962
|
any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
|
|
1605
1963
|
method and route, and that list holds only the exceptions below (the layout
|
|
1606
1964
|
cache, project open and reveal, demo open, refresh, and the four carve
|
|
1607
1965
|
steps), plus `POST /api/view`, which moves the open tabs and writes nothing
|
|
1608
|
-
(#914)
|
|
1966
|
+
(#914), `POST /api/templates/request`, which dispatches terragucci's
|
|
1967
|
+
request workflow (behold#1035), `POST /api/templates/upgrade`, which
|
|
1968
|
+
dispatches its rollout workflow (behold#1036), and `POST
|
|
1969
|
+
/api/templates/action`, which dispatches its action workflow (behold#1037). A new write route is refused on a terragucci repo until it is added
|
|
1609
1970
|
there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
|
|
1610
1971
|
app (`app.routes`, built plain, with a carve report and with `--terragucci`)
|
|
1611
1972
|
and asserts each one is allowlisted or answers 409, and that every allowlist
|
|
@@ -1649,6 +2010,76 @@ These are also the only writes a guarded product repo answers: terragucci
|
|
|
1649
2010
|
(`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
|
|
1650
2011
|
listed in `TERRAGUCCI_ALLOWED_WRITES`.
|
|
1651
2012
|
|
|
2013
|
+
`POST /api/templates/request` (behold#1035, `src/templates.ts`),
|
|
2014
|
+
`POST /api/templates/upgrade` (behold#1036) and `POST /api/templates/action`
|
|
2015
|
+
(behold#1037) are the three starts on a terragucci repo, and they write
|
|
2016
|
+
nothing anywhere. The request is described first. It is on the
|
|
2017
|
+
allowlist, and because the list also guards SQL Yodeler repos the handler
|
|
2018
|
+
refuses on its own (`409`, the product's refusal or `code: "no-templates"`)
|
|
2019
|
+
unless the served repo is terragucci and its terragucci.yml sets
|
|
2020
|
+
`templates`. It checks the request against what the repo's own
|
|
2021
|
+
`terragucci templates list --json` printed (`GET /api/templates` answers that
|
|
2022
|
+
output byte for byte) and against chant's template-request/v1 (`@intentius/chant/template-request`), then dispatches
|
|
2023
|
+
the committed `terragucci-request.yml` with the inputs `template`, `version`,
|
|
2024
|
+
`name` and `inputs`, plus `claimed_by` (the person behold says filled the
|
|
2025
|
+
form) only when that workflow declares the input. On GitHub the dispatch and
|
|
2026
|
+
every read go through the operator's `gh` (`dispatchWorkflow`,
|
|
2027
|
+
`pullRequestOn` in src/gh-run.ts); on Forgejo through the HTTP API with the
|
|
2028
|
+
operator's `FORGEJO_TOKEN` (src/forgejo-api.ts), sent only to the origin's
|
|
2029
|
+
host and never stored or shown. GitLab has no request workflow and answers
|
|
2030
|
+
`422 request-forge` with the `npx terragucci request` line to run. behold
|
|
2031
|
+
never runs `terragucci request`, never shells out to plan or apply, and holds
|
|
2032
|
+
no apply credential: the run in CI opens the pull request with the repo's own
|
|
2033
|
+
token, its actor is the requester the forge vouches for, and the pull request
|
|
2034
|
+
is planned and reviewed like any other (ruling A of INTENTIUS/chant#4642). The
|
|
2035
|
+
follow runs in the runner's single slot, and `GET /api/templates/requests/:id`
|
|
2036
|
+
answers the run's end and the pull request's number and URL. `--public`
|
|
2037
|
+
refuses both reads (`403`) and the post (`405`).
|
|
2038
|
+
|
|
2039
|
+
With `app` in the body (behold#1036) the request asks for an add-on in that
|
|
2040
|
+
app's root. The template must be an add-on template (else `422 wrong-kind`),
|
|
2041
|
+
the app must be one the repo's own `terragucci templates apps --json` lists
|
|
2042
|
+
(`GET /api/templates/apps` answers that output byte for byte), else `422
|
|
2043
|
+
not-an-app`, and the add-on's name must not be a module the app's root already
|
|
2044
|
+
has (`422 addon-exists`). The dispatch adds the `app` input, and the branch is
|
|
2045
|
+
`request/<template>/<app>/<addon>`.
|
|
2046
|
+
|
|
2047
|
+
`POST /api/templates/upgrade` takes `{app, version?}`. It reads the apps again
|
|
2048
|
+
and takes the module and version from terragucci, never from the caller: the
|
|
2049
|
+
app's `template` and its `upgrade` (`422 not-an-app`, `422 no-upgrade` when
|
|
2050
|
+
`upgrade` is null, `409 stale-upgrade` when `version` is not it). It refuses
|
|
2051
|
+
on its own like the request, then dispatches the committed
|
|
2052
|
+
`terragucci-rollout.yml` with `module` and `version` only (`409
|
|
2053
|
+
no-rollout-workflow` when it is not committed, `409 terragucci-too-old` when
|
|
2054
|
+
it takes neither input), through the same `gh` and Forgejo paths and the same
|
|
2055
|
+
runner slot. A person starts it; terragucci's existing rollout opens one pull
|
|
2056
|
+
request per wave, and each wave is planned, reviewed and applied by the
|
|
2057
|
+
pipeline (ruling D). GitLab's rollout job takes no dispatch inputs, so GitLab
|
|
2058
|
+
answers `422 request-forge` with the `npx terragucci rollout` line. `--public`
|
|
2059
|
+
refuses the apps read (`403`) and the post (`405`).
|
|
2060
|
+
|
|
2061
|
+
`POST /api/templates/action` takes `{root, address}`. It reads the apps again,
|
|
2062
|
+
and the address must be one terragucci lists in that root's `actions` (`422
|
|
2063
|
+
not-an-app` for a root no app has, `422 unknown-action` otherwise); nothing
|
|
2064
|
+
starts before that. A root whose engine has no action invocation (terragucci.yml's
|
|
2065
|
+
`binary`, the repo's `.opentofu-version`, or `.tofu` files in the root, as
|
|
2066
|
+
terragucci detects it) answers `422 action-engine` naming OpenTofu or
|
|
2067
|
+
choudoufu (ruling E), and `/api/project` carries `terragucciActionRefusal` so
|
|
2068
|
+
the buttons say so. It refuses on its own like the request, then dispatches the
|
|
2069
|
+
committed `terragucci-action.yml` with `root` and `address` only (`409
|
|
2070
|
+
no-action-workflow` when it is not committed, which terragucci does only for
|
|
2071
|
+
Terraform roots; `409 terragucci-too-old` when it takes neither input), through
|
|
2072
|
+
the same `gh` and Forgejo paths and the same runner slot. The run asks chant's
|
|
2073
|
+
gated request (op `tf-action`, gate `<root>:<address>`) and waits for a person
|
|
2074
|
+
other than the requester to run `terragucci approve action <root> --plan
|
|
2075
|
+
<digest>`; behold approves nothing and never runs the action. The lifecycle
|
|
2076
|
+
lane reads `_gates/tf-action.jsonl` and `_gates/tf-action/applied.jsonl` into
|
|
2077
|
+
`actions` (`src/terragucci-lifecycle.ts`), apart from the waves: a waiting
|
|
2078
|
+
gate carries that approve line, the requester's own approval is listed as one
|
|
2079
|
+
that does not count, and an applied one carries the run's `ok` or `failed`.
|
|
2080
|
+
GitLab answers `422 request-forge` with the `npx terragucci action` line.
|
|
2081
|
+
`--public` refuses the post (`405`).
|
|
2082
|
+
|
|
1652
2083
|
`POST /api/layout` (#228) writes **one** file, and not in the served project:
|
|
1653
2084
|
the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
|
|
1654
2085
|
with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
|
|
@@ -1755,12 +2186,29 @@ changing it, the working rules that used to live in a handoff note and now
|
|
|
1755
2186
|
live here, with the enforceable ones enforced.
|
|
1756
2187
|
|
|
1757
2188
|
- **Branches and merges.** Work on a branch off `main` (an isolated worktree
|
|
1758
|
-
when more than one agent is active). `main` is protected by
|
|
1759
|
-
|
|
1760
|
-
|
|
2189
|
+
when more than one agent is active). `main` is protected by ruleset
|
|
2190
|
+
22042490, which requires a PR and a green `check` job in `ci.yml` of
|
|
2191
|
+
everyone but the repository admin role. That role bypasses it
|
|
2192
|
+
(`bypass_mode: always`, behold#1006, as chant and choudoufu have), so an
|
|
2193
|
+
admin may push a tested integration branch's merge to `main` directly;
|
|
2194
|
+
every other change arrives as a PR and merges once the check is green. A
|
|
2195
|
+
check that has merely settled is not a pass — read the lines. The
|
|
2196
|
+
ruleset's name still reads "every change is a PR with a green ci check";
|
|
2197
|
+
renaming it is a settings change for the maintainer (behold#1018).
|
|
1761
2198
|
No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
|
|
1762
2199
|
next onto what landed.
|
|
1763
|
-
- **
|
|
2200
|
+
- **Emulator e2e scripts** take their container names, ports and images
|
|
2201
|
+
from the environment and run under `e2e/lib/safe-env.sh`, which keeps real
|
|
2202
|
+
cloud credentials out of reach and fails on a real-cloud rejection in the
|
|
2203
|
+
log; e2e/README.md has the variables (behold#1032).
|
|
2204
|
+
- **The local gate** is `just check` (tsc, tests, build). The tests never read
|
|
2205
|
+
the caller's environment (behold#1013): src/test-env.ts, vitest's setup
|
|
2206
|
+
file, removes CHOUDOUFU_BIN, PLUNGE_BIN and the other variables behold
|
|
2207
|
+
reads to pick a binary or a service, and vitest.config.ts points
|
|
2208
|
+
PULUMI_BACKEND_URL at an empty `file://` directory made for the run, with
|
|
2209
|
+
PULUMI_SKIP_UPDATE_CHECK=true, so no pulumi or plunge a test starts sees
|
|
2210
|
+
the machine's login. A test that needs one of them sets it and puts back
|
|
2211
|
+
what was there. Every vitest run
|
|
1764
2212
|
also writes `.vitest-last.json` (the json reporter, PR #351), and `just
|
|
1765
2213
|
test` keeps the reporter's full output in `vitest.log`, both gitignored —
|
|
1766
2214
|
because #334's one-shot first-run failures kept losing the failing file's
|
|
@@ -2203,6 +2651,17 @@ same facts per card as JSON.
|
|
|
2203
2651
|
stays pending with no physical id, and chant carries its plan attributes
|
|
2204
2652
|
onto the declared node anyway (chant#4372). Its rows read `plan: create`,
|
|
2205
2653
|
`unknown: N until apply`, `read: plan`.
|
|
2654
|
+
- **A `count`/`for_each` block draws a card per instance** (#996,
|
|
2655
|
+
src/instance-cards.ts). The id is the block's node id and the key as
|
|
2656
|
+
Terraform prints it, `app/aws_s3_bucket.logs[0]`, `<member>/` in front on an
|
|
2657
|
+
estate, the same rule chant's graph uses for its instance nodes
|
|
2658
|
+
(INTENTIUS/chant#4454). Until chant emits them, behold derives them from the
|
|
2659
|
+
plan's per-instance rows (`planActions` by instance address, each change and
|
|
2660
|
+
drift row's `instance`), so each card has its own action, changes and drift.
|
|
2661
|
+
An instance node chant draws is kept and only painted. The block card stays
|
|
2662
|
+
as the rollup: chant's aggregate `_plan`, `attrs._instances` and an
|
|
2663
|
+
`instances` row. A key under a module instance (`module.a[0]...[1]`) stays
|
|
2664
|
+
in the rollup. A choudoufu member's roster is per instance already.
|
|
2206
2665
|
- **choudoufu members read ownership and the plan through chant together**
|
|
2207
2666
|
(src/choudoufu-chant-read.ts, #924): src/choudoufu-plan.ts is gone, and a
|
|
2208
2667
|
re-check's `live-plan` is chant's, handed back to behold. See the choudoufu
|