@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/builtin-views/_lib/states.mjs

@@ -0,0 +1,161 @@
+// @ts-check
+/**
+ * Standard view states — the four states every crtr view must *design* rather
+ * than leave bare (design §4): loading-skeleton, empty-reward, error-keeps-its-
+ * shape, and the guided not-ready takeover.
+ *
+ * Copy-pasteable BODY HELPERS: this is a sibling lib the builtin views import
+ * RELATIVELY (`import { loadingState } from '../_lib/states.mjs'`). It imports
+ * NOTHING from crtr — the view passes in the `draw` + content `rect` the host
+ * already handed it, and these paint the state into `draw`.
+ *
+ * Discipline (design §2): all color is NUMERIC SGR codes ('32' green, '31' red,
+ * '36' cyan, '33' yellow); color NEVER carries meaning alone — every colored
+ * element pairs its hue with a glyph or weight so it survives NO_COLOR / dumb
+ * terminals. Hue is the framework's job to gate (draw.ts gates fg/bg on caps);
+ * structural weight (bold/dim) always renders.
+ *
+ * @module _lib/states
+ */
+
+/** @typedef {import('../../core/tui/draw.js').Draw} Draw */
+/** @typedef {import('../../core/tui/draw.js').Rect} Rect */
+/** @typedef {import('../../core/tui/draw.js').Span} Span */
+/** @typedef {import('../../core/tui/draw.js').Style} Style */
+
+// ── internal ──────────────────────────────────────────────────────────────────
+
+/** @param {Span[]} spans @returns {number} */
+function spanWidth(spans) {
+  let n = 0;
+  for (const s of spans) n += Array.from(s.text).length;
+  return n;
+}
+
+/** @param {string|string[]|undefined|null} v @returns {string[]} */
+function toLines(v) {
+  if (v == null) return [];
+  if (Array.isArray(v)) return v.map((s) => String(s == null ? '' : s));
+  return [String(v)];
+}
+
+/**
+ * Place a vertically + horizontally centered stack of span-lines in `rect`.
+ * Each entry is one line's spans; rows that fall outside the rect are skipped.
+ * @param {Draw} draw @param {Rect} rect @param {Span[][]} lines
+ */
+function centeredStack(draw, rect, lines) {
+  if (!rect || rect.width <= 0 || rect.height <= 0 || lines.length === 0) return;
+  const start = rect.row + Math.max(0, Math.floor((rect.height - lines.length) / 2));
+  lines.forEach((spans, i) => {
+    const row = start + i;
+    if (row < rect.row || row >= rect.row + rect.height) return;
+    const w = spanWidth(spans);
+    const col = rect.col + Math.max(0, Math.floor((rect.width - w) / 2));
+    draw.spans(row, col, spans, rect.col + rect.width - col);
+  });
+}
+
+// ── states ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Loading — paint a SKELETON of where content will land (dim `····` placeholder
+ * rows), not a lone centered "Loading…". The layout is legible before data
+ * arrives. Pair with the host's `⟳ working` chip + a `setStatus('Loading…')`.
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ rows?: number, label?: string }} [opts]
+ *   rows  — how many skeleton rows (default 4); label — optional dim caption below.
+ */
+export function loadingState(draw, rect, opts = {}) {
+  if (!rect || rect.width <= 0 || rect.height <= 0) return;
+  const n = Math.max(1, Math.min(opts.rows ?? 4, rect.height));
+  const snippetLens = [10, 8, 12, 7, 11];
+  for (let i = 0; i < n; i++) {
+    const row = rect.row + i;
+    const label = '·'.repeat(4);
+    const snipLen = Math.min(snippetLens[i % snippetLens.length], Math.max(0, rect.width - 8));
+    /** @type {Span[]} */
+    const spans = [{ text: label, style: { dim: true } }];
+    if (snipLen > 0) spans.push({ text: '  ' + '·'.repeat(snipLen), style: { dim: true } });
+    draw.spans(row, rect.col + 1, spans, rect.width - 1);
+  }
+  if (opts.label) {
+    const below = { row: rect.row + n + 1, col: rect.col, width: rect.width, height: Math.max(0, rect.height - n - 1) };
+    centeredStack(draw, below, [[{ text: opts.label, style: { dim: true } }]]);
+  }
+}
+
+/**
+ * Empty — the reward state. A small centered stack: a green `✓`, a default-weight
+ * headline, then dim secondary lines. Inbox-zero is a reward, not a void.
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ glyph?: string, headline?: string, secondary?: string|string[] }} [opts]
+ */
+export function emptyState(draw, rect, opts = {}) {
+  const glyph = opts.glyph ?? '✓';
+  const headline = opts.headline ?? 'All caught up';
+  /** @type {Span[][]} */
+  const lines = [
+    [{ text: glyph + '  ', style: { fg: '32' } }, { text: headline }], // green glyph + default headline
+    [{ text: '' }],
+  ];
+  for (const t of toLines(opts.secondary)) lines.push([{ text: t, style: { dim: true } }]);
+  centeredStack(draw, rect, lines);
+}
+
+/**
+ * Error — a centered error block, used ONLY when there is no last-known content
+ * to keep (on a refresh error with a still-good view, raise a banner instead).
+ * `✗` + headline in red/bold, the cause in default weight, a dim retry hint.
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ headline?: string, cause?: string|string[], hint?: string }} [opts]
+ */
+export function errorState(draw, rect, opts = {}) {
+  const headline = opts.headline ?? 'Something went wrong';
+  const cause = toLines(opts.cause);
+  const hint = opts.hint ?? 'Press g to retry.';
+  /** @type {Span[][]} */
+  const lines = [
+    [{ text: '✗  ', style: { fg: '31', bold: true } }, { text: headline, style: { fg: '31', bold: true } }],
+    [{ text: '' }],
+  ];
+  for (const t of cause) lines.push([{ text: t }]);
+  if (cause.length) lines.push([{ text: '' }]);
+  if (hint) lines.push([{ text: hint, style: { dim: true } }]);
+  centeredStack(draw, rect, lines);
+}
+
+/**
+ * Not-ready / guided takeover — the full-content recovery substrate (design §5).
+ * A centered stack: a state glyph (its hue passed by the caller, mono-safe via
+ * the glyph itself), a bold headline naming the state, a dim explanation, and the
+ * explicit next step (an auto-progress note the view writes, or a key to press).
+ *
+ * @param {Draw} draw
+ * @param {Rect} rect
+ * @param {{ glyph?: string, glyphFg?: string, headline?: string, explanation?: string|string[], nextStep?: string }} [opts]
+ *   glyphFg — NUMERIC SGR code for the glyph hue (e.g. '36' cyan working, '31' red blocked).
+ */
+export function notReadyState(draw, rect, opts = {}) {
+  const glyph = opts.glyph ?? '⊙';
+  /** @type {Style} */
+  const glyphStyle = opts.glyphFg ? { fg: opts.glyphFg, bold: true } : { bold: true };
+  const headline = opts.headline ?? 'Not ready';
+  /** @type {Span[][]} */
+  const lines = [
+    [{ text: glyph + '  ', style: glyphStyle }, { text: headline, style: { bold: true } }],
+    [{ text: '' }],
+  ];
+  for (const t of toLines(opts.explanation)) lines.push([{ text: t, style: { dim: true } }]);
+  if (opts.nextStep) {
+    lines.push([{ text: '' }]);
+    lines.push([{ text: opts.nextStep }]); // default weight — the call to action
+  }
+  centeredStack(draw, rect, lines);
+}

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

@@ -0,0 +1,303 @@
+// @ts-check
+/**
+ * Canvas data layer for the crtr `canvas` view (the monitor archetype).
+ *
+ * Self-contained ESM, Node-builtins-only. Imports NOTHING from crtr so it ships
+ * verbatim (`cp -R src/builtin-views dist/builtin-views`) and is dynamically
+ * `import()`ed by the view at runtime where there is no TS toolchain.
+ *
+ * It shells the `crtr` binary itself — exactly as the LinkedIn view shells
+ * `capture`. Two read-only `--json` leaves give the whole graph:
+ *   - `crtr node inspect list --json`   → every node row, incl. `parent` (so the
+ *                                          view rebuilds the forest) + `lifecycle`.
+ *   - `crtr canvas attention list --json` → which nodes have pending human asks
+ *                                          (the "blocked on a human" signal).
+ * Both are read-only (query canvas.db) and exit 0. No `--json` affordance was
+ * missing — every command we need already emits machine-readable JSON.
+ *
+ * NOTHING here throws. Every exported function returns a `Result<T>`; failures
+ * surface as a typed `ClientError` so the view renders guidance, not a crash.
+ *
+ * NOTE on the crtr help-gate: that gate is a pi-side `bash` tool-call
+ * interceptor — it inspects the AGENT's command string. A `crtr` spawned from
+ * inside the view host (a grandchild of `node dist/cli.js view run`) is not a
+ * tool call pi can see, so these shell-outs are never gated.
+ *
+ * @module canvas/client
+ */
+
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * One canvas node, flattened from `node inspect list --json`.
+ * @typedef {Object} CanvasNode
+ * @property {string} nodeId      Full node id (`<time>-<hash>`).
+ * @property {string} name        Display name.
+ * @property {string} kind        Node kind (general/developer/explore/human/…).
+ * @property {string} mode        base | orchestrator.
+ * @property {string} lifecycle   resident | terminal.
+ * @property {string} status      active | idle | done | dead | canceled.
+ * @property {string|null} parent Spawn/subscription parent id (null ⇒ a forest root).
+ * @property {string} created     ISO 8601 birth timestamp (drives child ordering).
+ */
+
+/**
+ * One cwd with pending human asks, from `canvas attention list --json`. The
+ * `nodeId` is the cwd's representative node — the node the attention system
+ * points at.
+ * @typedef {Object} AttentionItem
+ * @property {string} nodeId
+ * @property {string} name
+ * @property {string} cwd
+ * @property {number} count    Pending ask count.
+ */
+
+/**
+ * Typed failure. `kind` drives the guidance banner the view shows.
+ * @typedef {{kind:'crtr-missing', message:string}
+ *   | {kind:'crtr-failed', message:string}
+ *   | {kind:'parse', message:string}
+ *   | {kind:'error', message:string}} ClientError
+ */
+
+/**
+ * Never-throw return contract.
+ * @template T
+ * @typedef {{ok:true, data:T} | {ok:false, error:ClientError}} Result
+ */
+
+// ── Result helpers ───────────────────────────────────────────────────────────
+
+/** @template T @param {T} data @returns {Result<T>} */
+function ok(data) {
+  return { ok: true, data };
+}
+
+/** @param {ClientError} error @returns {{ok:false, error:ClientError}} */
+function fail(error) {
+  return { ok: false, error };
+}
+
+// ── Locating the `crtr` binary ───────────────────────────────────────────────
+
+/**
+ * One candidate way to invoke crtr: a binary plus any fixed prefix args.
+ * @typedef {Object} Candidate
+ * @property {string} bin
+ * @property {string[]} prefix
+ */
+
+/**
+ * Candidates, in order: explicit override → PATH `crtr` → PATH `crouter` → the
+ * dev fallback `node <dist/cli.js>` resolved relative to THIS file (which, when
+ * shipped, lives at `dist/builtin-views/canvas/client.mjs`, so `../../cli.js` is
+ * `dist/cli.js`). We try the next only when a candidate fails to spawn (ENOENT);
+ * a candidate that spawns and exits nonzero is authoritative.
+ * @returns {Candidate[]}
+ */
+function crtrCandidates() {
+  /** @type {Candidate[]} */
+  const out = [];
+  if (process.env.CRTR_BIN) out.push({ bin: process.env.CRTR_BIN, prefix: [] });
+  out.push({ bin: 'crtr', prefix: [] });
+  out.push({ bin: 'crouter', prefix: [] });
+  try {
+    const here = dirname(fileURLToPath(import.meta.url)); // …/dist/builtin-views/canvas
+    const cli = join(here, '..', '..', 'cli.js'); // …/dist/cli.js
+    if (existsSync(cli)) out.push({ bin: process.execPath, prefix: [cli] });
+  } catch {
+    /* import.meta.url unavailable — skip the dev fallback */
+  }
+  return out;
+}
+
+// ── Process runner (never throws) ────────────────────────────────────────────
+
+/**
+ * @typedef {Object} RunResult
+ * @property {boolean} spawned   False ⇒ no candidate binary could be spawned.
+ * @property {number}  exitCode  Process exit code (0 on success; -1 if not spawned).
+ * @property {string}  stdout
+ * @property {string}  stderr
+ */
+
+/**
+ * Run one candidate. Resolves (never rejects). ENOENT ⇒ `spawned:false` so the
+ * caller can try the next candidate.
+ * @param {Candidate} c
+ * @param {string[]} argv
+ * @returns {Promise<RunResult>}
+ */
+function runOnce(c, argv) {
+  return new Promise((resolve) => {
+    execFile(
+      c.bin,
+      [...c.prefix, ...argv],
+      { maxBuffer: 64 * 1024 * 1024, encoding: 'utf8' },
+      (err, stdout, stderr) => {
+        const out = typeof stdout === 'string' ? stdout : '';
+        const errOut = typeof stderr === 'string' ? stderr : '';
+        if (err && /** @type {any} */ (err).code === 'ENOENT') {
+          resolve({ spawned: false, exitCode: -1, stdout: out, stderr: errOut });
+          return;
+        }
+        const code = err
+          ? typeof /** @type {any} */ (err).code === 'number'
+            ? /** @type {any} */ (err).code
+            : 1
+          : 0;
+        resolve({ spawned: true, exitCode: code, stdout: out, stderr: errOut });
+      }
+    );
+  });
+}
+
+/**
+ * Run `crtr` with the given argv, walking candidates until one spawns.
+ * @param {string[]} argv
+ * @returns {Promise<RunResult>}
+ */
+async function runCrtr(argv) {
+  /** @type {RunResult} */
+  let last = { spawned: false, exitCode: -1, stdout: '', stderr: '' };
+  for (const c of crtrCandidates()) {
+    last = await runOnce(c, argv);
+    if (last.spawned) return last;
+  }
+  return last; // never spawned
+}
+
+/** @returns {ClientError} */
+function crtrMissingError() {
+  return {
+    kind: 'crtr-missing',
+    message:
+      "crtr not found — tried CRTR_BIN, PATH 'crtr'/'crouter', and the local cli.js. " +
+      'Install crtr or set CRTR_BIN.',
+  };
+}
+
+/**
+ * Pull a human message out of crtr stderr: prefer the last `ERROR:` line, else
+ * the last non-empty line, else a generic fallback.
+ * @param {string} stderr
+ * @returns {string}
+ */
+function extractMessage(stderr) {
+  const lines = String(stderr || '')
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (/^ERROR:/i.test(lines[i])) return lines[i].replace(/^ERROR:\s*/i, '').trim();
+  }
+  if (lines.length) return lines[lines.length - 1];
+  return 'crtr command failed';
+}
+
+/**
+ * Map a failed crtr invocation to a typed {@link ClientError}.
+ * @param {string} stderr
+ * @returns {ClientError}
+ */
+function classifyError(stderr) {
+  const s = String(stderr || '');
+  if (/help-gate:\s*blocked/i.test(s)) {
+    return { kind: 'error', message: 'crtr help-gate blocked the call (run the command with -h once).' };
+  }
+  return { kind: 'crtr-failed', message: extractMessage(s) };
+}
+
+/**
+ * Run a crtr `--json` leaf and parse stdout as JSON.
+ * @param {string[]} argv
+ * @returns {Promise<Result<any>>}
+ */
+async function runJson(argv) {
+  const r = await runCrtr(argv);
+  if (!r.spawned) return fail(crtrMissingError());
+  if (r.exitCode !== 0) return fail(classifyError(r.stderr || r.stdout));
+  const out = String(r.stdout || '').trim();
+  if (out === '') return ok(null);
+  try {
+    return ok(JSON.parse(out));
+  } catch {
+    return fail({ kind: 'parse', message: `could not parse \`crtr ${argv.join(' ')}\` output as JSON` });
+  }
+}
+
+// ── Field mappers ────────────────────────────────────────────────────────────
+
+/** @param {unknown} v @returns {string} */
+function str(v) {
+  return v == null ? '' : String(v);
+}
+
+/** @param {any} n @returns {CanvasNode} */
+function toNode(n) {
+  const o = n || {};
+  return {
+    nodeId: str(o.node_id),
+    name: str(o.name) || '(unnamed)',
+    kind: str(o.kind) || '?',
+    mode: str(o.mode) || '?',
+    lifecycle: str(o.lifecycle) || '?',
+    status: str(o.status) || '?',
+    parent: o.parent ? str(o.parent) : null,
+    created: str(o.created),
+  };
+}
+
+/** @param {any} i @returns {AttentionItem} */
+function toAttention(i) {
+  const o = i || {};
+  return {
+    nodeId: str(o.node_id),
+    name: str(o.name),
+    cwd: str(o.cwd),
+    count: typeof o.count === 'number' ? o.count : 0,
+  };
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Every node on the canvas (all statuses). The view rebuilds the forest from the
+ * `parent` edges and filters to active trees itself.
+ * @returns {Promise<Result<CanvasNode[]>>}
+ */
+export async function fetchNodes() {
+  const r = await runJson(['node', 'inspect', 'list', '--json']);
+  if (!r.ok) return r;
+  const arr = r.data && Array.isArray(r.data.nodes) ? r.data.nodes : [];
+  return ok(arr.map(toNode));
+}
+
+/**
+ * Pending human asks across the canvas (the "blocked on a human" signal).
+ * @returns {Promise<Result<{items:AttentionItem[], total:number}>>}
+ */
+export async function fetchAttention() {
+  const r = await runJson(['canvas', 'attention', 'list', '--json']);
+  if (!r.ok) return r;
+  const items = r.data && Array.isArray(r.data.items) ? r.data.items : [];
+  const total = r.data && typeof r.data.total === 'number' ? r.data.total : 0;
+  return ok({ items: items.map(toAttention), total });
+}
+
+/**
+ * Introspection helper (not used at runtime): the exact crtr commands this
+ * client shells, so the shape can be eyeballed without a live canvas.
+ * @returns {Record<string,string>}
+ */
+export function describeCommands() {
+  return {
+    fetchNodes: 'crtr node inspect list --json',
+    fetchAttention: 'crtr canvas attention list --json',
+  };
+}