@intentius/behold 0.29.0 → 0.29.2

package/web/terragucci-change.js

@@ -105,12 +105,18 @@ export function readTag(e) {
   return `reads ${e.to} · ${e.composed !== undefined ? "in the composed run" : e.outputs}${e.unknown.length ? ` · ${e.unknown.length} unknown` : ""}`;
 }
 
-/** The checkout's card id for a reader's data block, for each kind of block that reads another root. */
+/**
+ * The checkout's card id for a reader's data block, for each kind of block
+ * that reads another root. The run view names no data block (#569): there the
+ * block named after the root it reads is tried, and the caller falls back to
+ * the reader's box when the checkout has none.
+ */
 export function readCardIds(answer, e) {
-  if (!e.data || !answer || !answer.roots) return [];
+  const data = e.data || (e.stage === "apply" ? e.to : null);
+  if (!data || !answer || !answer.roots) return [];
   const r = answer.roots.find((x) => x.path === e.from);
   if (!r) return [];
-  return [`${r.member}/${r.name}/data.terraform_remote_state.${e.data}`, `${r.member}/${r.name}/data.terraform_estate_outputs.${e.data}`];
+  return [`${r.member}/${r.name}/data.terraform_remote_state.${data}`, `${r.member}/${r.name}/data.terraform_estate_outputs.${data}`];
 }
 
 /** "5 create · 1 update", no-ops and zeros left out; "no changes" when nothing moves. */
@@ -421,3 +427,142 @@ export function changeSection(answer, progress, now, ui) {
   }
   return box;
 }
+
+// ---------------------------------------------------------------------------
+// #569: the change drawn on the view itself, so the graph says what the panel
+// says: each root's wave and its state on its box, each read between roots as
+// a labelled line, and which run all of it comes from.
+
+/** The colour a state is drawn in: one word per channel, mapped to a theme token in app.js. */
+export const STATE_TONE = {
+  planned: "plan",
+  "not-started": "idle",
+  waiting: "wait",
+  applying: "busy",
+  applied: "ok",
+  refused: "bad",
+  failed: "bad",
+  outside: "idle",
+  unchanged: "idle",
+};
+
+/**
+ * #569 review: whether a root of a run-view wave plans a change. A root its
+ * wave planned without a change (`changed`, the roots whose plan changes a
+ * resource or an output) is never shown waiting, applying or failed: nothing
+ * of it is approved or applied. A composed run's member says for itself.
+ * Unknown (true) until the wave has planned, or on a run view without
+ * `changed`.
+ */
+export function rootChanges(w, root) {
+  const m = w.composed && w.composed.members ? w.composed.members.find((x) => x.root === root) : null;
+  if (m && m.apply) return m.apply !== "no-changes";
+  const planned = w.state !== "not-started" && (!!w.totals || !!w.digest);
+  if (!planned || !Array.isArray(w.changed)) return true;
+  return w.changed.includes(root);
+}
+
+/** The roots of a wave that plan a change, in the wave's order (all of them while that isn't known). */
+export function changingRoots(w, roots) {
+  return roots.filter((r) => rootChanges(w, r));
+}
+
+/** A member of a composed run, once it ended, as a root state. */
+const MEMBER_STATE = { applied: "applied", partial: "failed", failed: "failed", "not-started": "not-started", "no-changes": "applied" };
+
+/**
+ * Each root's wave and state, for its box on the view. `roots` maps a root's
+ * path to `{ wave, state, tone, words, facts }`: "wave 2 · waiting for an
+ * approval", with the facts under it (the plan's digest it waits on, its
+ * changes, that it plans again after an earlier wave). A root the change
+ * doesn't plan, or the run doesn't apply, is `outside`. A root in a composed
+ * run that failed part way takes its own part's outcome: what applied says
+ * applied.
+ */
+export function rootStates(answer, progress) {
+  const stage = changeStage(answer, progress);
+  const roots = {};
+  const known = (answer && answer.roots ? answer.roots.map((r) => r.path) : []).filter(Boolean);
+  if (stage === "pull-request") {
+    const pr = answer.pull_request;
+    for (const w of pr.waves) {
+      const c = w.composed;
+      const members = c ? c.members.map((m) => m.root) : [];
+      for (const root of [...new Set([...w.roots, ...members])]) {
+        // #569 review: a root the pull request plans without a change, and that
+        // reads nothing unknown, shows no changes rather than a wave's plan.
+        const blast = pr.blast && Array.isArray(pr.blast.roots) ? pr.blast.roots : null;
+        const readsUnknown = (pr.reads || []).some((r) => r.root === root && r.unknown && r.unknown.length) || !!(c && c.held_by_unknown && c.held_by_unknown.includes(root));
+        if (blast && !blast.includes(root) && !readsUnknown) {
+          roots[root] = { wave: w.number, state: "unchanged", tone: STATE_TONE.unchanged, words: `wave ${w.number} · no changes`, facts: [] };
+          continue;
+        }
+        const facts = [];
+        if (w.replans_after && w.replans_after.length) facts.push(`plans again once wave ${list(w.replans_after)} applies`);
+        else if (w.review_digest || w.set_digest) facts.push(`plan ${short(w.review_digest || w.set_digest)}`);
+        if (c && c.held_by_unknown && c.held_by_unknown.includes(root)) facts.push("reads a value unknown when planned");
+        if (w.waits) facts.push("will wait for an approval");
+        roots[root] = { wave: w.number, state: "planned", tone: STATE_TONE.planned, words: `wave ${w.number} · planned${c ? ", composed" : ""}`, facts };
+      }
+    }
+    for (const root of known) if (!roots[root]) roots[root] = { wave: null, state: "outside", tone: STATE_TONE.outside, words: "not in this change", facts: [] };
+    return { stage, roots };
+  }
+  if (stage === "apply") {
+    const composedOf = new Map(progress.reads.filter((r) => r.composed).map((r) => [r.root, r.composed.wave]));
+    for (const w of progress.states) {
+      const c = w.composed;
+      const inRun = [...composedOf].filter(([, n]) => n === w.number).map(([r]) => r);
+      for (const root of [...new Set([...w.roots, ...(c ? c.roots : []), ...inRun])]) {
+        if (!rootChanges(w, root)) {
+          roots[root] = { wave: w.number, state: "unchanged", tone: STATE_TONE.unchanged, words: `wave ${w.number} · no changes`, facts: [] };
+          continue;
+        }
+        const m = c && c.members ? c.members.find((x) => x.root === root) : null;
+        const state = m && m.apply ? MEMBER_STATE[m.apply] || w.state : w.state;
+        const facts = [];
+        if (state === "waiting" && w.digest) facts.push(`approve plan ${short(w.digest)}`);
+        if (state === "waiting" && c && c.unknown && c.unknown.includes(root)) facts.push("read a value unknown when planned");
+        const totals = totalsLine(w.totals);
+        const together = new Set([...w.roots, ...(c ? c.roots : []), ...inRun]).size > 1;
+        const composedHere = !!c && (c.roots.includes(root) || inRun.includes(root));
+        if (m && m.apply) facts.push(memberApplyLine(m).replace(`${root}: `, "")); // this root's own part, not the wave's
+        else if (c && !composedHere) {
+          // Beside a composed run in its wave: the wave's figures are the run's, not this root's.
+        } else if (totals && state !== "not-started") facts.push(totals === "no changes" ? `${together ? "the wave: " : ""}no changes` : `${together ? "the wave " : ""}${state === "applied" ? "applied" : state === "failed" || state === "refused" ? "planned" : "plans"} ${totals}`);
+        if (state === "failed" || state === "refused") {
+          const before = progress.states.filter((x) => x.number < w.number && x.state === "applied").map((x) => x.number);
+          if (before.length) facts.push(`wave ${list(before)} stays applied`);
+        }
+        const words = `wave ${w.number} · ${STATE_WORDS[state] || state}${composedHere ? ", composed" : ""}`;
+        roots[root] = { wave: w.number, state, tone: STATE_TONE[state] || "idle", words, facts };
+      }
+    }
+    for (const root of known) if (!roots[root]) roots[root] = { wave: null, state: "outside", tone: STATE_TONE.outside, words: "not in this run", facts: [] };
+    return { stage, roots };
+  }
+  return { stage, roots };
+}
+
+/** The short label on a read's line: "reads network's planned http_proxy_port, unknown until network applies". */
+export function readLabel(e) {
+  if (e.composed !== undefined) {
+    return `reads ${e.to} in wave ${e.composed}'s composed run${e.unknown.length ? `: ${list(e.unknown)} known once ${e.to}'s part applies` : ""}`;
+  }
+  if (e.outputs === "planned") return e.unknown.length ? `reads ${list(e.unknown)} from ${e.to}: unknown until ${e.to} applies` : `reads ${e.to}'s planned outputs`;
+  return `reads ${e.to}'s applied state`;
+}
+
+/** Which run the view's marks come from, dated: "the plan of pull request #201, 03:11 UTC". */
+export function viewCaption(answer, progress, now = new Date()) {
+  const stage = changeStage(answer, progress);
+  if (stage === "pull-request") {
+    const r = answer.pull_request.run;
+    return `the plan of pull request #${r.pull_request} at ${clock(r.finished, now)}: not merged yet, nothing applied`;
+  }
+  if (stage === "apply") {
+    const r = progress.run;
+    return `the run of merge ${r.commit.slice(0, 8)}, as of ${clock(r.updated, now)}`;
+  }
+  return null;
+}

package/web/terragucci-change.test.js

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import { readCardIds, readLabel, rootStates, viewCaption } from "./terragucci-change.js";
+
+const roots = ["app", "edge", "network", "other"].map((name) => ({ member: "demo", name, path: name }));
+const prAnswer = {
+  roots,
+  pull_request: {
+    run: { pull_request: "201", finished: "2026-10-15T03:11:13.605Z", commit: "c9dfc649c704" },
+    reads: [{ root: "app", upstream: "network", data: "network", outputs: "planned", unknown: ["http_proxy_port"] }],
+    roots: ["app", "edge", "network"],
+    waves: [
+      { number: 1, roots: ["network"], state: "planned", review_digest: "jcs1-sha256:f8851fb619215c0eab", waits: false },
+      { number: 2, roots: ["app"], state: "planned", review_digest: null, waits: true, replans_after: [1] },
+      { number: 3, roots: ["edge"], state: "planned", review_digest: null, waits: true, replans_after: [2] },
+    ],
+  },
+};
+const run = (states, reads) => ({ run: { present: true, commit: "6b9f7e255f6f", updated: "2026-10-15T03:20:00.000Z" }, states, reads });
+
+describe("rootStates (#569)", () => {
+  it("puts each planned wave on its roots, and says which root the change leaves out", () => {
+    const { stage, roots: r } = rootStates(prAnswer, null);
+    expect(stage).toBe("pull-request");
+    expect(r.network).toMatchObject({ wave: 1, state: "planned", tone: "plan", words: "wave 1 · planned", facts: ["plan f8851fb61921"] });
+    expect(r.app.facts).toEqual(["plans again once wave 1 applies", "will wait for an approval"]);
+    expect(r.other).toMatchObject({ state: "outside", words: "not in this change" });
+  });
+  it("shows a failed wave's roots failed and the waves before it applied", () => {
+    const p = run(
+      [
+        { number: 1, state: "applied", roots: ["network", "other"], reads: [], totals: { update: 1 } },
+        { number: 2, state: "failed", roots: ["app"], reads: [1], totals: { create: 1, update: 1 } },
+        { number: 3, state: "not-started", roots: ["edge"], reads: [2] },
+      ],
+      [],
+    );
+    const { roots: r } = rootStates(prAnswer, p);
+    expect(r.network).toMatchObject({ state: "applied", tone: "ok", facts: ["the wave applied 1 update"] });
+    expect(r.app).toMatchObject({ state: "failed", tone: "bad", words: "wave 2 · failed", facts: ["planned 1 create · 1 update", "wave 1 stays applied"] });
+    expect(r.edge).toMatchObject({ state: "not-started", tone: "idle", facts: [] });
+  });
+  it("names the plan a waiting wave waits on", () => {
+    const p = run([{ number: 2, state: "waiting", roots: ["app"], reads: [1], digest: "jcs1-sha256:83b0533bb8085dfad2" }], []);
+    expect(rootStates(prAnswer, p).roots.app).toMatchObject({ state: "waiting", tone: "wait", facts: ["approve plan 83b0533bb808"] });
+  });
+  it("gives each root of a composed run that failed part way its own outcome", () => {
+    const p = run(
+      [{ number: 1, state: "failed", roots: ["network"], reads: [], composed: { roots: ["network", "app"], members: [{ root: "network", module: "module.network", apply: "applied", state: "written" }, { root: "app", module: "module.app", apply: "failed", state: "written" }] } }],
+      [{ root: "app", wave: 2, reads: ["network"], composed: { wave: 1, own_wave: 2, module: "module.app" } }],
+    );
+    const { roots: r } = rootStates(prAnswer, p);
+    expect(r.network).toMatchObject({ wave: 1, state: "applied", words: "wave 1 · applied, composed", facts: ["applied; state written"] });
+    expect(r.app).toMatchObject({ wave: 1, state: "failed" });
+    expect(r.edge.state).toBe("outside");
+  });
+});
+
+describe("rootStates, a root that plans no change (#569 review)", () => {
+  it("never shows a root its wave plans no change in as waiting", () => {
+    const p = run([{ number: 1, state: "waiting", roots: ["network", "other"], reads: [], digest: "jcs1-sha256:365a4f0d54d7aa", totals: { create: 5 }, changed: ["network"] }], []);
+    const { roots: r } = rootStates(prAnswer, p);
+    expect(r.network.state).toBe("waiting");
+    expect(r.other).toMatchObject({ state: "unchanged", tone: "idle", words: "wave 1 · no changes", facts: [] });
+  });
+  it("takes a composed member's own no-changes over the wave's state", () => {
+    const p = run([{ number: 1, state: "failed", roots: ["network"], reads: [], composed: { roots: ["network", "edge"], members: [{ root: "network", module: "m", apply: "failed" }, { root: "edge", module: "e", apply: "no-changes" }] } }], []);
+    expect(rootStates(prAnswer, p).roots.edge.state).toBe("unchanged");
+  });
+  it("shows a planned root outside the blast radius that reads nothing unknown as no changes", () => {
+    const a = { ...prAnswer, pull_request: { ...prAnswer.pull_request, blast: { roots: ["app", "network"], downstream: [] } } };
+    const { roots: r } = rootStates(a, null);
+    expect(r.edge.state).toBe("unchanged");
+    expect(r.app.state).toBe("planned");
+  });
+});
+
+describe("readLabel (#569)", () => {
+  it("says what is read and when it is known", () => {
+    expect(readLabel({ from: "app", to: "network", outputs: "planned", unknown: ["http_proxy_port"] })).toBe("reads http_proxy_port from network: unknown until network applies");
+    expect(readLabel({ from: "app", to: "network", outputs: "planned", unknown: [] })).toBe("reads network's planned outputs");
+    expect(readLabel({ from: "app", to: "network", outputs: "applied", unknown: [] })).toBe("reads network's applied state");
+    expect(readLabel({ from: "app", to: "network", outputs: "planned", unknown: ["subnet_id"], composed: 1 })).toBe("reads network in wave 1's composed run: subnet_id known once network's part applies");
+  });
+});
+
+describe("readCardIds (#569)", () => {
+  it("tries the block named after the root read when the run view names none", () => {
+    expect(readCardIds({ roots }, { from: "edge", to: "app", data: null, stage: "apply" })[0]).toBe("demo/edge/data.terraform_remote_state.app");
+    expect(readCardIds({ roots }, { from: "edge", to: "app", data: null, stage: "pull-request" })).toEqual([]);
+  });
+});
+
+describe("viewCaption (#569)", () => {
+  it("says which run the marks come from", () => {
+    const now = new Date("2026-10-15T03:30:00Z");
+    expect(viewCaption(prAnswer, null, now)).toBe("the plan of pull request #201 at 03:11 UTC: not merged yet, nothing applied");
+    expect(viewCaption(prAnswer, run([{ number: 1, state: "applied", roots: ["network"], reads: [] }], []), now)).toBe("the run of merge 6b9f7e25, as of 03:20 UTC");
+  });
+});

package/web/view-url.js

@@ -10,8 +10,13 @@
 /** The view's keys, in the order they are written back. Anything else in the
  * query (embed, theme, host, #476) is left where it is. `gates` is the env the
  * gate strip reads when it isn't the graph's (#477); it is the view's because
- * a host can move it with `behold:view`, and a reload has to keep that. */
-export const VIEW_KEYS = ["member", "zoom", "env", "tier", "lens", "node", "radial", "gates"];
+ * a host can move it with `behold:view`, and a reload has to keep that.
+ * `focus` (#569) names the boxes the view brings forward, comma-separated
+ * (a terragucci repo's roots): the rest are drawn dimmed, nothing is hidden.
+ * `run` (#569) pins which terragucci run the view draws: a commit's run view,
+ * `none` (no run view: the pull request's plan) or `base` (nothing in
+ * flight); absent, the newest. */
+export const VIEW_KEYS = ["member", "zoom", "env", "tier", "lens", "node", "radial", "gates", "focus", "run"];
 
 /** An env name as the server takes one (src/workspace-gates.ts isEnvName). */
 export function isEnvName(env) {
@@ -43,6 +48,10 @@ export function readViewQuery(search) {
       want.env = v || null;
       continue;
     }
+    if (k === "focus" || k === "run") {
+      want[k] = v || null;
+      continue;
+    }
     if (v) want[k] = v;
   }
   return want;
@@ -71,6 +80,8 @@ export function writeViewQuery(search, state, defaults = {}) {
   if (s.node) q.set("node", s.node);
   if (s.radial) q.set("radial", "1");
   if (s.gates) q.set("gates", s.gates);
+  if (s.focus) q.set("focus", s.focus);
+  if (s.run) q.set("run", s.run);
   const out = q.toString();
   return out ? `?${out}` : "";
 }
@@ -112,6 +123,17 @@ export function settleView(want, offer) {
     if (want.gates === null || isEnvName(want.gates)) apply.gates = want.gates;
     else refused.push({ key: "gates", value: want.gates, reason: "an env name is letters, digits, '.', '_' and '-'" });
   }
+  if ("focus" in want) {
+    // null: nothing brought forward. Otherwise box names, comma-separated.
+    const names = want.focus === null ? [] : String(want.focus).split(",").map((x) => x.trim()).filter(Boolean);
+    if (names.every((n) => /^[A-Za-z0-9][A-Za-z0-9._\/-]*$/.test(n))) apply.focus = names.length ? names.join(",") : null;
+    else refused.push({ key: "focus", value: want.focus, reason: "focus is box names, comma-separated" });
+  }
+  if ("run" in want) {
+    // null: the newest run, as without the key.
+    if (want.run === null || /^([0-9a-f]{7,40}|none|base)$/.test(String(want.run))) apply.run = want.run;
+    else refused.push({ key: "run", value: want.run, reason: "run is a commit sha, none or base" });
+  }
   if (want.member) apply.member = want.member;
   if (want.node) apply.node = want.node;
   return { apply, refused };

package/web/view-url.test.js

@@ -107,3 +107,26 @@ describe("settlePlace (#475)", () => {
     expect(refusalLine([])).toBe("");
   });
 });
+
+describe("focus (#569)", () => {
+  it("reads, writes and settles a list of box names", () => {
+    expect(readViewQuery("?focus=app,edge")).toEqual({ focus: "app,edge" });
+    expect(readViewQuery("?focus=")).toEqual({ focus: null });
+    expect(writeViewQuery("?embed=1", { focus: "app,edge" })).toBe("?embed=1&focus=app%2Cedge");
+    expect(settleView({ focus: " app , edge " }, {}).apply).toEqual({ focus: "app,edge" });
+    expect(settleView({ focus: null }, {}).apply).toEqual({ focus: null });
+  });
+  it("refuses a focus that isn't box names", () => {
+    expect(settleView({ focus: "app,<b>" }, {}).refused[0].key).toBe("focus");
+  });
+});
+
+describe("run (#569)", () => {
+  it("takes a commit, none or base, and null for the newest", () => {
+    expect(readViewQuery("?run=abc1234")).toEqual({ run: "abc1234" });
+    expect(settleView({ run: "base" }, {}).apply).toEqual({ run: "base" });
+    expect(settleView({ run: null }, {}).apply).toEqual({ run: null });
+    expect(settleView({ run: "main" }, {}).refused[0].key).toBe("run");
+    expect(writeViewQuery("", { run: "none" })).toBe("?run=none");
+  });
+});