@intentius/behold 0.30.0 → 0.30.2
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 +97 -33
- package/README.md +78 -56
- package/dist/cli.js +6913 -2448
- package/example-choudoufu-estate/chant.workspace.json +1 -1
- package/example-terraform-estate/README.md +1 -1
- package/example-terraform-estate/chant.workspace.json +1 -1
- package/example-terralith/README.md +1 -1
- package/example-three-cloud/package-lock.json +19 -19
- package/example-three-cloud/package.json +4 -4
- package/package.json +5 -5
- package/web/app.js +330 -19
- 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/index.html +18 -0
- package/web/kiosk-ask-layout.js +85 -0
- package/web/kiosk-ask-layout.test.js +83 -0
- package/web/kiosk-ask-tips.js +467 -0
- package/web/kiosk-ask-tips.test.js +359 -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 +203 -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 +196 -0
- package/web/kiosk-light.js +509 -0
- package/web/kiosk-light.test.js +297 -0
- package/web/kiosk-metrics.js +7 -4
- package/web/kiosk-modal-sticky.test.js +2 -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-vendor.js +85 -7
- package/web/kiosk-vendor.test.js +9 -9
- package/web/kiosk-watch.js +8 -4
- package/web/kiosk.html +107 -1
- package/web/kiosk.js +149 -23
- package/web/kiosk.test.js +25 -1
- package/web/layout-store.js +3 -3
- package/web/small-stage.test.js +4 -0
- package/web/terragucci-change.js +30 -13
- 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/web/vendors/choudoufu-128.png +0 -0
- package/web/vendors/choudoufu-64.png +0 -0
package/AGENTS.md
CHANGED
|
@@ -369,6 +369,34 @@ checkout declares no Terraform root (`controlRepo` in
|
|
|
369
369
|
structural check otherwise. The page (`web/terragucci-estate.js`) draws it
|
|
370
370
|
in a layer over the graph area.
|
|
371
371
|
|
|
372
|
+
|
|
373
|
+
### The kiosk's prompt pane (#936)
|
|
374
|
+
|
|
375
|
+
A step of terragucci's `demo.json` may carry an `ask` (or `asks`, a list of
|
|
376
|
+
them played in order), and the file may carry `opening` and `closing` strings
|
|
377
|
+
(src/terragucci-demo.ts parses them; a field of the wrong type is null, and an
|
|
378
|
+
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,
|
|
379
|
+
the pane (`#k-ask`, web/kiosk-ask.js) takes the place of `#bar` and
|
|
380
|
+
`#k-caption` in Watch: a big monospace block at the foot of the screen. A
|
|
381
|
+
`prompt` is typed after `>` at 40 ms a character; an `action` shows at once
|
|
382
|
+
after a check mark; the `reply` prints after it, with `{roots}`, `{creates}`,
|
|
383
|
+
`{updates}`, `{deletes}` and `{error}` filled from the step's report (an
|
|
384
|
+
unknown token, or one without a value, is empty). The last three entries stay
|
|
385
|
+
above, faded. `opening` shows once at the scenario's first step
|
|
386
|
+
(`pull-request` or `planned`), `closing` at `applied`. While a job runs
|
|
387
|
+
(`pull-request`, `approved`, `merged`, `applying`, `resumed`) a status line
|
|
388
|
+
gives what is happening, the time since `started_at`, and `next`. With
|
|
389
|
+
`prefers-reduced-motion` everything shows at once. The pane's height is fixed
|
|
390
|
+
and replaces the caption in `captionRoomPx`, so it never covers the graph. A
|
|
391
|
+
step without an ask looks as it always did.
|
|
392
|
+
|
|
393
|
+
The pane tells the page through window events, each with detail
|
|
394
|
+
`{ ask, step, scenario }`: `behold:ask-start` before a beat is typed,
|
|
395
|
+
`behold:ask-done` when its reply has printed, and `behold:ask-clear` on a new
|
|
396
|
+
step with no ask. `{dependents}` is left to the lighting: it sets
|
|
397
|
+
`window.beholdAskTokens = { dependents: n }` on `behold:ask-start`, and the
|
|
398
|
+
reply reads it when it prints.
|
|
399
|
+
|
|
372
400
|
## Releases per environment, from the release ledger (#525)
|
|
373
401
|
|
|
374
402
|
`GET /api/lifecycle/releases[?fresh=1]` (src/lifecycle-releases.ts) reads
|
|
@@ -735,7 +763,7 @@ block in M1.
|
|
|
735
763
|
|
|
736
764
|
With a traffic level, `/api/overlay` predicts each member twice and carries
|
|
737
765
|
both figures and their difference. The level is `?traffic=` on the request,
|
|
738
|
-
else
|
|
766
|
+
else the per-user settings' `{"behaviour": {"traffic": "100 rps, p50"}}` (src/user-settings.ts, #470), else none;
|
|
739
767
|
with none nothing is asked for and the payload is exactly M1's. behold never
|
|
740
768
|
defaults a level, because every figure is *at* one.
|
|
741
769
|
|
|
@@ -990,7 +1018,9 @@ folder's scratch project. Each capability has its `name`, `meaning`,
|
|
|
990
1018
|
it leaves `notEvaluated`, its `rule`, and per lexicon whether it is
|
|
991
1019
|
supplied. A chant below 0.124.46 answers 422 `code: "chant-too-old"`
|
|
992
1020
|
(`CAPABILITIES_CHANT_FLOOR`). behold mcp's `capabilities` tool returns the
|
|
993
|
-
same text.
|
|
1021
|
+
same text. behold keeps the document per checkout and commit, so a second
|
|
1022
|
+
read of an unmoved checkout runs no chant; a `--public` serve refuses the
|
|
1023
|
+
route with 403 (#978).
|
|
994
1024
|
|
|
995
1025
|
```
|
|
996
1026
|
GET /api/capabilities
|
|
@@ -1003,7 +1033,7 @@ GET /api/capabilities
|
|
|
1003
1033
|
|
|
1004
1034
|
`POST /api/view` changes what every open tab of this serve draws. It is a
|
|
1005
1035
|
view change and writes nothing: no infrastructure, no project file, not
|
|
1006
|
-
|
|
1036
|
+
the layout cache, and nothing kept on the server.
|
|
1007
1037
|
|
|
1008
1038
|
```
|
|
1009
1039
|
POST /api/view
|
|
@@ -1181,12 +1211,21 @@ best-effort, and only its exit code is certain (src/ci-run.ts).
|
|
|
1181
1211
|
|
|
1182
1212
|
### The executor contract (#165, #61)
|
|
1183
1213
|
|
|
1184
|
-
|
|
1214
|
+
A member's `chant.config.ts` may designate which forge deploys an environment,
|
|
1215
|
+
on the environment's entry (#470):
|
|
1185
1216
|
|
|
1186
|
-
```
|
|
1187
|
-
{
|
|
1217
|
+
```ts
|
|
1218
|
+
environments: [{ name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } }]
|
|
1188
1219
|
```
|
|
1189
1220
|
|
|
1221
|
+
behold reads it from `chant workspace graph --composites --json`
|
|
1222
|
+
(`components[].environments[].executor`, floor `EXECUTOR_CHANT_FLOOR` 0.124.47,
|
|
1223
|
+
src/executor.ts) through the workspace reader. It never reads `.behold.json`'s
|
|
1224
|
+
`executor` (retired; `behold doctor` warns), and never derives it from a
|
|
1225
|
+
`chant-components-<env>` workflow name (maintainer ruling, 2026-10-23). An older
|
|
1226
|
+
chant prints no `executor`, and no row means none declared. `reason.code`
|
|
1227
|
+
`executor-config-unreadable` stays designated and fails closed.
|
|
1228
|
+
|
|
1190
1229
|
It designates the committed WORKFLOW, not just the forge: two environments'
|
|
1191
1230
|
generated pipelines carry identical job ids, so a picker cannot tell them
|
|
1192
1231
|
apart, and a contract that names prod must not sit on a guess. For a
|
|
@@ -1219,8 +1258,8 @@ A dispatched run is followed honestly (#165 §6, PR #350): only GitHub's own
|
|
|
1219
1258
|
follow deadline promotes the run to `lost` (chips frozen at last-observed,
|
|
1220
1259
|
the run possibly still live at its own page), never to a verdict. The adopted
|
|
1221
1260
|
run id is persisted as one JSON per project under `~/.behold/ci-runs/`, the
|
|
1222
|
-
operator's machine-state, outside the project tree, so
|
|
1223
|
-
|
|
1261
|
+
operator's machine-state, outside the project tree, so behold still writes
|
|
1262
|
+
nothing in a served project (the Invariant below). `GET /api/ci/run` reads the
|
|
1224
1263
|
record; `POST /api/ci/readopt` (also attempted once at boot) re-follows an
|
|
1225
1264
|
unconcluded run by its saved id, so a restart mid-deploy leaves the run a
|
|
1226
1265
|
reader instead of nothing.
|
|
@@ -1290,13 +1329,13 @@ chant never signs a person in (ws-052); the surface that does passes the person
|
|
|
1290
1329
|
to chant as `--actor` (ws-080). behold has no login, so `src/approver.ts` names
|
|
1291
1330
|
the person for each request, in this order:
|
|
1292
1331
|
|
|
1293
|
-
- `--identity-header <name>` (BEHOLD_IDENTITY_HEADER,
|
|
1332
|
+
- `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, the per-user settings'
|
|
1294
1333
|
`approver.header`): behold sits behind a proxy that signed the person in
|
|
1295
1334
|
through the forge or OIDC, and the header names them. A bare login is an
|
|
1296
1335
|
account on `--identity-forge` (github unless set). A request without the
|
|
1297
1336
|
header approves nothing (`403 no-identity`). Refused at startup with a
|
|
1298
1337
|
`--host` other than loopback, since anyone reaching the port could send it.
|
|
1299
|
-
- `--as <principal>` (BEHOLD_APPROVER,
|
|
1338
|
+
- `--as <principal>` (BEHOLD_APPROVER, the per-user settings' `approver.as`): one
|
|
1300
1339
|
person runs behold and names themselves, `github:<login>` or a principal the
|
|
1301
1340
|
signers file lists.
|
|
1302
1341
|
- Neither: chant's own fallback (GITHUB_ACTOR, GITLAB_USER_LOGIN, USER), and
|
|
@@ -1311,7 +1350,7 @@ Every approve route (`/api/workspace/gates/approve`, the converge gate's
|
|
|
1311
1350
|
behold"`. chant's ledger has no channel for a surface (its `origin` is `cli`,
|
|
1312
1351
|
`mcp` or `acp`), so the note is where behold is named. A workspace gate that
|
|
1313
1352
|
status marks `signed` is approved with `--sign <key>` when behold holds the
|
|
1314
|
-
person's key (`--signing-key` beside `--as`, or
|
|
1353
|
+
person's key (`--signing-key` beside `--as`, or the per-user settings'
|
|
1315
1354
|
`approver.keys` by principal) and refused `422 signed` with the line to run
|
|
1316
1355
|
otherwise. The key path never reaches a page: `GET /api/workspace/gates`
|
|
1317
1356
|
carries `approverIdentity: {principal, source, forge, signs}`, or `approver:
|
|
@@ -1576,6 +1615,14 @@ If a request would have behold write to a cloud or to source directly, it's wron
|
|
|
1576
1615
|
behold shows truth and triggers Ops. Authority stays in the committed source and the
|
|
1577
1616
|
executor.
|
|
1578
1617
|
|
|
1618
|
+
behold writes nothing in a served project (#469, ruled 2026-10-23). What it
|
|
1619
|
+
keeps for itself (the hand layout, the per-user settings, dispatched CI run
|
|
1620
|
+
ids, recents, the serve registry) lives in the user's own home, cache or temp directory, keyed by the
|
|
1621
|
+
project, never in the tree. The only files behold puts in a project are the
|
|
1622
|
+
ones a person asks for by name: `behold doctor --fix` writing
|
|
1623
|
+
`chant.workspace.json`, and the carve walkthrough writing into the demo copy
|
|
1624
|
+
behold made itself (both below).
|
|
1625
|
+
|
|
1579
1626
|
The commands behold starts run with behold's own environment, so Deploy (`POST
|
|
1580
1627
|
/api/apply`, chant's local executor) applies with the credentials of whoever
|
|
1581
1628
|
started it. On a terragucci repo (a `terragucci.yml` in the served directory or
|
|
@@ -1586,7 +1633,7 @@ so the page offers no write, and auto-sync declines. The boundary is an
|
|
|
1586
1633
|
allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
|
|
1587
1634
|
any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
|
|
1588
1635
|
method and route, and that list holds only the exceptions below (the layout
|
|
1589
|
-
|
|
1636
|
+
cache, project open and reveal, demo open, refresh, and the four carve
|
|
1590
1637
|
steps), plus `POST /api/view`, which moves the open tabs and writes nothing
|
|
1591
1638
|
(#914). A new write route is refused on a terragucci repo until it is added
|
|
1592
1639
|
there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
|
|
@@ -1632,35 +1679,52 @@ These are also the only writes a guarded product repo answers: terragucci
|
|
|
1632
1679
|
(`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
|
|
1633
1680
|
listed in `TERRAGUCCI_ALLOWED_WRITES`.
|
|
1634
1681
|
|
|
1635
|
-
`POST /api/layout` (#228) writes **one** file in the served project:
|
|
1636
|
-
|
|
1637
|
-
|
|
1638
|
-
|
|
1639
|
-
|
|
1640
|
-
|
|
1641
|
-
|
|
1642
|
-
|
|
1643
|
-
- It **
|
|
1644
|
-
|
|
1645
|
-
|
|
1682
|
+
`POST /api/layout` (#228) writes **one** file, and not in the served project:
|
|
1683
|
+
the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
|
|
1684
|
+
with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
|
|
1685
|
+
`$XDG_CACHE_HOME` or `~/.cache`), `<key>` the first 32 hex characters of the
|
|
1686
|
+
sha256 of the project directory's realpath, and `BEHOLD_CACHE_DIR` replacing
|
|
1687
|
+
`<user cache>/behold`. The file is `{version, projectDir, lenses: {<lens>:
|
|
1688
|
+
{<node id>: {dx,dy,dw,dh}}}}`, mode 0600 in a 0700 directory (src/layout.ts):
|
|
1689
|
+
|
|
1690
|
+
- It is **one operator's view**, not estate truth. Deltas describe how *you*
|
|
1691
|
+
want the picture arranged on top of dagre's layout; the graph underneath
|
|
1692
|
+
stays chant's, and a delta for a node that left the estate is dropped on read.
|
|
1693
|
+
- It **never touches the cloud, your source or the project**. The path is a
|
|
1694
|
+
hash of `cfg.projectDir` + constants; nothing from the request reaches the
|
|
1695
|
+
filesystem.
|
|
1646
1696
|
- It refuses politely when it shouldn't write: preview mode, a static-export
|
|
1647
|
-
capture, a
|
|
1648
|
-
-
|
|
1649
|
-
|
|
1697
|
+
capture, a cache directory that isn't writable, an oversized or malformed body.
|
|
1698
|
+
- A project served before #469 may carry `.behold/layout.json`. When the cache
|
|
1699
|
+
has no file for the project, that file is read once and copied into the
|
|
1700
|
+
cache; it is never written, moved or deleted. Clearing the last lens keeps
|
|
1701
|
+
an empty cache file, so the old one is not read back in.
|
|
1702
|
+
|
|
1703
|
+
The per-user settings (#470, src/user-settings.ts) sit beside it at
|
|
1704
|
+
`<user cache>/behold/settings/<key>.json`, same key, same modes: the operator's
|
|
1705
|
+
`approver` block and `behaviour.traffic`, which are not facts about the estate.
|
|
1706
|
+
No route writes them. When the cache has none for a project with a
|
|
1707
|
+
`.behold.json`, that file's two blocks are read once and copied in (key paths
|
|
1708
|
+
made absolute against the project), and a copy is kept even when neither
|
|
1709
|
+
block is there, so `.behold.json` is not read for them again. It is never
|
|
1710
|
+
written, moved or deleted. The tier axis is not a setting: it is the
|
|
1711
|
+
project's `chant.config.ts` `buildParams` entry with a string `enum`
|
|
1712
|
+
(src/project.ts `readTierParam`), read per request through `detectProject`
|
|
1713
|
+
and passed to `chant graph` as `--param`.
|
|
1650
1714
|
|
|
1651
1715
|
`GET /api/layout` reads it back; `GET /api/graph?layout=1` (and `/api/overlay`)
|
|
1652
1716
|
render with the deltas baked into the SVG, which is how `behold export` and
|
|
1653
1717
|
static snapshots honour a hand layout.
|
|
1654
1718
|
|
|
1655
|
-
A declared workspace (#464)
|
|
1656
|
-
directory holding `chant.workspace.json`, rather than
|
|
1719
|
+
A declared workspace (#464) keys the layout by the workspace root, the
|
|
1720
|
+
directory holding `chant.workspace.json`, rather than by its first member.
|
|
1657
1721
|
|
|
1658
1722
|
`behold doctor --fix` (#464, ws-015) is the third exception, and it runs only
|
|
1659
1723
|
when you type the flag: for an estate root whose members are listed in
|
|
1660
1724
|
`.behold.json`, it writes `chant.workspace.json` in that root (never over an
|
|
1661
|
-
existing one) and
|
|
1662
|
-
|
|
1663
|
-
|
|
1725
|
+
existing one) and copies the first member's saved layout to the root's cache
|
|
1726
|
+
entry with its node ids rewritten. It then runs `chant workspace check`. The
|
|
1727
|
+
first member's layout and `.behold.json` are left as they were.
|
|
1664
1728
|
|
|
1665
1729
|
The fourth exception is the carve walkthrough's two steps above (#254), and it
|
|
1666
1730
|
is narrower still: they exist only when behold booted a `behold demo carve`
|
|
@@ -2019,8 +2083,8 @@ exists to draw is a directory of `.tf` files and nothing else, and #378 chose
|
|
|
2019
2083
|
not to ask one for a `chant.config.ts` of its own — INTENTIUS/waterpark#88 was
|
|
2020
2084
|
withdrawn because the estate is more useful untouched. So `behold serve
|
|
2021
2085
|
<terraform-dir>` generates the reader config itself, outside the estate, and
|
|
2022
|
-
points chant at it.
|
|
2023
|
-
|
|
2086
|
+
points chant at it. behold writes nothing in a served project (the
|
|
2087
|
+
Invariant), nothing is written under the served directory, and
|
|
2024
2088
|
`src/terraform-member.test.ts` asserts the estate's source stamp is unchanged
|
|
2025
2089
|
across a read. Three decisions, each a trade #384 left open and each measured on
|
|
2026
2090
|
water park's `access/` before it was taken:
|
package/README.md
CHANGED
|
@@ -446,12 +446,17 @@ log, which the loop driver copies into the bucket under `runs/`. It needs
|
|
|
446
446
|
`--terragucci`, asks only GETs, and has no control.
|
|
447
447
|
The docs' terragucci page says what it shows.
|
|
448
448
|
|
|
449
|
-
|
|
450
|
-
`/
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
449
|
+
The demo is served at `/`: the live demo's page, else the first listed one.
|
|
450
|
+
`/kiosk` redirects to `/`. The listed demos are the multi-state plan-and-apply
|
|
451
|
+
ones, each at a path of its own (`/choudoufu-compose`, `/terragrunt-choudoufu`,
|
|
452
|
+
`/atmos-choudoufu`, `/chant-compose`); one is listed once its tool has a published cycle
|
|
453
|
+
(`cycles/<tool>/latest.json` beside `demo.json`) or is live, and
|
|
454
|
+
`/api/terragucci/demos` says which. A page shows the demo's live run, or replays
|
|
455
|
+
its latest cycle, under a banner with the example's name, its products, a link to
|
|
456
|
+
its code in INTENTIUS/terragucci, and a switcher when more than one is listed.
|
|
457
|
+
The older tools' URLs (`/terraform`, `/terragrunt`, `/cdk-terrain`, `/choudoufu`,
|
|
458
|
+
`/chant`, and the fan-out pages) redirect to `/`. Any other short path answers
|
|
459
|
+
404 with a link to the front page.
|
|
455
460
|
|
|
456
461
|
In a declared workspace, the gates waiting on a person come from
|
|
457
462
|
`chant workspace status <env> --json`, keyed `member/op/gate` the way arugula's
|
|
@@ -460,7 +465,7 @@ button says who chant will record before the click: the person `--as` names
|
|
|
460
465
|
(`--as github:<login>`), the person an authenticating proxy names in the header
|
|
461
466
|
`--identity-header` trusts, or else the user running behold. A gate the
|
|
462
467
|
workspace names in `identity.gates` is signed with that person's key when
|
|
463
|
-
`--signing-key` (or
|
|
468
|
+
`--signing-key` (or `approver.keys` in behold's per-user settings) gives one, and sent to the
|
|
464
469
|
command line otherwise (#690). Every approve route refuses in preview mode.
|
|
465
470
|
|
|
466
471
|
In a declared workspace, the inspect pane of a member's box or a card has a
|
|
@@ -560,50 +565,67 @@ nothing else. Your Terraform is never edited; see AGENTS.md, "Invariant".
|
|
|
560
565
|
## Configuration: `.behold.json`
|
|
561
566
|
|
|
562
567
|
An optional `.behold.json` in the served project's root is **behold's own**
|
|
563
|
-
config,
|
|
564
|
-
tier picker) don't leak into chant's. Three keys: `tiers` below, `executor`
|
|
565
|
-
(which forge deploys an environment), and `members`, spelled `[{ "dir": "x", "kind":
|
|
568
|
+
config, which #470 retired. One key is still read, `members`, spelled `[{ "dir": "x", "kind":
|
|
566
569
|
"chant" | "choudoufu" | "terraform" }]`, how an estate root names what it
|
|
567
570
|
composes, fail-closed on a kind behold has no reader for. `members` is
|
|
568
571
|
deprecated: a chant workspace declaration (`chant.workspace.json`) lists an
|
|
569
572
|
estate's members for every reader, and beside one, `.behold.json`'s list is
|
|
570
573
|
ignored. `behold doctor --fix` writes the declaration from it (see
|
|
571
|
-
[Serve a chant workspace](https://intentius.io/behold/using/workspace/)).
|
|
572
|
-
project's deploy-**tier** axis, a dimension orthogonal to `environment` (chant
|
|
573
|
-
has no native tier concept; it is entirely a project convention, e.g. Loom's
|
|
574
|
-
components branching on an env-conditioned `namingParams.tier`):
|
|
574
|
+
[Serve a chant workspace](https://intentius.io/behold/using/workspace/)).
|
|
575
575
|
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
576
|
+
### The tier axis: `buildParams` in `chant.config.ts`
|
|
577
|
+
|
|
578
|
+
The deploy-**tier** axis, a dimension orthogonal to `environment`, is a chant
|
|
579
|
+
build-time parameter (#470): a `buildParams` entry with a string `enum`, the
|
|
580
|
+
one named `tier` first, else the first such entry.
|
|
581
|
+
|
|
582
|
+
```typescript
|
|
583
|
+
buildParams: {
|
|
584
|
+
tier: { type: "string", enum: ["light", "production", "production-ha"], default: "light", env: "LOOM_TIER" },
|
|
585
|
+
},
|
|
583
586
|
```
|
|
584
587
|
|
|
585
|
-
- `
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
588
|
+
- The `enum` is the tier picker's options.
|
|
589
|
+
- A picked tier (`?tier=`) reaches `chant graph` as `--param tier=<value>`, and
|
|
590
|
+
the parameter's `env` variable is set for the chant shell-out when it
|
|
591
|
+
declares one, so a chant command without `--param` sees it too.
|
|
592
|
+
- The current tier in the header is that `env` variable's value in behold's
|
|
593
|
+
own environment, when the parameter declares one.
|
|
594
|
+
|
|
595
|
+
No such parameter means no tier axis: the picker doesn't render and the graph
|
|
596
|
+
loads with no tier selected. `.behold.json`'s old `tiers` block is not read;
|
|
597
|
+
`behold doctor` warns where one is left.
|
|
598
|
+
|
|
599
|
+
### Per-user settings: `approver` and `behaviour.traffic`
|
|
589
600
|
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
601
|
+
Who is approving (`approver`, see [Approving](https://intentius.io/behold/using/approving/))
|
|
602
|
+
and the traffic level the behaviour overlay predicts at (`behaviour.traffic`)
|
|
603
|
+
are one operator's settings, so since #470 they live in a per-user file outside
|
|
604
|
+
the project, beside the hand layout: `<cache>/behold/settings/<key>.json`
|
|
605
|
+
(`~/Library/Caches/behold/settings/` on macOS, `~/.cache/behold/settings/` on Linux, `%LOCALAPPDATA%\behold\settings\` on Windows; `BEHOLD_CACHE_DIR` moves it), keyed by the project's realpath like the layout. A project
|
|
606
|
+
whose `.behold.json` carried either block has it copied in on the first read
|
|
607
|
+
(relative key paths made absolute against the project); `.behold.json` is
|
|
608
|
+
never written or deleted.
|
|
594
609
|
|
|
595
610
|
### Deploy executors: `executor`
|
|
596
611
|
|
|
597
|
-
|
|
612
|
+
A member's `chant.config.ts` designates which forge deploys an environment
|
|
613
|
+
(#165, #470), on the environment's entry:
|
|
598
614
|
|
|
599
|
-
```
|
|
600
|
-
|
|
601
|
-
"
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
}
|
|
615
|
+
```ts
|
|
616
|
+
environments: [
|
|
617
|
+
"staging",
|
|
618
|
+
{ name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } },
|
|
619
|
+
],
|
|
605
620
|
```
|
|
606
621
|
|
|
622
|
+
behold reads it from chant (`chant workspace graph --composites`, each
|
|
623
|
+
`components[].environments[]` row's `executor`, chant 0.124.47 or newer), and
|
|
624
|
+
never from the name of a generated `chant-components-<env>` workflow. A chant
|
|
625
|
+
older than that, or an environment that declares none, reads as no designation.
|
|
626
|
+
`.behold.json`'s old `executor` block is not read; `behold doctor` warns where
|
|
627
|
+
one is left, with the entry to add.
|
|
628
|
+
|
|
607
629
|
It names the committed **workflow**, not just the forge, because two
|
|
608
630
|
environments' generated pipelines carry identical job ids and a picker cannot
|
|
609
631
|
tell them apart. For a designated environment the Deploy button dispatches that
|
|
@@ -624,33 +646,33 @@ state outside the project, so a behold restarted mid-deploy re-adopts the run
|
|
|
624
646
|
and keeps following it. A follow whose stream dies is reported as `lost`, never
|
|
625
647
|
as a verdict; `just e2e-ci-github` proves the whole contract against GitHub.
|
|
626
648
|
|
|
627
|
-
### The hand
|
|
649
|
+
### The hand layout: a per-user cache
|
|
628
650
|
|
|
629
651
|
dagre places your nodes; you can move them. Drag a card, resize a containment
|
|
630
652
|
box, and the offsets are remembered per project and lens: in `localStorage`
|
|
631
|
-
first, and
|
|
632
|
-
|
|
633
|
-
by `behold export`:
|
|
653
|
+
first, and in a per-user cache file outside the project, which is what
|
|
654
|
+
`behold export` bakes into its SVGs:
|
|
634
655
|
|
|
635
656
|
```json
|
|
636
|
-
{ "version": 1, "lenses": { "components": { "src/api#Component": { "dx": 40, "dy": -25 } } } }
|
|
657
|
+
{ "version": 1, "projectDir": "/path/to/project", "lenses": { "components": { "src/api#Component": { "dx": 40, "dy": -25 } } } }
|
|
637
658
|
```
|
|
638
659
|
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
660
|
+
The file is `<user cache>/behold/layouts/<key>.json`, where `<user cache>` is
|
|
661
|
+
`~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows and `$XDG_CACHE_HOME`
|
|
662
|
+
(or `~/.cache`) elsewhere, and `<key>` is a hash of the project directory's
|
|
663
|
+
realpath. `BEHOLD_CACHE_DIR` moves `<user cache>/behold`. behold writes nothing
|
|
664
|
+
inside a served project (#469), so there is nothing to gitignore.
|
|
665
|
+
|
|
666
|
+
It stores deltas rather than absolute positions, so the graph stays chant's and
|
|
667
|
+
your layout sits on top of it. A delta whose node has left the estate is
|
|
668
|
+
dropped. `POST /api/layout` refuses politely in preview mode, during a
|
|
669
|
+
static-export capture, when the cache isn't writable, and above its size caps.
|
|
670
|
+
`↺ layout` in the graph clears the current lens on both tiers.
|
|
671
|
+
|
|
672
|
+
A project served by an older behold may have a `.behold/layout.json`. The first
|
|
673
|
+
time the cache has nothing for that project, behold reads the old file once
|
|
674
|
+
and copies it into the cache. It never changes or deletes it; remove it
|
|
675
|
+
yourself when you like.
|
|
654
676
|
|
|
655
677
|
## Layout
|
|
656
678
|
|