catherd-cli 0.2.1 → 1.0.0

package/src/core/reconcile.ts

@@ -1,26 +0,0 @@
-import type { RunRecord } from "../types.ts";
-import { finalizeCodex } from "./codex.ts";
-import { finalizeOpencode } from "./opencode.ts";
-import { type LiveMarker, readLive } from "./runstore.ts";
-
-export function pidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    return (e as NodeJS.ErrnoException).code === "EPERM";
-  }
-}
-
-export function reconcileLive(runDir: string): { finished: RunRecord[]; stillRunning: LiveMarker[] } {
-  const finished: RunRecord[] = [];
-  const stillRunning: LiveMarker[] = [];
-  for (const m of readLive(runDir)) {
-    if (pidAlive(m.pid)) {
-      stillRunning.push(m);
-      continue;
-    }
-    finished.push(m.backend === "codex" ? finalizeCodex(runDir, m, null) : finalizeOpencode(runDir, m, null));
-  }
-  return { finished, stillRunning };
-}

package/src/core/reply.ts

@@ -1,54 +0,0 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
-import type { ReplyStatus } from "../types.ts";
-
-const STATUS = /^STATUS:\s*(complete|partial|blocked|refused)\s*(?:—|–|-)\s*(.*)$/;
-
-/** Dirs never worth hashing, even under an owned path. */
-const SKIP = new Set(["node_modules", ".git", "dist", ".next", "coverage"]);
-
-export function parseReplyStatus(reply: string): { status: ReplyStatus | null; why: string | null } {
-  const last = reply.trimEnd().split("\n").at(-1)?.trim() ?? "";
-  const m = STATUS.exec(last);
-  return m ? { status: m[1] as ReplyStatus, why: (m[2] ?? "").trim() } : { status: null, why: null };
-}
-
-function hashFile(path: string): string {
-  return new Bun.CryptoHasher("sha1").update(readFileSync(path)).digest("hex");
-}
-
-/** Owned paths are matched literally: walked with node:fs, never interpreted as glob patterns. */
-function walk(root: string, dir: string, out: Map<string, string>): void {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (SKIP.has(entry.name)) continue;
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) walk(root, full, out);
-    else if (entry.isFile()) out.set(relative(root, full), hashFile(full));
-  }
-}
-
-export function snapshotOwned(repo: string, owned: string[]): Map<string, string> {
-  const m = new Map<string, string>();
-  for (const o of owned) {
-    const full = join(repo, o);
-    if (!existsSync(full)) {
-      m.set(o, "<absent>");
-      continue;
-    }
-    if (statSync(full).isDirectory()) walk(repo, full, m);
-    else m.set(o, hashFile(full));
-  }
-  return m;
-}
-
-export function changedSince(repo: string, before: Map<string, string>, owned: string[]): string[] {
-  const after = snapshotOwned(repo, owned);
-  const changed = new Set<string>();
-  for (const [p, h] of after) {
-    if (before.get(p) !== h && !(h === "<absent>" && !before.has(p))) changed.add(p);
-  }
-  for (const [p, h] of before) {
-    if (!after.has(p) && h !== "<absent>") changed.add(p);
-  }
-  return [...changed].sort();
-}

package/src/core/runstore.ts

@@ -1,163 +0,0 @@
-import {
-  appendFileSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
-import { join } from "node:path";
-import { dataDir, runsRoot } from "../paths.ts";
-import type { Role, RungId, RunMeta, RunRecord, StateSnapshot } from "../types.ts";
-
-export interface Run {
-  dir: string;
-  id: string;
-  meta: RunMeta;
-}
-
-/** Dirs under the data root that are catherd's own, not a repo's runs. */
-const NOT_REPOS = new Set(["locks", "codex-home", "opencode-home"]);
-
-const slug = (s: string) =>
-  s
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-|-$/g, "")
-    .slice(0, 40) || "run";
-
-const stamp = (d: Date) => d.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
-
-export function createRun(repo: string, title: string, aLines: string[]): Run {
-  const now = new Date();
-  const id = `${stamp(now)}-${slug(title)}`;
-  const dir = join(runsRoot(repo), id);
-  mkdirSync(join(dir, "lanes"), { recursive: true });
-  mkdirSync(join(dir, "roles"), { recursive: true });
-  mkdirSync(join(dir, "shots"), { recursive: true });
-  const meta: RunMeta = { id, repo, title, aLines, createdAt: now.toISOString() };
-  writeFileSync(join(dir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`);
-  writeFileSync(join(dir, "ledger.md"), "milestone | what | commit | minutes | evidence\n");
-  writeFileSync(join(dir, "state.md"), `# ${title}\n\n${aLines.join("\n")}\n\nNext: plan the milestones\n`);
-  return { dir, id, meta };
-}
-
-export function openRun(repo: string, id: string): Run {
-  const dir = join(runsRoot(repo), id);
-  const meta = JSON.parse(readFileSync(join(dir, "meta.json"), "utf8")) as RunMeta;
-  return { dir, id, meta };
-}
-
-export function listRuns(): Run[] {
-  const root = dataDir();
-  if (!existsSync(root)) return [];
-  const runs: Run[] = [];
-  for (const repo of readdirSync(root, { withFileTypes: true })) {
-    if (!repo.isDirectory() || NOT_REPOS.has(repo.name)) continue;
-    for (const run of readdirSync(join(root, repo.name), { withFileTypes: true })) {
-      const dir = join(root, repo.name, run.name);
-      if (!run.isDirectory() || !existsSync(join(dir, "meta.json"))) continue;
-      const meta = JSON.parse(readFileSync(join(dir, "meta.json"), "utf8")) as RunMeta;
-      runs.push({ dir, id: meta.id, meta });
-    }
-  }
-  return runs.sort((a, b) => b.meta.createdAt.localeCompare(a.meta.createdAt));
-}
-
-export function rolePaths(dir: string, name: string) {
-  const base = join(dir, "roles", name);
-  return {
-    brief: `${base}.md`,
-    fix: `${base}.fix.md`,
-    out: `${base}.out`,
-    jsonl: `${base}.jsonl`,
-    err: `${base}.err`,
-  };
-}
-
-/** Moves the latest round's out/jsonl/err to <name>.r<k>.* so the new round starts clean. */
-export function rotateRound(dir: string, name: string): void {
-  const p = rolePaths(dir, name);
-  const current = [p.out, p.jsonl, p.err].filter((f) => existsSync(f));
-  if (current.length === 0) return;
-  let k = 1;
-  while (["out", "jsonl", "err"].some((x) => existsSync(join(dir, "roles", `${name}.r${k}.${x}`)))) k++;
-  for (const x of ["out", "jsonl", "err"] as const) {
-    if (existsSync(p[x])) renameSync(p[x], join(dir, "roles", `${name}.r${k}.${x}`));
-  }
-}
-
-export function appendJsonl(file: string, value: unknown): void {
-  appendFileSync(file, `${JSON.stringify(value)}\n`);
-}
-
-export function readJsonl<T>(file: string): T[] {
-  if (!existsSync(file)) return [];
-  return readFileSync(file, "utf8")
-    .split("\n")
-    .filter((l) => l.trim())
-    .map((l) => JSON.parse(l) as T);
-}
-
-export const appendRunRecord = (dir: string, r: RunRecord) => appendJsonl(join(dir, "runs.jsonl"), r);
-export const readRunRecords = (dir: string) => readJsonl<RunRecord>(join(dir, "runs.jsonl"));
-
-export function writeState(dir: string, s: StateSnapshot): void {
-  const lines = [
-    `HEAD ${s.head}`,
-    "",
-    "Dirty:",
-    ...(s.dirty.length ? s.dirty.map((d) => `- ${d.path}${d.owner ? ` (${d.owner})` : ""}`) : ["- none"]),
-    "",
-    "Running:",
-    ...(s.running.length
-      ? s.running.map(
-          (r) => `- ${r.name} · ${r.rung} · thread ${r.thread ?? "new"} · since ${r.since} · ${r.brief}`,
-        )
-      : ["- none"]),
-    "",
-    `Last check: ${s.lastCheck ?? "none"}`,
-    "",
-    `Next: ${s.next}`,
-  ];
-  const title = readFileSync(join(dir, "state.md"), "utf8").split("\n")[0] ?? "# run";
-  writeFileSync(join(dir, "state.md"), `${title}\n\n${lines.join("\n")}\n`);
-}
-
-export function appendLedger(dir: string, row: string): void {
-  appendFileSync(join(dir, "ledger.md"), `${row}\n`);
-}
-
-export interface LiveMarker {
-  name: string;
-  role: Role;
-  backend: "codex" | "opencode";
-  rung: RungId;
-  pid: number;
-  thread: string | null;
-  startedAt: string;
-  cwd: string;
-  ownedFiles: string[];
-  isolated: boolean;
-  before: Record<string, string>;
-}
-
-const livePath = (dir: string, name: string) => join(dir, "roles", `${name}.live.json`);
-
-export function writeLive(dir: string, m: LiveMarker): void {
-  writeFileSync(livePath(dir, m.name), JSON.stringify(m));
-}
-
-export function clearLive(dir: string, name: string): void {
-  rmSync(livePath(dir, name), { force: true });
-}
-
-export function readLive(dir: string): LiveMarker[] {
-  const roles = join(dir, "roles");
-  if (!existsSync(roles)) return [];
-  return readdirSync(roles)
-    .filter((f) => f.endsWith(".live.json"))
-    .map((f) => JSON.parse(readFileSync(join(roles, f), "utf8")) as LiveMarker);
-}

package/src/core/spawn.ts

@@ -1,89 +0,0 @@
-import { closeSync, existsSync, openSync, readFileSync } from "node:fs";
-
-export interface ChildOpts {
-  cwd: string;
-  env: Record<string, string | undefined>;
-  /** file to feed on stdin; stdin is /dev/null without it */
-  stdinFile?: string;
-  stdoutFile: string;
-  stderrFile: string;
-  /** called with each batch of new stdout lines, every pollMs */
-  onLines?: (lines: string[]) => void;
-  pollMs?: number;
-  /** called every tickMs while the child runs */
-  onTick?: () => void;
-  tickMs?: number;
-  /** called once, right after the child starts */
-  onSpawn?: (c: { pid: number; kill: () => void }) => void;
-}
-
-export interface ChildResult {
-  code: number | null;
-  pid: number | null;
-  signal: NodeJS.Signals | null;
-}
-
-export function readLines(file: string): string[] {
-  if (!existsSync(file)) return [];
-  return readFileSync(file, "utf8")
-    .split("\n")
-    .filter((l) => l.trim());
-}
-
-/** Kills the whole process group a detached child leads (pgid === pid on POSIX). */
-function killGroup(pid: number): void {
-  try {
-    process.kill(-pid, "SIGTERM");
-  } catch {
-    try {
-      process.kill(pid, "SIGTERM");
-    } catch {
-      // already gone
-    }
-  }
-}
-
-/**
- * The child gets raw file descriptors, not a pipe through this process, so no stream passes
- * through catherd: with `detached: true` it starts its own process group (POSIX `setsid()`),
- * outlives catherd, and `reconcileLive` reads its files after a restart.
- */
-export async function runChild(cmd: string, args: string[], o: ChildOpts): Promise<ChildResult> {
-  if (!Bun.which(cmd, { PATH: o.env?.PATH ?? process.env.PATH ?? "" })) {
-    throw new Error(`catherd: ${cmd} is not on PATH; install it, or untick its models in the profile`);
-  }
-  const stdin = o.stdinFile ? openSync(o.stdinFile, "r") : "ignore";
-  const stdout = openSync(o.stdoutFile, "w");
-  const stderr = openSync(o.stderrFile, "w");
-  const proc = Bun.spawn([cmd, ...args], {
-    cwd: o.cwd,
-    env: o.env,
-    stdin,
-    stdout,
-    stderr,
-    detached: true,
-  });
-  for (const fd of [stdin, stdout, stderr]) if (typeof fd === "number") closeSync(fd);
-  const pid = proc.pid;
-  if (pid) o.onSpawn?.({ pid, kill: () => killGroup(pid) });
-  let seen = 0;
-  const drain = () => {
-    const lines = readLines(o.stdoutFile);
-    if (lines.length > seen) {
-      o.onLines?.(lines.slice(seen));
-      seen = lines.length;
-    }
-  };
-  const poll = o.onLines ? setInterval(drain, o.pollMs ?? 1000) : null;
-  const tick = o.onTick ? setInterval(o.onTick, o.tickMs ?? 60_000) : null;
-  let code: number | null;
-  try {
-    code = await proc.exited;
-  } finally {
-    if (poll) clearInterval(poll);
-    if (tick) clearInterval(tick);
-  }
-  if (o.onLines) drain();
-  if (!pid) throw new Error(`catherd: could not start ${cmd}`);
-  return { code, pid, signal: proc.signalCode ?? null };
-}

package/src/core/status.ts

@@ -1,193 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { activeProfileName, loadProfile } from "../profile/profile.ts";
-import type { Profile, Role, RungId, Tokens } from "../types.ts";
-import { formatHarness, type HarnessCost, harnessCosts } from "./harness.ts";
-import { readRoutes } from "./lanes.ts";
-import { reconcileLive } from "./reconcile.ts";
-import { listRuns, readJsonl, readRunRecords, type Run } from "./runstore.ts";
-
-export type RunTotals = {
-  runs: number;
-  ok: number;
-  notOk: string[];
-  secs: number;
-  tokens: Tokens;
-  costUsd: number;
-};
-
-export interface RunSummary {
-  id: string;
-  title: string;
-  repo: string;
-  stateTail: string[];
-  live: { name: string; rung: RungId; secs: number; pid: number }[];
-  totals: RunTotals;
-  jev: { decisions: number; fallbacks: number };
-  milestones: string[];
-  harness: HarnessCost[];
-  /** spec §11b: this run's spend against the active profile's budget, or null with no budget set */
-  budget: BudgetStatus | null;
-}
-
-export interface BudgetStatus {
-  /** the highest spent/cap ratio across the caps the profile set; ≥ 1 means exhausted */
-  fraction: number;
-  minutes?: { spent: number; cap: number };
-  tokens?: { spent: number; cap: number };
-  usd?: { spent: number; cap: number };
-}
-
-export function budgetStatus(totals: RunTotals, budget: Profile["budget"] | undefined): BudgetStatus | null {
-  if (!budget) return null;
-  const b: BudgetStatus = { fraction: 0 };
-  const consider = (spent: number, cap: number | undefined, key: "minutes" | "tokens" | "usd") => {
-    if (cap === undefined) return;
-    b[key] = { spent, cap };
-    b.fraction = Math.max(b.fraction, cap > 0 ? spent / cap : spent > 0 ? 1 : 0);
-  };
-  consider(totals.secs / 60, budget.minutes, "minutes");
-  consider(totals.tokens.input + totals.tokens.output, budget.tokens, "tokens");
-  consider(totals.costUsd, budget.usd, "usd");
-  return b;
-}
-
-export function formatBudget(b: BudgetStatus): string {
-  const parts: string[] = [];
-  if (b.minutes) parts.push(`${Math.round(b.minutes.spent)}/${b.minutes.cap} min`);
-  if (b.tokens) parts.push(`${b.tokens.spent}/${b.tokens.cap} tokens`);
-  if (b.usd) parts.push(`$${b.usd.spent.toFixed(2)}/$${b.usd.cap.toFixed(2)}`);
-  return `${parts.join(" · ")} (${Math.round(b.fraction * 100)}%)`;
-}
-
-/** The active profile's budget for this run's repo, or undefined when there is none or the profile fails to load. */
-function budgetFor(run: Run): Profile["budget"] | undefined {
-  try {
-    return loadProfile(activeProfileName(run.meta.repo)).budget;
-  } catch {
-    return undefined;
-  }
-}
-
-const lines = (file: string) =>
-  existsSync(file)
-    ? readFileSync(file, "utf8")
-        .split("\n")
-        .filter((l) => l.trim())
-    : [];
-
-export function summarizeRun(run: Run): RunSummary {
-  const { stillRunning } = reconcileLive(run.dir);
-  const recs = readRunRecords(run.dir);
-  const jev = readJsonl<{ source?: string }>(join(run.dir, "jev.jsonl"));
-  const now = Date.now();
-  const totals: RunTotals = {
-    runs: recs.length,
-    ok: recs.filter((r) => r.status === "ok").length,
-    notOk: recs.filter((r) => r.status !== "ok").map((r) => `${r.name} (${r.status})`),
-    secs: recs.reduce((n, r) => n + r.secs, 0),
-    tokens: {
-      input: recs.reduce((n, r) => n + r.tokens.input, 0),
-      cached: recs.reduce((n, r) => n + r.tokens.cached, 0),
-      output: recs.reduce((n, r) => n + r.tokens.output, 0),
-    },
-    costUsd: recs.reduce((n, r) => n + (r.costUsd ?? 0), 0),
-  };
-  return {
-    id: run.id,
-    title: run.meta.title,
-    repo: run.meta.repo,
-    stateTail: lines(join(run.dir, "state.md")).slice(-3),
-    live: stillRunning.map((m) => ({
-      name: m.name,
-      rung: m.rung,
-      secs: Math.round((now - Date.parse(m.startedAt)) / 1000),
-      pid: m.pid,
-    })),
-    totals,
-    jev: { decisions: jev.length, fallbacks: jev.filter((j) => j.source === "default").length },
-    milestones: lines(join(run.dir, "ledger.md")).slice(1),
-    harness: harnessCosts(listRuns().map((r) => r.dir)),
-    budget: budgetStatus(totals, budgetFor(run)),
-  };
-}
-
-const mmss = (s: number) =>
-  `${String(Math.floor(s / 60)).padStart(2, "0")}:${String(s % 60).padStart(2, "0")}`;
-
-export function formatSummary(s: RunSummary): string {
-  const t = s.totals;
-  return [
-    `== ${s.title} · ${s.id}`,
-    ...s.stateTail,
-    "-- running",
-    ...(s.live.length ? s.live.map((l) => `  ${l.name}  ${l.rung}  ${mmss(l.secs)}`) : ["  none"]),
-    `-- done  ${t.runs} runs · ${t.ok} ok · ${Math.round(t.secs / 60)} min · ${t.tokens.input} in / ${t.tokens.output} out tokens · $${t.costUsd.toFixed(2)}${t.notOk.length ? ` · not ok: ${t.notOk.join(", ")}` : ""}`,
-    `-- jev  ${s.jev.decisions} decisions · ${s.jev.fallbacks} fell back to default`,
-    ...(s.harness.length
-      ? s.harness.map((h) => `-- harness  ${formatHarness(h)}`)
-      : ["-- harness  no data yet"]),
-    ...(s.budget ? [`-- budget  ${formatBudget(s.budget)}`] : []),
-    ...(s.milestones.length ? ["-- landed", ...s.milestones.map((m) => `  ${m}`)] : []),
-  ].join("\n");
-}
-
-export interface RungStats {
-  role: Role;
-  rung: RungId;
-  runs: number;
-  ok: number;
-  refusals: number;
-  climbsFrom: number;
-  secs: number;
-  tokens: Tokens;
-}
-
-export function runsSummary(
-  f: { run?: string; repo?: string; role?: Role; sinceDays?: number } = {},
-): RungStats[] {
-  const since = f.sinceDays ? Date.now() - f.sinceDays * 86_400_000 : 0;
-  const runs = listRuns().filter(
-    (r) =>
-      (!f.run || r.id === f.run) &&
-      (!f.repo || r.meta.repo === f.repo) &&
-      Date.parse(r.meta.createdAt) >= since,
-  );
-  const stats = new Map<string, RungStats>();
-  const at = (role: Role, rung: RungId): RungStats => {
-    const key = `${role} ${rung}`;
-    let s = stats.get(key);
-    if (!s) {
-      s = {
-        role,
-        rung,
-        runs: 0,
-        ok: 0,
-        refusals: 0,
-        climbsFrom: 0,
-        secs: 0,
-        tokens: { input: 0, cached: 0, output: 0 },
-      };
-      stats.set(key, s);
-    }
-    return s;
-  };
-  for (const run of runs) {
-    for (const r of readRunRecords(run.dir)) {
-      if (f.role && r.role !== f.role) continue;
-      const s = at(r.role, r.rung);
-      s.runs++;
-      if (r.status === "ok") s.ok++;
-      if (r.replyStatus === "refused" || r.replyStatus === "blocked") s.refusals++;
-      s.secs += r.secs;
-      s.tokens.input += r.tokens.input;
-      s.tokens.cached += r.tokens.cached;
-      s.tokens.output += r.tokens.output;
-    }
-    for (const c of readRoutes(run.dir)) {
-      if (c.source !== "climb" || !c.from || (f.role && c.role !== f.role)) continue;
-      at(c.role, c.from).climbsFrom++;
-    }
-  }
-  return [...stats.values()].sort((a, b) => a.role.localeCompare(b.role) || a.rung.localeCompare(b.rung));
-}

package/src/files.ts

@@ -1,19 +0,0 @@
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { z } from "zod";
-
-// This module sits one level below the package root as src/files.ts, and catherd ships with no
-// build step, so one relative URL finds shipped files both in tests and after install alike.
-export const assetPath = (rel: string): string => fileURLToPath(new URL(`../${rel}`, import.meta.url));
-
-export function readJsonFile<T>(schema: z.ZodType<T>, file: string): T {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(readFileSync(file, "utf8"));
-  } catch (e) {
-    throw new Error(`catherd: ${file} is not readable JSON: ${(e as Error).message}`);
-  }
-  const r = schema.safeParse(raw);
-  if (!r.success) throw new Error(`catherd: ${file} is invalid:\n${z.prettifyError(r.error)}`);
-  return r.data;
-}