@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/builtin-views/canvas/view.mjs

@@ -0,0 +1,576 @@
+// @ts-check
+/**
+ * Canvas Dashboard — the crtr `canvas` view (the monitor archetype).
+ *
+ * Self-contained ESM. Imports its data layer from `./client.mjs` (which shells
+ * the `crtr` binary) and the shared state helpers from `../_lib/states.mjs`. It
+ * imports NOTHING from crtr — the host injects the `Draw` + `ViewHost` API and
+ * dynamically `import()`s this module's DEFAULT EXPORT.
+ *
+ * A READ-ONLY monitor of the live agent graph: it rebuilds the forest from each
+ * node's `parent` edge, keeps only trees that contain live (active/idle) or
+ * human-blocked work, and renders them as a scrollable ASCII tree. It auto-polls
+ * (refreshMs) — no node-focus / close / swap (views are sessionless). j/k move a
+ * read cursor; g forces a refresh; q quits.
+ *
+ * VISUAL LANGUAGE (crtr-views-visual-design §2/§3/§4): hierarchy is carried by
+ * weight + hue + position, never boxes. The status glyph hues match `canvas
+ * browse`'s authoritative palette (active=green, idle=yellow, done=cyan,
+ * dead=red, canceled=grey; asks=bright-yellow) — "not a recolor." The chrome's
+ * one state chip is host-derived from data freshness (busy→working, an error
+ * banner→blocked, an action banner→attention, else ready/idle), driven here by
+ * toggling banners + the busy lane. Per-row metadata (the relative age) is
+ * right-flushed via `ListItemRow.right`; secondary text recedes via grey+dim so
+ * it survives NO_COLOR. The four standard states come from `_lib/states.mjs`.
+ *
+ * @module canvas/view
+ */
+
+import { fetchNodes, fetchAttention } from './client.mjs';
+import { loadingState, emptyState, notReadyState } from '../_lib/states.mjs';
+
+/** @typedef {import('./client.mjs').CanvasNode} CanvasNode */
+/** @typedef {import('./client.mjs').ClientError} ClientError */
+
+/**
+ * One rendered tree line (a flattened forest node). Width-independent, so it is
+ * built once per refresh and re-rendered on resize without a re-fetch.
+ * @typedef {Object} TreeRow
+ * @property {string} nodeId
+ * @property {string} prefix     Tree-branch art (e.g. "│  └─ "); '' for a root.
+ * @property {string} glyph      Status glyph.
+ * @property {string} status
+ * @property {string} name
+ * @property {string} kind
+ * @property {string} mode
+ * @property {string} lifecycle
+ * @property {string} shortId
+ * @property {string} created    ISO 8601 birth timestamp (drives the right-flush age).
+ * @property {boolean} blocked   True ⇒ this node has pending human asks.
+ * @property {number} askCount
+ */
+
+/**
+ * The view's single mutable state object. The view owns it; hooks mutate it in
+ * place.
+ * @typedef {Object} CanvasState
+ * @property {TreeRow[]} rows      Flattened active-tree forest (render source).
+ * @property {number} cursor       Read cursor into rows (j/k).
+ * @property {number} scroll       draw.list scroll, stored back each frame.
+ * @property {number} shownRoots   How many trees survived the active filter.
+ * @property {number} totalNodes   Total nodes on the canvas (all statuses).
+ * @property {number} activeCount  Nodes with status 'active' (canvas-wide).
+ * @property {number} attnTotal    Total pending human asks (canvas-wide).
+ * @property {number} lastFetch    Epoch ms of the last successful refresh.
+ * @property {string|null} sourceError  Non-null ⇒ the data source failed; the
+ *   string is the cause (drives the not-ready takeover when there is no data, and
+ *   is the dump fallback). Cleared on a successful refresh.
+ */
+
+// ── Status vocabulary (mirrors core/canvas/browse/render.ts — single source) ──
+
+const LIVE_STATUS = new Set(['active', 'idle']);
+
+/** @type {Record<string,string>} */
+const STATUS_GLYPH = {
+  active: '●',
+  idle: '○',
+  done: '✓',
+  dead: '✗',
+  canceled: '⊘',
+};
+
+/**
+ * Load-bearing status hue — NUMERIC SGR codes, matching `canvas browse`'s
+ * STATUS_COLOR exactly (active=green, idle=yellow, done=cyan, dead=red,
+ * canceled=grey). The design is explicit: keep these, "this is not a recolor."
+ * @type {Record<string,string>}
+ */
+const STATUS_FG = {
+  active: '32', // green
+  idle: '33', // yellow
+  done: '36', // cyan
+  dead: '31', // red
+  canceled: '90', // grey
+};
+
+/** @param {string} status @returns {import('../../core/tui/draw.js').Style|undefined} */
+function glyphStyle(status) {
+  const fg = STATUS_FG[status];
+  return fg ? { fg } : undefined; // hue only — the glyph SHAPE is the mono carrier
+}
+
+/**
+ * Name weight = hierarchy (design §2 "weight creates hierarchy"): live work
+ * (active) LEADS in bold; terminal nodes (done/dead/canceled) recede dim; idle
+ * stays default weight (readable, not shouting). Mono-safe (weight, not hue).
+ * @param {string} status @returns {import('../../core/tui/draw.js').Style|undefined}
+ */
+function nameStyle(status) {
+  if (status === 'active') return { bold: true };
+  if (status === 'done' || status === 'dead' || status === 'canceled') return { dim: true };
+  return undefined;
+}
+
+/** @param {string} lifecycle @returns {string} */
+function lifeAbbr(lifecycle) {
+  if (lifecycle === 'resident') return 'res';
+  if (lifecycle === 'terminal') return 'term';
+  return lifecycle || '?';
+}
+
+/** @param {string} id @returns {string} */
+function shortId(id) {
+  const s = String(id || '');
+  const dash = s.indexOf('-');
+  return dash > 0 ? s.slice(0, dash) : s.slice(0, 8);
+}
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/**
+ * Relative-age ladder (design §5): `now` (<60s), `{m}m` (<60m), `{h}h` (<24h),
+ * `{d}d` (<7d), else a calendar date `Mon D` (`Mar 4`), prior-year `Mon ʼYY`.
+ * Max ~5 cols. Used for the right-flushed per-row age (the node's birth time).
+ * @param {string} createdIso @param {number} now @returns {string}
+ */
+function relAge(createdIso, now) {
+  const t = Date.parse(createdIso);
+  if (Number.isNaN(t)) return '';
+  const s = Math.max(0, Math.floor((now - t) / 1000));
+  if (s < 60) return 'now';
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  const d = Math.floor(h / 24);
+  if (d < 7) return `${d}d`;
+  const date = new Date(t);
+  const mon = MONTHS[date.getMonth()] || '?';
+  if (date.getFullYear() === new Date(now).getFullYear()) return `${mon} ${date.getDate()}`;
+  return `${mon} ʼ${String(date.getFullYear()).slice(-2)}`;
+}
+
+/** @param {number} n @param {string} w @returns {string} */
+function plural(n, w) {
+  return `${n} ${w}${n === 1 ? '' : 's'}`;
+}
+
+// ── Error → guidance text ─────────────────────────────────────────────────────
+
+/**
+ * Map a typed {@link ClientError} to guidance text (the host error banner +
+ * dump fallback).
+ * @param {ClientError} error
+ * @returns {string}
+ */
+function bannerFor(error) {
+  switch (error && error.kind) {
+    case 'crtr-missing':
+      return error.message;
+    case 'crtr-failed':
+      return 'crtr command failed: ' + (error.message || 'unknown error');
+    case 'parse':
+      return error.message || 'could not parse crtr output';
+    case 'error':
+      return (error && error.message) || 'Unknown error.';
+    default:
+      return (error && /** @type {any} */ (error).message) || 'Unknown error.';
+  }
+}
+
+// ── Forest builder ───────────────────────────────────────────────────────────
+
+/**
+ * Build the flattened active-tree forest from a flat node list + the
+ * human-blocked id→count map.
+ *
+ * A tree is shown iff its subtree contains any LIVE node (status active|idle) OR
+ * any human-blocked node — so a fully-finished tree drops out, but a blocked one
+ * always surfaces. Shown trees are rendered IN FULL (finished children included)
+ * to preserve context, mirroring `crtr canvas dashboard`.
+ *
+ * @param {CanvasNode[]} nodes
+ * @param {Map<string,number>} blockedById
+ * @returns {{rows: TreeRow[], shownRoots: number}}
+ */
+function buildForest(nodes, blockedById) {
+  /** @type {Map<string, CanvasNode>} */
+  const byId = new Map();
+  for (const n of nodes) byId.set(n.nodeId, n);
+
+  /** @type {Map<string, CanvasNode[]>} */
+  const children = new Map();
+  /** @type {CanvasNode[]} */
+  const roots = [];
+  for (const n of nodes) {
+    const parent = n.parent && byId.has(n.parent) ? n.parent : null;
+    if (parent) {
+      const arr = children.get(parent);
+      if (arr) arr.push(n);
+      else children.set(parent, [n]);
+    } else {
+      roots.push(n);
+    }
+  }
+  // Order siblings + roots by birth time (matches spawn order).
+  const cmp = (/** @type {CanvasNode} */ a, /** @type {CanvasNode} */ b) =>
+    a.created < b.created ? -1 : a.created > b.created ? 1 : 0;
+  for (const arr of children.values()) arr.sort(cmp);
+  roots.sort(cmp);
+
+  // Subtree liveness, memoised + cycle-guarded (the graph is a forest, but the
+  // db is mutable — guard defensively).
+  /** @type {Map<string, boolean>} */
+  const liveMemo = new Map();
+  /** @param {string} id @param {Set<string>} guard @returns {boolean} */
+  function subtreeLive(id, guard) {
+    const memo = liveMemo.get(id);
+    if (memo !== undefined) return memo;
+    if (guard.has(id)) return false;
+    guard.add(id);
+    const node = byId.get(id);
+    let res = !!node && (LIVE_STATUS.has(node.status) || blockedById.has(id));
+    if (!res) {
+      for (const c of children.get(id) || []) {
+        if (subtreeLive(c.nodeId, guard)) {
+          res = true;
+          break;
+        }
+      }
+    }
+    guard.delete(id);
+    liveMemo.set(id, res);
+    return res;
+  }
+
+  /** @param {CanvasNode} node @param {string} prefix @returns {TreeRow} */
+  function makeRow(node, prefix) {
+    const askCount = blockedById.get(node.nodeId) || 0;
+    return {
+      nodeId: node.nodeId,
+      prefix,
+      glyph: STATUS_GLYPH[node.status] || '?',
+      status: node.status,
+      name: node.name,
+      kind: node.kind,
+      mode: node.mode,
+      lifecycle: node.lifecycle,
+      shortId: shortId(node.nodeId),
+      created: node.created,
+      blocked: askCount > 0,
+      askCount,
+    };
+  }
+
+  /** @type {TreeRow[]} */
+  const rows = [];
+  /** @type {Set<string>} */
+  const visited = new Set();
+  /** @param {CanvasNode} node @param {string} indent @param {boolean} isLast @param {boolean} isRoot */
+  function walk(node, indent, isLast, isRoot) {
+    if (visited.has(node.nodeId)) return; // cycle guard
+    visited.add(node.nodeId);
+    const prefix = isRoot ? '' : indent + (isLast ? '└─ ' : '├─ ');
+    rows.push(makeRow(node, prefix));
+    const kids = children.get(node.nodeId) || [];
+    const childIndent = isRoot ? '' : indent + (isLast ? '   ' : '│  ');
+    for (let i = 0; i < kids.length; i++) {
+      walk(kids[i], childIndent, i === kids.length - 1, false);
+    }
+  }
+
+  let shownRoots = 0;
+  for (const r of roots) {
+    if (!subtreeLive(r.nodeId, new Set())) continue;
+    shownRoots++;
+    walk(r, '', true, true);
+  }
+  return { rows, shownRoots };
+}
+
+// ── Chrome copy (subtitle / footer / banner / dump) ───────────────────────────
+
+/**
+ * Live title subtitle — canvas-wide health (design §3 "a dim ` · <subtitle>`").
+ * `null` ⇒ no subtitle (the title leads alone) on an empty canvas.
+ * @param {CanvasState} state @returns {string|null}
+ */
+function subtitleFor(state) {
+  if (state.totalNodes === 0) return null;
+  return `${state.activeCount} active · ${plural(state.totalNodes, 'node')}`;
+}
+
+/**
+ * Footer status (left, transient) — the RENDERED forest scope, distinct from the
+ * canvas-wide subtitle. `null` ⇒ nothing (the empty/loading state speaks).
+ * @param {CanvasState} state @returns {string|null}
+ */
+function footerSummary(state) {
+  if (state.rows.length === 0) return null;
+  return `${plural(state.shownRoots, 'live tree')} · ${state.rows.length} shown`;
+}
+
+/** @param {CanvasState} state @returns {string} */
+function dumpSummary(state) {
+  return (
+    `${plural(state.shownRoots, 'tree')} · ${state.rows.length} shown · ` +
+    `${state.activeCount} active · ${plural(state.attnTotal, 'ask')} · ` +
+    `${state.totalNodes} total`
+  );
+}
+
+// ── Row → ListItemRow (left spans + right-flushed age) ─────────────────────────
+
+/**
+ * Build one list row: a 1-cell left gutter (§2), the tree prefix (dim), the
+ * status glyph (hue), the name (weight = status), the dim `[kind/mode]` cue, and
+ * a bright-yellow `⚑N` attention flag when blocked — with the relative age
+ * RIGHT-FLUSHED into a clean scannable column via `ListItemRow.right`.
+ * @param {TreeRow} r @param {number} now
+ * @returns {import('../../core/tui/draw.js').ListItemRow}
+ */
+function rowToItem(r, now) {
+  /** @type {import('../../core/tui/draw.js').Span[]} */
+  const spans = [{ text: ' ', style: undefined }]; // 1-cell gutter (rides the cursor bg)
+  if (r.prefix) spans.push({ text: r.prefix, style: { dim: true } });
+  spans.push({ text: r.glyph, style: glyphStyle(r.status) });
+  spans.push({ text: ' ', style: undefined });
+  spans.push({ text: r.name, style: nameStyle(r.status) });
+  spans.push({ text: ` [${r.kind}/${r.mode}]`, style: { fg: '90', dim: true } }); // muted: grey + dim (mono-safe)
+  if (r.blocked) spans.push({ text: ` ⚑${r.askCount}`, style: { fg: '93', bold: true } }); // attention
+
+  const age = relAge(r.created, now);
+  if (age) {
+    return { spans, right: [{ text: age, style: { fg: '90', dim: true } }] };
+  }
+  return { spans };
+}
+
+// ── Refresh (data lane) ──────────────────────────────────────────────────────
+
+/**
+ * Pull the node graph + attention, rebuild the active-tree forest. Runs in the
+ * host's single-flight lane (launch, refreshMs, and `{type:'refresh'}`). Maps any
+ * fetch failure to guidance (a banner + the data-freshness chip) instead of
+ * crashing, and KEEPS the last-known forest on a transient failure.
+ * @param {CanvasState} state
+ * @param {import('../../core/tui/contract.js').ViewHost} host
+ * @returns {Promise<void>}
+ */
+async function refresh(state, host) {
+  host.setStatus('Loading the canvas…');
+
+  const rn = await fetchNodes();
+  if (!rn.ok) {
+    // Data source down. KEEP the last-known forest; raise the cause as the error
+    // banner → the host derives the BLOCKED (red) chip. The not-ready takeover
+    // only owns the screen when there is nothing to keep (see render()).
+    state.sourceError = bannerFor(rn.error);
+    host.setStatus(null);
+    host.setError(state.sourceError);
+    return;
+  }
+  state.sourceError = null;
+  const nodes = rn.data;
+
+  // Attention is best-effort: a failure here still renders the graph (just
+  // without the blocked flags), so the monitor degrades gracefully.
+  /** @type {Map<string,number>} */
+  const blockedById = new Map();
+  let attnTotal = 0;
+  const ra = await fetchAttention();
+  if (ra.ok) {
+    for (const it of ra.data.items) {
+      if (it.nodeId) blockedById.set(it.nodeId, it.count);
+    }
+    attnTotal = ra.data.total;
+  }
+
+  const built = buildForest(nodes, blockedById);
+  state.rows = built.rows;
+  state.shownRoots = built.shownRoots;
+  state.totalNodes = nodes.length;
+  state.activeCount = nodes.filter((n) => n.status === 'active').length;
+  state.attnTotal = attnTotal;
+  if (state.cursor >= state.rows.length) state.cursor = Math.max(0, state.rows.length - 1);
+  state.lastFetch = Date.now();
+
+  host.setSubtitle(subtitleFor(state));
+
+  // Data-freshness → state chip. Pending human asks are the one thing that wants
+  // a human: raise an ACTION banner → the host derives the ATTENTION (yellow)
+  // chip. Otherwise clear → READY (green). (busy→working is automatic.)
+  if (attnTotal > 0) {
+    host.setBanner(`${plural(attnTotal, 'ask')} waiting on a human — see the ⚑ rows`, 'action');
+  } else {
+    host.setError(null);
+  }
+
+  host.setStatus(footerSummary(state));
+}
+
+// ── ViewModule ───────────────────────────────────────────────────────────────
+
+/** @type {import('../../core/tui/contract.js').ViewModule<CanvasState>} */
+const view = {
+  manifest: {
+    id: 'canvas',
+    title: 'Canvas',
+    description: 'Live agent graph — who is working, who is blocked',
+    refreshMs: 3000,
+    keymap: [
+      { keys: 'j/k', label: 'move' },
+      { keys: 'g', label: 'refresh' },
+      { keys: 'q', label: 'quit' },
+    ],
+  },
+
+  /**
+   * Cheap + synchronous initial state — NO slow fetch (the host paints a loading
+   * frame, then calls refresh()).
+   * @returns {CanvasState}
+   */
+  init() {
+    return {
+      rows: [],
+      cursor: 0,
+      scroll: 0,
+      shownRoots: 0,
+      totalNodes: 0,
+      activeCount: 0,
+      attnTotal: 0,
+      lastFetch: 0,
+      sourceError: null,
+    };
+  },
+
+  refresh,
+
+  /**
+   * Paint the forest, or one of the four standard states. Pure (reads state,
+   * calls draw.*); the only state write is storing draw.list's adjusted scroll
+   * back, per the Draw contract.
+   * @param {CanvasState} state
+   * @param {import('../../core/tui/draw.js').Draw} draw
+   * @param {import('../../core/tui/draw.js').Rect} content
+   */
+  render(state, draw, content) {
+    if (content.width <= 0 || content.height <= 0) return;
+
+    if (state.rows.length === 0) {
+      // Hard not-ready: the data source is down and there is nothing to keep —
+      // a guided takeover owns the whole content rect (design §4/§5). The
+      // specific cause rides the host error banner (full-width); this names the
+      // state + the next action so the view never dead-ends.
+      if (state.sourceError) {
+        notReadyState(draw, content, {
+          glyph: '⚠',
+          glyphFg: '31', // red — pairs with the blocked chip
+          headline: 'Canvas unavailable',
+          explanation: 'crtr could not read the canvas graph.',
+          nextStep: 'Press g to retry.',
+        });
+        return;
+      }
+      // First load in flight — a skeleton, not a blank screen.
+      if (state.lastFetch === 0) {
+        loadingState(draw, content, { rows: Math.min(5, content.height), label: 'Loading the canvas…' });
+        return;
+      }
+      // Loaded, nothing to render — the reward state, two flavors.
+      if (state.totalNodes === 0) {
+        emptyState(draw, content, {
+          headline: 'No nodes on the canvas',
+          secondary: ['Spawn one with `crtr node new`.', 'Press g to refresh.'],
+        });
+      } else {
+        emptyState(draw, content, {
+          headline: 'All caught up',
+          secondary: [`${plural(state.totalNodes, 'node')} finished — none active.`, 'Press g to refresh.'],
+        });
+      }
+      return;
+    }
+
+    // The forest. A 1-row section gap below the header (§2 rhythm) when there is
+    // room; full-width list so the cursor highlight + age column reach the edges.
+    const now = Date.now();
+    const gap = content.height > 4 ? 1 : 0;
+    const listRect = {
+      row: content.row + gap,
+      col: content.col,
+      width: content.width,
+      height: content.height - gap,
+    };
+    const items = state.rows.map((r) => rowToItem(r, now));
+    const res = draw.list(listRect, items, state.cursor, state.scroll);
+    state.scroll = res.scroll; // store adjusted scroll back (Draw.list contract)
+  },
+
+  /**
+   * Read-only navigation: j/k move the cursor, g refreshes, q quits. No async
+   * actions — this is a monitor, not a controller.
+   * @param {import('../../core/tui/contract.js').ViewKey} k
+   * @param {CanvasState} state
+   * @returns {import('../../core/tui/contract.js').ViewAction}
+   */
+  onKey(k, state) {
+    const key = k.key;
+    const ch = k.input;
+    if (ch === 'q') return { type: 'quit' };
+    if (ch === 'g') return { type: 'refresh' };
+    if (key.downArrow || ch === 'j') {
+      if (state.rows.length) state.cursor = Math.min(state.rows.length - 1, state.cursor + 1);
+      return { type: 'render' };
+    }
+    if (key.upArrow || ch === 'k') {
+      state.cursor = Math.max(0, state.cursor - 1);
+      return { type: 'render' };
+    }
+    return { type: 'none' };
+  },
+
+  /**
+   * Plain-text snapshot for the non-TTY / piped path. No ANSI. The host threads
+   * its current banner via `ctx` so guidance (a source error / a pending-ask
+   * action) surfaces without the view mirroring it into state.
+   * @param {CanvasState} state
+   * @param {import('../../core/tui/contract.js').DumpContext} [ctx]
+   * @returns {string}
+   */
+  dump(state, ctx) {
+    /** @type {string[]} */
+    const lines = ['Canvas — live agent graph'];
+    const banner = ctx && ctx.banner ? ctx.banner : null;
+    if (banner) lines.push('', `[${banner.level}] ${banner.msg}`);
+    else if (state.sourceError) lines.push('', `[error] ${state.sourceError}`);
+
+    lines.push('', dumpSummary(state), '');
+
+    if (state.rows.length === 0) {
+      lines.push(
+        state.sourceError
+          ? '(canvas unavailable)'
+          : state.lastFetch === 0
+            ? '(loading…)'
+            : state.totalNodes === 0
+              ? '(no nodes on the canvas)'
+              : '(no active trees)',
+      );
+      return lines.join('\n');
+    }
+
+    const now = Date.now();
+    for (const r of state.rows) {
+      const blk = r.blocked ? ` ⚑${r.askCount}` : '';
+      const age = relAge(r.created, now);
+      lines.push(
+        `${r.prefix}${r.glyph} ${r.name} [${r.kind}/${r.mode}] ${lifeAbbr(r.lifecycle)} ${r.shortId} ${age}${blk}`,
+      );
+    }
+    return lines.join('\n');
+  },
+};
+
+export default view;