@intentius/behold 0.29.49 → 0.29.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/AGENTS.md +155 -4
  2. package/demos.json +15 -0
  3. package/dist/cli.js +2440 -998
  4. package/example-three-cloud/README.md +38 -0
  5. package/example-three-cloud/aws/chant.config.ts +8 -0
  6. package/example-three-cloud/aws/src/site.ts +20 -0
  7. package/example-three-cloud/azure/chant.config.ts +1 -0
  8. package/example-three-cloud/azure/src/site.ts +19 -0
  9. package/example-three-cloud/chant.workspace.json +10 -0
  10. package/example-three-cloud/dns/chant.config.ts +1 -0
  11. package/example-three-cloud/dns/ops/front-door.op.ts +21 -0
  12. package/example-three-cloud/dns/src/route53.ts +54 -0
  13. package/example-three-cloud/gcp/chant.config.ts +1 -0
  14. package/example-three-cloud/gcp/src/site.ts +19 -0
  15. package/example-three-cloud/package-lock.json +715 -0
  16. package/example-three-cloud/package.json +16 -0
  17. package/example-three-cloud/scripts/emulators-up.sh +46 -0
  18. package/example-three-cloud/scripts/front-door.ts +400 -0
  19. package/package.json +4 -2
  20. package/web/app.js +250 -23
  21. package/web/composite-members.js +21 -0
  22. package/web/composite-members.test.js +25 -0
  23. package/web/decision-points.js +70 -0
  24. package/web/decision-points.test.js +87 -0
  25. package/web/dots-kiosk.js +4 -1
  26. package/web/dots-live.test.js +10 -0
  27. package/web/dots.js +41 -4
  28. package/web/export-note.js +35 -0
  29. package/web/export-note.test.js +45 -0
  30. package/web/health-marks.js +146 -0
  31. package/web/health-marks.test.js +67 -0
  32. package/web/index.html +52 -0
  33. package/web/kiosk-runs.js +51 -5
  34. package/web/kiosk-runs.test.js +42 -1
  35. package/web/kiosk-source.js +23 -0
  36. package/web/kiosk-source.test.js +19 -1
  37. package/web/kiosk-track.js +9 -5
  38. package/web/kiosk-track.test.js +12 -2
  39. package/web/kiosk.html +26 -3
  40. package/web/kiosk.js +28 -6
  41. package/web/local-run.js +276 -0
  42. package/web/local-run.test.js +46 -0
  43. package/web/sql-yodeler-lane.js +1 -1
  44. package/web/terragucci-timeline.js +5 -4
  45. package/web/terragucci-timeline.test.js +1 -1
  46. package/web/trunk-lane.js +54 -5
  47. package/web/trunk-lane.test.js +86 -3
  48. package/web/view-url.js +25 -0
  49. package/web/view-url.test.js +24 -1
  50. package/web/why.js +1 -1
  51. package/web/why.test.js +1 -1
  52. package/web/workspace-gates.js +35 -18
package/AGENTS.md CHANGED
@@ -97,6 +97,63 @@ an address it answers 404. The kiosk's "Pipeline metrics" pane
97
97
  (web/kiosk-metrics.js) shows only what it returns, and no pane when it
98
98
  returns nothing for the repo.
99
99
 
100
+ ## Runs from chant's run index (behold#815)
101
+
102
+ `behold serve --ci-report-url <url>` (or `BEHOLD_CI_REPORT_URL`) points the
103
+ kiosk's runs pane at chant's run index, `<url>/runs/index.json`
104
+ (ci-run-index/v1, floor `CI_RUN_INDEX_CHANT_FLOOR`, 0.124.31), instead of the
105
+ forge's runs (src/ci-run-index.ts). The text goes through
106
+ `ciRunIndexOf` in src/workspace-reader.ts (contract 1), then the floor against
107
+ the index's own `chant`, then the vendored schema
108
+ (src/ci-run-index-schema/, chant commit in `CI_RUN_INDEX_SCHEMA_SOURCE`) with
109
+ its `status` and `job` enums left out, since v1 adds to them. An entry the
110
+ schema refuses, or whose key is not `<pr>/<commit>[/<member>]`, is dropped and
111
+ listed in `skipped`. `GET /api/chant/ci/runs` answers the runs in demo.runs/v1
112
+ shape; `GET /api/chant/ci/runs/:runId` reads that entry's
113
+ `pr-<job>.events.jsonl` and `pr-<job>.json` under its key only and builds the
114
+ log with `demoRunOf` (src/chant-demo.ts). No events file is one step saying
115
+ so. An apply refused with `plan-changed`, `not-approved` or a wave's
116
+ equivalent exited 3 and is drawn waiting with "the plan moved or waits:
117
+ re-plan and re-approve". So is an apply whose entry has `exitCode: 3` and a
118
+ failure that isn't another refusal (#818; the field follows chant#4165, not
119
+ merged, and isn't in the vendored schema; absent reads as before). `signer` shows only when it is a string; runOrigin's
120
+ URL is the link, named by its host, never by `forge`. The page learns of it
121
+ from `<meta name="kiosk-runs" content="chant-ci">` (web/kiosk-source.js
122
+ `pageRuns`); only the runs pane switches, the cycle and approval panel read
123
+ as before. #818: without the flag, a served workspace's declared
124
+ `ci.reportUrl` (s3:// or file://, read from the `workspace ls` behold already
125
+ makes, `declaredReportUrl` in src/workspace.ts, floor
126
+ `CI_REPORT_URL_CHANT_FLOOR`, 0.124.32, chant#4160) is used, a memberless
127
+ declaration included; the flag overrides it, and each answer's `urlFrom` says
128
+ `flag` or `declaration`. With neither, nothing changes.
129
+
130
+ ## A plan job run locally (behold#685)
131
+
132
+ `POST /api/chant/ci/local` `{job: "plan", commit, pr, env?, base?, member?,
133
+ forge?}` starts `chant ci run plan --local --events-json --env <env> --base
134
+ <sha> --commit <sha> --pr <n> --forge <forge>` (src/ci-local-run.ts, floor
135
+ `CI_RUN_LOCAL_CHANT_FLOOR`, 0.124.32, chant#4161) in the workspace root or the
136
+ named member's declared directory. Each value is checked; the commit and base
137
+ are resolved by `git rev-parse` in the root, the base defaulting to where the
138
+ commit leaves the trunk, the forge to the one workflow directory present. It
139
+ runs through the runner's `track`, so it shares the one-command guard and the
140
+ now-line, and is refused like an Op run: preview `403`, a terragucci or SQL
141
+ Yodeler repo `409` (not allowlisted), `--public` `405` and its GETs `403`.
142
+ stdout lines cross `readRunLine`; stderr is the step output, filed under its
143
+ `[<phase>]`. `GET /api/chant/ci/local/:id` answers the run in demo.run/v1
144
+ (`from: "chant-ci-local"`) and `ci`, CI's run of the same job, commit and
145
+ member from the run index (`ciRunsRoutes`' lookup) when `--ci-report-url` is
146
+ set. The SSE `local-run` event names a run that moved. The page's **Local** tab
147
+ (web/local-run.js) draws both with kiosk-runs.js `renderRun`, and is not drawn
148
+ in a public view, an embed, a static export, preview or a guarded repo.
149
+
150
+ Apply is never started: `job: "apply"` answers `422 local-apply`.
151
+ `--local` does not make an apply safe (it still changes real infrastructure
152
+ and pushes release records and gate facts), and behold has no emulator notion
153
+ that holds for it: `ci run` gives the job a clean environment that keeps HOME,
154
+ so `serve --local`'s emulator env does not reach the job and the operator's
155
+ own credentials would. Cached-step marks wait on chant#4015.
156
+
100
157
  ## A terragucci estate, from its reports (#490)
101
158
 
102
159
  `behold serve <repo> --terragucci <dir|s3://bucket/prefix|https://…>`
@@ -1074,10 +1131,25 @@ superseded, never approvable), `rollback` on an environment's releases, and
1074
1131
  `release` and `rollback` on a deploy record. `releaseColumn: {full, floor}`
1075
1132
  says whether they were read. Below the floor nothing is refused: the column
1076
1133
  comes from `release list` alone with no revoked mark, and the tab says which
1077
- chant would add it. The fixtures in `src/__fixtures__/trunk-lane/` are
1078
- recorded from chant main in the workspace `src/trunk-lane-fixture.ts` makes,
1079
- and `src/trunk-lane-chant.test.ts` reads the same workspace through a real
1080
- chant when `BEHOLD_TEST_CHANT_BIN` names one.
1134
+ chant would add it.
1135
+
1136
+ A mixed environment (#731): from chant 0.124.29
1137
+ (`MIXED_ENVIRONMENT_CHANT_FLOOR`, chant#4035, chant#4072) status gives an
1138
+ environment `mixed` when its components run different releases, or a
1139
+ promote, rollback or redeploy left one `failed` or `gated` (its
1140
+ `outcomes.jsonl` on chant/lifecycle). Each environment carries `mixed[]`, one
1141
+ per member: `components` (each with its recorded `release`, `state` and the
1142
+ `attempt` that left it unsettled), `redeploy` lines and the `rollback` line,
1143
+ as chant wrote them. The tab heads the environment `(mixed)` and shows the
1144
+ lines to copy, run in the member's directory; behold runs none of them.
1145
+ `mixedEnvironments: {read, floor}` says whether it was read; below the floor
1146
+ `mixed` is empty and the lane is drawn as before.
1147
+
1148
+ The fixtures in `src/__fixtures__/trunk-lane/` are recorded from chant main
1149
+ in the workspace `src/trunk-lane-fixture.ts` makes (staging carries a deploy
1150
+ outcome: v3's promote deployed api and failed on web), and
1151
+ `src/trunk-lane-chant.test.ts` reads the same workspace through a real chant
1152
+ when `BEHOLD_TEST_CHANT_BIN` names one.
1081
1153
 
1082
1154
  ## A gate's change set on the graph (#681)
1083
1155
 
@@ -1176,6 +1248,85 @@ the graph draws no marks. A public view refuses the route.
1176
1248
  `BEHOLD_TEST_CHANT_BIN` names one. `status.schema.json` in
1177
1249
  src/trunk-lane-schemas/ is chant main at e9c996e93.
1178
1250
 
1251
+ ## Open decision points beside their gates (#472)
1252
+
1253
+ The approvals inbox is arugula's rail (arugula-salad/arugula#621); behold
1254
+ draws open decision points and answers none. `GET /api/workspace/points`
1255
+ (src/decision-points.ts) reads `chant workspace points --open --json` through
1256
+ the reader's `readPoints` (floor `DECISION_POINTS_CHANT_FLOOR`, 0.107.0, the
1257
+ chant where a gate can ask a point, chant#3170). chant's conformance suite
1258
+ does not list `points`, so the read is not in `BEHOLD_READS`; the reader test
1259
+ holds every other module to not naming it. Each open question carries its
1260
+ point's question, who may answer (the quorum's count and roles), a model's
1261
+ proposal when there is one, and chant's `points answer` line. A gate that
1262
+ asks a point carries `answer` in `workspace status` (the open question's id,
1263
+ its point and path), and its `approve` is that same `points answer` line. The
1264
+ gate strip (web/decision-points.js, web/workspace-gates.js) puts a question
1265
+ on the card of the gate whose `answer.id` names it and gives a question no
1266
+ waiting gate names a card of its own, naming the gate from its
1267
+ `gate:<op>/<gate>@<env>` subject when a gate asked it. Such a gate gets no
1268
+ approve button, framed or not, and `POST /api/workspace/gates/approve`
1269
+ refuses it with `422 decision-point`. Standalone, a point card shows the line
1270
+ as text to copy; framed, it says to answer in the host's rail. There is no
1271
+ write route. Below the floor the route answers the refusal and `degraded`,
1272
+ and the strip says which chant adds points. A public view refuses the route.
1273
+ `src/decision-points-chant.test.ts` reads the workspace
1274
+ `src/decision-points-fixture.ts` makes through a real chant when
1275
+ `BEHOLD_TEST_CHANT_BIN` names one; src/__fixtures__/decision-points/ is
1276
+ chant 0.124.31's output for it.
1277
+
1278
+ ## Runtime health and rotation (#825)
1279
+
1280
+ `GET /api/health?env=<env>` (src/health-overlay.ts) reads `chant lifecycle
1281
+ health <env> --json` (chant#4177, floor `HEALTH_CHANT_FLOOR`, 0.124.33, read
1282
+ "runtime health") once per chant project: the served project, or each chant
1283
+ member of a workspace or an estate in its own directory with its own chant,
1284
+ ids composed `<member>/<id>`. The read is the reader's `readHealth`
1285
+ (src/workspace-reader.ts). Its document is `chant-health/v1`, not a contract 1
1286
+ document, so it is checked against chant's schema, vendored unchanged in
1287
+ src/health-schema/ (chant PR #4193 at d727944c4) and validated with ajv, with
1288
+ a hole's `reason` loosened to any string; a document the schema refuses is
1289
+ refused whole. A project with no lexicon that reads health is `none`, not a
1290
+ failure. A member below the floor is refused before anything is spawned; when
1291
+ every member is, the answer carries the refusal and `degraded`.
1292
+
1293
+ The answer is `nodes` (per id: `healthy`, `unhealthy` or `unknown` with
1294
+ chant's `detail`, `observedAt` and `checkedAt`; `unobserved` with chant's
1295
+ `reason`; or `absent`), `rotation`, `members` and `counts`. Rotation is
1296
+ behold's (src/runtime-health.ts, `rotationOf`): a Route 53 record whose
1297
+ `HealthCheckId` edge (or `$ref` attribute) names a declared check is out of
1298
+ rotation only when that check is unhealthy, in rotation when it is healthy,
1299
+ and `inRotation: null` with the reason in words otherwise. The edges come
1300
+ from each member's cached source graph (`memberIr` at detail 2). The answer
1301
+ is cached per environment for 30 s, `?fresh=1` reads again, and `POST
1302
+ /api/refresh` drops it. A public view refuses the route (it reads the live
1303
+ estate with behold's credentials), and `behold export` captures it once per
1304
+ environment. The page (web/health-marks.js) draws a tag under each card, a
1305
+ solid ring on an unhealthy one and a dashed ring on a hole, dims a record out
1306
+ of rotation with its edges, counts the states in the Model tab and shows the
1307
+ detail in the inspect pane. It never changes a card's fill.
1308
+ `src/__fixtures__/health/` was recorded from chant main at cd9a90716 against
1309
+ a floci whose health checks probe (lex00/floci#259); src/runtime-health.test.ts
1310
+ names each file's provenance. A multi-stack document (a project that declares
1311
+ `stacks`) is keyed `<member>/<stack>::<name>` (#824), the ids chant's live
1312
+ overlay gives that project's nodes.
1313
+
1314
+ ## The three-cloud demo (#824)
1315
+
1316
+ `example-three-cloud` is a chant workspace (`dns`, `aws`, `azure`, `gcp`) on
1317
+ floci, floci-az and floci-gcp; docs/src/content/docs/using/three-cloud.mdx is
1318
+ its page. `behold demo three-cloud` runs `scripts/emulators-up.sh` (the
1319
+ emulators under chant's own container names, with the Docker socket, floci-az
1320
+ running Container Apps unmocked), then serves with `--local --env local`.
1321
+ `--local` on a workspace boots every chant member's emulators
1322
+ (`emulatorDirs`/`emulatorsUp` in src/emulator.ts), not the first member's, and
1323
+ tears down the same set. The `front-door` Op (`dns/ops/front-door.op.ts`)
1324
+ runs `scripts/front-door.ts`: apply all four, deactivate the Azure revision,
1325
+ wait for `azureCheck` to read unhealthy, then `behold export --open-env local
1326
+ --open-zoom composites --note …`. `--note` (`settleNote` in src/export.ts) is
1327
+ one line under 200 characters, written to the manifest as `note` and drawn at
1328
+ the foot of a static page by web/export-note.js, backticked spans as code.
1329
+
1179
1330
  ## Invariant
1180
1331
 
1181
1332
  If a request would have behold write to a cloud or to source directly, it's wrong.
package/demos.json CHANGED
@@ -129,6 +129,21 @@
129
129
  "terralith": true
130
130
  }
131
131
  },
132
+ {
133
+ "name": "three-cloud",
134
+ "description": "A website in three clouds behind Route 53: ECS on Fargate, Azure Container Apps and Cloud Run, each answering through a latency record guarded by a health check, as one chant workspace on the floci, floci-az and floci-gcp emulators. Turn Azure off and its record drops out of rotation; dns/ops/front-door.op.ts (or npm run front-door) applies it all, does that, and exports the page. Pulls three emulator images on first run.",
135
+ "source": "bundled",
136
+ "dir": "example-three-cloud",
137
+ "requires": [
138
+ "docker",
139
+ "curl"
140
+ ],
141
+ "setup": "bash scripts/emulators-up.sh",
142
+ "serve": {
143
+ "local": true,
144
+ "env": "local"
145
+ }
146
+ },
132
147
  {
133
148
  "name": "fountain",
134
149
  "description": "The mature estate: self-hosted fountain (a real app) on a throwaway k3d cluster — tiers (try the ha tier picker), seams, drift, runtime Pods. Clones INTENTIUS/fountain-ops; ~5 minutes, mostly image pulls. `just down` in the clone removes the cluster.",