@intentius/behold 0.25.0 → 0.27.0

package/web/terragucci-timeline.js

@@ -116,3 +116,80 @@ export function laneElement(answer, opts = {}) {
   }
   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/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");
+  });
+
+});