@intentius/behold 0.24.0 → 0.26.0

package/web/terragucci-timeline.js

@@ -0,0 +1,195 @@
+// #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;
+}
+
+// #522: the gate ledgers' history on chant/lifecycle, from
+// /api/lifecycle/history (chant's gate-audit over `git log -p`). Drawn beside
+// the audit record, or alone when the source has no audit.jsonl, and labelled
+// "ledger" so the two are never mistaken for each other.
+
+const HISTORY_WORDS = {
+  "approval-requested": "approval requested",
+  approved: "approved",
+  "override-requested": "override requested",
+  "override-recorded": "policy overridden",
+  applied: "applied",
+  "override-spent": "override spent",
+};
+
+/** One ledger entry as a line: "approved wave-2 by dana: unsigned · plan 4be1…". */
+export function historyLine(entry) {
+  const what = entry.kind === "revoked" ? `${entry.subject || "approval"} revoked` : HISTORY_WORDS[entry.kind] || entry.kind;
+  const op = entry.op && entry.op !== "tf-apply" ? ` (${entry.op})` : "";
+  const by = entry.actor ? ` by ${entry.actor}` : "";
+  const seal = entry.seal && (entry.kind === "approved" || entry.kind === "override-recorded") ? `: ${entry.seal}` : "";
+  const digest = entry.digest ? ` · plan ${entry.digest.replace(/^(jcs1-)?sha256:/, "").slice(0, 12)}` : "";
+  return `${what} ${entry.gate}${op}${by}${seal}${digest}`;
+}
+
+/** The history's rows, newest first: clock, line, tone, and the line's file, commit and committer in the title. */
+export function historyRows(answer, { now = new Date() } = {}) {
+  if (!answer || !answer.entries) return [];
+  return answer.entries.map((e) => {
+    const s = e.source || {};
+    const commit = s.commit ? `${s.change === "removed" ? "removed" : "added"} in ${s.commit.slice(0, 12)}${s.committer ? ` by ${s.committer}` : ""}${s.committed ? ` at ${s.committed}` : ""}` : "";
+    return {
+      id: e.id,
+      when: `${clock(e.at, now)}, ${ago(e.at, now)}`,
+      text: historyLine(e),
+      tone: e.kind === "revoked" ? "drift" : e.kind.endsWith("-requested") ? "wave" : "ok",
+      title: [e.at, `${s.path}${s.line ? `:${s.line}` : ""}`, commit, e.note || ""].filter(Boolean).join("\n"),
+    };
+  });
+}
+
+/** The line over the history: its source, how many entries, where it was read from and how old. */
+export function historyLegend(answer, { shown = 0 } = {}) {
+  if (!answer) return "ledger history not read";
+  if (answer.error) return answer.error;
+  if (!answer.found) return `ledger: ${answer.note}`;
+  if (!shown) return `ledger: no gate record on ${answer.branch}`;
+  const more = answer.total > shown ? ` of ${answer.total}` : "";
+  const via = answer.via === "checkout-ref" ? " (the checkout's copy: the fetch failed)" : "";
+  const tip = answer.commit ? `, tip committed ${answer.commit.committed}` : "";
+  return `ledger: ${shown}${more} entr${shown === 1 ? "y" : "ies"} from the gate ledgers on ${answer.branch}${via}${tip}, newest first`;
+}
+
+/** The history as DOM. Browser-only (the tests take the pure functions above). */
+export function historyElement(answer, opts = {}) {
+  const rows = historyRows(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 = historyLegend(answer, { shown: rows.length });
+  if (answer && answer.note) head.title = answer.note;
+  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);
+    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");
+  });
+});

package/web/workspace-gates.js

@@ -18,6 +18,7 @@ export function gateCards(answer, { embed = false, member = null } = {}) {
   const all = (answer && answer.gates) || [];
   const shown = member ? all.filter((g) => g.member === member) : all;
   const cards = shown.map((g) => {
+    if (g.override) return overrideCard(g);
     const facts = [`${g.approvals.length} of ${g.needed} approval${g.needed === 1 ? "" : "s"}`];
     if (g.env) facts.push(`env ${g.env}`);
     if (g.planDigest) facts.push(`plan ${shortDigest(g.planDigest)}`);
@@ -38,6 +39,34 @@ export function gateCards(answer, { embed = false, member = null } = {}) {
   return { cards, elsewhere, refusal: (answer && answer.refusal) || null };
 }
 
+/**
+ * #519: a policy denial. chant's override needs the denied rules and a
+ * person's reason, so the card shows them and the command to run, and never a
+ * button, framed or not. An override that counts reads as overridden until a
+ * run applies it, then as spent.
+ */
+export function overrideCard(g) {
+  const o = g.override;
+  const facts = [];
+  facts.push(o.rules.length ? `denied by ${o.rules.join(", ")}` : "denied by rules the ledger did not name");
+  if (o.plan) facts.push(`plan ${shortDigest(o.plan)}`);
+  if (o.digest) facts.push(`override digest ${shortDigest(o.digest)}`);
+  if (g.recordedAt) facts.push(`denied ${g.recordedAt}`);
+  if (o.source) facts.push(`from ${o.source}`);
+  const card = { key: g.key, member: g.member, facts: facts.join(" · "), command: o.command, override: o.state };
+  if (o.state === "spent") {
+    card.title = `${g.member}: the override of ${o.subject} is spent`;
+    card.note = `a run applied under it${o.spentAt ? ` at ${o.spentAt}` : ""}; a new denial needs a new override`;
+  } else if (o.state === "overridden") {
+    card.title = `${g.member}: ${o.subject} is overridden`;
+    card.note = "an override counts for this plan; the next run applies it once";
+  } else {
+    card.title = `${g.member}: the policy denied ${o.subject}`;
+    card.note = `a reason is required. Override it at your shell: ${o.command}`;
+  }
+  return card;
+}
+
 function shortDigest(d) {
   const s = String(d).replace(/^sha256:/, "");
   return s.length > 12 ? s.slice(0, 12) : s;

package/web/yodel-report.js

@@ -0,0 +1,99 @@
+// #526: SQL Yodeler's report and drift, read from files by /api/yodel-report.
+// Pure helpers; app.js places the marks and draws the panel. A mark is a
+// dated corner tag, never a fill: none of this is live.
+import { ago, clock } from "./terragucci.js";
+
+/** The ids of the cards an object names: the id itself, or a member's `<member>/<name>`. */
+export function cardsFor(object, ids) {
+  return ids.filter((id) => id === object || id.endsWith("/" + object));
+}
+
+/** Join the read's marks onto the drawn card ids: marks by card, and the objects no card is. */
+export function joinMarks(answer, ids) {
+  const cards = {};
+  const unmatched = [];
+  for (const m of (answer && answer.marks) || []) {
+    const hit = cardsFor(m.object, ids);
+    if (hit.length === 0) unmatched.push(m);
+    for (const id of hit) (cards[id] ||= []).push(m);
+  }
+  return { cards, unmatched };
+}
+
+/** When and from where, in words: "drift-prod.json, written 06:04 UTC, 4h ago". */
+export function datedWords(dated, now = new Date()) {
+  const how = dated.by === "generatedAt" ? "generated" : "written";
+  return `${dated.file}, ${how} ${clock(dated.at, now)}, ${ago(dated.at, now)}`;
+}
+
+/** One mark as a line: "prod: changed out of band (ttl) · drift-prod.json, written 06:04 UTC, 4h ago". */
+export function markLine(m, now = new Date()) {
+  const paths = m.changes.map((c) => c.path).filter(Boolean);
+  return `${m.environment}: ${m.words}${paths.length ? ` (${paths.join(", ")})` : ""} · ${datedWords(m.dated, now)}`;
+}
+
+/** The corner tag for a card's marks: "drift prod · 4h", the age of the newest. */
+export function cornerText(marks, now = new Date()) {
+  const envs = [...new Set(marks.map((m) => m.environment))].join(", ");
+  const newest = marks.map((m) => m.dated.at).sort().pop();
+  const s = Math.max(0, (now.getTime() - Date.parse(newest)) / 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 `drift ${envs} · ${age}`;
+}
+
+/** The panel's lines for one environment, from the report. */
+export function environmentLines(e, now = new Date()) {
+  const lines = [];
+  if (e.error) lines.push(`could not be read: ${e.error}`);
+  const newest = e.applied[e.applied.length - 1];
+  lines.push(
+    `${e.applied.length} applied` +
+      (newest ? `, newest ${newest.id}${newest.at ? ` at ${clock(newest.at, now)}` : ""}${newest.by ? ` by ${newest.by}` : ""}` : ""),
+  );
+  for (const m of e.other) lines.push(`${m.id}: ${m.state}${m.inDirectory ? "" : " (not in the directory)"}`);
+  for (const g of e.gaps) lines.push(`gap (${g.kind}): ${g.detail}`);
+  for (const n of e.notes) lines.push(`note: ${n}`);
+  return lines;
+}
+
+/** The panel's head: what was read, how it was checked, and when. */
+export function legend(answer, now = new Date()) {
+  const v = answer.validation;
+  const checked = v.from === "package" ? `@intentius/sql-yodeler ${v.sqlYodeler}'s schemas` : `behold's pinned copy of SQL Yodeler's schemas (${v.commit})`;
+  const what = answer.report ? `${answer.report.file}, generated ${clock(answer.report.generatedAt, now)}, ${ago(answer.report.generatedAt, now)}` : "no report";
+  return { text: `SQL Yodeler, not live · ${what} · ${answer.drift.length} drift file${answer.drift.length === 1 ? "" : "s"}`, title: `Read from ${answer.source}, checked against ${checked}. behold never runs yodel or reads the database.` };
+}
+
+// #537: the report's audit entries. Each is dated by its own `at` and says
+// where SQL Yodeler read it: a gate ledger on chant/lifecycle, or a row of
+// the environment's history table.
+const AUDIT_WORDS = {
+  "approval-requested": "approval asked",
+  approved: "approved",
+  override: "overridden",
+  silenced: "silenced",
+  applied: "applied",
+  refused: "refused",
+  failed: "failed",
+  repaired: "repaired",
+  reverted: "reverted",
+  step: "step",
+};
+
+/** Where an entry came from: "ledger <l>, <op>/<gate>" or "<history> row <seq>, run <run>". */
+export function auditSource(a) {
+  const s = a.source || {};
+  if (s.ledger !== undefined) return `chant/lifecycle ledger ${s.ledger}, ${s.op}/${s.gate}`;
+  if (s.history !== undefined) return `${s.history} row ${s.seq}, run ${s.run}`;
+  return "an unnamed source";
+}
+
+/** One entry as a line and its source line. Pure. */
+export function auditLines(a, now = new Date()) {
+  const what = [AUDIT_WORDS[a.kind] || a.kind, a.migration || "", a.by ? `by ${a.by}` : ""].filter(Boolean).join(" ");
+  const extra = [a.detail || "", a.digest ? `plan ${String(a.digest).replace(/^(jcs1-)?sha256:/, "").slice(0, 12)}` : "", a.wave ? `wave gate ${a.wave.gate} ${a.wave.status === "approved" ? "approved" : "needed no approval"}` : ""].filter(Boolean);
+  return {
+    text: `${what}${extra.length ? ` (${extra.join(", ")})` : ""} · ${clock(a.at, now)}, ${ago(a.at, now)}`,
+    source: `from ${auditSource(a)}, in ${a.file}`,
+  };
+}

package/web/yodel-report.test.js

@@ -0,0 +1,18 @@
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { readYodelReport, yodelValidator } from "../src/yodel-report.ts";
+import { cardsFor, joinMarks, markLine } from "./yodel-report.js";
+
+const fx = join(import.meta.dirname, "..", "src", "__fixtures__", "yodel-report");
+
+describe("yodel report marks on cards (#526)", () => {
+  it("places drift on the example's table cards and lists the rest", () => {
+    const r = readYodelReport(join(fx, "good"), yodelValidator([]));
+    const j = joinMarks(r, ["shop/orders", "shop/shopSchema"]);
+    expect(Object.keys(j.cards)).toEqual(["shop/orders"]);
+    expect(j.unmatched.map((m) => m.object)).toEqual(["ordersStatusIdx"]);
+    expect(cardsFor("orders", ["orders", "x/orders", "ordersX"])).toEqual(["orders", "x/orders"]);
+    expect(markLine(j.cards["shop/orders"][0], new Date("2026-10-11T10:00:00Z"))).toContain("prod: changed out of band (columns[2].default) · drift-prod.json, written");
+  });
+
+});