@intentius/behold 0.30.0 → 0.30.1

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 CHANGED
@@ -735,7 +735,7 @@ block in M1.
735
735
 
736
736
  With a traffic level, `/api/overlay` predicts each member twice and carries
737
737
  both figures and their difference. The level is `?traffic=` on the request,
738
- else `.behold.json`'s `{"behaviour": {"traffic": "100 rps, p50"}}`, else none;
738
+ else the per-user settings' `{"behaviour": {"traffic": "100 rps, p50"}}` (src/user-settings.ts, #470), else none;
739
739
  with none nothing is asked for and the payload is exactly M1's. behold never
740
740
  defaults a level, because every figure is *at* one.
741
741
 
@@ -1003,7 +1003,7 @@ GET /api/capabilities
1003
1003
 
1004
1004
  `POST /api/view` changes what every open tab of this serve draws. It is a
1005
1005
  view change and writes nothing: no infrastructure, no project file, not
1006
- `.behold/layout.json`, and nothing kept on the server.
1006
+ the layout cache, and nothing kept on the server.
1007
1007
 
1008
1008
  ```
1009
1009
  POST /api/view
@@ -1181,12 +1181,21 @@ best-effort, and only its exit code is certain (src/ci-run.ts).
1181
1181
 
1182
1182
  ### The executor contract (#165, #61)
1183
1183
 
1184
- `.behold.json` may designate which forge deploys an environment:
1184
+ A member's `chant.config.ts` may designate which forge deploys an environment,
1185
+ on the environment's entry (#470):
1185
1186
 
1186
- ```json
1187
- { "executor": { "prod": { "forge": "github", "workflow": "deploy-prod.yml" } } }
1187
+ ```ts
1188
+ environments: [{ name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } }]
1188
1189
  ```
1189
1190
 
1191
+ behold reads it from `chant workspace graph --composites --json`
1192
+ (`components[].environments[].executor`, floor `EXECUTOR_CHANT_FLOOR` 0.124.47,
1193
+ src/executor.ts) through the workspace reader. It never reads `.behold.json`'s
1194
+ `executor` (retired; `behold doctor` warns), and never derives it from a
1195
+ `chant-components-<env>` workflow name (maintainer ruling, 2026-10-23). An older
1196
+ chant prints no `executor`, and no row means none declared. `reason.code`
1197
+ `executor-config-unreadable` stays designated and fails closed.
1198
+
1190
1199
  It designates the committed WORKFLOW, not just the forge: two environments'
1191
1200
  generated pipelines carry identical job ids, so a picker cannot tell them
1192
1201
  apart, and a contract that names prod must not sit on a guess. For a
@@ -1219,8 +1228,8 @@ A dispatched run is followed honestly (#165 §6, PR #350): only GitHub's own
1219
1228
  follow deadline promotes the run to `lost` (chips frozen at last-observed,
1220
1229
  the run possibly still live at its own page), never to a verdict. The adopted
1221
1230
  run id is persisted as one JSON per project under `~/.behold/ci-runs/`, the
1222
- operator's machine-state, outside the project tree, so the Invariant below
1223
- still names the whole in-project write surface. `GET /api/ci/run` reads the
1231
+ operator's machine-state, outside the project tree, so behold still writes
1232
+ nothing in a served project (the Invariant below). `GET /api/ci/run` reads the
1224
1233
  record; `POST /api/ci/readopt` (also attempted once at boot) re-follows an
1225
1234
  unconcluded run by its saved id, so a restart mid-deploy leaves the run a
1226
1235
  reader instead of nothing.
@@ -1290,13 +1299,13 @@ chant never signs a person in (ws-052); the surface that does passes the person
1290
1299
  to chant as `--actor` (ws-080). behold has no login, so `src/approver.ts` names
1291
1300
  the person for each request, in this order:
1292
1301
 
1293
- - `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, `.behold.json`
1302
+ - `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, the per-user settings'
1294
1303
  `approver.header`): behold sits behind a proxy that signed the person in
1295
1304
  through the forge or OIDC, and the header names them. A bare login is an
1296
1305
  account on `--identity-forge` (github unless set). A request without the
1297
1306
  header approves nothing (`403 no-identity`). Refused at startup with a
1298
1307
  `--host` other than loopback, since anyone reaching the port could send it.
1299
- - `--as <principal>` (BEHOLD_APPROVER, `.behold.json` `approver.as`): one
1308
+ - `--as <principal>` (BEHOLD_APPROVER, the per-user settings' `approver.as`): one
1300
1309
  person runs behold and names themselves, `github:<login>` or a principal the
1301
1310
  signers file lists.
1302
1311
  - Neither: chant's own fallback (GITHUB_ACTOR, GITLAB_USER_LOGIN, USER), and
@@ -1311,7 +1320,7 @@ Every approve route (`/api/workspace/gates/approve`, the converge gate's
1311
1320
  behold"`. chant's ledger has no channel for a surface (its `origin` is `cli`,
1312
1321
  `mcp` or `acp`), so the note is where behold is named. A workspace gate that
1313
1322
  status marks `signed` is approved with `--sign <key>` when behold holds the
1314
- person's key (`--signing-key` beside `--as`, or `.behold.json`'s
1323
+ person's key (`--signing-key` beside `--as`, or the per-user settings'
1315
1324
  `approver.keys` by principal) and refused `422 signed` with the line to run
1316
1325
  otherwise. The key path never reaches a page: `GET /api/workspace/gates`
1317
1326
  carries `approverIdentity: {principal, source, forge, signs}`, or `approver:
@@ -1576,6 +1585,14 @@ If a request would have behold write to a cloud or to source directly, it's wron
1576
1585
  behold shows truth and triggers Ops. Authority stays in the committed source and the
1577
1586
  executor.
1578
1587
 
1588
+ behold writes nothing in a served project (#469, ruled 2026-10-23). What it
1589
+ keeps for itself (the hand layout, the per-user settings, dispatched CI run
1590
+ ids, recents, the serve registry) lives in the user's own home, cache or temp directory, keyed by the
1591
+ project, never in the tree. The only files behold puts in a project are the
1592
+ ones a person asks for by name: `behold doctor --fix` writing
1593
+ `chant.workspace.json`, and the carve walkthrough writing into the demo copy
1594
+ behold made itself (both below).
1595
+
1579
1596
  The commands behold starts run with behold's own environment, so Deploy (`POST
1580
1597
  /api/apply`, chant's local executor) applies with the credentials of whoever
1581
1598
  started it. On a terragucci repo (a `terragucci.yml` in the served directory or
@@ -1586,7 +1603,7 @@ so the page offers no write, and auto-sync declines. The boundary is an
1586
1603
  allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
1587
1604
  any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
1588
1605
  method and route, and that list holds only the exceptions below (the layout
1589
- sidecar, project open and reveal, demo open, refresh, and the four carve
1606
+ cache, project open and reveal, demo open, refresh, and the four carve
1590
1607
  steps), plus `POST /api/view`, which moves the open tabs and writes nothing
1591
1608
  (#914). A new write route is refused on a terragucci repo until it is added
1592
1609
  there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
@@ -1632,35 +1649,52 @@ These are also the only writes a guarded product repo answers: terragucci
1632
1649
  (`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
1633
1650
  listed in `TERRAGUCCI_ALLOWED_WRITES`.
1634
1651
 
1635
- `POST /api/layout` (#228) writes **one** file in the served project:
1636
- `.behold/layout.json`, the hand-layout sidecar, `{version, lenses: {<lens>:
1637
- {<node id>: {dx,dy,dw,dh}}}}`. That is the whole of behold's write surface
1638
- inside a project, and it does not weaken the invariant above:
1639
-
1640
- - It is **workspace metadata**, not estate truth. Deltas describe how *you* want
1641
- the picture arranged on top of dagre's layout; the graph underneath stays
1642
- chant's, and a delta for a node that left the estate is dropped on read.
1643
- - It **never touches the cloud and never touches your source**. No `.ts`, no
1644
- `chant.config.ts`, no `.behold.json`. The path is `cfg.projectDir` + two
1645
- constants; nothing from the request reaches the filesystem.
1652
+ `POST /api/layout` (#228) writes **one** file, and not in the served project:
1653
+ the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
1654
+ with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
1655
+ `$XDG_CACHE_HOME` or `~/.cache`), `<key>` the first 32 hex characters of the
1656
+ sha256 of the project directory's realpath, and `BEHOLD_CACHE_DIR` replacing
1657
+ `<user cache>/behold`. The file is `{version, projectDir, lenses: {<lens>:
1658
+ {<node id>: {dx,dy,dw,dh}}}}`, mode 0600 in a 0700 directory (src/layout.ts):
1659
+
1660
+ - It is **one operator's view**, not estate truth. Deltas describe how *you*
1661
+ want the picture arranged on top of dagre's layout; the graph underneath
1662
+ stays chant's, and a delta for a node that left the estate is dropped on read.
1663
+ - It **never touches the cloud, your source or the project**. The path is a
1664
+ hash of `cfg.projectDir` + constants; nothing from the request reaches the
1665
+ filesystem.
1646
1666
  - It refuses politely when it shouldn't write: preview mode, a static-export
1647
- capture, a read-only project directory, an oversized or malformed body.
1648
- - It is **per-user state**, unlike `.behold.json` (config, meant to be tracked).
1649
- Projects should gitignore `.behold/`.
1667
+ capture, a cache directory that isn't writable, an oversized or malformed body.
1668
+ - A project served before #469 may carry `.behold/layout.json`. When the cache
1669
+ has no file for the project, that file is read once and copied into the
1670
+ cache; it is never written, moved or deleted. Clearing the last lens keeps
1671
+ an empty cache file, so the old one is not read back in.
1672
+
1673
+ The per-user settings (#470, src/user-settings.ts) sit beside it at
1674
+ `<user cache>/behold/settings/<key>.json`, same key, same modes: the operator's
1675
+ `approver` block and `behaviour.traffic`, which are not facts about the estate.
1676
+ No route writes them. When the cache has none for a project with a
1677
+ `.behold.json`, that file's two blocks are read once and copied in (key paths
1678
+ made absolute against the project), and a copy is kept even when neither
1679
+ block is there, so `.behold.json` is not read for them again. It is never
1680
+ written, moved or deleted. The tier axis is not a setting: it is the
1681
+ project's `chant.config.ts` `buildParams` entry with a string `enum`
1682
+ (src/project.ts `readTierParam`), read per request through `detectProject`
1683
+ and passed to `chant graph` as `--param`.
1650
1684
 
1651
1685
  `GET /api/layout` reads it back; `GET /api/graph?layout=1` (and `/api/overlay`)
1652
1686
  render with the deltas baked into the SVG, which is how `behold export` and
1653
1687
  static snapshots honour a hand layout.
1654
1688
 
1655
- A declared workspace (#464) keeps that file in the workspace root, the
1656
- directory holding `chant.workspace.json`, rather than in its first member.
1689
+ A declared workspace (#464) keys the layout by the workspace root, the
1690
+ directory holding `chant.workspace.json`, rather than by its first member.
1657
1691
 
1658
1692
  `behold doctor --fix` (#464, ws-015) is the third exception, and it runs only
1659
1693
  when you type the flag: for an estate root whose members are listed in
1660
1694
  `.behold.json`, it writes `chant.workspace.json` in that root (never over an
1661
- existing one) and moves the saved `.behold/layout.json` from the first member to
1662
- the root with its node ids rewritten. It then runs `chant workspace check`. The
1663
- old layout file and `.behold.json` are left as they were.
1695
+ existing one) and copies the first member's saved layout to the root's cache
1696
+ entry with its node ids rewritten. It then runs `chant workspace check`. The
1697
+ first member's layout and `.behold.json` are left as they were.
1664
1698
 
1665
1699
  The fourth exception is the carve walkthrough's two steps above (#254), and it
1666
1700
  is narrower still: they exist only when behold booted a `behold demo carve`
@@ -2019,8 +2053,8 @@ exists to draw is a directory of `.tf` files and nothing else, and #378 chose
2019
2053
  not to ask one for a `chant.config.ts` of its own — INTENTIUS/waterpark#88 was
2020
2054
  withdrawn because the estate is more useful untouched. So `behold serve
2021
2055
  <terraform-dir>` generates the reader config itself, outside the estate, and
2022
- points chant at it. The Invariant's one in-project write stays
2023
- `.behold/layout.json`; nothing is written under the served directory, and
2056
+ points chant at it. behold writes nothing in a served project (the
2057
+ Invariant), nothing is written under the served directory, and
2024
2058
  `src/terraform-member.test.ts` asserts the estate's source stamp is unchanged
2025
2059
  across a read. Three decisions, each a trade #384 left open and each measured on
2026
2060
  water park's `access/` before it was taken:
package/README.md CHANGED
@@ -460,7 +460,7 @@ button says who chant will record before the click: the person `--as` names
460
460
  (`--as github:<login>`), the person an authenticating proxy names in the header
461
461
  `--identity-header` trusts, or else the user running behold. A gate the
462
462
  workspace names in `identity.gates` is signed with that person's key when
463
- `--signing-key` (or `.behold.json`'s `approver.keys`) gives one, and sent to the
463
+ `--signing-key` (or `approver.keys` in behold's per-user settings) gives one, and sent to the
464
464
  command line otherwise (#690). Every approve route refuses in preview mode.
465
465
 
466
466
  In a declared workspace, the inspect pane of a member's box or a card has a
@@ -560,50 +560,67 @@ nothing else. Your Terraform is never edited; see AGENTS.md, "Invariant".
560
560
  ## Configuration: `.behold.json`
561
561
 
562
562
  An optional `.behold.json` in the served project's root is **behold's own**
563
- config, kept separate from `chant.config.ts` so behold's concerns (like the
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":
563
+ config, which #470 retired. One key is still read, `members`, spelled `[{ "dir": "x", "kind":
566
564
  "chant" | "choudoufu" | "terraform" }]`, how an estate root names what it
567
565
  composes, fail-closed on a kind behold has no reader for. `members` is
568
566
  deprecated: a chant workspace declaration (`chant.workspace.json`) lists an
569
567
  estate's members for every reader, and beside one, `.behold.json`'s list is
570
568
  ignored. `behold doctor --fix` writes the declaration from it (see
571
- [Serve a chant workspace](https://intentius.io/behold/using/workspace/)). First, the
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`):
569
+ [Serve a chant workspace](https://intentius.io/behold/using/workspace/)).
575
570
 
576
- ```json
577
- {
578
- "tiers": {
579
- "envVar": "LOOM_TIER",
580
- "values": ["light", "production", "production-ha"]
581
- }
582
- }
571
+ ### The tier axis: `buildParams` in `chant.config.ts`
572
+
573
+ The deploy-**tier** axis, a dimension orthogonal to `environment`, is a chant
574
+ build-time parameter (#470): a `buildParams` entry with a string `enum`, the
575
+ one named `tier` first, else the first such entry.
576
+
577
+ ```typescript
578
+ buildParams: {
579
+ tier: { type: "string", enum: ["light", "production", "production-ha"], default: "light", env: "LOOM_TIER" },
580
+ },
583
581
  ```
584
582
 
585
- - `envVar` is the env var name the project's source branches on; behold sets it
586
- for the chant shell-out whenever a tier is picked (`?tier=` → this var, never
587
- a chant CLI flag).
588
- - `values` is the tier picker's options.
583
+ - The `enum` is the tier picker's options.
584
+ - A picked tier (`?tier=`) reaches `chant graph` as `--param tier=<value>`, and
585
+ the parameter's `env` variable is set for the chant shell-out when it
586
+ declares one, so a chant command without `--param` sees it too.
587
+ - The current tier in the header is that `env` variable's value in behold's
588
+ own environment, when the parameter declares one.
589
+
590
+ No such parameter means no tier axis: the picker doesn't render and the graph
591
+ loads with no tier selected. `.behold.json`'s old `tiers` block is not read;
592
+ `behold doctor` warns where one is left.
593
+
594
+ ### Per-user settings: `approver` and `behaviour.traffic`
589
595
 
590
- **No `.behold.json` (or no `tiers` key) → no tier axis:** the picker doesn't
591
- render and the graph loads with no tier selected, which is the default for any
592
- project that doesn't opt in. There's no other tier config surface (not
593
- `chant.config.ts`, not an env var behold guesses the name of).
596
+ Who is approving (`approver`, see [Approving](https://intentius.io/behold/using/approving/))
597
+ and the traffic level the behaviour overlay predicts at (`behaviour.traffic`)
598
+ are one operator's settings, so since #470 they live in a per-user file outside
599
+ the project, beside the hand layout: `<cache>/behold/settings/<key>.json`
600
+ (`~/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
601
+ whose `.behold.json` carried either block has it copied in on the first read
602
+ (relative key paths made absolute against the project); `.behold.json` is
603
+ never written or deleted.
594
604
 
595
605
  ### Deploy executors: `executor`
596
606
 
597
- The same file can designate which forge deploys an environment (#165):
607
+ A member's `chant.config.ts` designates which forge deploys an environment
608
+ (#165, #470), on the environment's entry:
598
609
 
599
- ```json
600
- {
601
- "executor": {
602
- "prod": { "forge": "github", "workflow": "deploy-prod.yml" }
603
- }
604
- }
610
+ ```ts
611
+ environments: [
612
+ "staging",
613
+ { name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } },
614
+ ],
605
615
  ```
606
616
 
617
+ behold reads it from chant (`chant workspace graph --composites`, each
618
+ `components[].environments[]` row's `executor`, chant 0.124.47 or newer), and
619
+ never from the name of a generated `chant-components-<env>` workflow. A chant
620
+ older than that, or an environment that declares none, reads as no designation.
621
+ `.behold.json`'s old `executor` block is not read; `behold doctor` warns where
622
+ one is left, with the entry to add.
623
+
607
624
  It names the committed **workflow**, not just the forge, because two
608
625
  environments' generated pipelines carry identical job ids and a picker cannot
609
626
  tell them apart. For a designated environment the Deploy button dispatches that
@@ -624,33 +641,33 @@ state outside the project, so a behold restarted mid-deploy re-adopts the run
624
641
  and keeps following it. A follow whose stream dies is reported as `lost`, never
625
642
  as a verdict; `just e2e-ci-github` proves the whole contract against GitHub.
626
643
 
627
- ### The hand-layout sidecar: `.behold/layout.json`
644
+ ### The hand layout: a per-user cache
628
645
 
629
646
  dagre places your nodes; you can move them. Drag a card, resize a containment
630
647
  box, and the offsets are remembered per project and lens: in `localStorage`
631
- first, and (when the served project is writable) in a `.behold/layout.json`
632
- sidecar beside it, so a layout is shareable, reviewable in a diff, and honoured
633
- by `behold export`:
648
+ first, and in a per-user cache file outside the project, which is what
649
+ `behold export` bakes into its SVGs:
634
650
 
635
651
  ```json
636
- { "version": 1, "lenses": { "components": { "src/api#Component": { "dx": 40, "dy": -25 } } } }
652
+ { "version": 1, "projectDir": "/path/to/project", "lenses": { "components": { "src/api#Component": { "dx": 40, "dy": -25 } } } }
637
653
  ```
638
654
 
639
- This is the **only** file behold writes inside a served project. It stores
640
- deltas rather than absolute positions, so the graph stays chant's and your
641
- layout sits on top of it. A delta whose node has left the estate is dropped.
642
- `POST /api/layout` refuses politely in preview mode, during a static-export
643
- capture, on a read-only directory, and above its size caps. `↺ layout` in the
644
- graph clears the current lens on both tiers.
645
-
646
- **Gitignore it.** `.behold.json` (above) is config and belongs in the repo;
647
- `.behold/` is per-user state, one person's arrangement of the picture, so add
648
- it to the served project's `.gitignore` unless you actually want to share and
649
- review a layout:
650
-
651
- ```gitignore
652
- .behold/
653
- ```
655
+ The file is `<user cache>/behold/layouts/<key>.json`, where `<user cache>` is
656
+ `~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows and `$XDG_CACHE_HOME`
657
+ (or `~/.cache`) elsewhere, and `<key>` is a hash of the project directory's
658
+ realpath. `BEHOLD_CACHE_DIR` moves `<user cache>/behold`. behold writes nothing
659
+ inside a served project (#469), so there is nothing to gitignore.
660
+
661
+ It stores deltas rather than absolute positions, so the graph stays chant's and
662
+ your layout sits on top of it. A delta whose node has left the estate is
663
+ dropped. `POST /api/layout` refuses politely in preview mode, during a
664
+ static-export capture, when the cache isn't writable, and above its size caps.
665
+ `↺ layout` in the graph clears the current lens on both tiers.
666
+
667
+ A project served by an older behold may have a `.behold/layout.json`. The first
668
+ time the cache has nothing for that project, behold reads the old file once
669
+ and copies it into the cache. It never changes or deletes it; remove it
670
+ yourself when you like.
654
671
 
655
672
  ## Layout
656
673