@intentius/behold 0.29.9 → 0.29.11

package/dist/cli.js

@@ -21775,6 +21775,7 @@ function watchSource(projectDir, onChange, debounceMs = 200) {
     clearTimeout(timer);
     timer = setTimeout(onChange, debounceMs);
   });
+  watcher.on("error", (e) => console.warn(`behold: watching ${dir}: ${e.message}`));
   return () => {
     clearTimeout(timer);
     watcher.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/behold",
-  "version": "0.29.9",
+  "version": "0.29.11",
   "license": "Apache-2.0",
   "type": "module",
   "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/kiosk-annotations.js

@@ -123,7 +123,7 @@ export const ANNOTATIONS = [
   {
     id: "T12", product: "chant", feature: "Waiting for approval",
     pattern: String.raw`^Nothing in wave \d+ or after it ran\. (?:Read the plans, then|It waits on .+\.) approve: (chant approve \S+ \S+ --plan \S+) \(with --resume, the approval also starts this job again\)$`,
-    note: "The job ended without applying this wave or any later one; the printed chant approve command records the approval and can restart the job.",
+    note: "The job ends at this wave; the printed chant approve command records the approval and can restart the job.",
     docs: { product: "chant", path: "/guide/op-waves/#resume-the-waiting-job" },
     source: "chant:packages/core/src/op/op-waves-run.ts:1587",
     sample: "Nothing in wave 2 or after it ran. Read the plans, then approve: chant approve tf-apply wave-2 --plan jcs1-sha256:95b79f4946fffd67b2d3da8971084852c4182623d8223b4a307f7067375fe37a (with --resume, the approval also starts this job again)",
@@ -163,7 +163,7 @@ export const ANNOTATIONS = [
   {
     id: "T17", product: "terragucci", feature: "Changed after approval",
     pattern: String.raw`^wave \d+ changed after it was approved, so nothing in it was applied\. approved: (\S+); planned now: (\S+)\. `,
-    note: "The wave planned to a different digest than the one approved, so nothing applied; the new plan needs its own approval.",
+    note: "The wave planned to a different digest than the one approved; the new plan needs its own approval.",
     docs: { product: "terragucci", path: "/guides/fix-a-refused-wave/" },
     source: "terragucci:packages/terragucci/src/apply.ts:2983",
     sample: "wave 1 changed after it was approved, so nothing in it was applied. approved: jcs1-sha256:c7d57fcf0bf559242e2104f4d0ed562888f6bd99ed8c5af350db462771169877; planned now: jcs1-sha256:0be8353d2143e463577e05eca00b62cabd51791aaa383051930e384340812052. Read the new plan, then approve it: terragucci approve wave-1 --plan jcs1-sha256:0be8353d2143e463577e05eca00b62cabd51791aaa383051930e384340812052",
@@ -171,7 +171,7 @@ export const ANNOTATIONS = [
   {
     id: "T18", product: "terragucci", feature: "Changed after approval",
     pattern: String.raw`^wave \d+ of \d+: approved by (\S+), but these roots planned differently since: (.+)$`,
-    note: "Names the roots whose plans differ from the approved ones, which is why the approval no longer covers the wave.",
+    note: "Names the roots whose plans differ from the approved ones, so the wave needs a new approval.",
     docs: { product: "terragucci", path: "/tutorial/changed-wave/" },
     source: "terragucci:packages/terragucci/src/apply.ts:2984",
     sample: "wave 1 of 3: approved by terragucci-admin, but these roots planned differently since: network",
@@ -187,7 +187,7 @@ export const ANNOTATIONS = [
   {
     id: "T20", product: "terragucci", feature: "Unreviewed outputs",
     pattern: String.raw`^wave \d+ of \d+: nobody reviewed the plan it made on those outputs, so it waits for an approval of it(?: although gate is \S+)?$`,
-    note: "This wave planned on outputs nobody could see in review, so it waits for an approval even when its gate would let it through.",
+    note: "This wave planned on outputs that got their values during the apply, so a person approves it even when its gate would let it through.",
     docs: { product: "terragucci", path: "/concepts/waves-and-approvals/#linked-roots" },
     source: "terragucci:packages/terragucci/src/apply.ts:2562",
     sample: "wave 1 of 3: nobody reviewed the plan it made on those outputs, so it waits for an approval of it although gate is on-destructive",
@@ -203,7 +203,7 @@ export const ANNOTATIONS = [
   {
     id: "T22", product: "terragucci", feature: "Unreviewed outputs",
     pattern: String.raw`^wave \d+ of \d+: (\S+) reads? no output of (\S+) that (.+) left unknown$`,
-    note: "Every output this root reads was already known when it was planned, so its plan holds no values nobody reviewed.",
+    note: "Every output this root reads was known when it was planned, so its plan holds only reviewed values.",
     docs: { product: "terragucci", path: "/concepts/waves-and-approvals/#linked-roots" },
     source: "terragucci:packages/terragucci/src/unknown-reads.ts:142",
     sample: "wave 2 of 3: app reads no output of network that wave 1's plan of network in this push (2026/10/e8863ee426177316d84499a5b8401c4b6adfb546/tf-apply-wave-1) left unknown",
@@ -235,7 +235,7 @@ export const ANNOTATIONS = [
   {
     id: "T26", product: "terragucci", feature: "Unreviewed outputs",
     pattern: String.raw`^wave \d+ of \d+: (\S+) reads (.+), unknown at plan time and computed in this apply$`,
-    note: "Inside a composed run this root reads a value that only gets computed during the apply, so nobody saw it in the plan.",
+    note: "Inside a composed run this root reads a value computed during the apply.",
     docs: { product: "terragucci", path: "/concepts/waves-and-approvals/#approval" },
     source: "terragucci:packages/terragucci/src/apply.ts:2022",
     sample: "wave 1 of 3: app reads subnet_id of network, unknown at plan time and computed in this apply",
@@ -275,7 +275,7 @@ export const ANNOTATIONS = [
   {
     id: "T31", product: "chant", feature: "Apply failed",
     pattern: String.raw`^wave \d+ \(([^)]+)\): apply failed, so none of (.+) counts as applied$`,
-    note: "The wave's apply failed. None of its roots count as applied and later waves do not run.",
+    note: "The wave's apply failed. Its roots and the later waves wait for a re-run.",
     docs: { product: "terragucci", path: "/reference/responses/#apply-failed" },
     source: "chant:packages/core/src/op/op-waves-run.ts:2092",
     sample: "wave 2 (wave-2): apply failed, so none of app counts as applied",
@@ -379,7 +379,7 @@ export const ANNOTATIONS = [
   {
     id: "T44", product: "terragucci", feature: "Eligible approvers",
     pattern: String.raw`^wave \d+ of \d+: (\S+) (.+), so \1's (approval|review) doesn't count$`,
-    note: "This person had a hand in the change. Their approval or review does not count toward the gate.",
+    note: "This person worked on the change, so the gate counts approvals from someone else.",
     docs: { product: "terragucci", path: "/guides/approve-a-wave/#eligible-approvers" },
     source: "terragucci:packages/terragucci/src/involved.ts:175",
     sample: "wave 2 of 3: demo-author opened pull request 1086, so demo-author's review doesn't count", // made from the source, no run printed it yet
@@ -387,7 +387,7 @@ export const ANNOTATIONS = [
   {
     id: "T45", product: "terragucci", feature: "Eligible approvers",
     pattern: String.raw`^wave \d+ of \d+: an approval counts only from someone who had no hand in the change, so not from (.+)$`,
-    note: "An approval from the people named here does not count because they had a hand in the change.",
+    note: "The people named here worked on the change, so the gate counts approvals from someone else.",
     docs: { product: "terragucci", path: "/guides/approve-a-wave/#eligible-approvers" },
     source: "terragucci:packages/terragucci/src/apply.ts:3001",
     sample: "wave 2 of 3: an approval counts only from someone who had no hand in the change, so not from demo-author", // made from the source, no run printed it yet

package/web/kiosk-approval.js

@@ -123,7 +123,7 @@ export function approvalModel({ demo, runs = [], history = null, lifecycle = nul
       commit: requested && requested.source ? requested.source.commit || null : null,
       line: reqLine,
     });
-  } else Object.assign(reqRow, { state: "dim", text: `Wave ${wave} has not asked for an approval yet.` });
+  } else Object.assign(reqRow, { state: "dim", text: `Wave ${wave} asks for an approval when it reaches its gate.` });
 
   // Approved.
   const apRow = { id: "approved", label: "Approved" };
@@ -159,7 +159,7 @@ export function approvalModel({ demo, runs = [], history = null, lifecycle = nul
       line: start2 ? { run: resume.id, ...start2 } : found,
     });
   } else if (resume) {
-    Object.assign(rsRow, { state: "going", text: `/terragucci apply started the waves again; wave ${wave} has not reached its gate yet.`, at: resume.started_at || resume.created_at, runId: resume.id, line: start2 ? { run: resume.id, ...start2 } : null });
+    Object.assign(rsRow, { state: "going", text: `/terragucci apply started the waves again; wave ${wave} reaches its gate next.`, at: resume.started_at || resume.created_at, runId: resume.id, line: start2 ? { run: resume.id, ...start2 } : null });
   } else {
     Object.assign(rsRow, { state: "dim", text: driver && driver.comment ? `Then a comment of ${driver.comment} on ${driver.on} starts the waves again.` : "A comment of /terragucci apply starts the waves again." });
   }

package/web/kiosk-popover.js

@@ -31,9 +31,9 @@ export const ACTION_HEAD = {
 
 export const WORDS = {
   same: "The plan leaves this resource as it is.",
-  untouched: "This plan does not touch its root, so nothing changes here.",
+  untouched: "This plan leaves its root as it is.",
   noPlan: "No plan yet for this resource.",
-  unknown: "known after apply, so no review shows this value",
+  unknown: "known after apply",
   long: "too long to show here",
   noneYet: "none yet",
   gone: "gone",

package/web/kiosk-popover.test.js

@@ -49,11 +49,11 @@ describe("what the popover says about a resource (behold#571)", () => {
     expect(p.applied).toBeNull();
   });
 
-  it("says an attribute known only after apply in the unknown tone, and that no review shows it", () => {
+  it("says an attribute known only after apply in the unknown tone", () => {
     const p = resourcePopover(answer(), "repo/app/terraform_data.listener_port");
     expect(p.unknown).toBe(true);
-    expect(p.lines).toEqual([{ text: "input: 8070 -> known after apply, so no review shows this value", tone: "unknown" }]);
-    expect(attributeLine({ path: "input", unknown: true })).toEqual({ text: "input: known after apply, so no review shows this value", tone: "unknown" });
+    expect(p.lines).toEqual([{ text: "input: 8070 -> known after apply", tone: "unknown" }]);
+    expect(attributeLine({ path: "input", unknown: true })).toEqual({ text: "input: known after apply", tone: "unknown" });
   });
 
   it("says no change for a card the plan leaves alone, and that a root the plan does not hold is untouched", () => {

package/web/kiosk.html

@@ -137,6 +137,7 @@
       .k-box.k-more-below { -webkit-mask-image: linear-gradient(to bottom, #000 calc(100% - 1.3em), transparent); mask-image: linear-gradient(to bottom, #000 calc(100% - 1.3em), transparent); }
       .k-box.k-more-above { -webkit-mask-image: linear-gradient(to top, #000 calc(100% - 1.3em), transparent); mask-image: linear-gradient(to top, #000 calc(100% - 1.3em), transparent); }
       .k-box.k-more-above.k-more-below { -webkit-mask-image: linear-gradient(to bottom, transparent, #000 1.3em, #000 calc(100% - 1.3em), transparent); mask-image: linear-gradient(to bottom, transparent, #000 1.3em, #000 calc(100% - 1.3em), transparent); }
+      .k-box-empty { background: transparent; }
       .k-box-title { background: transparent; padding: 0.1em 0.1em 0; overflow: hidden; }
       /* behold#571: between scenarios the card's box carries what the demo is about. */
       .k-intro { margin: 0; font-size: 1.12em; line-height: 1.4; color: var(--fg); }
@@ -217,6 +218,8 @@
         border-radius: 8px; box-shadow: 0 6px 24px color-mix(in srgb, var(--shadow) 70%, transparent); font-size: 1.15em; line-height: 1.45; }
       #k-what-pop[hidden] { display: none; }
       #k-what-pop p { margin: 0; }
+      #k-what-pop .k-what-more { margin-top: 0.5em; }
+      #k-what-pop a { color: var(--focus); }
       .k-menu summary { cursor: pointer; color: var(--muted); list-style: none; }
       .k-menu summary::-webkit-details-marker { display: none; }
       .k-menu summary::after { content: " ▾"; }

package/web/kiosk.js

@@ -137,7 +137,7 @@ export function countdownWords(secs) {
 
 /** The driver's next action, as the kiosk says it. */
 export function nextWords(demo, now = new Date()) {
-  if (!demo.next) return { action: "nothing until the driver resets", when: "the driver stalled; it resets and starts the next cycle", secs: null };
+  if (!demo.next) return { action: "reset and start the next cycle", when: "the driver stalled; it resets and starts the next cycle", secs: null };
   const secs = secondsUntil(demo.next.at, now);
   return {
     action: demo.next.action,
@@ -198,9 +198,9 @@ export function runPanel(demo, answer, progress) {
   if (run) return { stage: "apply", run };
   if (pr) return { stage: "pull-request", pr };
   if (stage === "pull-request") {
-    return { stage: "pull-request", note: demo.pull === null ? "The pull request isn't open yet." : `The plan of pull request #${demo.pull} isn't in the reports yet: the pipeline is planning it.` };
+    return { stage: "pull-request", note: demo.pull === null ? "The pull request opens next." : `The pipeline is planning pull request #${demo.pull}.` };
   }
-  return { stage: "apply", note: demo.commit ? `The run view of ${demo.commit.slice(0, 8)} isn't in the reports yet: the pipeline writes it as the waves start.` : "No run yet." };
+  return { stage: "apply", note: demo.commit ? `The pipeline writes the run view of ${demo.commit.slice(0, 8)} as the waves start.` : "The first run starts next." };
 }
 
 /** The pull request's waves and reads, when the panel shows its plan. */
@@ -584,6 +584,8 @@ function drawBar(bar, s, now, foot) {
     if (panel.note) holdBox.appendChild(elRoots("p", "k-note", panel.note, s));
     else if (panel.stage === "pull-request") for (const u of unreviewedLines(s.answer)) holdBox.appendChild(elRoots("p", "k-note k-unknown", u, s));
   }
+  // behold#571: render what's present: an empty hold keeps its place (nothing moves when one comes) but draws no box.
+  if (!holdBox.children.length) holdBox.className += " k-box-empty";
   right.appendChild(holdBox);
   bar.appendChild(right);
 
@@ -642,7 +644,7 @@ export function approvalPanel(model, s = {}) {
 }
 
 /** behold#571: the header's line when this behold serves another repo than the page's. */
-export const NO_GRAPH_WORDS = "This page shows the runs and their logs; the graph of this repo isn't served here.";
+export const NO_GRAPH_WORDS = "This page shows the runs and their logs.";
 
 /** behold#571: a tool's name, and its logo where its owner allows one, linking to its official site. */
 function brandEl(vendor) {
@@ -689,10 +691,11 @@ export const APPROVAL_POLL_MS = 4_000;
 export const LEDGER_POLL_MS = 10_000;
 
 /** behold#571: the approval panel's words for the approval the driver gives next, over its command. */
-export const DRIVER_SIGNS = "Next the driver plays a reviewer with no hand in the change and signs this plan with that reviewer's key:";
+export const DRIVER_SIGNS = "Next the driver plays a reviewer outside the change and signs this plan with that reviewer's key:";
 
-/** behold#571: "What is this?" before demo.json says. */
-export const WHAT_FALLBACK = "A demo that runs a real infrastructure change through its pipeline in a loop, and shows each step as it happens.";
+/** behold#571: "What is this?" says what behold is; the demo's own intro stays on the card between scenarios. */
+export const WHAT_TEXT = "This is behold, a live view of infrastructure. It draws the setup as a graph and shows its pipeline runs, their logs and the approvals they wait for, as they happen. Here it watches a demo pipeline that runs one change through several Terraform states in a loop.";
+export const WHAT_DOCS = { text: "behold's documentation", url: "https://intentius.io/behold/" };
 
 /** behold#571: a fade at a box's edge where its text goes on past it. */
 function fade(b) {
@@ -959,14 +962,16 @@ export function startKiosk({ bar, frame, foot, side, main, views, tools = null }
   };
   if (tools && tools.runsToggle) tools.runsToggle.addEventListener("click", () => setRunsOpen(!document.body.classList.contains("k-runs-open")));
 
-  // behold#571: "What is this?" opens the intro over the page (no layout moves); a click elsewhere or Escape closes it.
+  // behold#571: "What is this?" opens what behold is over the page (no layout moves); a click elsewhere or Escape closes it.
   const whatText = () => {
-    if (!tools || !tools.pop) return;
-    const d = s.demo && s.demo.demo;
-    const text = (d && introText(d)) || WHAT_FALLBACK;
-    const p = tools.pop.firstElementChild;
-    if (p && p.textContent === text) return;
-    tools.pop.replaceChildren(el("p", null, text));
+    if (!tools || !tools.pop || tools.pop.firstElementChild) return;
+    const docs = el("a", null, WHAT_DOCS.text);
+    docs.href = WHAT_DOCS.url;
+    docs.target = "_blank";
+    docs.rel = "noopener";
+    const more = el("p", "k-what-more");
+    more.append(docs);
+    tools.pop.replaceChildren(el("p", null, WHAT_TEXT), more);
   };
   if (tools && tools.what && tools.pop) {
     const setWhat = (open) => {

package/web/kiosk.test.js

@@ -81,7 +81,7 @@ describe("before the merge, no other cycle's plan (#569)", () => {
       expect(matchingPull(ours, now(step))).toBe(ours.pull_request);
       expect(focusRoots(now(step), older, null)).toBe(null);
       expect(factLines(now(step), older)).toEqual([]);
-      expect(runPanel(now(step), older, null).note).toBe("The plan of pull request #989 isn't in the reports yet: the pipeline is planning it.");
+      expect(runPanel(now(step), older, null).note).toBe("The pipeline is planning pull request #989.");
     }
   });
   it("from the merge on, takes the plan by its number: demo.json's commit is the merge's", () => {