catherd-cli 0.1.0

package/src/tui/theme.ts

@@ -0,0 +1,140 @@
+import { WriteStream } from "node:tty";
+import type { HarnessCost } from "../core/harness.ts";
+
+export type Mood = "good" | "working" | "waiting" | "failed" | "landed";
+export type Tone = "ginger" | "cream" | "charcoal" | "pink";
+/** Node's getColorDepth: 1 none, 4 sixteen, 8 256, 24 true colour. */
+export type Depth = 1 | 4 | 8 | 24;
+
+export interface Ui {
+  plain: boolean;
+  reducedMotion: boolean;
+  depth: Depth;
+}
+
+// OpenTUI renders true-colour RGB only and downsamples itself for the terminal it finds, so
+// every depth above 1 gets the same hex; depth 1 (NO_COLOR) gets no colour at all.
+const TONES: Record<Tone, string> = {
+  ginger: "#E8833A",
+  cream: "#F5E6C8",
+  charcoal: "#4A4340",
+  pink: "#FF6FA5",
+};
+
+export const GRADIENT: string[] = [TONES.ginger, TONES.pink];
+
+export function tint(tone: Tone, depth: Depth): string | undefined {
+  return depth === 1 ? undefined : TONES[tone];
+}
+
+export function detectUi(rawArgs: string[], env: NodeJS.ProcessEnv = process.env): Ui {
+  return {
+    // is-unicode-supported answers exactly this on macOS and Linux.
+    plain: rawArgs.includes("--plain") || env.TERM === "linux",
+    reducedMotion: rawArgs.includes("--reduced-motion"),
+    depth: WriteStream.prototype.getColorDepth.call(process.stdout as WriteStream, env) as Depth,
+  };
+}
+
+export const FACES: Record<Mood, string> = {
+  good: "=^.^=",
+  working: "=o.o=",
+  waiting: "=-.-=",
+  failed: "=x.x=",
+  landed: "=^ω^=",
+};
+
+export function face(mood: Mood, plain: boolean): string {
+  return plain ? FACES[mood].replace("ω", "w") : FACES[mood];
+}
+
+const GLYPHS = {
+  on: ["🐾", "[x]"],
+  off: ["○ ", "[ ]"],
+  cat: ["🐈", "*"],
+  dot: ["·", "-"],
+  more: ["…", "..."],
+  open: ["▾", "v"],
+  shut: ["▸", ">"],
+  cursor: ["❯", ">"],
+  arrow: ["→", "->"],
+  keys: ["↑↓", "up/down"],
+  swap: ["⇄", "<->"],
+} as const;
+
+export type Glyph = keyof typeof GLYPHS;
+export const GLYPH_NAMES = Object.keys(GLYPHS) as Glyph[];
+
+export function glyph(g: Glyph, plain: boolean): string {
+  return GLYPHS[g][plain ? 1 : 0];
+}
+
+/** The conductor: ears, a face that follows the mood, a raised baton, paws. */
+export function mascot(mood: Mood, plain: boolean): [string, string, string] {
+  return [" /\\_/\\  .", `(${face(mood, plain)})/`, ' (")(")'].map((l) => l.padEnd(9)) as [
+    string,
+    string,
+    string,
+  ];
+}
+
+export const HERDING = [
+  "herding",
+  "counting whiskers",
+  "negotiating with Luna",
+  "coaxing Sol off the keyboard",
+  "lining up the kittens",
+  "untangling the yarn",
+] as const;
+
+export function herdLine(i: number, plain: boolean): string {
+  return `${HERDING[i % HERDING.length]}${glyph("more", plain)}`;
+}
+
+/** Kneading paws (m/n) and a flicking tail. ASCII already, so --plain needs no second set. */
+export const SPINNER = {
+  frames: ["m=o.o=~", "n=o.o=-", "m=o.o=_", "n=o.o=-"],
+  ms: 160,
+  copyMs: 2400,
+} as const;
+
+/** The init intro: 6 frames of 200 ms, 1.2 s in all, inside the spec's 1.5 s. */
+export const INTRO = { steps: 6, ms: 200 } as const;
+
+export const HARNESS_HINT: Record<"codex" | "opencode", string> = {
+  codex: "native keeps your Codex config, hooks, skills, AGENTS.md; isolated saves tokens",
+  opencode: "native keeps your opencode config, agents and plugins; isolated saves tokens",
+};
+
+const kTokens = (n: number) => `~${Math.round(n / 1000)}k`;
+
+export function costNote(h: HarnessCost): string {
+  if (h.extraPerRun !== null) return `customizations ${kTokens(h.extraPerRun)} tokens/run`;
+  if (h.nativeMedian !== null) return `native ${kTokens(h.nativeMedian)} tokens/run`;
+  return h.isolatedMedian !== null ? `isolated ${kTokens(h.isolatedMedian)} tokens/run` : "";
+}
+
+export function clock(secs: number): string {
+  const s = Math.max(0, Math.floor(secs));
+  const h = Math.floor(s / 3600);
+  const mm = String(Math.floor(s / 60) % 60).padStart(2, "0");
+  const ss = String(s % 60).padStart(2, "0");
+  return h > 0 ? `${h}:${mm}:${ss}` : `${mm}:${ss}`;
+}
+
+/** "gpt-6-sol#medium" -> "sol#medium"; provider paths drop to the last segment. */
+export function shortRung(rung: string): string {
+  return rung.replace(/^.*\//, "").replace(/^gpt-\d+-/, "");
+}
+
+export function nick(rung: string): string {
+  const model = shortRung(rung).split("#")[0] ?? "";
+  return model.charAt(0).toUpperCase() + model.slice(1);
+}
+
+export function climbLine(name: string, from: string, to: string, plain: boolean): string {
+  const a = nick(from);
+  const b = nick(to);
+  const story = a === b ? `${a} digs deeper` : `${a} gave up, ${b} takes over`;
+  return `${story} ${glyph("dot", plain)} ${name} ${shortRung(from)} ${glyph("arrow", plain)} ${shortRung(to)}`;
+}

package/src/tui/ui.tsx

@@ -0,0 +1,104 @@
+import { TextAttributes } from "@opentui/core";
+import { useKeyboard, useTerminalDimensions } from "@opentui/react";
+import { type ReactNode, useEffect, useState } from "react";
+import { GRADIENT, glyph, herdLine, INTRO, type Mood, mascot, SPINNER, tint, type Ui } from "./theme.ts";
+
+export function Screen({ children }: { children: ReactNode }) {
+  const { width } = useTerminalDimensions();
+  return <box style={{ flexDirection: "column", width: Math.min(width || 80, 80) }}>{children}</box>;
+}
+
+const hex = (h: string): [number, number, number] => [
+  Number.parseInt(h.slice(1, 3), 16),
+  Number.parseInt(h.slice(3, 5), 16),
+  Number.parseInt(h.slice(5, 7), 16),
+];
+
+/** One colour per letter, interpolated between GRADIENT's two hex stops. */
+export function gradientLetters(word: string): { ch: string; fg: string }[] {
+  const [a, b] = [hex(GRADIENT[0] as string), hex(GRADIENT[1] as string)];
+  return [...word].map((ch, i) => {
+    const t = word.length > 1 ? i / (word.length - 1) : 0;
+    const rgb = a.map((c, k) => Math.round(c + ((b[k] as number) - c) * t));
+    return { ch, fg: `#${rgb.map((c) => c.toString(16).padStart(2, "0")).join("")}` };
+  });
+}
+
+export function Header({
+  ui,
+  mood,
+  title,
+  word = "catherd",
+}: {
+  ui: Ui;
+  mood: Mood;
+  title: string;
+  word?: string;
+}) {
+  const [ears, head, paws] = mascot(mood, ui.plain);
+  const ginger = tint("ginger", ui.depth);
+  return (
+    <box style={{ flexDirection: "row", marginBottom: 1 }}>
+      <box style={{ flexDirection: "column", marginRight: 2 }}>
+        <text fg={ginger}>{ears}</text>
+        <text fg={ginger}>{head}</text>
+        <text fg={ginger}>{paws}</text>
+      </box>
+      <box style={{ flexDirection: "column", flexGrow: 1, overflow: "hidden" }}>
+        {ui.depth >= 8 && word ? (
+          <text attributes={TextAttributes.BOLD}>
+            {gradientLetters(word).map((s, i) => (
+              // biome-ignore lint: index key is stable, the wordmark never reorders
+              <span key={i} fg={s.fg}>
+                {s.ch}
+              </span>
+            ))}
+          </text>
+        ) : (
+          <text fg={ginger} attributes={TextAttributes.BOLD}>
+            {word || " "}
+          </text>
+        )}
+        <text fg={tint("cream", ui.depth)}>herds coding agents</text>
+        <text fg={tint("pink", ui.depth)} attributes={TextAttributes.BOLD} wrapMode="none" truncate>
+          {title}
+        </text>
+      </box>
+    </box>
+  );
+}
+
+export function CatSpinner({ ui, label }: { ui: Ui; label: string }) {
+  const [n, setN] = useState(0);
+  useEffect(() => {
+    if (ui.reducedMotion) return;
+    const t = setInterval(() => setN((x) => x + 1), SPINNER.ms);
+    return () => clearInterval(t);
+  }, [ui.reducedMotion]);
+  const frame = SPINNER.frames[n % SPINNER.frames.length];
+  const copy = herdLine(Math.floor((n * SPINNER.ms) / SPINNER.copyMs), ui.plain);
+  return (
+    <text wrapMode="none" truncate>
+      <span fg={tint("ginger", ui.depth)}>{frame}</span> {label}{" "}
+      <span attributes={TextAttributes.DIM}>
+        {glyph("dot", ui.plain)} {copy}
+      </span>
+    </text>
+  );
+}
+
+export function Intro({ ui, onDone }: { ui: Ui; onDone: () => void }) {
+  const [step, setStep] = useState(ui.reducedMotion ? INTRO.steps : 0);
+  useKeyboard(() => onDone());
+  useEffect(() => {
+    if (step >= INTRO.steps) {
+      onDone();
+      return;
+    }
+    const t = setTimeout(() => setStep(step + 1), INTRO.ms);
+    return () => clearTimeout(t);
+  }, [step]);
+  const mood: Mood = step < 2 ? "waiting" : step < INTRO.steps ? "working" : "good";
+  const word = "catherd".slice(0, Math.round((7 * step) / INTRO.steps));
+  return <Header ui={ui} mood={mood} title={herdLine(step, ui.plain)} word={word} />;
+}

package/src/tui/watch-model.ts

@@ -0,0 +1,83 @@
+import type { RunSummary } from "../core/status.ts";
+import type { RunRecord, RungId } from "../types.ts";
+import { climbLine, clock, face, glyph, type Mood, shortRung } from "./theme.ts";
+
+/**
+ * The fields `watch` shows from one `jev.jsonl` row (`JevLogRow` in `src/routing/jev.ts`):
+ * which questions were asked, the answer actually used, and whether Jev answered or the
+ * profile default did. `ts`, `answers` and `why` are in the file but not shown here.
+ */
+export interface JevLine {
+  questions: string[];
+  used: string;
+  source: "jev" | "default";
+}
+
+export function runMood(s: RunSummary): Mood {
+  if (s.live.length > 0) return "working";
+  if (s.totals.notOk.length > 0) return "failed";
+  return s.totals.runs > 0 ? "good" : "waiting";
+}
+
+export function runLine(s: RunSummary, plain: boolean): string {
+  return [
+    `${face(runMood(s), plain)} ${s.title}`,
+    `${s.live.length} live`,
+    `${s.totals.runs} runs`,
+    `${s.milestones.length} landed`,
+  ].join(` ${glyph("dot", plain)} `);
+}
+
+export function liveLine(l: RunSummary["live"][number], plain: boolean): string {
+  return `${glyph("cat", plain)} ${l.name}  ${shortRung(l.rung)}  ${clock(l.secs)}  ${face("working", plain)}`;
+}
+
+export function milestoneLine(m: string, plain: boolean): string {
+  const id = /\bM\d+\b/.exec(m)?.[0];
+  if (!id) return `${face("landed", plain)} ${m}`;
+  const mins = /\b(\d+)m\b/.exec(m)?.[1];
+  const sha = /\b[0-9a-f]{7,40}\b/.exec(m)?.[0]?.slice(0, 7);
+  return [`${face("landed", plain)} ${id} landed`, mins ? `${mins}m` : null, sha ?? null]
+    .filter((x): x is string => x !== null)
+    .join(` ${glyph("dot", plain)} `);
+}
+
+/** Remembers each role's last rung across polls; a role that comes back on another rung has climbed. */
+export function climbs(seen: Map<string, RungId>, s: RunSummary, plain: boolean): string[] {
+  const out: string[] = [];
+  for (const l of s.live) {
+    const key = `${s.id}/${l.name}`;
+    const from = seen.get(key);
+    if (from !== undefined && from !== l.rung) out.push(climbLine(l.name, from, l.rung, plain));
+    seen.set(key, l.rung);
+  }
+  return out;
+}
+
+export function recordLine(r: RunRecord, plain: boolean): string {
+  const tail = r.replyStatus ? ` ${glyph("dot", plain)} ${r.replyStatus}` : "";
+  return `${r.name}  ${shortRung(r.rung)}  ${r.status}  ${clock(r.secs)}${tail}`;
+}
+
+export function jevLine(e: JevLine, plain: boolean): string {
+  const tail = e.source === "default" ? ` ${glyph("dot", plain)} fell back to the profile default` : "";
+  return `${e.questions.join(", ")} ${glyph("arrow", plain)} ${e.used}${tail}`;
+}
+
+/** spec §11b: --plain's stand-in for the coloured budget bar, e.g. "[#####-----] 52%". */
+export function plainBudgetBar(fraction: number, width = 10): string {
+  const f = Math.max(0, Math.min(1, fraction));
+  const filled = Math.round(f * width);
+  return `[${"#".repeat(filled)}${"-".repeat(width - filled)}] ${Math.round(f * 100)}%`;
+}
+
+/** spec §11b: the bar is the ginger-to-pink gradient below 80%, a solid warning tint from 80%,
+ * and a solid error tint once the budget is spent. Only ginger/pink exist in the warm palette
+ * (theme.ts), so "warning" and "error" reuse them rather than adding new tones. */
+export type BudgetTone = "gradient" | "warning" | "error";
+
+export function budgetTone(fraction: number): BudgetTone {
+  if (fraction >= 1) return "error";
+  if (fraction >= 0.8) return "warning";
+  return "gradient";
+}

package/src/tui/watch.tsx

@@ -0,0 +1,258 @@
+import { join } from "node:path";
+import { TextAttributes } from "@opentui/core";
+import { useKeyboard, useRenderer } from "@opentui/react";
+import { useEffect, useRef, useState } from "react";
+import { type BudgetStatus, formatBudget, type RunSummary, summarizeRun } from "../core/status.ts";
+import { listRuns, readJsonl, readRunRecords, type Run } from "../core/runstore.ts";
+import type { RunRecord, RungId } from "../types.ts";
+import { face, glyph, type Mood, tint, type Ui } from "./theme.ts";
+import { CatSpinner, Header, Screen, gradientLetters } from "./ui.tsx";
+import {
+  budgetTone,
+  climbs,
+  jevLine,
+  type JevLine,
+  liveLine,
+  milestoneLine,
+  plainBudgetBar,
+  recordLine,
+  runLine,
+  runMood,
+} from "./watch-model.ts";
+
+export interface WatchDeps {
+  listRuns: () => Run[];
+  summarizeRun: (run: Run) => RunSummary;
+  readRunRecords: (dir: string) => RunRecord[];
+  readJev: (dir: string) => JevLine[];
+}
+
+const watchDeps: WatchDeps = {
+  listRuns,
+  summarizeRun,
+  readRunRecords,
+  readJev: (dir) => readJsonl<JevLine>(join(dir, "jev.jsonl")),
+};
+
+// ponytail: only the 20 newest runs are summarized each poll; add paging when someone keeps more than that live
+const MAX_RUNS = 20;
+const SHOWN = 6;
+
+interface Item {
+  run: Run;
+  summary: RunSummary | null;
+  error: string | null;
+}
+
+function poll(d: WatchDeps): { items: Item[]; problem: string | null } {
+  try {
+    const items = d
+      .listRuns()
+      .slice(0, MAX_RUNS)
+      .map((run): Item => {
+        try {
+          return { run, summary: d.summarizeRun(run), error: null };
+        } catch (e) {
+          return { run, summary: null, error: (e as Error).message };
+        }
+      });
+    return { items, problem: null };
+  } catch (e) {
+    return { items: [], problem: (e as Error).message };
+  }
+}
+
+/** spec §11b: a bar in the ginger-to-pink gradient, solid ginger from 80% spent and solid pink once
+ * the budget is exhausted (the palette has no dedicated warning/error tones, see watch-model.ts). */
+function BudgetBar({ ui, budget }: { ui: Ui; budget: BudgetStatus }) {
+  const width = 10;
+  if (ui.plain) {
+    return (
+      <text
+        wrapMode="none"
+        truncate
+      >{`    ${plainBudgetBar(budget.fraction, width)} ${formatBudget(budget)}`}</text>
+    );
+  }
+  const filled = Math.round(Math.max(0, Math.min(1, budget.fraction)) * width);
+  const tone = budgetTone(budget.fraction);
+  const solid =
+    tone === "error" ? tint("pink", ui.depth) : tone === "warning" ? tint("ginger", ui.depth) : null;
+  const cells = solid
+    ? Array.from({ length: filled }, () => ({ ch: "█", fg: solid }))
+    : gradientLetters("█".repeat(filled));
+  return (
+    <text wrapMode="none" truncate>
+      {"    "}
+      {cells.map((cell, i) => (
+        // biome-ignore lint: index key is stable, the bar never reorders
+        <span key={i} fg={cell.fg}>
+          {cell.ch}
+        </span>
+      ))}
+      <span attributes={TextAttributes.DIM}>{"░".repeat(width - filled)}</span>
+      {` ${formatBudget(budget)}`}
+    </text>
+  );
+}
+
+function RunBlock({ ui, it, here }: { ui: Ui; it: Item; here: boolean }) {
+  const cur = here ? glyph("cursor", ui.plain) : " ";
+  if (!it.summary) {
+    return (
+      <text wrapMode="none" truncate attributes={TextAttributes.DIM}>
+        {`${cur} ${face("failed", ui.plain)} ${it.run.id} ${glyph("dot", ui.plain)} unreadable: ${it.error}`}
+      </text>
+    );
+  }
+  const s = it.summary;
+  const ginger = tint("ginger", ui.depth);
+  const pink = tint("pink", ui.depth);
+  return (
+    <box style={{ flexDirection: "column" }}>
+      <text
+        wrapMode="none"
+        truncate
+        attributes={here ? TextAttributes.BOLD : TextAttributes.NONE}
+      >{`${cur} ${runLine(s, ui.plain)}`}</text>
+      {s.live.map((l) => (
+        <text key={l.name} wrapMode="none" truncate fg={ginger}>{`    ${liveLine(l, ui.plain)}`}</text>
+      ))}
+      {s.milestones.map((m) => (
+        <text key={m} wrapMode="none" truncate fg={pink}>{`    ${milestoneLine(m, ui.plain)}`}</text>
+      ))}
+      {s.budget ? <BudgetBar ui={ui} budget={s.budget} /> : null}
+    </box>
+  );
+}
+
+function Detail({ ui, run, summary, deps }: { ui: Ui; run: Run; summary: RunSummary; deps: WatchDeps }) {
+  const records = deps.readRunRecords(run.dir);
+  const jev = deps.readJev(run.dir);
+  const dot = ` ${glyph("dot", ui.plain)} `;
+  const ginger = tint("ginger", ui.depth);
+  return (
+    <box style={{ flexDirection: "column" }}>
+      <text
+        wrapMode="none"
+        truncate
+        attributes={TextAttributes.DIM}
+      >{`${run.meta.repo}${dot}${run.id}`}</text>
+      <text fg={ginger} attributes={TextAttributes.BOLD}>
+        state
+      </text>
+      {summary.stateTail.map((l, i) => (
+        <text key={`s${i}`} wrapMode="none" truncate>{`  ${l}`}</text>
+      ))}
+      <text fg={ginger} attributes={TextAttributes.BOLD}>{`records${dot}${records.length}`}</text>
+      {records.slice(-8).map((r, i) => (
+        <text key={`r${i}`} wrapMode="none" truncate>{`  ${recordLine(r, ui.plain)}`}</text>
+      ))}
+      <text fg={ginger} attributes={TextAttributes.BOLD}>
+        {`jev${dot}${summary.jev.decisions} decisions${dot}${summary.jev.fallbacks} fell back`}
+      </text>
+      {jev.slice(-6).map((e, i) => (
+        <text key={`j${i}`} wrapMode="none" truncate>{`  ${jevLine(e, ui.plain)}`}</text>
+      ))}
+      <text attributes={TextAttributes.DIM}>{`esc back${dot}q quit`}</text>
+    </box>
+  );
+}
+
+export function Watch({
+  ui,
+  deps = {},
+  intervalMs = 2000,
+}: {
+  ui: Ui;
+  deps?: Partial<WatchDeps>;
+  intervalMs?: number;
+}) {
+  const d = { ...watchDeps, ...deps };
+  const renderer = useRenderer();
+  const seen = useRef(new Map<string, RungId>());
+  const [state, setState] = useState<{ items: Item[]; problem: string | null } | null>(null);
+  const [climbed, setClimbed] = useState<string[]>([]);
+  const [cursor, setCursor] = useState(0);
+  const [open, setOpen] = useState<string | null>(null);
+
+  useEffect(() => {
+    const refresh = () => {
+      const next = poll(d);
+      const fresh = next.items.flatMap((it) =>
+        it.summary ? climbs(seen.current, it.summary, ui.plain) : [],
+      );
+      if (fresh.length > 0) setClimbed((c) => [...fresh, ...c].slice(0, 3));
+      setState(next);
+    };
+    refresh();
+    const t = setInterval(refresh, intervalMs);
+    return () => clearInterval(t);
+  }, []);
+
+  const items = state?.items ?? [];
+  const at = Math.min(cursor, Math.max(0, items.length - 1));
+  const detail = items.find((it) => it.run.dir === open);
+
+  useKeyboard((key) => {
+    if (key.sequence === "q") {
+      renderer.destroy();
+      return;
+    }
+    if (detail) {
+      if (key.name === "escape" || key.name === "left" || key.name === "return") setOpen(null);
+      return;
+    }
+    const it = items[at];
+    if (key.name === "up") setCursor(Math.max(0, at - 1));
+    else if (key.name === "down") setCursor(Math.min(items.length - 1, at + 1));
+    else if (key.name === "return" && it?.summary) setOpen(it.run.dir);
+  });
+
+  const summaries = items.flatMap((it) => (it.summary ? [it.summary] : []));
+  const mood: Mood =
+    state === null || summaries.some((s) => s.live.length > 0)
+      ? "working"
+      : state.problem || items.some((it) => it.error) || summaries.some((s) => runMood(s) === "failed")
+        ? "failed"
+        : items.length > 0
+          ? "good"
+          : "waiting";
+  const dot = ` ${glyph("dot", ui.plain)} `;
+  const pink = tint("pink", ui.depth);
+  const start = Math.max(0, Math.min(at - Math.floor(SHOWN / 2), items.length - SHOWN));
+
+  return (
+    <Screen>
+      <Header
+        ui={ui}
+        mood={mood}
+        title={detail ? `watch${dot}${detail.run.meta.title}` : `watch${dot}${items.length} runs`}
+      />
+      {detail?.summary ? (
+        <Detail ui={ui} run={detail.run} summary={detail.summary} deps={d} />
+      ) : (
+        <box style={{ flexDirection: "column" }}>
+          {state === null ? <CatSpinner ui={ui} label="reading the runs" /> : null}
+          {state?.problem ? (
+            <text fg={pink} wrapMode="none" truncate>{`${face("failed", ui.plain)} ${state.problem}`}</text>
+          ) : null}
+          {state !== null && !state.problem && items.length === 0 ? (
+            <text>No runs yet. Start one with /catherd in Claude Code.</text>
+          ) : null}
+          {items.slice(start, start + SHOWN).map((it, i) => (
+            <RunBlock key={it.run.dir} ui={ui} it={it} here={start + i === at} />
+          ))}
+          {climbed.map((c, i) => (
+            <text key={`c${i}`} fg={pink} wrapMode="none" truncate>
+              {c}
+            </text>
+          ))}
+          <text attributes={TextAttributes.DIM} wrapMode="none" truncate>
+            {`${glyph("keys", ui.plain)} move${dot}enter details${dot}q quit${dot}refreshes every ${intervalMs / 1000} s`}
+          </text>
+        </box>
+      )}
+    </Screen>
+  );
+}