@intentius/behold 0.29.22 → 0.29.24

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intentius/behold",
3
- "version": "0.29.22",
3
+ "version": "0.29.24",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "description": "behold — a live control plane on chant. See your whole estate (every substrate in one graph), coloured by drift; act through delegated, gated Ops.",
package/web/app.js CHANGED
@@ -21,6 +21,8 @@ import { renderLane } from "./terragucci-lifecycle.js";
21
21
  import { renderReleases } from "./releases.js";
22
22
  import { renderYodelLane } from "./sql-yodeler-lane.js";
23
23
  import { initTerragucciEstate } from "./terragucci-estate.js";
24
+ import { chantComponentMarks } from "./chant-pr-marks.js";
25
+ import { noStateFill } from "./frame-fill.js";
24
26
  import { componentMarks as tgComponentMarks, runsCommit as tgRunsCommit, waveOfKey as tgWaveOfKey } from "./terragucci-components-live.js";
25
27
  import { FORGES, MARK, componentsForge, forgeOfName, iconSvg, markLink, markTitle, waveJobUrl } from "./forge-mark.js";
26
28
  import { TOOLS, orderTools } from "./tool-mark.js";
@@ -32,7 +34,7 @@ import { edgeKey, edgeLabel, edgeLegend, edgeTitle, isCiKind, viaIndex } from ".
32
34
  import { readCostLine } from "./read-cost.js";
33
35
  import { mountHistoryPicker } from "./history-picker.js";
34
36
  import { applyMemberFrame, pendingLine, stillPending } from "./pending.js";
35
- import { initTheme, setTheme, mountThemePicker, readableOn, colorForCategory, onThemeChange, getTokens, getTheme, pinTokensFor } from "./theme.js";
37
+ import { initTheme, setTheme, mountThemePicker, readableOn, inkOn, colorForCategory, onThemeChange, getTokens, getTheme, pinTokensFor } from "./theme.js";
36
38
  // #399 M2 / #401 M4 of #397: the colour-by modes' arithmetic and the
37
39
  // provenance badge's wording — every decision the behaviour overlay makes,
38
40
  // pure and unit-tested beside the file. This module owns the fetches, the SVG
@@ -203,9 +205,13 @@ function colourPlan(graphIr) {
203
205
  // #569 review: a terragucci repo's view with no drift read draws each root's
204
206
  // wave state on its box, so the cards wear the neutral ground: colour there
205
207
  // means a wave's state, never a category hue that reads as an error.
206
- if (mode === "drift" && tokens && tgStatesDrawn(graphIr)) {
208
+ // behold#571: in the kiosk's frame a card's state is its outline, bar and
209
+ // words, never its fill, so a card with no state yet (before the pull
210
+ // request's first plan, or reports that name another checkout) wears the
211
+ // same neutral ground, not a category hue that reads as an error.
212
+ if (mode === "drift" && tokens && (tgStatesDrawn(graphIr) || noStateFill({ frame: !!embedOpts.bare, live: graphIr.nodes.some((n) => n.attrs && n.attrs._status) }))) {
207
213
  const neutral = theme ? pinTokensFor(theme).neutralFill : tokens.neutral;
208
- return { mode, fillOf: () => ({ fill: neutral, unpriced: false }) };
214
+ return { mode, neutral: true, fillOf: () => ({ fill: neutral, unpriced: false }) };
209
215
  }
210
216
  if (mode === "drift" || !tokens) {
211
217
  return { mode, fillOf: (id) => ({ fill: colorForCategory(kindOf.get(id)), unpriced: false }) };
@@ -242,7 +248,8 @@ function recolorNodesByCategory(ir) {
242
248
  const kind = kindOf.get(id);
243
249
  if (!kind) continue;
244
250
  const paint = plan.fillOf(id);
245
- const cat = paint.fill, ink = readableOn(cat);
251
+ // behold#571: on the neutral card ground, the ink that reads best on it (theme.js inkOn).
252
+ const cat = paint.fill, ink = plan.neutral ? inkOn(cat) : readableOn(cat);
246
253
  // #399: an unpriced card is marked, not merely coloured — a hex cannot be
247
254
  // read back out into "the engine did not price this", and the legend's
248
255
  // unpriced count has to agree with what is on the canvas.
@@ -2531,7 +2538,10 @@ window.addEventListener("message", (e) => {
2531
2538
  const focusBefore = view.focus;
2532
2539
  const runBefore = view.run;
2533
2540
  const moved = applyWantedView(want);
2534
- if (view.run !== runBefore) void loadTgProgress({ fresh: true }); // #569: the run the narration is about
2541
+ if (view.run !== runBefore) {
2542
+ void loadTgProgress({ fresh: true }); // #569: the run the narration is about
2543
+ if (chantFacets) void loadChantPr(); // behold#631
2544
+ }
2535
2545
  else if (view.focus !== focusBefore && !moved) drawTgReads(); // #569
2536
2546
  // #477: the host's env for the gate strip moved. Read it now, not on the
2537
2547
  // next `changed`; renderStatusbar below writes it into the URL.
@@ -3495,7 +3505,8 @@ const TG_TONE = { plan: "var(--frame-pending, var(--pending))", wait: "var(--fra
3495
3505
  const TG_CARD_TONE = Object.fromEntries(Object.entries(TG_TONE).map(([k, v]) => [k, v.replace("--frame-", "--frame-card-")]));
3496
3506
  function drawTgReads() {
3497
3507
  if (embedOpts.bare) queueMicrotask(kioskDecorate); // behold#571: once this draw is done
3498
- watchTgRuns(); // #571: the wave boxes' jobs, while the components zoom is on screen
3508
+ watchTgRuns();
3509
+ watchChantPr(); // behold#631 // #571: the wave boxes' jobs, while the components zoom is on screen
3499
3510
  const svg = document.querySelector("#graph svg");
3500
3511
  if (!svg) return;
3501
3512
  drawPipelineMarks(svg); // behold#571: the forge and tool marks, before the wave boxes' status finds room around them
@@ -3519,7 +3530,9 @@ function drawTgReads() {
3519
3530
  g.removeAttribute("data-tg-dim");
3520
3531
  g.style.opacity = "";
3521
3532
  }
3522
- if (!tgAnswer || tgAnswer.error || !tgAnswer.roots) return;
3533
+ // behold#631: a chant repo's pull-request loop marks its components from chant's records, not terragucci's reports.
3534
+ const chantMode = chantPrDrawn();
3535
+ if (!chantMode && (!tgAnswer || tgAnswer.error || !tgAnswer.roots)) return;
3523
3536
  const toSvg = svg.getScreenCTM && svg.getScreenCTM();
3524
3537
  if (!toSvg) return;
3525
3538
  const inv = toSvg.inverse();
@@ -3571,6 +3584,10 @@ function drawTgReads() {
3571
3584
  if (text !== undefined) n.textContent = text;
3572
3585
  return n;
3573
3586
  };
3587
+ if (chantMode) {
3588
+ drawTgComponentMarks(svg, { marks: chantComponentMarks(chantPrAnswer, chantFacets), focus: null, boxOf, make, edgePoints: chantEdgePoints(svg) });
3589
+ return;
3590
+ }
3574
3591
  const layer = make("g", { "data-tg-reads": "1", "pointer-events": "none" });
3575
3592
  svg.appendChild(layer); // over the boxes and cards: the lines end at the borders, and the labels carry a background
3576
3593
  // A pill of text with a background, centred on (cx, cy); measured once it is in the svg.
@@ -3937,8 +3954,11 @@ function watchTgRuns() {
3937
3954
  * spot that is clear, in the words that fit, else only in the tooltip.
3938
3955
  * Returns the wave boxes, in the svg's coordinates.
3939
3956
  */
3940
- function drawTgComponentMarks(svg, { drawnAnswer, focus, boxOf, make, edgePoints }) {
3941
- const marks = tgComponentMarks(drawnAnswer, tgProgress, tgComponentFacets, { runs: tgRuns, pin: view.run || null });
3957
+ function drawTgComponentMarks(svg, { drawnAnswer, focus, boxOf, make, edgePoints, marks: given = null }) {
3958
+ const marks = given || tgComponentMarks(drawnAnswer, tgProgress, tgComponentFacets, { runs: tgRuns, pin: view.run || null });
3959
+ // behold#631: where the marks came from, said in each tooltip.
3960
+ const cardSource = marks.source || "(from terragucci's reports, not live)";
3961
+ const boxSource = marks.source || "(the job's status from the pipeline's runs; the wave's from terragucci's reports)";
3942
3962
  const group = make("g", { "data-tg-root": "components", "pointer-events": "none" });
3943
3963
  svg.appendChild(group);
3944
3964
  const grow = (b, d) => ({ x: b.x - d, y: b.y - d, x2: b.x2 + d, y2: b.y2 + d });
@@ -4000,7 +4020,7 @@ function drawTgComponentMarks(svg, { drawnAnswer, focus, boxOf, make, edgePoints
4000
4020
  const t = make("text", { "data-tg-root": "card", x, y, "font-size": 12, "font-weight": 700, fill: quiet ? "var(--frame-card-muted, var(--muted))" : TG_CARD_TONE[m.tone] || TG_CARD_TONE.idle }, words);
4001
4021
  if (m.state === "applying") t.setAttribute("class", "pin-pulse");
4002
4022
  if (!inFocus) t.style.opacity = "0.6";
4003
- t.appendChild(make("title", {}, [`wave ${m.wave} · ${m.words}`, ...m.facts].join("\n") + "\n(from terragucci's reports, not live)"));
4023
+ t.appendChild(make("title", {}, [`wave ${m.wave} · ${m.words}`, ...m.facts].join("\n") + "\n" + cardSource));
4004
4024
  g.appendChild(t);
4005
4025
  }
4006
4026
 
@@ -4048,7 +4068,7 @@ function drawTgComponentMarks(svg, { drawnAnswer, focus, boxOf, make, edgePoints
4048
4068
  }
4049
4069
  }
4050
4070
  if (title) {
4051
- const tip = make("title", { "data-tg-root": "tip" }, [w.title, ...(w.state ? [`wave ${n} ${tgStateWords[w.state] || w.state}`] : []), ...w.facts].join("\n") + "\n(the job's status from the pipeline's runs; the wave's from terragucci's reports)");
4071
+ const tip = make("title", { "data-tg-root": "tip" }, [w.title, ...(w.state ? [`wave ${n} ${tgStateWords[w.state] || w.state}`] : []), ...w.facts].join("\n") + "\n" + boxSource);
4052
4072
  title.appendChild(tip);
4053
4073
  }
4054
4074
  // The wave's first fact (a waiting wave's plan digest) in the box's bottom padding, where it fits.
@@ -4833,11 +4853,40 @@ let ciForge = null; // the forge the pipeline was generated for (#164) — heads
4833
4853
  let terragucciComponentsRepo = false;
4834
4854
  // #571: the components graph's facets (jobs, component -> root), for the live marks drawTgReads puts on it.
4835
4855
  let tgComponentFacets = null;
4856
+ // behold#631: a chant repo's pull-request loop: the graph's `meta.chantPr` and /api/chant/pr's answer at the view's run pin.
4857
+ let chantFacets = null;
4858
+ let chantPrAnswer = null;
4859
+ let chantPrTimer = null;
4860
+ function chantPrDrawn() {
4861
+ return !!(view.components && chantFacets && !terragucciComponentsRepo && chantPrAnswer && !chantPrAnswer.error && chantPrAnswer.loop);
4862
+ }
4863
+ async function loadChantPr() {
4864
+ const pin = view.run || "";
4865
+ const was = JSON.stringify(chantPrAnswer);
4866
+ const answer = await apiFetch(`/api/chant/pr${pin ? `?pin=${encodeURIComponent(pin)}` : ""}`)
4867
+ .then((r) => (r.ok ? r.json() : null))
4868
+ .catch(() => null);
4869
+ if ((view.run || "") !== pin) return; // the pin moved while this read ran
4870
+ chantPrAnswer = answer;
4871
+ if (JSON.stringify(answer) !== was) drawTgReads();
4872
+ }
4873
+ /** Read the loop every few seconds while a chant repo's components view is on screen. */
4874
+ function watchChantPr() {
4875
+ const on = !staticMode && !!(view.components && chantFacets && !terragucciComponentsRepo);
4876
+ if (on && !chantPrTimer) {
4877
+ void loadChantPr();
4878
+ chantPrTimer = setInterval(() => void loadChantPr(), 3_000);
4879
+ } else if (!on && chantPrTimer) {
4880
+ clearInterval(chantPrTimer);
4881
+ chantPrTimer = null;
4882
+ }
4883
+ }
4836
4884
 
4837
4885
  /** #571: the CI and resources facets from a terragucci repo's components
4838
4886
  * graph: component -> its declared job ({jobName, needs, wave, alsoIn}), and
4839
4887
  * component -> the resources its root holds. */
4840
4888
  function takeTerragucciFacets(m) {
4889
+ chantFacets = (m && m.chantPr) || null; // behold#631
4841
4890
  const tg = m && m.terragucciComponents;
4842
4891
  tgComponentFacets = tg || null;
4843
4892
  if (!tg) return;
@@ -5491,6 +5540,8 @@ function pipelineMarksFor(n) {
5491
5540
  const carried = roots.flatMap((r) => (tgComponentFacets.rootTools && tgComponentFacets.rootTools[r]) || []);
5492
5541
  return { forge: componentsForge(tgComponentFacets, tgAnswer), job: jobs[0] ? jobs[0].jobName : null, tools: orderTools([...(tgComponentFacets.tools || []), ...carried]) };
5493
5542
  }
5543
+ // behold#631: a chant repo's pull-request loop: its forge and chant, with the engine its roots run.
5544
+ if (chantFacets) return { forge: forgeOfName(chantFacets.forge), job: chantFacets.workflow, tools: orderTools(chantFacets.tools || []), loop: true };
5494
5545
  if (ciByComponent.size) return { forge: forgeOfName(ciForge), job: null, tools: [], projection: true };
5495
5546
  return null;
5496
5547
  }
@@ -0,0 +1,178 @@
1
+ // behold#631: the marks on a chant project's components view, for a repo
2
+ // whose CI runs chant's pull-request loop (`chant components pr-plan` on a
3
+ // pull request, `pr-apply` on its merge). What /api/chant/pr read (chant's
4
+ // pr-report, or the summary each stage prints in its run's log, and the
5
+ // gate's ledger) as the same marks a terragucci repo's components carry
6
+ // (web/terragucci-components-live.js), so app.js draws both one way:
7
+ //
8
+ // - `cards[component]`: its wave and state (planned, applied, unchanged,
9
+ // failed, refused), the words on the card and the facts in its tooltip;
10
+ // - `waves[n]`: the wave's state (waiting while the gate waits on the plan's
11
+ // digest), the run's job status while it runs, and the facts on its box.
12
+ //
13
+ // Only what chant recorded: while pr-apply runs, chant has printed nothing
14
+ // per wave or component yet (chant#4007), so the boxes say the job runs and
15
+ // the cards keep the plan they apply.
16
+
17
+ /** The issue that asks chant for progress per wave and component, and a report a reader can fetch. */
18
+ export const PROGRESS_ISSUE = "chant#4007";
19
+
20
+ /** A card's state in one or two words, when the full words don't fit. */
21
+ export const CHANT_SHORT = { planned: "planned", applied: "applied", unchanged: "unchanged", failed: "failed", refused: "refused", "not-started": "held back" };
22
+
23
+ const TONE = { planned: "plan", waiting: "wait", applying: "busy", applied: "ok", failed: "bad", refused: "bad" };
24
+ const toneOf = (state) => TONE[state] || "idle";
25
+
26
+ /** A plan's changes as Terraform sums them up, "+1 ~2 -1" (create, update, delete; a replace is both), or null for none. */
27
+ export function countWords(counts) {
28
+ if (!counts) return null;
29
+ const add = (counts.create || 0) + (counts.replace || 0);
30
+ const del = (counts.delete || 0) + (counts.replace || 0);
31
+ const parts = [];
32
+ if (add) parts.push(`+${add}`);
33
+ if (counts.update) parts.push(`~${counts.update}`);
34
+ if (del) parts.push(`-${del}`);
35
+ return parts.length ? parts.join(" ") : null;
36
+ }
37
+
38
+ /** The same in words, for a tooltip: "1 to create, 2 to update". */
39
+ export function countSentence(counts) {
40
+ if (!counts) return null;
41
+ const parts = [];
42
+ if (counts.create) parts.push(`${counts.create} to create`);
43
+ if (counts.update) parts.push(`${counts.update} to update`);
44
+ if (counts.replace) parts.push(`${counts.replace} to replace`);
45
+ if (counts.delete) parts.push(`${counts.delete} to delete`);
46
+ return parts.length ? parts.join(", ") : null;
47
+ }
48
+
49
+ /** A digest's hex part, without its `jcs1-sha256:` scheme. */
50
+ export const hexOf = (d) => (typeof d === "string" ? d.slice(d.lastIndexOf(":") + 1) : "");
51
+ /** A digest as a viewer reads it: its first 8 hex digits. */
52
+ export const short8 = (d) => hexOf(d).slice(0, 8);
53
+
54
+ /** The stage the marks follow: the apply once it reported, else the plan. */
55
+ const stageOf = (a) => (a && a.apply ? a.apply : a && a.plan ? a.plan : null);
56
+
57
+ /** A member's state in a stage. */
58
+ function memberState(m, stage) {
59
+ if (!m) return "unchanged";
60
+ if (m.status === "applied") return "applied";
61
+ if (m.status === "failed" || m.status === "plan-failed") return "failed";
62
+ if (m.status === "blocked") return "not-started";
63
+ if (stage.stage === "apply" && stage.status === "refused") return "refused";
64
+ return "planned";
65
+ }
66
+
67
+ /** The words on a card for its state. */
68
+ function cardWords(state, m, gate) {
69
+ if (state === "unchanged") return "unchanged";
70
+ if (state === "failed") return m && m.status === "plan-failed" ? "plan failed" : "apply failed";
71
+ if (state === "not-started") return "held back by an earlier wave";
72
+ if (state === "refused") return gate && gate.refusal ? `refused (${gate.refusal})` : "refused";
73
+ const c = countWords(m && m.counts);
74
+ if (state === "applied") return c ? `applied ${c}` : "applied";
75
+ return c ? `planned ${c}` : "planned, no changes";
76
+ }
77
+
78
+ /**
79
+ * The marks for /api/chant/pr's answer and the components graph's
80
+ * `meta.chantPr` facets. Empty (no cards, no waves) before the pull
81
+ * request's first plan: a card with no state draws as the view's neutral.
82
+ */
83
+ export function chantComponentMarks(answer, facets) {
84
+ const cards = {};
85
+ const waves = {};
86
+ const empty = { stage: null, cards, waves, source: null };
87
+ if (!answer || answer.error || !facets || !facets.waves) return empty;
88
+ const stage = stageOf(answer);
89
+ const gate = answer.gate || null;
90
+ const running = answer.running || null;
91
+ const componentOf = (m) => m.component || (facets.members && facets.members[m.member]) || m.member;
92
+ const waveNumbers = [...new Set(Object.values(facets.waves))].filter(Number.isInteger).sort((a, b) => a - b);
93
+ if (!stage && !running) return empty;
94
+
95
+ const facts = (state, m) => {
96
+ const out = [];
97
+ if (m && countSentence(m.counts)) out.push(countSentence(m.counts));
98
+ if (stage && stage.digest) out.push(`plan ${short8(stage.digest)}`);
99
+ if (m && m.error) out.push(m.error);
100
+ if (m && m.inputsMoved && m.inputsMoved.length) out.push(`inputs from ${m.inputsMoved.join(", ")} moved; the next run plans it again`);
101
+ if (state === "planned" && running && running.stage === "apply") out.push(`per-component progress: ${PROGRESS_ISSUE}`);
102
+ return out;
103
+ };
104
+ if (stage) {
105
+ for (const [c, n] of Object.entries(facets.waves)) {
106
+ const m = stage.members.find((x) => componentOf(x) === c) || null;
107
+ const state = memberState(m, stage);
108
+ cards[c] = { root: c, wave: n, state, tone: toneOf(state), words: cardWords(state, m, gate), short: CHANT_SHORT[state] || state, facts: facts(state, m) };
109
+ }
110
+ }
111
+ for (const n of waveNumbers) {
112
+ const members = Object.entries(facets.waves).filter(([, w]) => w === n).map(([c]) => cards[c]).filter(Boolean);
113
+ const touched = members.filter((m) => m.state !== "unchanged");
114
+ let state = null;
115
+ if (touched.length) {
116
+ if (touched.some((m) => m.state === "failed")) state = "failed";
117
+ else if (touched.some((m) => m.state === "refused")) state = "refused";
118
+ else if (touched.every((m) => m.state === "applied")) state = "applied";
119
+ else if (touched.some((m) => m.state === "not-started")) state = "not-started";
120
+ else state = gate && gate.state === "waiting" && !answer.apply ? "waiting" : "planned";
121
+ }
122
+ const status = running ? { status: running.status, words: `${running.job} ${running.status}`, tone: running.status === "running" ? "busy" : "idle", run: running.run } : null;
123
+ const f = [];
124
+ if (state === "waiting" && gate && gate.digest) f.push(`approve plan ${hexOf(gate.digest)}`);
125
+ else if (state === "planned" && gate && gate.state === "approved") f.push(gate.by ? `approved by ${gate.by.replace(/^.*:/, "")}` : "approved");
126
+ if (state === "applied" && stage && stage.digest) f.push(`applied plan ${short8(stage.digest)}`);
127
+ // While pr-apply runs, chant has said nothing per wave yet: that first, with the issue that asks for it.
128
+ if (running && running.stage === "apply" && touched.length && state !== "applied") f.unshift(`per-wave progress: ${PROGRESS_ISSUE}`);
129
+ waves[n] = { number: n, job: running ? running.job : null, state, tone: state ? toneOf(state) : status ? status.tone : "idle", status, title: status ? `wave-${n} · ${status.words}` : `wave-${n}`, facts: f };
130
+ }
131
+ return { stage: stage ? stage.stage : null, cards, waves, source: sourceWords(answer) };
132
+ }
133
+
134
+ /** Where the marks came from, for each tooltip. */
135
+ export function sourceWords(answer) {
136
+ const from = (s) => (s.from === "report" ? `chant's pr-${s.stage} report` : `chant pr-${s.stage}'s summary in run #${s.run}`);
137
+ const parts = [answer.plan, answer.apply].filter(Boolean).map(from);
138
+ if (answer.gate && answer.gate.from === "ledger") parts.push("the gate's ledger");
139
+ return parts.length ? `(from ${parts.join(", ")})` : null;
140
+ }
141
+
142
+ /** The steps chant's gate shows its panel on: the plan waits, it is approved, the merge applied it. */
143
+ export const CHANT_PANEL_STEPS = ["waiting", "approved", "merged", "applying", "applied"];
144
+
145
+ /**
146
+ * "How this hold ends" for chant's gate: one gate per pull request (op
147
+ * `pr-<n>`, gate `pr-apply`) on the plan's digest, approved before the
148
+ * merge. Three rows, each lit from a record: the plan asked for it (the
149
+ * approve line pr-plan printed), the ledger's approval of that digest, and
150
+ * pr-apply applying under it. Null when the answer has no gate.
151
+ */
152
+ export function chantApprovalModel({ demo, answer, sealCheck = null }) {
153
+ if (!demo || !CHANT_PANEL_STEPS.includes(demo.step) || !answer || !answer.gate || !answer.plan) return null;
154
+ const g = answer.gate;
155
+ const plan = answer.plan;
156
+ const apply = answer.apply;
157
+ const rows = [];
158
+ rows.push({ id: "requested", label: "Requested", state: "lit", text: `Pull request #${answer.pull} asks a reviewer to approve its plan.`, runId: plan.run || null, ...(g.approveCommand && g.state === "waiting" ? { command: g.approveCommand } : {}) });
159
+ if (g.state === "approved") {
160
+ const signed = g.seal === "sealed";
161
+ rows.push({
162
+ id: "approved",
163
+ label: "Approved",
164
+ state: "lit",
165
+ text: `${g.by || "A reviewer"} approved this exact digest.`,
166
+ seal: signed ? (sealCheck && sealCheck.ok ? { ok: true, text: "signed; matches the repo's allowed signers" } : { ok: null, text: "signed" }) : { ok: null, text: g.from === "ledger" ? "not signed" : "from the report" },
167
+ at: g.at || null,
168
+ commit: g.ledgerCommit || null,
169
+ });
170
+ } else if (g.state === "changed" || g.state === "refused") {
171
+ rows.push({ id: "approved", label: "Approved", state: "dim", text: g.state === "changed" ? "The plan moved after review and needs a fresh approval." : `The apply refused (${g.refusal || "no approval"}).` });
172
+ } else rows.push({ id: "approved", label: "Approved", state: "dim", text: "Next, a reviewer approves the digest." });
173
+ if (apply && apply.status === "applied") rows.push({ id: "spent", label: "Applied", state: "lit", text: "The merge planned again and applied this digest.", runId: apply.run || null });
174
+ else if (answer.running && answer.running.stage === "apply") rows.push({ id: "spent", label: "Applied", state: "going", text: "chant is applying this digest on merge now.", runId: answer.running.run });
175
+ else rows.push({ id: "spent", label: "Applied", state: "dim", text: "On merge, chant applies the plan when it matches." });
176
+ const run = apply ? apply.run : answer.running ? answer.running.run : plan.run;
177
+ return { wave: null, digest: g.digest, run: run || null, rows };
178
+ }
@@ -0,0 +1,90 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { chantApprovalModel, chantComponentMarks, countWords } from "./chant-pr-marks.js";
3
+
4
+ // behold#631: the marks on a chant repo's components view, from /api/chant/pr's
5
+ // answer, shaped as it answered for cycle 767 of terragucci's demo (scenario
6
+ // chant-pr-loop: network, app and edge, one wave each, pull request 13).
7
+ const DIGEST = "jcs1-sha256:909bbc5e4f02021bdff9d852c8253f215383a2489eee464ace2adb0fda138553";
8
+ const facets = { forge: "forgejo", workflow: ".forgejo/workflows/chant-pr.yml", env: "demo", gate: "pr-apply", tools: ["chant", "opentofu"], waves: { network: 1, app: 2, edge: 3, cache: 3 }, members: { network: "network", app: "app", edge: "edge", cache: "cache" } };
9
+ const member = (name, status) => ({ member: name, status, counts: { create: 1, update: 0, replace: 0, delete: 0 } });
10
+ const plan = { stage: "plan", from: "log", source: "run #3843", run: 3843, pr: 13, status: "planned", digest: DIGEST, op: "pr-13", gate: "pr-apply", members: ["app", "edge", "network"].map((m) => member(m, "planned")) };
11
+ const loop = { forge: "forgejo", workflow: facets.workflow, env: "demo", gate: "pr-apply", output: ".chant/pr", stages: ["plan", "apply"] };
12
+ const waiting = { op: "pr-13", gate: "pr-apply", digest: DIGEST, state: "waiting", from: "log", approveCommand: `chant approve pr-13 pr-apply --plan ${DIGEST} --approver <you> --sign` };
13
+ const approved = { op: "pr-13", gate: "pr-apply", digest: DIGEST, state: "approved", by: "forgejo@forgejo:3000:demo-reviewer", at: "2026-10-16T08:15:25.591Z", seal: "sealed", ledgerCommit: "10a36285", from: "ledger" };
14
+ const answer = (over) => ({ schema: "behold.chant-pr/v1", loop, pull: 13, plan: null, apply: null, running: null, gate: null, reads: [], gaps: [], ...over });
15
+
16
+ describe("a chant repo's components, marked from its pull-request loop (behold#631)", () => {
17
+ it("before the first plan: no card and no wave has a state", () => {
18
+ const m = chantComponentMarks(answer({}), facets);
19
+ expect(m.cards).toEqual({});
20
+ expect(m.waves).toEqual({});
21
+ });
22
+
23
+ it("planned: each component planned with its changes, a component the change missed unchanged, each wave waiting on the digest", () => {
24
+ const m = chantComponentMarks(answer({ plan, gate: waiting }), facets);
25
+ expect(m.cards.app).toMatchObject({ wave: 2, state: "planned", tone: "plan", words: "planned +1" });
26
+ expect(m.cards.app.facts).toEqual(["1 to create", "plan 909bbc5e"]);
27
+ expect(m.cards.cache).toMatchObject({ state: "unchanged", tone: "idle" });
28
+ expect(m.waves[1]).toMatchObject({ state: "waiting", tone: "wait", status: null, facts: [`approve plan ${DIGEST.slice(12)}`] });
29
+ expect(m.waves[3].state).toBe("waiting");
30
+ expect(m.source).toBe("(from chant pr-plan's summary in run #3843)");
31
+ });
32
+
33
+ it("approved: the waves planned, and who approved", () => {
34
+ const m = chantComponentMarks(answer({ plan, gate: approved }), facets);
35
+ expect(m.waves[2]).toMatchObject({ state: "planned", facts: ["approved by demo-reviewer"] });
36
+ expect(m.source).toMatch(/the gate's ledger/);
37
+ });
38
+
39
+ it("while the merge's apply runs: the job on each box and the plan on each card, with the issue that asks for progress", () => {
40
+ const m = chantComponentMarks(answer({ plan, gate: approved, running: { stage: "apply", run: 3844, job: "apply", status: "running", started_at: null } }), facets);
41
+ expect(m.cards.network.state).toBe("planned");
42
+ expect(m.cards.network.facts).toContain("per-component progress: chant#4007");
43
+ expect(m.waves[1]).toMatchObject({ state: "planned", status: { status: "running", words: "apply running", tone: "busy", run: 3844 }, title: "wave-1 · apply running" });
44
+ expect(m.waves[1].facts[0]).toBe("per-wave progress: chant#4007");
45
+ });
46
+
47
+ it("applied: each component and wave applied", () => {
48
+ const apply = { ...plan, stage: "apply", source: "run #3844", run: 3844, status: "applied", members: plan.members.map((x) => ({ ...x, status: "applied" })) };
49
+ const m = chantComponentMarks(answer({ plan, apply, gate: approved }), facets);
50
+ expect(m.cards.edge).toMatchObject({ state: "applied", tone: "ok", words: "applied +1" });
51
+ expect(m.waves[3]).toMatchObject({ state: "applied", tone: "ok", facts: ["applied plan 909bbc5e"] });
52
+ expect(m.cards.cache.state).toBe("unchanged");
53
+ });
54
+
55
+ it("a failed wave fails, and the waves after it are held back", () => {
56
+ const apply = { ...plan, stage: "apply", run: 3844, status: "failed", members: [member("network", "applied"), { ...member("app", "failed"), error: "exit 1" }, member("edge", "blocked")] };
57
+ const m = chantComponentMarks(answer({ plan, apply, gate: approved }), facets);
58
+ expect(m.waves[1].state).toBe("applied");
59
+ expect(m.cards.app).toMatchObject({ state: "failed", tone: "bad", words: "apply failed" });
60
+ expect(m.cards.app.facts).toContain("exit 1");
61
+ expect(m.cards.edge).toMatchObject({ state: "not-started", short: "held back" });
62
+ });
63
+
64
+ it("sums a plan's changes as Terraform does", () => {
65
+ expect(countWords({ create: 2, update: 1, replace: 1, delete: 0 })).toBe("+3 ~1 -1");
66
+ expect(countWords({ create: 0, update: 0, replace: 0, delete: 0 })).toBeNull();
67
+ });
68
+ });
69
+
70
+ describe("how chant's gate ends, the hold panel (behold#631)", () => {
71
+ const demo = (step) => ({ step, pull: 13 });
72
+ it("waiting: requested with the approve line, then the approval and the apply to come", () => {
73
+ const m = chantApprovalModel({ demo: demo("waiting"), answer: answer({ plan, gate: waiting }) });
74
+ expect(m).toMatchObject({ wave: null, digest: DIGEST, run: 3843 });
75
+ expect(m.rows.map((r) => [r.id, r.state])).toEqual([["requested", "lit"], ["approved", "dim"], ["spent", "dim"]]);
76
+ expect(m.rows[0].command).toBe(waiting.approveCommand);
77
+ });
78
+ it("applied: each row lit from its record, the ledger's approval with its seal and commit", () => {
79
+ const apply = { ...plan, stage: "apply", run: 3844, status: "applied" };
80
+ const m = chantApprovalModel({ demo: demo("applied"), answer: answer({ plan, apply, gate: approved }) });
81
+ expect(m.rows.map((r) => r.state)).toEqual(["lit", "lit", "lit"]);
82
+ expect(m.rows[1]).toMatchObject({ text: "forgejo@forgejo:3000:demo-reviewer approved this exact digest.", at: approved.at, commit: "10a36285", seal: { text: "signed" } });
83
+ expect(m.rows[0].command).toBeUndefined();
84
+ expect(m.run).toBe(3844);
85
+ });
86
+ it("shows on no step before the plan waits, and for no answer", () => {
87
+ expect(chantApprovalModel({ demo: demo("planned"), answer: answer({ plan, gate: waiting }) })).toBeNull();
88
+ expect(chantApprovalModel({ demo: demo("waiting"), answer: null })).toBeNull();
89
+ });
90
+ });
@@ -0,0 +1,16 @@
1
+ // behold#571: the kiosk frame's card fill. In the frame a card's state is its
2
+ // outline, its bar and its words (web/app.js drawTgReads), never its fill, so
3
+ // every card there wears the theme's neutral card ground (pinTokensFor's
4
+ // `neutralFill`, the ground frameInks makes each state's words readable on).
5
+ // That holds for a card with no state yet, too: before a pull request's first
6
+ // plan, or when the reports name another checkout. Left to the category
7
+ // palette, such a card took the theme's hue for its kind, which in Sea Shells
8
+ // and others is a crimson that reads as "broken".
9
+ //
10
+ // Outside the frame, and on a graph that carries a live read (`_status`),
11
+ // the fill stays the category hue it always was.
12
+
13
+ /** Whether the cards take the neutral fill: in the kiosk's frame, on a graph with no live read. */
14
+ export function noStateFill({ frame = false, live = false } = {}) {
15
+ return !!frame && !live;
16
+ }
@@ -0,0 +1,34 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { noStateFill } from "./frame-fill.js";
3
+ import { contrast, frameInks, inkOn, pinTokensFor, tokensFor } from "./theme.js";
4
+ import { THEMES } from "./themes.js";
5
+
6
+ // behold#571: a card in the kiosk's frame with no state yet wears the neutral
7
+ // card ground, never its category hue (crimson in Sea Shells, which read as
8
+ // "broken"), and stays readable on it in every theme.
9
+ describe("the kiosk frame's card fill (behold#571)", () => {
10
+ it("is the neutral ground in the frame, on a graph with no live read", () => {
11
+ expect(noStateFill({ frame: true })).toBe(true);
12
+ expect(noStateFill({ frame: true, live: true })).toBe(false);
13
+ expect(noStateFill({ frame: false })).toBe(false);
14
+ });
15
+
16
+ it("was Sea Shells' crimson before, and is its neutral card ground now", () => {
17
+ const th = THEMES["Sea Shells"];
18
+ const fill = pinTokensFor(th).neutralFill;
19
+ expect(fill).not.toBe(tokensFor(th).degraded);
20
+ expect(contrast(fill, "#b8304a")).toBeGreaterThan(1.5);
21
+ });
22
+
23
+ it("keeps a card's name and every state's words readable on it, in every theme (frameInks)", () => {
24
+ const short = [];
25
+ for (const th of Object.values(THEMES)) {
26
+ const fill = pinTokensFor(th).neutralFill;
27
+ const name = inkOn(fill);
28
+ if (contrast(name, fill) < 4.5) short.push(`${th.name} name ${name} on ${fill}: ${contrast(name, fill).toFixed(2)}`);
29
+ const inks = frameInks(th).card;
30
+ for (const [s, c] of Object.entries(inks)) if (contrast(c, fill) < 4.5) short.push(`${th.name} ${s} ${c} on ${fill}`);
31
+ }
32
+ expect(short).toEqual([]);
33
+ });
34
+ });
package/web/kiosk-repo.js CHANGED
@@ -4,8 +4,8 @@
4
4
  // and asks for that checkout by name with `?repo=`; the server answers from
5
5
  // it, or refuses a name it doesn't serve.
6
6
 
7
- /** The reads that depend on the served checkout: the project, the reports' marks, the run view, and (behold#571's approval panel) the gate ledger read from its chant/lifecycle. */
8
- const REPO_READS = new Set(["/api/project", "/api/terragucci", "/api/terragucci/progress", "/api/terragucci/lifecycle", "/api/lifecycle/history"]);
7
+ /** The reads that depend on the served checkout: the project, the reports' marks, the run view, (behold#571's approval panel) the gate ledger read from its chant/lifecycle, and (behold#631) a chant repo's pull-request loop. */
8
+ const REPO_READS = new Set(["/api/project", "/api/terragucci", "/api/terragucci/progress", "/api/terragucci/lifecycle", "/api/lifecycle/history", "/api/chant/pr"]);
9
9
 
10
10
  /** The checkout name for `repo` ("<owner>/<name>") when the server serves it; null otherwise. */
11
11
  export function repoParam(repo, served) {
@@ -20,6 +20,8 @@ describe("repoUrl", () => {
20
20
  expect(repoUrl("/api/terragucci/progress?commit=abc", "demo")).toBe("/api/terragucci/progress?commit=abc&repo=demo");
21
21
  expect(repoUrl("/api/terragucci/lifecycle", "demo")).toBe("/api/terragucci/lifecycle?repo=demo");
22
22
  expect(repoUrl("/api/lifecycle/history?limit=200", "demo")).toBe("/api/lifecycle/history?limit=200&repo=demo");
23
+ // behold#631: the hold panel's read of a chant repo's gate is that repo's, not the default checkout's.
24
+ expect(repoUrl("/api/chant/pr?pin=a157c47f", "demo-chant")).toBe("/api/chant/pr?pin=a157c47f&repo=demo-chant");
23
25
  expect(repoUrl("/api/terragucci/demo", "demo")).toBe("/api/terragucci/demo");
24
26
  expect(repoUrl("/api/terragucci/runs/4", "demo")).toBe("/api/terragucci/runs/4");
25
27
  expect(repoUrl("/api/project", null)).toBe("/api/project");
package/web/kiosk.js CHANGED
@@ -13,6 +13,7 @@
13
13
  // A wave that failed says which waves applied before it and stay applied.
14
14
  // Nothing here is all-or-nothing, and nothing says so.
15
15
 
16
+ import { CHANT_PANEL_STEPS, chantApprovalModel } from "./chant-pr-marks.js";
16
17
  import { PICK_HOLD_MS, annMark, mergeRun, startRuns } from "./kiosk-runs.js";
17
18
  import { PANEL_STEPS, PANEL_TITLE, approvalModel, cycleRuns, digestHex, rowFacts } from "./kiosk-approval.js";
18
19
  import { getThemeName, mountThemePicker, onThemeChange } from "./theme.js";
@@ -1136,7 +1137,7 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1136
1137
  const ap = { runs: new Map(), list: [], lifecycle: null, history: null, at: 0, ledgerAt: 0, busy: false };
1137
1138
  const readApproval = async () => {
1138
1139
  const d = s.demo && s.demo.demo;
1139
- if (!d || !PANEL_STEPS.includes(d.step) || ap.busy) return;
1140
+ if (!d || !(PANEL_STEPS.includes(d.step) || (s.chantLoop && CHANT_PANEL_STEPS.includes(d.step))) || ap.busy) return;
1140
1141
  const t = now().getTime();
1141
1142
  if (t - ap.at < APPROVAL_POLL_MS) return;
1142
1143
  ap.busy = true;
@@ -1160,6 +1161,12 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1160
1161
  ap.lifecycle = lifecycle && !lifecycle.error ? lifecycle : null;
1161
1162
  ap.history = history && !history.error ? history : null;
1162
1163
  }
1164
+ // behold#631: a chant repo's pull-request gate, from chant's records at the step's run.
1165
+ if (s.chantLoop) {
1166
+ const pin = runPin(d);
1167
+ const a = await fetchJson(`/api/chant/pr${pin ? `?pin=${encodeURIComponent(pin)}` : ""}`);
1168
+ ap.chant = a && !a.error && a.loop ? a : null;
1169
+ }
1163
1170
  } finally {
1164
1171
  ap.busy = false;
1165
1172
  }
@@ -1167,6 +1174,9 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1167
1174
  };
1168
1175
  const approvalNow = () => {
1169
1176
  const d = s.demo && s.demo.demo;
1177
+ // behold#631: chant's gate, one per pull request on the plan's digest, when the repo runs chant's loop.
1178
+ const chant = s.chantLoop && ap.chant ? chantApprovalModel({ demo: d, answer: ap.chant }) : null;
1179
+ if (chant) return chant;
1170
1180
  if (!d || !PANEL_STEPS.includes(d.step)) return null;
1171
1181
  const appr = pendingApproval(d, s.progress);
1172
1182
  const driver = appr && s.mode !== "replay" ? { gloss: DRIVER_SIGNS, approve: appr.approve, comment: appr.comment, on: appr.on } : null;
@@ -1274,6 +1284,8 @@ export function startKiosk({ bar, frame, side, main, views, read = null, tools =
1274
1284
  }
1275
1285
  // A chant project's graph is its components (web/app.js bootZoom), so it has that view too.
1276
1286
  s.components = !!(p && !p.error && (p.terragucciComponents || chantProject(p)));
1287
+ // behold#631: a chant project may run chant's pull-request loop; /api/chant/pr says (its `loop`).
1288
+ s.chantLoop = !!(p && !p.error && !p.terragucciComponents && chantProject(p));
1277
1289
  // behold#571: the declared roots (their colours' order) and the wave jobs that apply them.
1278
1290
  if (p && p.terragucciRoots) {
1279
1291
  s.roots = Array.isArray(p.terragucciRoots.roots) ? p.terragucciRoots.roots : [];
package/web/theme.js CHANGED
@@ -44,6 +44,10 @@ export function contrast(a, b) {
44
44
  const A = relLuminance(a), B = relLuminance(b);
45
45
  return (Math.max(A, B) + 0.05) / (Math.min(A, B) + 0.05);
46
46
  }
47
+ // behold#571: white or black, whichever reads better on `bg` by the real ratio
48
+ // above. readableOn's quick coin-flip picks white on a mid-tone ground where
49
+ // black reads better (Grass's and Blue Dolphin's neutral card).
50
+ export function inkOn(bg) { return contrast("#ffffff", bg) >= contrast("#000000", bg) ? "#ffffff" : "#000000"; }
47
51
  export function hexToOklch(hex) {
48
52
  const [R, G, B] = hexToRgb(hex).map(s2l);
49
53
  const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B);