@intentius/behold 0.11.0 → 0.12.0

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);
+    }
+  });
+});