@intentius/behold 0.29.40 → 0.29.41
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 +148 -10
- package/README.md +6 -2
- package/dist/cli.js +15965 -13076
- package/example-writes/README.md +1 -1
- package/example-writes/chant.config.ts +0 -6
- package/package.json +5 -2
- package/web/app.js +327 -21
- package/web/carve-export.js +142 -0
- package/web/carve-narration.js +268 -0
- package/web/carve-narration.test.js +18 -0
- package/web/change-set-overlay.js +147 -0
- package/web/change-set-overlay.test.js +83 -0
- package/web/dots-border.js +66 -0
- package/web/dots-border.test.js +27 -0
- package/web/dots-kiosk.js +279 -0
- package/web/dots-kiosk.test.js +60 -0
- package/web/dots-layout.d.ts +10 -0
- package/web/dots-layout.js +201 -0
- package/web/dots-live.js +316 -0
- package/web/dots-live.test.js +220 -0
- package/web/dots-lod.js +122 -0
- package/web/dots-lod.test.js +78 -0
- package/web/dots-recording.d.ts +7 -0
- package/web/dots-recording.js +247 -0
- package/web/dots-recording.test.js +71 -0
- package/web/dots-scene.js +294 -0
- package/web/dots-scene.test.js +118 -0
- package/web/dots-timeline.js +128 -0
- package/web/dots-timeline.test.js +83 -0
- package/web/dots-tour.js +153 -0
- package/web/dots.js +2124 -0
- package/web/dots.test.js +15 -0
- package/web/index.html +29 -0
- package/web/kiosk-carve.js +219 -0
- package/web/kiosk-carve.test.js +26 -0
- package/web/kiosk-event-help-ui.js +6 -0
- package/web/kiosk.js +21 -6
- package/web/operator.js +1 -1
- package/web/run-playhead.js +102 -19
- package/web/run-playhead.test.js +81 -11
- package/web/tour-player.js +204 -0
- package/web/tour-player.test.js +115 -0
- package/web/tours/behold.tour.v1.schema.json +182 -0
- package/web/tours/terralith.json +330 -0
- package/web/trunk-lane.js +254 -0
- package/web/trunk-lane.test.js +117 -0
- package/web/workspace-gates.js +29 -4
- package/web/workspace-gates.test.js +23 -2
package/AGENTS.md
CHANGED
|
@@ -59,6 +59,27 @@ a scheduled read: it holds a slot in the read budget, has the read deadline,
|
|
|
59
59
|
and stops when the request does. `serve --hud <url>` (or `BEHOLD_HUD_URL`)
|
|
60
60
|
links a proposed decision to its review in hud.
|
|
61
61
|
|
|
62
|
+
## Chant version floors (behold#691)
|
|
63
|
+
|
|
64
|
+
behold shells each project's own chant, so a read can reach a chant that
|
|
65
|
+
predates it. Every read has one floor, and every floor lives in
|
|
66
|
+
`src/chant-floors.ts`:
|
|
67
|
+
|
|
68
|
+
- one constant per read, named after the read (`WHY_CHANT_FLOOR`) and set to the
|
|
69
|
+
chant release that adds it;
|
|
70
|
+
- one entry in `CHANT_FLOORS` (the read in words, the floor, what adds it in
|
|
71
|
+
chant), which is what `behold doctor` lists with the project's chant version
|
|
72
|
+
and whether the floor is met;
|
|
73
|
+
- the code that makes the read checks the project's chant first (`floorMet`,
|
|
74
|
+
`floorRefusal`) and never sends the read to a chant that would reject it.
|
|
75
|
+
|
|
76
|
+
On an older chant the pane that needs the read shows `floorRefusal`'s words
|
|
77
|
+
(the read, the chant that adds it, the project's version) and the rest of
|
|
78
|
+
behold works. The why route does this: `GET /api/workspace/why` refuses before
|
|
79
|
+
spawning the read. A new read adds its constant and entry in the issue that
|
|
80
|
+
adds the read, once the chant release is known, and reads through the read
|
|
81
|
+
contract (`src/workspace-reader.ts`), never chant's library.
|
|
82
|
+
|
|
62
83
|
## A pipeline's numbers, from Prometheus (behold#571)
|
|
63
84
|
|
|
64
85
|
`behold serve --prometheus <url>` (or `BEHOLD_PROMETHEUS_URL`) adds `GET
|
|
@@ -296,7 +317,13 @@ checkout declares no Terraform root (`controlRepo` in
|
|
|
296
317
|
`GET /api/lifecycle/releases[?fresh=1]` (src/lifecycle-releases.ts) reads
|
|
297
318
|
`<env>/releases.jsonl` on the served checkout's `chant/lifecycle` with chant's
|
|
298
319
|
own reader (`listReleaseEnvironments`, `readReleaseLedger`,
|
|
299
|
-
`latestPerComponent`, `recordsForDigest`).
|
|
320
|
+
`latestPerComponent`, `recordsForDigest`). This one still imports
|
|
321
|
+
`@intentius/chant/lifecycle/release-ledger`: no read-contract command lists a
|
|
322
|
+
project's per-environment ledger outside a declared workspace (`workspace
|
|
323
|
+
status` needs a declaration, and `release list` lists cut releases, not the
|
|
324
|
+
`components release` records SQL Yodeler writes), so dropping the import would
|
|
325
|
+
blank the tab for every SQL Yodeler project. The trunk lane (#680) reads
|
|
326
|
+
releases through the contract only. The branch is fetched into the
|
|
300
327
|
same bare cache the terragucci lane uses (`fetchIntoCache` in
|
|
301
328
|
src/terragucci-lifecycle.ts). When that fetch fails, the checkout's
|
|
302
329
|
`refs/remotes/origin/chant/lifecycle` is fetched into a second cache of
|
|
@@ -816,13 +843,41 @@ behold does not apply. To change the estate:
|
|
|
816
843
|
Every mutation is a gated, durable Temporal workflow with a human-confirmable gate
|
|
817
844
|
and saga rollback. There is no behold endpoint that mutates the cloud.
|
|
818
845
|
|
|
819
|
-
A run behold triggered is asked for
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
with
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
846
|
+
A run behold triggered is asked for chant's run events (#679, chant#4019:
|
|
847
|
+
`chant run <op> --events-json`, `chant run <target> --components --env <env>
|
|
848
|
+
--events-json`), so the ops lens and the dial show each step's start and settle,
|
|
849
|
+
a skip with chant's reason, a cache hit, and the gate or decision point a run
|
|
850
|
+
waits on, as they happen, and a pending gate renders as a card with an Approve
|
|
851
|
+
button. That button is `op-signal`, the same delegated write, and nothing else
|
|
852
|
+
about the run is behold's to decide: the verdict is the stream's own
|
|
853
|
+
`run-settle`, a stream that ends without one leaves the playhead at the last
|
|
854
|
+
settled step and says it was lost, and a gate paints as pending only when chant
|
|
855
|
+
named it (`gate-waiting`, or `chant run status`).
|
|
856
|
+
|
|
857
|
+
`src/run-events.ts` is the one boundary every run line crosses. It validates
|
|
858
|
+
each line against chant's `run-event.schema.json` (vendored in
|
|
859
|
+
`src/run-event-schema/` from @intentius/chant 0.124.28, its source commit in
|
|
860
|
+
`RUN_EVENT_SCHEMA_SOURCE`), since the line comes from the project's chant,
|
|
861
|
+
not behold's, and refuses a line that fails it; it folds the stream into what
|
|
862
|
+
the dial and the ops lens render. The event types are chant's own `RunEvent`
|
|
863
|
+
and `RunEventBody`, imported as types only. `src/run-events-chant.test.ts`
|
|
864
|
+
runs the whole path against a real chant when `BEHOLD_TEST_CHANT_BIN` is set.
|
|
865
|
+
|
|
866
|
+
A run behold did not start is followed when the status read names it: `chant
|
|
867
|
+
run events <run> --json --follow` replays what chant kept on this host and tails
|
|
868
|
+
it to `run-settle`. A run killed outright writes no settle, so a follow that is
|
|
869
|
+
silent for `BEHOLD_RUN_EVENTS_IDLE_MS` (60 s) asks `chant run status` whether it
|
|
870
|
+
still runs, and ends as lost when it does not or after
|
|
871
|
+
`BEHOLD_RUN_EVENTS_MAX_IDLE_MS` (30 min) of silence. A steward run keeps no
|
|
872
|
+
events here, and the playhead says so.
|
|
873
|
+
|
|
874
|
+
The read has a floor, `RUN_EVENTS_CHANT_FLOOR` (0.124.28). Below it behold
|
|
875
|
+
starts runs with the older `--progress-json` (degraded mode: settled steps
|
|
876
|
+
only, no skip reasons, cache hits or gate events, and no follow), translates
|
|
877
|
+
those lines at the same boundary, and the dial and the playhead say they are
|
|
878
|
+
degraded. A local pipeline run (gitlab-ci-local, a forgejo runner) is the one
|
|
879
|
+
path that still reads a log, because chant does not run it; the dial labels it
|
|
880
|
+
best-effort, and only its exit code is certain (src/ci-run.ts).
|
|
826
881
|
|
|
827
882
|
### The executor contract (#165, #61)
|
|
828
883
|
|
|
@@ -905,8 +960,8 @@ Two gate cards exist and they are **different acts**:
|
|
|
905
960
|
- The **run gate** — `POST /api/ops/:name/signal/:gate` → `chant run approve
|
|
906
961
|
<op> <gate>` (chant#2121 renamed `chant run signal`, #459). Records the
|
|
907
962
|
resolution; a runtime that parks a run is woken, and the local one reads it
|
|
908
|
-
when the Op runs again (behold runs `chant run <op> --
|
|
909
|
-
|
|
963
|
+
when the Op runs again (behold runs `chant run <op> --events-json`, which
|
|
964
|
+
says `gate-waiting`, settles `gated` and exits 3).
|
|
910
965
|
- The **converge gate** — `POST /api/operator/approve/:op/:gate` →
|
|
911
966
|
`chant approve <op> <gate>`. **Records a fact and unblocks nothing.** chant's
|
|
912
967
|
gate ledger says it outright: the local executor still refuses a gated op,
|
|
@@ -929,6 +984,89 @@ appears in the entity graph. behold names it there, the Namespace as the loop's
|
|
|
929
984
|
home, each CronJob as a converge tick — off chant's own
|
|
930
985
|
`app.kubernetes.io/component: converge-tick` labels, never a naming convention.
|
|
931
986
|
|
|
987
|
+
## Who an approval is recorded as (#690)
|
|
988
|
+
|
|
989
|
+
chant never signs a person in (ws-052); the surface that does passes the person
|
|
990
|
+
to chant as `--actor` (ws-080). behold has no login, so `src/approver.ts` names
|
|
991
|
+
the person for each request, in this order:
|
|
992
|
+
|
|
993
|
+
- `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, `.behold.json`
|
|
994
|
+
`approver.header`): behold sits behind a proxy that signed the person in
|
|
995
|
+
through the forge or OIDC, and the header names them. A bare login is an
|
|
996
|
+
account on `--identity-forge` (github unless set). A request without the
|
|
997
|
+
header approves nothing (`403 no-identity`). Refused at startup with a
|
|
998
|
+
`--host` other than loopback, since anyone reaching the port could send it.
|
|
999
|
+
- `--as <principal>` (BEHOLD_APPROVER, `.behold.json` `approver.as`): one
|
|
1000
|
+
person runs behold and names themselves, `github:<login>` or a principal the
|
|
1001
|
+
signers file lists.
|
|
1002
|
+
- Neither: chant's own fallback (GITHUB_ACTOR, GITLAB_USER_LOGIN, USER), and
|
|
1003
|
+
behold passes no `--actor`.
|
|
1004
|
+
|
|
1005
|
+
Without a trusted header, a request carrying a usual proxy identity header
|
|
1006
|
+
(`PROXY_IDENTITY_HEADERS`, such as `X-Forwarded-User`) is refused with `403
|
|
1007
|
+
identity-header` on every approve route, rather than recorded as someone else.
|
|
1008
|
+
Every approve route (`/api/workspace/gates/approve`, the converge gate's
|
|
1009
|
+
`/api/operator/approve`, the run gate's `/api/ops/:name/signal`) adds
|
|
1010
|
+
`--actor` (`--approver` on `chant run approve`) and `--note "approved in
|
|
1011
|
+
behold"`. chant's ledger has no channel for a surface (its `origin` is `cli`,
|
|
1012
|
+
`mcp` or `acp`), so the note is where behold is named. A workspace gate that
|
|
1013
|
+
status marks `signed` is approved with `--sign <key>` when behold holds the
|
|
1014
|
+
person's key (`--signing-key` beside `--as`, or `.behold.json`'s
|
|
1015
|
+
`approver.keys` by principal) and refused `422 signed` with the line to run
|
|
1016
|
+
otherwise. The key path never reaches a page: `GET /api/workspace/gates`
|
|
1017
|
+
carries `approverIdentity: {principal, source, forge, signs}`, or `approver:
|
|
1018
|
+
null` and `approverRefusal`. `src/approver-chant.test.ts` runs the whole path
|
|
1019
|
+
against chant with a throwaway key and workspace.
|
|
1020
|
+
|
|
1021
|
+
## The trunk lane (#680)
|
|
1022
|
+
|
|
1023
|
+
`GET /api/workspace/lane` (src/trunk-lane.ts) answers "what is in flight and
|
|
1024
|
+
where is it?" for a served workspace, read through the reader on every request
|
|
1025
|
+
and kept nowhere:
|
|
1026
|
+
|
|
1027
|
+
- `chant ci list --json` at the root: the trunk's commits within ci.green's
|
|
1028
|
+
window, each `green`, `revoked` or `undecided`, with its phases and runs
|
|
1029
|
+
and its work items (`work`, chant#4029). It reads local tags only, so a
|
|
1030
|
+
commit that failed without ever being green reads `undecided`.
|
|
1031
|
+
- `chant workspace status <env> --json` once per environment, in the order the
|
|
1032
|
+
members' `promotionOrder` gives (merged in member order): the gates with
|
|
1033
|
+
`env` equal to that environment, with `gitSha`, `runId` and `changeSet`, and
|
|
1034
|
+
the deploy records.
|
|
1035
|
+
- `chant release list --json` in each member whose promotion order is not
|
|
1036
|
+
empty: the releases, each with its commit and the environments that run it.
|
|
1037
|
+
|
|
1038
|
+
The answer: `trunk` (or `trunkRefusal`), `commits[]` with `where` (`runs` or
|
|
1039
|
+
`waits` per environment), `environments[]` with `releases`, `deploys` (records
|
|
1040
|
+
no release covers) and `waiting` (each gate with `commitState`),
|
|
1041
|
+
`order` (`promotion`, or `env` when no member declares one), `releaseRefusals`,
|
|
1042
|
+
and the gate strip's approver fields. Gates with no environment stay in the
|
|
1043
|
+
gate strip. The three reads are `ci list` and `release list` through
|
|
1044
|
+
`readTrunk` on the reader (they are contract 1 documents outside `chant
|
|
1045
|
+
workspace`) and `status` through `read`; each has its floor in
|
|
1046
|
+
src/chant-floors.ts (0.124.28), and the route refuses a chant below any of them
|
|
1047
|
+
before spawning. The panel's Trunk tab (web/trunk-lane.js) reads it when opened
|
|
1048
|
+
and approves through `POST /api/workspace/gates/approve`.
|
|
1049
|
+
|
|
1050
|
+
## A gate's change set on the graph (#681)
|
|
1051
|
+
|
|
1052
|
+
`GET /api/workspace/change-set?gate=<member>/<op>/<gate>&env=<env>`
|
|
1053
|
+
(src/change-set-overlay.ts) reads the gate from `chant workspace status <env>
|
|
1054
|
+
--json`, never from the page, and the change set it binds (`changeSet`,
|
|
1055
|
+
chant#4022) from `chant change-set show <digest> --member <member> --json`
|
|
1056
|
+
(`readChangeSet` on the reader, floor `CHANGE_SET_SHOW_CHANT_FLOOR`,
|
|
1057
|
+
0.124.28). The answer is that document keyed by graph node: `entries` (those
|
|
1058
|
+
that change something, each with `bucket` create, change or delete and `node`,
|
|
1059
|
+
or null where chant mapped none), `nodes` (`<member>/<id>` to the strongest
|
|
1060
|
+
bucket and the actions on it), `counts`, `unchanged`, `gaps` (members that
|
|
1061
|
+
failed to plan or have holes), `gate` (commit, run, `releaseDigest`) and
|
|
1062
|
+
`planned` (a release gate's release and environment, chant#4045). An entry
|
|
1063
|
+
with no node is kept and listed in the Change set tab, never dropped. The page
|
|
1064
|
+
(web/change-set-overlay.js) outlines each card in the drift legend's tokens
|
|
1065
|
+
(managed for create, foreign for update or replace, degraded for delete or
|
|
1066
|
+
forget) with a tag above it, never a fill; it is opened from the "change set"
|
|
1067
|
+
link on a Trunk tab gate card and turned off from its tab. A public view
|
|
1068
|
+
refuses the route, as it refuses the lane.
|
|
1069
|
+
|
|
932
1070
|
## Invariant
|
|
933
1071
|
|
|
934
1072
|
If a request would have behold write to a cloud or to source directly, it's wrong.
|
package/README.md
CHANGED
|
@@ -456,8 +456,12 @@ a banner. Any other short path answers 404 with a link to `/kiosk`.
|
|
|
456
456
|
In a declared workspace, the gates waiting on a person come from
|
|
457
457
|
`chant workspace status <env> --json`, keyed `member/op/gate` the way arugula's
|
|
458
458
|
workspace block keys them, so the two show the same set. Standalone, a gate's
|
|
459
|
-
button says who chant will record
|
|
460
|
-
|
|
459
|
+
button says who chant will record before the click: the person `--as` names
|
|
460
|
+
(`--as github:<login>`), the person an authenticating proxy names in the header
|
|
461
|
+
`--identity-header` trusts, or else the user running behold. A gate the
|
|
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
|
|
464
|
+
command line otherwise (#690). Every approve route refuses in preview mode.
|
|
461
465
|
|
|
462
466
|
In a declared workspace, the inspect pane of a member's box or a card has a
|
|
463
467
|
"why" section. "Read why" asks `chant workspace graph --intent <member dir or
|