@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 +66 -32
- package/README.md +67 -50
- package/dist/cli.js +5404 -1615
- 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-three-cloud/package-lock.json +19 -19
- package/example-three-cloud/package.json +4 -4
- package/package.json +5 -5
- package/web/app.js +67 -3
- package/web/layout-store.js +3 -3
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
|
|
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
|
-
|
|
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
|
-
|
|
1184
|
+
A member's `chant.config.ts` may designate which forge deploys an environment,
|
|
1185
|
+
on the environment's entry (#470):
|
|
1185
1186
|
|
|
1186
|
-
```
|
|
1187
|
-
{
|
|
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
|
|
1223
|
-
|
|
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,
|
|
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,
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
1637
|
-
|
|
1638
|
-
|
|
1639
|
-
|
|
1640
|
-
|
|
1641
|
-
|
|
1642
|
-
|
|
1643
|
-
- It **
|
|
1644
|
-
|
|
1645
|
-
|
|
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
|
|
1648
|
-
-
|
|
1649
|
-
|
|
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)
|
|
1656
|
-
directory holding `chant.workspace.json`, rather than
|
|
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
|
|
1662
|
-
|
|
1663
|
-
|
|
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.
|
|
2023
|
-
|
|
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
|
|
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,
|
|
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/)).
|
|
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
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
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
|
-
- `
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
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
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
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
|
-
|
|
607
|
+
A member's `chant.config.ts` designates which forge deploys an environment
|
|
608
|
+
(#165, #470), on the environment's entry:
|
|
598
609
|
|
|
599
|
-
```
|
|
600
|
-
|
|
601
|
-
"
|
|
602
|
-
|
|
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
|
|
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
|
|
632
|
-
|
|
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
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
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
|
|