catherd-cli 0.2.1 → 1.0.0

package/src/entry/tui/effects.ts

@@ -0,0 +1,270 @@
+import { statSync } from "node:fs";
+import { adapterFor } from "../../adapters/registry.ts";
+import "../../adapters/all.ts";
+import { agentFiles } from "../../domain/agents.ts";
+import type { Catalog } from "../../domain/catalog.ts";
+import { HARNESS_KEYS, type Profile, type ProfileDoc, type ProfilePatch } from "../../domain/profile.ts";
+import { type Validation, validateProfile } from "../../domain/profile-rules.ts";
+import type { Access } from "../../domain/record.ts";
+import type { RouteSource } from "../../domain/route.ts";
+import { VERSION } from "../../infra/version.ts";
+import {
+  type CatalogModel,
+  catalogQuery,
+  loadCatalog,
+  type Refreshed,
+  refreshDiscovery,
+  saveTreatLike,
+} from "../../services/catalog-service.ts";
+import { cancel } from "../../services/dispatch-service.ts";
+import { type DoctorReport, doctor } from "../../services/doctor.ts";
+import type { Synced } from "../../services/agent-links.ts";
+import {
+  activate,
+  createProfile,
+  deleteProfile,
+  patchProfile,
+  type Saved,
+} from "../../services/profile-service.ts";
+import {
+  activeName,
+  configFile,
+  enforcementOf,
+  listProfiles,
+  profilesDir,
+  projectsFile,
+  readProfileDoc,
+  readProjects,
+  runnableBackends,
+} from "../../services/profile-store.ts";
+import { findRun, listRuns, readRoutes, type Run, runPaths } from "../../services/run-store.ts";
+import { type RunSummary, summarizeRun } from "../../services/summary.ts";
+import { defaultDeps } from "../deps.ts";
+import { mcpHandshake } from "../mcp/handshake.ts";
+
+/** A save refused because the profile changed on disk since its preview read it carries this path. */
+export { CHANGED_ON_DISK } from "../../services/profile-service.ts";
+
+/** One line of the run list. */
+export interface RunRow {
+  id: string;
+  title: string;
+  repo: string;
+  createdAt: string;
+  live: number;
+  roleRuns: number;
+  landed: number;
+  /** the budget's spent fraction, null without a cap */
+  budget: number | null;
+}
+
+interface Climb {
+  lane: string;
+  from: string;
+  to: string;
+  reason: string;
+  /** the environment's fault (a limit, a missing service), not the rung's */
+  env: boolean;
+}
+
+interface Decision {
+  lane: string;
+  role: string;
+  source: RouteSource;
+  kind: string | null;
+  difficulty: string | null;
+  rung: string;
+}
+
+/** Spec §9.1's run view: live lanes, climbs, Jev decisions, budget, landed milestones. */
+export interface RunDetail {
+  summary: RunSummary;
+  climbs: Climb[];
+  decisions: Decision[];
+}
+
+/**
+ * Everything the TUI reads or changes, behind one seam (spec §9.4 `effects.ts`: services injected).
+ * The live set calls the services; tests and the storybook pass fakes.
+ */
+export interface Effects {
+  version: string;
+  doctor(): Promise<DoctorReport>;
+  runs(): { rows: RunRow[]; warnings: string[] };
+  run(id: string): RunDetail;
+  /** stops a live role; resolves to the line the toast shows */
+  cancel(run: string, name: string): Promise<string>;
+  profiles(): {
+    names: string[];
+    /** global */
+    active: string;
+    /** what this directory runs on */
+    here: string;
+    /** the bound repo, null outside one or unbound */
+    repo: string | null;
+  };
+  readProfile(name: string): ProfileDoc;
+  catalog(billing: Profile["billing"]): { catalog: Catalog; models: CatalogModel[] };
+  validate(p: Profile, c: Catalog): Validation;
+  enforcement(rung: string, access: Access): "enforced" | "advisory";
+  /** the harnesses a profile can isolate */
+  harnesses: readonly string[];
+  /** the native agents a profile links, by name */
+  agents(p: Profile): string[];
+  /**
+   * writes the staged treat-likes, then the profile patch, through the ProfileService (validation reads
+   * the treat-likes, so they go first); a refused patch leaves the treat-likes written. With `shown` (the
+   * profile as the save dialog's last preview read it), the patch is written only over that profile: when
+   * another process changed it meanwhile (while a treat-like waited for the catalog lock, say), nothing
+   * is written and the result's one error has the path CHANGED_ON_DISK
+   */
+  save(
+    name: string,
+    patch: ProfilePatch,
+    treatLikes: Record<string, string>,
+    shown?: ProfileDoc,
+  ): Promise<Saved>;
+  /**
+   * applies the scope the user confirmed: binds `repo` (this TUI's repo) to it, or with null makes it the
+   * global active profile; never a scope recomputed as it writes
+   */
+  activate(name: string, repo: string | null): Synced;
+  create(name: string, from?: string): Saved;
+  remove(name: string): Synced;
+  refreshCatalog(): Promise<Refreshed[]>;
+}
+
+/** The word for `here`: the bound repo's profile, or the global active one. */
+export const hereWord = (p: { repo: string | null }): string => (p.repo ? "this repo" : "active");
+
+/**
+ * What changes when a run changes: the mtimes of its record files and of its roles folder, plus the
+ * profiles folder, config.json and projects.json (a saved budget cap or another active profile moves the
+ * run's budget fraction).
+ */
+export function stampOf(dir: string): string {
+  const p = runPaths(dir);
+  return [
+    p.runs,
+    p.routes,
+    p.jev,
+    p.agents,
+    p.state,
+    p.ledger,
+    p.roles,
+    profilesDir(),
+    configFile(),
+    projectsFile(),
+  ]
+    .map((f) => {
+      try {
+        return String(statSync(f).mtimeMs);
+      } catch {
+        return "-";
+      }
+    })
+    .join(" ");
+}
+
+/**
+ * The run list, each row computed again only when its run's files changed or a role is live (spec §9.4:
+ * runs data memoised by mtime). A live run's elapsed times move without any file changing.
+ */
+export function memoRuns(compute: (run: Run) => RunRow, stamp: (dir: string) => string = stampOf) {
+  const cache = new Map<string, { stamp: string; row: RunRow }>();
+  return (runs: Run[]): RunRow[] =>
+    runs.map((r) => {
+      const s = stamp(r.dir);
+      const hit = cache.get(r.dir);
+      if (hit && hit.stamp === s && hit.row.live === 0) return hit.row;
+      const row = compute(r);
+      cache.set(r.dir, { stamp: s, row });
+      return row;
+    });
+}
+
+export function rowOf(s: RunSummary): RunRow {
+  return {
+    id: s.id,
+    title: s.title,
+    repo: s.repo,
+    createdAt: s.createdAt,
+    live: s.live.length,
+    roleRuns: s.totals.runs,
+    landed: s.milestones.length,
+    budget: s.budget?.fraction ?? null,
+  };
+}
+
+/** The climbs and route decisions in a run's routes.jsonl. */
+function routesOf(run: Run): { climbs: Climb[]; decisions: Decision[] } {
+  const rows = readRoutes(run);
+  return {
+    climbs: rows
+      .filter((r) => r.source === "climb" && r.from !== null)
+      .map((r) => ({
+        lane: r.lane,
+        from: r.from as string,
+        to: r.rung,
+        reason: r.reason ?? "",
+        env: r.env === true,
+      })),
+    decisions: rows
+      .filter((r) => r.source === "route")
+      .map((r) => ({
+        lane: r.lane,
+        role: r.role,
+        source: r.decidedBy,
+        kind: r.kind,
+        difficulty: r.difficulty,
+        rung: r.rung,
+      })),
+  };
+}
+
+/**
+ * The live effects. `repo` is the git toplevel the TUI was opened in (null outside one): inside a repo
+ * bound to a profile, `here` is that profile and activating binds the repo instead of the global profile.
+ */
+export function liveEffects(repo: string | null = null): Effects {
+  const deps = defaultDeps();
+  const rows = memoRuns((r) => rowOf(summarizeRun(deps, r)));
+  const harnesses = HARNESS_KEYS.filter((h) => adapterFor(h));
+  const bound = () => (repo !== null && readProjects().bindings[repo] !== undefined ? repo : null);
+  return {
+    version: VERSION,
+    doctor: () => doctor({ bunVersion: Bun.version, version: VERSION, handshake: () => mcpHandshake() }),
+    runs() {
+      const { runs, corrupt } = listRuns();
+      return { rows: rows(runs), warnings: corrupt.map((c) => `skipped run ${c.id}: ${c.reason}`) };
+    },
+    run(id) {
+      const run = findRun(id);
+      return { summary: summarizeRun(deps, run), ...routesOf(run) };
+    },
+    async cancel(run, name) {
+      const r = await cancel(deps, run, name);
+      return `${r.record.name} ${r.record.status}`;
+    },
+    profiles: () => ({ names: listProfiles(), active: activeName(), here: activeName(repo), repo: bound() }),
+    readProfile: readProfileDoc,
+    catalog(billing) {
+      return {
+        catalog: loadCatalog({ timings: false }),
+        models: catalogQuery({ scoredOnly: false, limit: Number.MAX_SAFE_INTEGER }, billing).models,
+      };
+    },
+    validate: (p, c) => validateProfile(p, c, runnableBackends()),
+    enforcement: enforcementOf,
+    harnesses,
+    agents: (p) => agentFiles(p, VERSION).map((f) => f.name),
+    async save(name, patch, treatLikes, shown) {
+      for (const [rung, like] of Object.entries(treatLikes)) await saveTreatLike(rung, like);
+      return patchProfile(name, patch, shown === undefined ? {} : { expect: shown });
+    },
+    activate: (name, scope) => activate(name, scope),
+    create: createProfile,
+    remove: deleteProfile,
+    refreshCatalog: () => refreshDiscovery(),
+  };
+}

package/src/entry/tui/fixtures.ts

@@ -0,0 +1,318 @@
+import { isDeepStrictEqual } from "node:util";
+import {
+  applyPatch,
+  defaultProfileDoc,
+  diffProfiles,
+  type ProfileDoc,
+  resolveProfile,
+} from "../../domain/profile.ts";
+import { validateProfile } from "../../domain/profile-rules.ts";
+import { catalogQuery, loadCatalog } from "../../services/catalog-service.ts";
+import type { DoctorReport } from "../../services/doctor.ts";
+import type { RunSummary } from "../../services/summary.ts";
+import { CHANGED_ON_DISK, type Effects, type RunDetail, type RunRow, rowOf } from "./effects.ts";
+import { withStaged } from "./profile-tree.ts";
+
+/**
+ * Fixed data for the storybook (CATHERD_STORY=1), the frame snapshots and the view tests: a setup with
+ * one backend missing and one not logged in, two runs (one live), and profiles kept in memory. Only
+ * the catalog is the shipped one, read through the catalog service.
+ */
+export const FIXTURE_REPORT: DoctorReport = {
+  ready: false,
+  version: "1.0.0",
+  checks: [
+    { id: "bun", label: "Bun", state: "ok", word: "ready", detail: "1.4.2" },
+    { id: "config", label: "config", state: "ok", word: "ready", detail: "active profile default" },
+    { id: "profile", label: "profile default", state: "ok", word: "ready", detail: "valid" },
+    {
+      id: "backend:codex",
+      label: "codex",
+      state: "ok",
+      word: "ready",
+      detail: "0.156.1, logged in, 14 models",
+    },
+    {
+      id: "backend:claude-code",
+      label: "claude-code",
+      state: "ok",
+      word: "ready",
+      detail: "2.1.282, logged in, 6 models",
+    },
+    {
+      id: "backend:opencode",
+      label: "opencode",
+      state: "warn",
+      word: "not logged in",
+      detail: "2.0.16 (a failover stand-in uses it)",
+      fix: "opencode auth login",
+    },
+    {
+      id: "jev",
+      label: "Jev",
+      state: "skip",
+      word: "no key",
+      detail: "optional: routing uses the lane files",
+    },
+    {
+      id: "plugin",
+      label: "Claude Code plugin",
+      state: "fail",
+      word: "missing",
+      detail: "not installed",
+      fix: "claude plugin marketplace add 47vigen/catherd && claude plugin install catherd@catherd",
+    },
+    { id: "agents", label: "Claude agents", state: "ok", word: "ready", detail: "2 linked" },
+    { id: "mcp", label: "MCP server", state: "ok", word: "ready", detail: "21 tools" },
+  ],
+};
+
+const summary = (o: Partial<RunSummary> & Pick<RunSummary, "id" | "title">): RunSummary => ({
+  repo: "/home/me/app",
+  createdAt: "2026-09-26T11:48:00.000Z",
+  stateTail: [],
+  live: [],
+  totals: {
+    runs: 0,
+    ok: 0,
+    notOk: [],
+    tokens: { input: 0, cached: 0, output: 0 },
+    costUsd: 0,
+    wallMinutes: 12,
+  },
+  agents: { runs: 0, totalTokens: 0, costUsd: 0 },
+  jev: { decisions: 0, fallbacks: 0 },
+  harness: [],
+  budget: null,
+  milestones: [],
+  warnings: [],
+  ...o,
+});
+
+const FIXTURE_RUNS: RunDetail[] = [
+  {
+    summary: summary({
+      id: "20260926-114800-jobs-screen",
+      title: "Jobs screen",
+      stateTail: ["M1 in review", "Next: fix round for M1.L2"],
+      live: [
+        {
+          name: "worker-M1.L2",
+          rung: "codex:gpt-6-sol#medium",
+          state: "running",
+          secs: 252,
+          dispatchId: "d2",
+        },
+        { name: "reviewer-M1", rung: "codex:gpt-6-sol#high", state: "starting", secs: 4, dispatchId: "d3" },
+      ],
+      totals: {
+        runs: 3,
+        ok: 3,
+        notOk: [],
+        tokens: { input: 812_000, cached: 640_000, output: 41_000 },
+        costUsd: 0,
+        wallMinutes: 12,
+      },
+      jev: { decisions: 2, fallbacks: 0 },
+      budget: { fraction: 0.52, minutes: { spent: 31, cap: 60 } },
+      milestones: ["M0 | scaffold the jobs screen | 3f2a9c1 | 9 | bun test test/jobs"],
+    }),
+    climbs: [
+      {
+        lane: "M1.L2",
+        from: "codex:gpt-6-luna#high",
+        to: "codex:gpt-6-sol#medium",
+        reason: "refused",
+        env: false,
+      },
+    ],
+    decisions: [
+      {
+        lane: "M1.L1",
+        role: "worker",
+        source: "lane",
+        kind: "repo_code",
+        difficulty: "copy",
+        rung: "codex:gpt-6-luna#high",
+      },
+      {
+        lane: "M1.L2",
+        role: "worker",
+        source: "lane",
+        kind: "repo_code",
+        difficulty: "build",
+        rung: "codex:gpt-6-luna#high",
+      },
+    ],
+  },
+  {
+    summary: summary({
+      id: "20260925-090000-auth-refactor",
+      title: "Auth refactor",
+      repo: "/home/me/api",
+      createdAt: "2026-09-25T09:00:00.000Z",
+      stateTail: ["Next: done"],
+      totals: {
+        runs: 9,
+        ok: 8,
+        notOk: ["worker-M2.L1 (limit)"],
+        tokens: { input: 3_100_000, cached: 2_400_000, output: 160_000 },
+        costUsd: 1.84,
+        wallMinutes: 96,
+      },
+      milestones: [
+        "M1 | tokens | a1 | 30 | ok",
+        "M2 | sessions | b2 | 41 | ok",
+        "M3 | cleanup | c3 | 25 | ok",
+      ],
+    }),
+    climbs: [],
+    decisions: [],
+  },
+];
+
+const fixtureRow = (d: RunDetail): RunRow => rowOf(d.summary);
+
+const BACKENDS = ["claude", "codex", "claude-code", "opencode"];
+
+/**
+ * Effects over the fixtures; profile writes stay in memory and are recorded in `writes`. `repo` is the
+ * directory the TUI stands in and `bindings` the repo bindings, as `liveEffects(repo)` reads them.
+ */
+export function fixtureEffects(
+  o: {
+    runs?: RunDetail[];
+    report?: DoctorReport;
+    repo?: string;
+    bindings?: Record<string, string>;
+  } = {},
+): Effects & { writes: string[] } {
+  const runs = o.runs ?? FIXTURE_RUNS;
+  const docs = new Map<string, ProfileDoc>([["default", defaultProfileDoc()]]);
+  let active = "default";
+  const bindings = new Map(Object.entries(o.bindings ?? {}));
+  const bound = () => (o.repo && bindings.has(o.repo) ? o.repo : null);
+  const writes: string[] = [];
+  /** what the ProfileService returns for writing `after` over `before` */
+  const result = (
+    name: string,
+    before: ProfileDoc,
+    after: ProfileDoc,
+    staged: Record<string, string> = {},
+  ) => {
+    const p = resolveProfile(after, name);
+    const v = validateProfile(p, withStaged(loadCatalog({ timings: false }), staged), BACKENDS);
+    return {
+      saved: v.errors.length === 0,
+      ...v,
+      diff: diffProfiles(resolveProfile(before, name), p),
+      linked: [],
+      pruned: [],
+      newSessionNeededFor: [],
+    };
+  };
+  return {
+    writes,
+    version: "1.0.0",
+    doctor: async () => o.report ?? FIXTURE_REPORT,
+    runs: () => ({ rows: runs.map(fixtureRow), warnings: [] }),
+    run(id) {
+      const d = runs.find((r) => r.summary.id === id);
+      if (!d) throw new Error(`no run "${id}"`);
+      return d;
+    },
+    async cancel(run, name) {
+      writes.push(`cancel ${run} ${name}`);
+      return `${name} cancelled`;
+    },
+    profiles: () => ({
+      names: [...docs.keys()].sort(),
+      active,
+      here: bindings.get(o.repo ?? "") ?? active,
+      repo: bound(),
+    }),
+    readProfile(name) {
+      const d = docs.get(name);
+      if (!d) throw new Error(`no profile named "${name}"`);
+      return d;
+    },
+    catalog: (billing) => ({
+      catalog: loadCatalog({ timings: false }),
+      models: catalogQuery({ scoredOnly: false, limit: Number.MAX_SAFE_INTEGER }, billing).models,
+    }),
+    validate: (p, c) => validateProfile(p, c, BACKENDS),
+    enforcement: (rung) => (rung.startsWith("codex:") ? "enforced" : "advisory"),
+    harnesses: ["codex", "claude-code", "opencode"],
+    agents: (p) =>
+      (["architect", "verifier"] as const)
+        .filter((r) => p.roles[r].enabled)
+        .flatMap((r) =>
+          p.roles[r].rungs
+            .filter((x) => x.startsWith("claude:"))
+            .map((x) => `catherd-${p.name}-${r}-${x.slice(7).replace("#", "-")}`),
+        ),
+    async save(name, patch, treatLikes, shown) {
+      const before = docs.get(name) ?? defaultProfileDoc(name);
+      // the ProfileService's compare-and-swap: nothing is written over a profile the preview did not show
+      if (shown !== undefined && !isDeepStrictEqual(before, shown))
+        return {
+          saved: false,
+          errors: [
+            {
+              path: CHANGED_ON_DISK,
+              message: `profile "${name}" changed on disk since it was shown`,
+              fix: "check the changes and save again",
+            },
+          ],
+          warnings: [],
+          diff: [],
+          linked: [],
+          pruned: [],
+          newSessionNeededFor: [],
+        };
+      const after = applyPatch(before, patch);
+      const r = result(name, before, after, treatLikes);
+      if (r.saved) {
+        docs.set(name, after);
+        const tl = Object.keys(treatLikes).length ? ` ${JSON.stringify(treatLikes)}` : "";
+        writes.push(`save ${name} ${JSON.stringify(patch)}${tl}`);
+      }
+      return r;
+    },
+    activate(name, repo) {
+      if (repo !== null) {
+        bindings.set(repo, name);
+        writes.push(`bind ${name} ${repo}`);
+      } else {
+        active = name;
+        writes.push(`activate ${name}`);
+      }
+      return {
+        linked: [],
+        pruned: [],
+        newSessionNeededFor: [`catherd-${name}-architect-claude-opus-5-5-high`],
+      };
+    },
+    create(name, from) {
+      const doc = { ...(from ? (docs.get(from) as ProfileDoc) : defaultProfileDoc(name)), name };
+      const r = result(name, doc, doc);
+      if (r.saved) {
+        docs.set(name, doc);
+        writes.push(`create ${name}${from ? ` from ${from}` : ""}`);
+      }
+      return r;
+    },
+    remove(name) {
+      if (name === active) throw new Error(`"${name}" is the active profile`);
+      const at = [...bindings].find(([, p]) => p === name);
+      if (at) throw new Error(`"${name}" is bound to ${at[0]}`);
+      docs.delete(name);
+      writes.push(`remove ${name}`);
+      return { linked: [], pruned: [], newSessionNeededFor: [] };
+    },
+    async refreshCatalog() {
+      writes.push("refresh");
+      return [{ backend: "codex", models: 14, fetchedAt: "2026-09-26T12:00:00.000Z" }];
+    },
+  };
+}