@intentius/behold 0.10.1 → 0.12.0

package/web/operator.test.js

@@ -0,0 +1,158 @@
+// #234 joins 3 + 1: the pure half of web/operator.js, tested the way
+// web/run-playhead.js (#284) is — no DOM, no jsdom, no browser. Everything the
+// strip DECIDES (which loops get a row, how a lease reads, what the approve
+// button says it does) is a function from data to data; the DOM half is
+// smoke/ui-smoke.mjs's job.
+import { describe, it, expect } from "vitest";
+import {
+  hasOperator,
+  operatorRefusal,
+  operatorRows,
+  leaseText,
+  operatorHeadline,
+  convergeGates,
+  APPROVE_SEMANTICS,
+  APPROVED_SEMANTICS,
+  CONVERGE_LOOP_LINE,
+  ONE_TICK_CAVEAT,
+  LEASE_LABEL,
+} from "./operator.js";
+
+/** src/operator.ts's OperatorState, as the server broadcasts it. Values trace to
+ * chant's own operator tests — see src/operator.test.ts's provenance note. */
+const declared = [{ name: "staging-converge", env: "staging", dial: "apply" }];
+const stripRow = {
+  op: "staging-converge",
+  env: "staging",
+  log: "converge(staging): drifted=1 remediated=0 reported=0 skipped-budget=0 skipped-flap=0 gated=1 unobserved=0 adopted=0",
+  at: "2026-01-01T00:00:00.000Z",
+  lease: "held",
+  leaseHolder: "op-a",
+  leaseExpiresAt: "2026-01-01T00:05:00.000Z",
+  pendingGates: 1,
+};
+const gate = {
+  loop: "converge",
+  rule: "drift-apply",
+  op: "fountain-apply",
+  gate: "rollout-gate",
+  convergeOp: "staging-converge",
+  env: "staging",
+  since: "2026-01-01T00:00:00.000Z",
+  semantics: APPROVE_SEMANTICS,
+  approve: {
+    method: "POST",
+    path: "/api/operator/approve/fountain-apply/rollout-gate",
+    command: "chant approve fountain-apply rollout-gate",
+  },
+};
+const state = {
+  declared,
+  strip: { rows: [stripRow], pendingGates: 1 },
+  gates: [gate],
+  note: null,
+  code: null,
+  readAt: "2026-01-01T00:02:00.000Z",
+};
+const NOW = Date.parse("2026-01-01T00:02:00.000Z");
+
+describe("hasOperator", () => {
+  it("gates the strip on a DECLARED loop, never on a status read having answered", () => {
+    expect(hasOperator(null)).toBe(false);
+    expect(hasOperator({ declared: [] })).toBe(false);
+    // Declared, never read: the strip still appears and says so.
+    expect(hasOperator({ declared, strip: null })).toBe(true);
+  });
+});
+
+describe("operatorRefusal", () => {
+  it("is null on a clean read", () => {
+    expect(operatorRefusal(state)).toBeNull();
+  });
+
+  it("states a refusal plainly for each of the three ways a read can fail", () => {
+    for (const code of ["no-operator", "no-operator-cli", "operator-status"]) {
+      const r = operatorRefusal({ ...state, strip: null, gates: [], note: `something about ${code}`, code });
+      expect(r).toEqual({ code, text: `something about ${code}` });
+    }
+  });
+});
+
+describe("operatorRows", () => {
+  it("prints chant's own tick line verbatim, with the instant and a coarse age", () => {
+    const [row] = operatorRows(state, NOW);
+    expect(row.log).toBe(stripRow.log);
+    expect(row.at).toBe("2026-01-01T00:00:00.000Z");
+    expect(row.ago).toBe("2m");
+  });
+
+  it("keeps a declared loop the last read didn't mention, rather than undercounting", () => {
+    const rows = operatorRows({ ...state, declared: [...declared, { name: "prod-observe", env: "prod" }] }, NOW);
+    expect(rows.map((r) => r.op)).toEqual(["staging-converge", "prod-observe"]);
+    expect(rows[1]).toMatchObject({ log: null, at: null, leaseText: "not in the last status read" });
+  });
+
+  it("says a declared loop has not been read yet before the first ask", () => {
+    const [row] = operatorRows({ ...state, strip: null, gates: [] }, NOW);
+    expect(row.leaseText).toBe("not read yet");
+  });
+});
+
+describe("leaseText", () => {
+  it("always names the holder — 'held' with nobody named is unactionable", () => {
+    expect(leaseText(stripRow)).toBe("lease held by op-a until 2026-01-01T00:05:00.000Z");
+  });
+
+  it("says an expired lease will be reclaimed, not that it is free", () => {
+    expect(leaseText({ ...stripRow, lease: "expired" })).toMatch(/expired \(op-a until .+\) — the next round reclaims it/);
+  });
+
+  it("reads a lease-less row as free", () => {
+    expect(leaseText({ ...stripRow, lease: "free", leaseHolder: null })).toBe(LEASE_LABEL.free);
+  });
+});
+
+describe("operatorHeadline", () => {
+  it("counts the loops, and the gates when a human is owed one", () => {
+    expect(operatorHeadline(state)).toBe("⟳ operating loop — 1 ConvergeOp · 1 gate pending");
+    expect(operatorHeadline({ ...state, gates: [] })).toBe("⟳ operating loop — 1 ConvergeOp");
+  });
+});
+
+describe("the one-tick caveat", () => {
+  it("says the strip is not a timeline, and why", () => {
+    expect(ONE_TICK_CAVEAT).toMatch(/only the last one/);
+    expect(ONE_TICK_CAVEAT).toMatch(/chant#2029/);
+    expect(ONE_TICK_CAVEAT).toMatch(/strip, not a timeline/);
+  });
+});
+
+describe("the converge gate card's words", () => {
+  it("says approving records a fact and does not unblock the dispatch", () => {
+    expect(APPROVE_SEMANTICS).toMatch(/records a fact/);
+    expect(APPROVE_SEMANTICS).toMatch(/does not unblock the dispatch/);
+    expect(APPROVE_SEMANTICS).toMatch(/next tick reads it/);
+    expect(APPROVED_SEMANTICS).toBe("recorded; the next tick acts on it");
+  });
+
+  it("names its loop, so it can't be read as the Temporal run gate", () => {
+    expect(CONVERGE_LOOP_LINE).toMatch(/converge loop/);
+    expect(CONVERGE_LOOP_LINE).toMatch(/chant approve/);
+    expect(CONVERGE_LOOP_LINE).toMatch(/not the Temporal run gate/);
+  });
+
+  it("carries the delegated write it performs, and no URL (chant#2028)", () => {
+    const [g] = convergeGates(state);
+    expect(g.approve).toEqual({
+      method: "POST",
+      path: "/api/operator/approve/fountain-apply/rollout-gate",
+      command: "chant approve fountain-apply rollout-gate",
+    });
+    expect(JSON.stringify(g)).not.toMatch(/https?:/);
+  });
+
+  it("has no cards when nothing is pending", () => {
+    expect(convergeGates({ ...state, gates: [] })).toEqual([]);
+    expect(convergeGates(null)).toEqual([]);
+  });
+});

package/web/run-playhead.js

@@ -0,0 +1,194 @@
+/**
+ * The run playhead's panel (#284 item 2) — the SPA half of src/run-playhead.ts.
+ *
+ * Same discipline as web/carve-steps.js, web/json-view.js and
+ * web/layout-store.js: everything this panel DECIDES is a pure function that
+ * takes data and returns data, unit-tested next door in run-playhead.test.js;
+ * the DOM half at the bottom is smoke/ui-smoke.mjs's job. The fetches, the SSE
+ * subscription and the graph re-pull all stay in app.js.
+ *
+ * What it renders, from the `runState` the server broadcasts:
+ *  - one honest verdict line — and there is deliberately no wording for
+ *    "probably finished". A stream that died says so.
+ *  - the pending gate as a first-class card (#234): who is waiting, since when,
+ *    what it holds back, and an Approve button that POSTs the EXISTING
+ *    op-signal route. behold never signals on its own initiative.
+ *  - the settled steps, in the order they settled.
+ */
+
+/** Settled-step tones, in the same token vocabulary the apply progress panel
+ * uses (`APPLY_STATUS_COLOR` in app.js) so "green means it worked" reads the
+ * same everywhere. */
+export const RUN_STEP_COLOR = {
+  ok: "var(--managed)",
+  fail: "var(--degraded)",
+  skipped: "var(--muted)",
+};
+
+/** How the run as a whole reads. `lost` is its own tone, not a shade of
+ * failure: behold does not know what happened, which is a different statement
+ * from "it failed". */
+export const RUN_STATUS_COLOR = {
+  idle: "var(--muted)",
+  running: "var(--pending)",
+  ok: "var(--managed)",
+  failed: "var(--degraded)",
+  lost: "var(--foreign)",
+};
+
+/** `1062` → `1.1s`. */
+export function took(ms) {
+  return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+
+/**
+ * How long a gate has been waiting, from its ISO `since`. Coarse on purpose —
+ * an approval that has been pending "3h" is the fact; the second it started
+ * is on the card as the raw instant.
+ */
+export function waitingFor(since, now = Date.now()) {
+  const t = Date.parse(since);
+  if (!Number.isFinite(t)) return null;
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h`;
+  return `${Math.floor(s / 86400)}d`;
+}
+
+/**
+ * The one-line verdict, or null when there is nothing to say at all.
+ *
+ * Every branch states what behold KNOWS. `lost` never borrows the word
+ * "finished", and an adopted run (the gate query answered for a run this
+ * session didn't start) doesn't claim zero settled steps as if it had watched.
+ */
+export function runVerdict(run) {
+  if (!run || !run.op) return null;
+  const n = (run.records || []).length;
+  const settled = `${n} step${n === 1 ? "" : "s"} settled`;
+  if (run.status === "idle") {
+    return { text: `${run.op}: no per-step records — this session didn't start the run`, tone: "idle" };
+  }
+  if (run.status === "running") {
+    return {
+      text:
+        run.mode === "local"
+          ? `${run.op}: running on the local executor — steps arrive together when it ends`
+          : `${run.op}: running — ${settled}`,
+      tone: "running",
+    };
+  }
+  if (run.status === "ok") return { text: `${run.op}: exited cleanly — ${settled}`, tone: "ok" };
+  if (run.status === "failed") return { text: `${run.op}: a step failed — ${settled}`, tone: "failed" };
+  return { text: `${run.op}: stream lost — frozen at ${settled}`, tone: "lost" };
+}
+
+/** The settled steps, in arrival order, as rows. */
+export function stepRows(run) {
+  return (run?.records || []).map((r) => ({
+    label: `${r.phase} · ${r.fn}`,
+    status: r.status,
+    took: r.status === "skipped" ? "skipped" : took(r.durationMs),
+    error: r.error || null,
+  }));
+}
+
+/**
+ * The pending gate card (#234), from the run state alone.
+ *
+ * `guards` and `node` come from the graph's own answer (`meta.gate`, built by
+ * src/run-playhead.ts's `pendingGateCard`) when the ops lens has been loaded;
+ * this is the fallback so the card still appears on the Deploy tab of a session
+ * that never opened the lens. `approve` is stated, not implied — it is the same
+ * delegated write the existing gate button performs.
+ */
+export function gateCardFrom(run) {
+  if (!run || !run.op || !run.gate) return null;
+  return {
+    op: run.op,
+    signalName: run.gate.signalName,
+    description: run.gate.description || undefined,
+    since: run.gate.since,
+    approve: {
+      method: "POST",
+      path: `/api/ops/${encodeURIComponent(run.op)}/signal/${encodeURIComponent(run.gate.signalName)}`,
+    },
+  };
+}
+
+/** Does the panel have anything to show at all? */
+export function hasPlayhead(run) {
+  return Boolean(run && (run.op || (run.records && run.records.length)));
+}
+
+// ── the DOM half ─────────────────────────────────────────────────────────────
+
+function el(tag, cls, text) {
+  const n = document.createElement(tag);
+  if (cls) n.className = cls;
+  if (text !== undefined) n.textContent = text;
+  return n;
+}
+
+/**
+ * Render the playhead panel into `host` (cleared first — the whole subtree is
+ * rebuilt per event, exactly as renderDial() does).
+ *
+ * `card` is the graph's richer pending-gate answer when one has been loaded,
+ * else null. `actions.approve(op, signalName)` performs the delegated signal.
+ */
+export function renderPlayhead(host, run, card, actions = {}) {
+  host.textContent = "";
+  const verdict = runVerdict(run);
+  if (!verdict) return host;
+
+  const line = el("div", "run-verdict", verdict.text);
+  line.style.color = RUN_STATUS_COLOR[verdict.tone] || "var(--muted)";
+  host.appendChild(line);
+
+  if (run.lost) host.appendChild(el("div", "run-lost", run.lost));
+  if (run.gateNote) host.appendChild(el("div", "run-lost", `Gate state unavailable — ${run.gateNote}`));
+
+  const gate = card || gateCardFrom(run);
+  if (gate) host.appendChild(renderGateCard(gate, actions));
+
+  const rows = stepRows(run);
+  if (rows.length) {
+    const list = el("div", "run-steps");
+    for (const r of rows) {
+      const row = el("div", "run-step");
+      const dot = el("span", "run-dot");
+      dot.style.background = RUN_STEP_COLOR[r.status] || "var(--muted)";
+      row.appendChild(dot);
+      row.appendChild(el("span", "grow", r.label));
+      row.appendChild(el("span", "run-took", r.took));
+      if (r.error) row.title = r.error;
+      list.appendChild(row);
+    }
+    host.appendChild(list);
+  }
+  return host;
+}
+
+/**
+ * The pending-approval card. Its button is the delegated write, and the card
+ * says so out loud: behold triggers Ops and signals gates a human presses; it
+ * never approves anything on its own initiative.
+ */
+export function renderGateCard(gate, actions = {}) {
+  const box = el("div", "run-gate");
+  box.appendChild(el("div", "run-gate-title", `⏸ waiting for approval — ${gate.signalName}`));
+  if (gate.description) box.appendChild(el("div", "run-gate-desc", gate.description));
+  const waited = waitingFor(gate.since);
+  box.appendChild(
+    el("div", "run-gate-meta", `${gate.op} · pending ${waited ? `${waited} ` : ""}since ${gate.since}`),
+  );
+  if (gate.guards) box.appendChild(el("div", "run-gate-meta", `holds back: ${gate.guards}`));
+
+  const approve = el("button", "approve", `Approve ${gate.signalName}`);
+  approve.title = `${gate.approve.method} ${gate.approve.path} — the same delegated signal as chant run signal ${gate.op} ${gate.signalName}. behold never approves on its own.`;
+  approve.addEventListener("click", () => actions.approve?.(gate.op, gate.signalName));
+  box.appendChild(approve);
+  return box;
+}

package/web/run-playhead.test.js

@@ -0,0 +1,134 @@
+// #284 item 2: the pure half of web/run-playhead.js, tested the way
+// web/carve-steps.js (#254), web/json-view.js (#259) and web/layout-store.js
+// (#245) are — no DOM, no jsdom, no browser. Everything the panel DECIDES
+// (what the run's verdict is, how long a gate has been waiting, what the
+// approve button POSTs) is a function from data to data; the DOM half is
+// smoke/ui-smoke.mjs's job.
+import { describe, it, expect } from "vitest";
+import { runVerdict, stepRows, gateCardFrom, hasPlayhead, took, waitingFor } from "./run-playhead.js";
+
+const base = {
+  op: "playhead-probe",
+  mode: "temporal",
+  status: "running",
+  records: [],
+  gate: null,
+  gateNote: null,
+  startedAt: "2026-08-29T18:00:00.000Z",
+  endedAt: null,
+  lost: null,
+};
+const withRecords = (n) => ({
+  ...base,
+  records: Array.from({ length: n }, (_, i) => ({ phase: "P", fn: `f${i}`, status: "ok", durationMs: 1000 })),
+});
+
+describe("took", () => {
+  it("reads sub-second in ms and the rest in seconds", () => {
+    expect(took(5)).toBe("5ms");
+    expect(took(1062)).toBe("1.1s");
+  });
+});
+
+describe("waitingFor", () => {
+  const now = Date.parse("2026-08-29T18:30:00.000Z");
+  it("coarsens the wait, keeping the raw instant for the card", () => {
+    expect(waitingFor("2026-08-29T18:29:30.000Z", now)).toBe("30s");
+    expect(waitingFor("2026-08-29T18:00:00.000Z", now)).toBe("30m");
+    expect(waitingFor("2026-08-29T15:00:00.000Z", now)).toBe("3h");
+    expect(waitingFor("2026-08-26T18:00:00.000Z", now)).toBe("3d");
+  });
+
+  it("answers nothing rather than a wrong duration for an unreadable instant", () => {
+    expect(waitingFor("soon", now)).toBeNull();
+    expect(waitingFor("", now)).toBeNull();
+  });
+});
+
+describe("runVerdict", () => {
+  it("has nothing to say before anything has run", () => {
+    expect(runVerdict(null)).toBeNull();
+    expect(runVerdict({ op: null, status: "idle", records: [] })).toBeNull();
+  });
+
+  it("never calls a lost stream finished", () => {
+    const v = runVerdict({ ...withRecords(3), status: "lost", lost: "the stream ended" });
+    expect(v.tone).toBe("lost");
+    expect(v.text).toContain("frozen at 3 steps settled");
+    expect(v.text).not.toMatch(/complete|finished|done/i);
+  });
+
+  it("distinguishes a clean exit from a failed step", () => {
+    expect(runVerdict({ ...withRecords(2), status: "ok" })).toMatchObject({ tone: "ok" });
+    expect(runVerdict({ ...withRecords(2), status: "failed" }).text).toContain("a step failed");
+  });
+
+  it("explains why a local run shows nothing until it ends", () => {
+    expect(runVerdict({ ...base, mode: "local" }).text).toContain("steps arrive together when it ends");
+  });
+
+  it("doesn't claim to have watched a run it didn't start", () => {
+    const v = runVerdict({ ...base, status: "idle" });
+    expect(v.text).toContain("this session didn't start the run");
+    expect(v.text).not.toContain("0 steps");
+  });
+});
+
+describe("stepRows", () => {
+  it("keeps arrival order and labels a skip as a skip, not a duration", () => {
+    const rows = stepRows({
+      records: [
+        { phase: "Build", fn: "chantBuild", status: "ok", durationMs: 1062 },
+        { phase: "Verify", fn: "httpCheck", status: "fail", durationMs: 15164, error: "fetch failed" },
+        { phase: "Never", fn: "httpCheck", status: "skipped", durationMs: 0 },
+      ],
+    });
+    expect(rows.map((r) => `${r.label} ${r.took}`)).toEqual([
+      "Build · chantBuild 1.1s",
+      "Verify · httpCheck 15.2s",
+      "Never · httpCheck skipped",
+    ]);
+    expect(rows[1].error).toBe("fetch failed");
+    expect(rows[0].error).toBeNull();
+  });
+
+  it("survives a state with no records at all", () => {
+    expect(stepRows(null)).toEqual([]);
+    expect(stepRows({})).toEqual([]);
+  });
+});
+
+describe("gateCardFrom", () => {
+  it("is null unless a gate was actually NAMED — a stalled track is not a gate", () => {
+    expect(gateCardFrom(base)).toBeNull();
+    expect(gateCardFrom({ ...base, gateNote: "no run" })).toBeNull();
+  });
+
+  it("points approve at the existing delegated op-signal route", () => {
+    const card = gateCardFrom({
+      ...base,
+      op: "prod-promote",
+      gate: { signalName: "approve-promote", description: "Approve the prod promotion", since: "2026-08-29T18:00:12.000Z" },
+    });
+    expect(card).toEqual({
+      op: "prod-promote",
+      signalName: "approve-promote",
+      description: "Approve the prod promotion",
+      since: "2026-08-29T18:00:12.000Z",
+      approve: { method: "POST", path: "/api/ops/prod-promote/signal/approve-promote" },
+    });
+  });
+
+  it("escapes names into the signal path", () => {
+    const card = gateCardFrom({ ...base, op: "a b", gate: { signalName: "c/d", since: "x" } });
+    expect(card.approve.path).toBe("/api/ops/a%20b/signal/c%2Fd");
+  });
+});
+
+describe("hasPlayhead", () => {
+  it("is false on a fresh session and true once an Op is being watched", () => {
+    expect(hasPlayhead(null)).toBe(false);
+    expect(hasPlayhead({ op: null, records: [] })).toBe(false);
+    expect(hasPlayhead(base)).toBe(true);
+  });
+});

package/web/theme.test.js

@@ -0,0 +1,35 @@
+// #240: a few pathological palettes (Darkermatrix and friends) leave --muted
+// illegible on --panel because the quieted fg/panel mix lands well under a
+// readable ratio. tokensFor() pushes --muted's OKLCH L away from --panel's
+// until a real WCAG contrast() clears the floor (#229's guaranteed-visible
+// trick for --active, generalised to an actual ratio). smoke/ui-smoke.mjs
+// sweeps all 552 palettes for the same assertion; this pins the exact
+// palette the issue was filed against, with no browser involved.
+import { describe, it, expect } from "vitest";
+import { contrast, desaturate, mix, tokensFor } from "./theme.js";
+import { THEMES } from "./themes.js";
+
+describe("tokensFor — the --muted contrast floor (#240)", () => {
+  it("Darkermatrix's naive fg/panel mix reads at ~1.25:1, the issue's reported ratio — the floor push has to move it", () => {
+    const th = THEMES["Darkermatrix"];
+    const panel = tokensFor(th).panel;
+    // What tokensFor() derived --muted from before #240's floor push:
+    // fg mixed to 0.5, one chroma step down.
+    const naiveMuted = desaturate(mix(th.bg, th.fg, 0.5), 0.75);
+    const ratio = contrast(naiveMuted, panel);
+    expect(ratio).toBeGreaterThan(1.2);
+    expect(ratio).toBeLessThan(1.3);
+  });
+
+  it("clears the 3:1 floor on Darkermatrix after the push", () => {
+    const t = tokensFor(THEMES["Darkermatrix"]);
+    expect(contrast(t.muted, t.panel)).toBeGreaterThanOrEqual(3);
+  });
+
+  it("holds the floor across every shipped palette, not just the one reported", () => {
+    for (const th of Object.values(THEMES)) {
+      const t = tokensFor(th);
+      expect(contrast(t.muted, t.panel)).toBeGreaterThanOrEqual(3);
+    }
+  });
+});