@intentius/behold 0.23.0 → 0.25.0

package/web/terragucci-progress.js

@@ -0,0 +1,127 @@
+// #511: a choudoufu wave's progress per resource, from terragucci's run view.
+// app.js fetches /api/terragucci/progress (and hears the `progress` event on
+// /api/terragucci/events), then stamps cards and fills the panel from what
+// these functions return.
+//
+// A progress mark is dated by the records read it came from ("in flight,
+// records read 09:43 UTC, 2m ago"). It is a corner tag, never a fill: the
+// fill is the live-status channel, and this is what the wave job's last read
+// of the estates' records found, which may already be behind.
+
+import { ago, clock, hrefOf } from "./terragucci.js";
+
+export const PROGRESS_WORDS = { done: "done", "in-flight": "in flight", waiting: "waiting", "not-applied": "not applied" };
+const GLYPH = { done: "✓", "in-flight": "▶", waiting: "…", "not-applied": "✕" };
+
+/** "records read 09:43 UTC, 2m ago". */
+export function readWords(read, now = new Date()) {
+  return `records read ${clock(read, now)}, ${ago(read, now)}`;
+}
+
+/** The newest wave's mark on a card: a wave applying now outranks an earlier one. */
+export function cardProgress(marks) {
+  if (!marks || !marks.length) return null;
+  return [...marks].sort((a, b) => b.wave - a.wave)[0];
+}
+
+/** The corner tag of a card: "▶ wave 2 in flight · 2m". */
+export function progressTag(mark, now = new Date()) {
+  const s = Math.max(0, (now.getTime() - Date.parse(mark.read)) / 1000);
+  const age = s < 3600 ? `${Math.max(1, Math.round(s / 60))}m` : s < 172800 ? `${Math.round(s / 3600)}h` : `${Math.round(s / 86400)}d`;
+  return { text: `${GLYPH[mark.status]} wave ${mark.wave} ${PROGRESS_WORDS[mark.status]} · ${age}`, tone: mark.status };
+}
+
+/** One instance as a line: "module.x.aws_y.z[1] (replace): in flight", with when a read first found it done. */
+export function resourceLine(r, now = new Date()) {
+  const done = r.status === "done" && r.done_at ? ` ${clock(r.done_at, now)}` : "";
+  return `${r.address} (${r.action}): ${PROGRESS_WORDS[r.status]}${done}`;
+}
+
+/** A card's mark as sentences, for its tooltip and the inspect pane. */
+export function progressLines(mark, now = new Date()) {
+  return [`wave ${mark.wave} ${PROGRESS_WORDS[mark.status]}, ${readWords(mark.read, now)}`, ...mark.resources.map((r) => resourceLine(r, now))];
+}
+
+/** "2 of 5 done, 1 in flight, 2 waiting", plus "1 not applied" when there is one. */
+export function countsLine(counts) {
+  const total = counts.done + counts["in-flight"] + counts.waiting + counts["not-applied"];
+  return `${counts.done} of ${total} done, ${counts["in-flight"]} in flight, ${counts.waiting} waiting${counts["not-applied"] ? `, ${counts["not-applied"]} not applied` : ""}`;
+}
+
+/** The panel's rows: the run's line, then one per wave with progress. Never "live". */
+export function progressRows(answer, now = new Date()) {
+  if (!answer || answer.error) return { head: answer && answer.error ? `apply progress not read: ${answer.error}` : "", title: (answer && answer.remedy) || "", waves: [] };
+  if (!answer.run || !answer.run.present) return { head: answer.absent || "", title: "", waves: [] };
+  const head = `apply progress of ${answer.run.commit.slice(0, 12)}, from terragucci's run view${answer.watching ? " · asked again while a wave moves" : " · settled"}`;
+  const title = [`${answer.run.key}, read ${ago(answer.read, now)}`, answer.unmatched.length ? `no card: ${answer.unmatched.map((u) => `${u.root}: ${u.address}`).join(", ")}` : ""].filter(Boolean).join("\n");
+  return {
+    head,
+    title,
+    html: answer.run.html,
+    waves: answer.waves.map((w) => ({
+      number: w.number,
+      text: `wave ${w.number} ${w.state}: ${countsLine(w.counts)}`,
+      read: readWords(w.read, now),
+      tone: w.counts["not-applied"] ? "not-applied" : w.counts["in-flight"] ? "in-flight" : w.counts.waiting ? "waiting" : "done",
+      lines: w.resources.map((r) => `${r.root}: ${resourceLine(r, now)}`),
+    })),
+  };
+}
+
+const FILL = { done: "var(--muted)", "in-flight": "var(--pending)", waiting: "var(--muted)", "not-applied": "var(--degraded)" };
+
+/** Stamp each card's progress tag at its top-right corner. Replaces the previous stamps. */
+export function stampProgress(svg, answer, now = new Date()) {
+  if (!svg) return;
+  for (const old of svg.querySelectorAll("[data-tg-progress]")) old.remove();
+  if (!answer || !answer.cards) return;
+  for (const [id, marks] of Object.entries(answer.cards)) {
+    const g = svg.querySelector('[data-node-id="' + CSS.escape(id) + '"]');
+    const mark = cardProgress(marks);
+    if (!g || !mark) continue;
+    const rect = g.querySelector("rect");
+    const box = rect && rect.getBBox ? rect.getBBox() : null;
+    const t = progressTag(mark, now);
+    const tag = document.createElementNS("http://www.w3.org/2000/svg", "text");
+    tag.setAttribute("data-tg-progress", t.tone);
+    tag.setAttribute("x", String((box ? box.x + box.width : 150) - 10));
+    tag.setAttribute("y", String((box ? box.y : 0) + 14));
+    tag.setAttribute("text-anchor", "end");
+    tag.setAttribute("font-size", "10");
+    tag.setAttribute("fill", FILL[t.tone]);
+    tag.textContent = t.text;
+    const title = document.createElementNS("http://www.w3.org/2000/svg", "title");
+    title.textContent = progressLines(mark, now).join("\n") + "\n(from terragucci's run view, as of that read: not live)";
+    tag.appendChild(title);
+    g.appendChild(tag);
+  }
+}
+
+/** The panel section: the run's line, then each wave's counts and read time, its resources folded. */
+export function progressSection(answer, now, link) {
+  const rows = progressRows(answer, now);
+  const box = document.createElement("div");
+  box.className = "tg-progress";
+  if (!rows.head) return box;
+  const head = document.createElement("div");
+  head.className = "tg-legend";
+  head.textContent = rows.head + " ";
+  if (rows.title) head.title = rows.title;
+  if (rows.html && link) head.appendChild(link("run", hrefOf(answer, rows.html)));
+  box.appendChild(head);
+  for (const w of rows.waves) {
+    const d = document.createElement("details");
+    d.className = `tg-progress-wave tg-progress-${w.tone}`;
+    const s = document.createElement("summary");
+    s.textContent = `${w.text} · ${w.read}`;
+    d.appendChild(s);
+    for (const line of w.lines) {
+      const row = document.createElement("div");
+      row.className = "ws-gate-note";
+      row.textContent = line;
+      d.appendChild(row);
+    }
+    box.appendChild(d);
+  }
+  return box;
+}

package/web/terragucci-progress.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { cardProgress, countsLine, progressLines, progressRows, progressTag, resourceLine } from "./terragucci-progress.js";
+
+// #511: the progress words. Every mark is dated by the records read it came
+// from; none says "live".
+const NOW = new Date("2026-10-08T09:45:00Z");
+const mark = (over = {}) => ({
+  wave: 2,
+  state: "applying",
+  read: "2026-10-08T09:43:00.000Z",
+  status: "in-flight",
+  counts: { done: 1, "in-flight": 1, waiting: 0, "not-applied": 0 },
+  resources: [
+    { root: "envs/prod/orders", address: "module.service.aws_dynamodb_table.records[0]", action: "replace", status: "done", done_at: "2026-10-08T09:42:20.000Z" },
+    { root: "envs/prod/orders", address: "module.service.aws_dynamodb_table.records[1]", action: "replace", status: "in-flight" },
+  ],
+  ...over,
+});
+
+describe("progress marks (#511)", () => {
+  it("tags a card with its newest wave's status and the read's age", () => {
+    const m = cardProgress([mark({ wave: 1, status: "done" }), mark()]);
+    expect(m.wave).toBe(2);
+    expect(progressTag(m, NOW)).toEqual({ text: "▶ wave 2 in flight · 2m", tone: "in-flight" });
+    expect(cardProgress([])).toBeNull();
+  });
+
+  it("dates every line by the records read, and a done instance by when a read found it", () => {
+    expect(progressLines(mark(), NOW)).toEqual([
+      "wave 2 in flight, records read 09:43 UTC, 2m ago",
+      "module.service.aws_dynamodb_table.records[0] (replace): done 09:42 UTC",
+      "module.service.aws_dynamodb_table.records[1] (replace): in flight",
+    ]);
+    expect(resourceLine({ address: "a.b", action: "create", status: "not-applied" }, NOW)).toBe("a.b (create): not applied");
+  });
+
+  it("counts a wave the way terragucci's log line does", () => {
+    expect(countsLine({ done: 2, "in-flight": 1, waiting: 2, "not-applied": 0 })).toBe("2 of 5 done, 1 in flight, 2 waiting");
+    expect(countsLine({ done: 2, "in-flight": 0, waiting: 0, "not-applied": 3 })).toBe("2 of 5 done, 0 in flight, 0 waiting, 3 not applied");
+  });
+
+  it("says when there is no run view, and never paints one as live", () => {
+    expect(progressRows({ run: { commit: "c", key: "k", present: false }, absent: "has no k" }, NOW)).toEqual({ head: "has no k", title: "", waves: [] });
+    const rows = progressRows(
+      {
+        read: "2026-10-08T09:44:00Z",
+        run: { commit: "d3e4f5a6b7c8d9e0", key: "p/runs/d3e4/run.json", present: true, html: "p/runs/d3e4/run.html" },
+        watching: true,
+        unmatched: [{ root: "envs/prod/payments", address: "module.service.aws_iam_role.worker" }],
+        waves: [{ number: 2, state: "applying", read: "2026-10-08T09:43:00.000Z", counts: { done: 2, "in-flight": 1, waiting: 2, "not-applied": 0 }, resources: [] }],
+      },
+      NOW,
+    );
+    expect(rows.head).toBe("apply progress of d3e4f5a6b7c8, from terragucci's run view · asked again while a wave moves");
+    expect(rows.head).not.toMatch(/\blive\b/);
+    expect(rows.title).toContain("no card: envs/prod/payments: module.service.aws_iam_role.worker");
+    expect(rows.waves[0]).toMatchObject({ text: "wave 2 applying: 2 of 5 done, 1 in flight, 2 waiting", read: "records read 09:43 UTC, 2m ago", tone: "in-flight" });
+  });
+});

package/web/terragucci-timeline.js

@@ -0,0 +1,118 @@
+// #506: the timeline lane, from terragucci's audit record. app.js fetches
+// /api/terragucci/timeline once (the whole project, newest first) and hands
+// the answer here: the Terragucci tab shows every entry, a card's inspect pane
+// the entries of its root. The record holds no per-resource entry, so a card's
+// lane is its root's.
+//
+// An entry is dated and attributed as the record has it, and links its run's
+// report through the same file route the marks use. An absent record is said
+// in words: it is not "nothing happened".
+
+import { ago, clock, hrefOf } from "./terragucci.js";
+
+const KIND_WORDS = {
+  "approval-requested": "approval requested",
+  approval: "approved",
+  "approval-revoked": "approval revoked",
+  "override-requested": "override requested",
+  override: "policy overridden",
+  "override-revoked": "override revoked",
+  apply: "apply",
+  refused: "refused",
+  migration: "state migration",
+  unlock: "lock released",
+  "state-export": "state exported",
+  "ephemeral-apply": "ephemeral copy applied",
+  "ephemeral-destroy": "ephemeral copy destroyed",
+};
+
+/** The tone an entry is drawn in: a refusal or a failure stands out, a wait is pending, the rest is quiet. */
+export function toneOf(entry) {
+  if (entry.kind === "refused" || entry.result === "failed" || entry.result === "denied") return "failed";
+  if (entry.result === "waiting" || entry.kind === "approval-requested" || entry.kind === "override-requested") return "wave";
+  if (entry.kind.endsWith("-revoked")) return "drift";
+  return "ok";
+}
+
+/** One entry as a line: "approved wave-2 by dana: unsigned · plan 4be1…". */
+export function entryLine(entry) {
+  const what = KIND_WORDS[entry.kind] || entry.kind;
+  const by = entry.who ? ` by ${entry.who}` : "";
+  const result = entry.result && entry.result !== entry.kind ? `: ${entry.result}` : "";
+  const digest = entry.digest ? ` · plan ${entry.digest.replace(/^(jcs1-)?sha256:/, "").slice(0, 12)}` : "";
+  return `${what} ${entry.what}${by}${result}${digest}`;
+}
+
+/** The root a card sits in, by terragucci's path, from /api/terragucci's roots: a card id is `<member>/<root name>/…`. */
+export function rootOfCard(marksAnswer, nodeId) {
+  if (!marksAnswer || !marksAnswer.roots || !nodeId) return null;
+  let best = null;
+  for (const r of marksAnswer.roots) {
+    const prefix = `${r.member}/${r.name}/`;
+    if (nodeId.startsWith(prefix) && (!best || prefix.length > best.prefix.length)) best = { prefix, path: r.path };
+  }
+  return best ? best.path : null;
+}
+
+/** The lane's rows, newest first, of `root` when given. Each row: its clock, its line, its tone, and its links. */
+export function laneRows(answer, { root = null, now = new Date() } = {}) {
+  if (!answer || !answer.entries) return [];
+  const entries = root ? answer.entries.filter((e) => (e.roots || []).includes(root)) : answer.entries;
+  return entries.map((e) => {
+    const links = [];
+    if (e.run && e.run.report) links.push({ text: "report", href: hrefOf(answer, e.run.report) });
+    if (e.run && e.run.job_url) links.push({ text: "job", href: e.run.job_url });
+    if (e.evidence && e.evidence.source === "ledger" && /^https?:\/\//.test(e.evidence.url || "")) links.push({ text: "ledger commit", href: e.evidence.url });
+    return {
+      id: e.id,
+      when: `${clock(e.at, now)}, ${ago(e.at, now)}`,
+      text: entryLine(e),
+      tone: toneOf(e),
+      title: [e.at, e.roots && e.roots.length ? `roots: ${e.roots.join(", ")}` : "", e.run && e.run.commit ? `commit ${e.run.commit}` : "", e.run && e.run.pull_request ? `PR #${e.run.pull_request}` : ""].filter(Boolean).join("\n"),
+      links,
+    };
+  });
+}
+
+/** The line over the lane: whose record, how many entries, or that the source has none. */
+export function laneLegend(answer, { root = null, shown = 0 } = {}) {
+  if (!answer) return "audit record not read";
+  if (answer.error) return answer.error;
+  if (answer.absent) return answer.absent;
+  if (!shown) return root ? `the audit record names no entry for ${root}` : `the audit record holds no entry for ${answer.project || "this project"}`;
+  const more = !root && answer.total > answer.entries.length ? ` of ${answer.total}` : "";
+  return `${shown}${more} entr${shown === 1 ? "y" : "ies"} from terragucci's audit record${root ? ` for ${root}` : ""}, newest first`;
+}
+
+/** The lane as DOM: a legend line and one row per entry. Browser-only (the tests take the pure functions above). */
+export function laneElement(answer, opts = {}) {
+  const rows = laneRows(answer, opts);
+  const box = document.createElement("div");
+  box.className = "tg-timeline";
+  const head = document.createElement("div");
+  head.className = answer && answer.error ? "tg-refusal" : "tg-legend";
+  head.textContent = laneLegend(answer, { root: opts.root || null, shown: rows.length });
+  if (answer && answer.remedy) head.title = answer.remedy;
+  box.appendChild(head);
+  for (const r of rows) {
+    const row = document.createElement("div");
+    row.className = `tg-entry tg-${r.tone}`;
+    row.title = r.title;
+    const when = document.createElement("span");
+    when.className = "tg-when";
+    when.textContent = r.when;
+    const text = document.createElement("span");
+    text.textContent = ` ${r.text}`;
+    row.append(when, text);
+    for (const l of r.links) {
+      const a = document.createElement("a");
+      a.textContent = l.text;
+      a.href = l.href;
+      a.target = "_blank";
+      a.rel = "noopener";
+      row.append(" · ", a);
+    }
+    box.appendChild(row);
+  }
+  return box;
+}

package/web/terragucci-timeline.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import { entryLine, laneLegend, laneRows, rootOfCard, toneOf } from "./terragucci-timeline.js";
+
+// #506: the lane's words, from answers shaped like /api/terragucci/timeline.
+const NOW = new Date("2026-10-08T13:31:00Z");
+const answer = {
+  project: "github.com/acme/shop",
+  files: "/api/terragucci/file?key=",
+  record: { key: "audit.jsonl", present: true },
+  total: 3,
+  limit: 200,
+  entries: [
+    { id: "c", kind: "apply", at: "2026-10-08T09:31:00.000Z", who: null, what: "wave-2", wave: 2, digest: "jcs1-sha256:2e0fba16ce38925adf41", result: "waiting", roots: ["envs/staging/orders"], run: { report: "github.com/acme/shop/r2/report.html", job_url: "https://ci/9131" }, evidence: { source: "report" } },
+    { id: "b", kind: "approval", at: "2026-10-08T09:20:00.000Z", who: "dana", what: "wave-1", digest: null, result: "unsigned", roots: ["envs/dev/orders"], run: {}, evidence: { source: "ledger", url: "https://github.com/acme/shop/commit/7f1e" } },
+    { id: "a", kind: "refused", at: "2026-10-06T09:00:00.000Z", who: "lee", what: "wave-1", digest: null, result: "changed-after-approval", roots: ["envs/dev/orders"], run: {}, evidence: { source: "report" } },
+  ],
+};
+
+describe("the timeline lane (#506)", () => {
+  it("words an entry by its kind, who and result", () => {
+    expect(entryLine(answer.entries[0])).toBe("apply wave-2: waiting · plan 2e0fba16ce38");
+    expect(entryLine(answer.entries[1])).toBe("approved wave-1 by dana: unsigned");
+  });
+
+  it("draws refusals and failures as failed, waits as pending", () => {
+    expect(answer.entries.map(toneOf)).toEqual(["wave", "ok", "failed"]);
+    expect(toneOf({ kind: "approval-revoked", result: "revoked" })).toBe("drift");
+  });
+
+  it("dates every row and links its report through the file route, its job and its ledger commit", () => {
+    const rows = laneRows(answer, { now: NOW });
+    expect(rows.map((r) => r.when)).toEqual(["09:31 UTC, 4h ago", "09:20 UTC, 4h ago", "2026-10-06 09:00 UTC, 2d ago"]);
+    expect(rows[0].links).toEqual([
+      { text: "report", href: "/api/terragucci/file?key=github.com%2Facme%2Fshop%2Fr2%2Freport.html" },
+      { text: "job", href: "https://ci/9131" },
+    ]);
+    expect(rows[1].links).toEqual([{ text: "ledger commit", href: "https://github.com/acme/shop/commit/7f1e" }]);
+    // In an export the key is relative to the bucket.
+    expect(laneRows({ ...answer, files: "../../" }, { now: NOW })[0].links[0].href).toBe("../../github.com/acme/shop/r2/report.html");
+  });
+
+  it("keeps a root's entries for a card's inspect pane", () => {
+    expect(laneRows(answer, { root: "envs/dev/orders", now: NOW }).map((r) => r.id)).toEqual(["b", "a"]);
+    const marks = { roots: [{ member: "tg-example", name: "envs-dev-orders", path: "envs/dev/orders" }, { member: "tg-example", name: "envs-dev", path: "envs/dev" }] };
+    expect(rootOfCard(marks, "tg-example/envs-dev-orders/module.service/aws_sqs_queue.jobs")).toBe("envs/dev/orders");
+    expect(rootOfCard(marks, "other/x")).toBeNull();
+  });
+
+  it("says when the source has no record, rather than that nothing happened", () => {
+    expect(laneLegend({ ...answer, entries: [], record: { present: false }, absent: "/r has no audit.jsonl: …" })).toBe("/r has no audit.jsonl: …");
+    expect(laneLegend({ ...answer, entries: [] }, { shown: 0 })).toBe("the audit record holds no entry for github.com/acme/shop");
+    expect(laneLegend(answer, { root: "envs/prod/search", shown: 0 })).toBe("the audit record names no entry for envs/prod/search");
+    expect(laneLegend({ ...answer, total: 250 }, { shown: 3 })).toBe("3 of 250 entries from terragucci's audit record, newest first");
+    expect(laneLegend({ error: "audit.jsonl in /r, line 2, is not JSON.", code: "terragucci-report" })).toContain("line 2");
+  });
+});