catherd-cli 0.2.1 → 1.1.0

package/src/services/agent-links.ts

@@ -0,0 +1,139 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { basename, join, sep } from "node:path";
+import { type AgentFile, agentFiles } from "../domain/agents.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { claudeAgentsDir } from "../infra/paths.ts";
+import { ensurePrivateDir, writeTextAtomic } from "../infra/store.ts";
+import { VERSION } from "../infra/version.ts";
+import { activeName, agentsRoot, getProfile, profileExists, readProjects } from "./profile-store.ts";
+
+// Spec §7.3: the agent files and their links in Claude Code's agents dir. Only profile-service.ts writes
+// them, under its profiles lock.
+
+const lstatOrNull = (p: string) => {
+  try {
+    return lstatSync(p);
+  } catch {
+    return null;
+  }
+};
+const ours = (): string => `${agentsRoot()}${sep}`;
+/** A link catherd made: a symlink into `<config>/agents/`. Nothing else in the agents dir is ever touched. */
+const isOurLink = (path: string): boolean => {
+  const st = lstatOrNull(path);
+  return st !== null && st.isSymbolicLink() && readlinkSync(path).startsWith(ours());
+};
+
+/** Spec §7.3: the active profile and every repo-bound one are linked at once. */
+export function linkedProfiles(): string[] {
+  const names = new Set([activeName(), ...Object.values(readProjects().bindings)]);
+  return [...names].filter(profileExists).sort();
+}
+
+export interface Planned {
+  files: Map<string, AgentFile[]>;
+  links: Map<string, string>;
+}
+
+export function plan(extra: string[] = []): Planned {
+  const files = new Map<string, AgentFile[]>();
+  for (const name of new Set([...linkedProfiles(), ...extra.filter(profileExists)]))
+    files.set(name, agentFiles(getProfile(name), VERSION));
+  const links = new Map<string, string>();
+  for (const name of linkedProfiles())
+    for (const f of files.get(name) ?? [])
+      links.set(join(claudeAgentsDir(), `${f.name}.md`), join(agentsRoot(), name, `${f.name}.md`));
+  return { files, links };
+}
+
+/** Refuses before anything is written when a planned link would replace a file catherd does not own. */
+function assertNoConflict(p: Planned): void {
+  for (const link of p.links.keys())
+    if (lstatOrNull(link) && !isOurLink(link))
+      throw new CatherdError("E_CONFIG_INVALID", `${link} exists and is not catherd's`, {
+        fix: `move ${link} away, then run the command again`,
+      });
+}
+
+export interface Synced {
+  linked: string[];
+  pruned: string[];
+  /** agents whose link is new or whose file changed: Claude Code reads them only at a session's start */
+  newSessionNeededFor: string[];
+}
+
+/**
+ * Writes the planned agent files and links, prunes catherd's stale ones, and says what changed. The
+ * ownership check runs before the first write, so no caller can replace a file catherd does not own.
+ */
+export function apply(p: Planned, removed: string[] = []): Synced {
+  assertNoConflict(p);
+  const changed = new Set<string>();
+  for (const [name, files] of p.files) {
+    const dir = join(agentsRoot(), name);
+    ensurePrivateDir(dir);
+    const keep = new Set(files.map((f) => `${f.name}.md`));
+    for (const f of files) {
+      const path = join(dir, `${f.name}.md`);
+      if (!existsSync(path) || readFileSync(path, "utf8") !== f.text) {
+        writeTextAtomic(path, f.text);
+        changed.add(path);
+      }
+    }
+    for (const f of readdirSync(dir)) if (!keep.has(f)) rmSync(join(dir, f), { force: true });
+  }
+  for (const name of removed) rmSync(join(agentsRoot(), name), { recursive: true, force: true });
+
+  const target = claudeAgentsDir();
+  const newSession: string[] = [];
+  if (p.links.size > 0) mkdirSync(target, { recursive: true });
+  for (const [link, file] of p.links) {
+    const fresh = !isOurLink(link) || readlinkSync(link) !== file;
+    if (fresh) {
+      rmSync(link, { force: true });
+      symlinkSync(file, link);
+    }
+    if (fresh || changed.has(file)) newSession.push(basename(link, ".md"));
+  }
+  const pruned: string[] = [];
+  if (existsSync(target))
+    for (const entry of readdirSync(target)) {
+      const link = join(target, entry);
+      if (isOurLink(link) && !p.links.has(link)) {
+        rmSync(link, { force: true });
+        pruned.push(entry);
+      }
+    }
+  return {
+    linked: [...p.links.keys()].map((l) => basename(l, ".md")).sort(),
+    pruned: pruned.sort(),
+    // a removed agent is still loaded in the running Claude Code session until a new one starts
+    newSessionNeededFor: [...newSession, ...pruned.map((e) => basename(e, ".md"))].sort(),
+  };
+}
+
+/** What `doctor` compares: each link that should exist, and whether it and its file are current. */
+export function agentLinkState(): { missing: string[]; stale: string[]; ok: string[] } {
+  const p = plan();
+  const out = { missing: [] as string[], stale: [] as string[], ok: [] as string[] };
+  for (const [name, files] of p.files)
+    for (const f of files) {
+      const link = join(claudeAgentsDir(), `${f.name}.md`);
+      if (!p.links.has(link)) continue;
+      const file = join(agentsRoot(), name, `${f.name}.md`);
+      if (!isOurLink(link)) out.missing.push(f.name);
+      else if (readlinkSync(link) !== file || !existsSync(file) || readFileSync(file, "utf8") !== f.text)
+        out.stale.push(f.name);
+      else out.ok.push(f.name);
+    }
+  return out;
+}

package/src/services/backends.ts

@@ -0,0 +1,44 @@
+import type { BackendAdapter, Probe } from "../adapters/backend.ts";
+import { adapterFor } from "../adapters/registry.ts";
+import "../adapters/all.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { formatRung, tryParseRung } from "../domain/ids.ts";
+
+const READY_TTL_MS = 10 * 60_000;
+const ready = new Map<string, { at: number; probe: Probe }>();
+
+/** Forget every cached probe (tests, and after the user fixes a backend). */
+export const resetReadiness = (): void => ready.clear();
+
+/**
+ * Spec §4.4: the adapter for `backend` once its last probe says it is ready. A ready probe is kept
+ * for 10 minutes; a failing one is never kept, so a fixed backend works on the next dispatch.
+ */
+export async function readyAdapter(backend: string): Promise<{ adapter: BackendAdapter; probe: Probe }> {
+  const now = Date.now();
+  const adapter = adapterFor(backend);
+  if (!adapter)
+    throw new CatherdError("E_BACKEND_MISSING", `catherd has no ${backend} adapter yet`, {
+      fix: "use a rung on a backend catherd supports; catalog_query lists them",
+    });
+  const hit = ready.get(backend);
+  if (hit && now - hit.at < READY_TTL_MS) return { adapter, probe: hit.probe };
+  const probe = await adapter.probe();
+  const problem = probe.problems[0];
+  if (problem) throw new CatherdError(problem.code, problem.message, { fix: problem.fix });
+  ready.set(backend, { at: now, probe });
+  return { adapter, probe };
+}
+
+/**
+ * Spec §4.5: a rung's stand-in on a usage limit: the profile's, else its backend's default (for `repo`,
+ * when given), else none.
+ */
+export function standInFor(failover: Record<string, string>, rung: string, repo?: string): string | null {
+  const own = failover[rung];
+  if (own) return own;
+  const r = tryParseRung(rung);
+  if (!r) return null;
+  const byAdapter = adapterFor(r.backend)?.failoverFor?.(r, repo) ?? null;
+  return byAdapter && formatRung(byAdapter);
+}

package/src/services/budget.ts

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync } from "node:fs";
+import { adapterFor } from "../adapters/registry.ts";
+import "../adapters/all.ts";
+import { type Budget, type BudgetStatus, budgetStatus, type Spend } from "../domain/budget.ts";
+import type { RunRecord } from "../domain/record.ts";
+import { dispatchPaths } from "../infra/dispatch-dir.ts";
+import { type Dispatch, liveDispatches } from "./dispatches.ts";
+import { readAgentRuns, readRecords, type Run } from "./run-store.ts";
+
+/** Tokens a running dispatch has used so far, summed from the events its CLI has written. */
+export function liveTokens(d: Dispatch): number {
+  const a = adapterFor(d.admit.backend);
+  const file = dispatchPaths(d.dir).events;
+  if (!a || !existsSync(file)) return 0;
+  let n = 0;
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const t = a.parse(line).tokens;
+      if (t) n += t.input + t.output;
+    } catch {
+      // a line the adapter cannot read adds nothing
+    }
+  }
+  return n;
+}
+
+/**
+ * Spec §4.6: minutes are wall clock since run_start; tokens and dollars sum every record (every
+ * backend), every native subagent run the orchestrator reported, and what live roles used so far.
+ */
+export function spendOf(run: Run, records: RunRecord[], live: Dispatch[], now: number): Spend {
+  const agents = readAgentRuns(run);
+  const sum = <T>(xs: T[], f: (x: T) => number) => xs.reduce((n, x) => n + f(x), 0);
+  return {
+    minutes: Math.max(0, (now - Date.parse(run.meta.createdAt)) / 60_000),
+    tokens:
+      sum(records, (r) => r.tokens.input + r.tokens.output) +
+      sum(agents, (a) => a.totalTokens) +
+      sum(live, liveTokens),
+    usd: sum(records, (r) => r.costUsd ?? 0) + sum(agents, (a) => a.costUsd ?? 0),
+  };
+}
+
+export function budgetOf(run: Run, budget: Budget, now: number): BudgetStatus | null {
+  return budgetStatus(spendOf(run, readRecords(run).records, liveDispatches(run, now), now), budget);
+}

package/src/services/capture.ts

@@ -0,0 +1,233 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import type { BackendAdapter, FinishedRun } from "../adapters/backend.ts";
+import { isCatherdError } from "../domain/errors.ts";
+import { parseRung } from "../domain/ids.ts";
+import type { Access } from "../domain/record.ts";
+import { sanitize, type Scrub } from "../domain/sanitize.ts";
+import { secretEnvValues } from "../domain/secrets.ts";
+import { workerEnv } from "../infra/env.ts";
+import { git } from "../infra/git.ts";
+import { killGroup } from "../infra/proc.ts";
+import { writeJsonAtomic } from "../infra/store.ts";
+import { readyAdapter } from "./backends.ts";
+import { settled } from "./finalize.ts";
+import { collect, DRAIN_MS } from "./preflight.ts";
+
+interface CaptureCase {
+  backend: string;
+  name: string;
+  rung: string;
+  access: Access;
+  brief: string;
+}
+
+const SAY_HELLO =
+  "Reply with the single word hello. The last line of your reply is exactly: STATUS: complete — said hello";
+const TRY_WRITE =
+  "Create a file named out.txt containing the word hi. If you cannot, say why. The last line of your reply is: STATUS: complete|blocked — <one line why>";
+const HAIKU = "claude-code:claude-haiku-4-5-20251001#default";
+const BUNNY = "opencode:opencode/space-bunny-free#default";
+
+/** Spec §11.7–8: one cheap run per backend, plus a read-only role trying to write where enforcement is advisory. */
+const CAPTURE_CASES: CaptureCase[] = [
+  { backend: "codex", name: "ok", rung: "codex:gpt-6-luna#low", access: "read-only", brief: SAY_HELLO },
+  { backend: "claude-code", name: "ok", rung: HAIKU, access: "read-only", brief: SAY_HELLO },
+  { backend: "claude-code", name: "read-only-write", rung: HAIKU, access: "read-only", brief: TRY_WRITE },
+  { backend: "opencode", name: "ok", rung: BUNNY, access: "read-only", brief: SAY_HELLO },
+  { backend: "opencode", name: "read-only-write", rung: BUNNY, access: "read-only", brief: TRY_WRITE },
+];
+export const CAPTURE_BACKENDS = [...new Set(CAPTURE_CASES.map((c) => c.backend))];
+
+export type Captured =
+  | {
+      backend: string;
+      name: string;
+      status: "captured";
+      dir: string;
+      cliVersion: string;
+      exitCode: number | null;
+    }
+  | { backend: string; name: string; status: "skipped"; reason: string };
+
+async function scratchRepo(): Promise<{ work: string; repo: string }> {
+  const work = realpathSync(mkdtempSync(join(tmpdir(), "catherd-capture-")));
+  const repo = join(work, "repo");
+  mkdirSync(repo);
+  await git(repo, ["init", "-q"]);
+  await git(repo, [
+    "-c",
+    "user.name=catherd",
+    "-c",
+    "user.email=capture@catherd.invalid",
+    "commit",
+    "-q",
+    "--allow-empty",
+    "-m",
+    "init",
+  ]);
+  return { work, repo };
+}
+
+/** Every string in `v`, cleaned: meta values are sanitized before JSON escapes them, not after. */
+function cleanStrings(v: unknown, clean: (s: string) => string): unknown {
+  if (typeof v === "string") return clean(v);
+  if (Array.isArray(v)) return v.map((x) => cleanStrings(x, clean));
+  if (v && typeof v === "object")
+    return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, cleanStrings(x, clean)]));
+  return v;
+}
+
+/**
+ * Runs one case the way an isolated dispatch would (prepare, plan, the worker env), without the
+ * supervisor. Isolated, so the stream names none of the owner's own hooks, plugins, MCP servers or config:
+ * the fixtures are committed.
+ */
+async function captureOne(
+  adapter: BackendAdapter,
+  version: string,
+  c: CaptureCase,
+  outDir: string,
+  timeoutMs: number,
+): Promise<Captured> {
+  const { work, repo } = await scratchRepo();
+  try {
+    const briefPath = join(work, "brief.md");
+    writeFileSync(briefPath, c.brief);
+    const rung = parseRung(c.rung);
+    await adapter.prepare?.({ rung, access: c.access, isolated: true, repo });
+    const request = {
+      rung,
+      access: c.access,
+      thread: null,
+      isolated: true,
+      repo,
+      briefPath,
+      replyPath: join(work, "reply.md"),
+      dispatchDir: work,
+    };
+    const plan = adapter.plan(request);
+    const startedAtMs = Date.now();
+    const p = Bun.spawn([plan.cmd, ...plan.args], {
+      cwd: plan.cwd,
+      env: workerEnv(process.env, plan.env, plan.cwd),
+      stdin: Bun.file(briefPath),
+      stdout: "pipe",
+      stderr: "pipe",
+      // its own group, so a timeout stops whatever the CLI started too, as the supervisor does
+      detached: true,
+    });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup(p.pid, "SIGKILL");
+    }, timeoutMs);
+    // as preflight does: a process the CLI left behind (in its own session) may hold the pipes open
+    const out = collect(p.stdout);
+    const err = collect(p.stderr);
+    const code = await p.exited;
+    clearTimeout(timer);
+    const drained = await Promise.race([
+      Promise.all([out.done, err.done]).then(() => true),
+      Bun.sleep(DRAIN_MS).then(() => false),
+    ]);
+    if (!drained) killGroup(p.pid, "SIGKILL"); // leftovers still in the CLI's group
+    out.stop();
+    err.stop();
+    const events = out.text();
+    const stderr = err.text();
+    const run: FinishedRun = {
+      request,
+      eventLines: events.split("\n").filter((l) => l.trim()),
+      reply: "",
+      stderr,
+      exit: {
+        code: p.signalCode ? null : code,
+        signal: p.signalCode ?? null,
+        reason: timedOut ? "wall-timeout" : "exited",
+        endedAt: new Date().toISOString(),
+      },
+      startedAtMs,
+    };
+    // as a dispatch records it: the backend's own totals and limits, on a fresh thread (nothing prior)
+    const o = await settled(adapter, adapter.finalize(run), run, () => ({
+      tokens: { input: 0, cached: 0, output: 0 },
+      costUsd: 0,
+    }));
+    const scrub: Scrub = {
+      secrets: secretEnvValues(process.env),
+      paths: [
+        { from: repo, to: "<repo>" },
+        { from: work, to: "<tmp>" },
+        { from: realpathSync(tmpdir()), to: "<tmp>" },
+        { from: homedir(), to: "~" },
+      ],
+    };
+    const clean = (t: string) => sanitize(t, scrub);
+    const dir = join(outDir, c.backend, version);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, `${c.name}.jsonl`), clean(events));
+    writeFileSync(join(dir, `${c.name}.stderr`), clean(stderr));
+    writeJsonAtomic(
+      join(dir, `${c.name}.json`),
+      cleanStrings(
+        {
+          schema: 1,
+          backend: c.backend,
+          cliVersion: version,
+          case: c.name,
+          rung: c.rung,
+          access: c.access,
+          isolated: true,
+          brief: c.brief,
+          exitCode: run.exit.code,
+          reason: run.exit.reason,
+          capturedAt: new Date().toISOString(),
+          outcome: {
+            status: o.status,
+            thread: o.thread,
+            tokens: o.tokens,
+            costUsd: o.costUsd,
+            error: o.error,
+          },
+        },
+        clean,
+      ),
+      { mode: 0o644 },
+    );
+    return {
+      backend: c.backend,
+      name: c.name,
+      status: "captured",
+      dir,
+      cliVersion: version,
+      exitCode: run.exit.code,
+    };
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Spec §11.8: records the capture cases of every ready backend (or only `backends`) under
+ * `<outDir>/<backend>/<cli-version>/`, with secrets and home paths stripped. A backend that is not
+ * ready is skipped with the reason.
+ */
+export async function captureFixtures(o: {
+  outDir: string;
+  backends?: string[];
+  timeoutMs?: number;
+}): Promise<Captured[]> {
+  const out: Captured[] = [];
+  for (const c of CAPTURE_CASES.filter((x) => !o.backends || o.backends.includes(x.backend))) {
+    try {
+      const { adapter, probe } = await readyAdapter(c.backend);
+      out.push(await captureOne(adapter, probe.version ?? "unknown", c, o.outDir, o.timeoutMs ?? 300_000));
+    } catch (e) {
+      if (!isCatherdError(e)) throw e;
+      out.push({ backend: c.backend, name: c.name, status: "skipped", reason: `${e.code}: ${e.message}` });
+    }
+  }
+  return out;
+}