catherd-cli 0.2.1 → 1.0.0

package/src/mcp/server.ts

@@ -1,26 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { reconcileLive } from "../core/reconcile.ts";
-import { listRuns } from "../core/runstore.ts";
-import { VERSION } from "../version.ts";
-import { registerDispatch } from "./dispatch.ts";
-import { registerLaneTools } from "./lane-tools.ts";
-import { registerPreflight } from "./preflight.ts";
-import { registerRunTools } from "./run-tools.ts";
-import { registerSetupTools } from "./setup-tools.ts";
-
-export function buildServer(): McpServer {
-  const server = new McpServer({ name: "catherd", version: VERSION });
-  registerRunTools(server);
-  registerLaneTools(server);
-  registerDispatch(server);
-  registerSetupTools(server);
-  registerPreflight(server);
-  return server;
-}
-
-export async function startMcpServer(): Promise<void> {
-  process.env.CATHERD_TICK_MS ??= "30000";
-  for (const run of listRuns()) reconcileLive(run.dir);
-  await buildServer().connect(new StdioServerTransport());
-}

package/src/mcp/setup-tools.ts

@@ -1,175 +0,0 @@
-import { existsSync, readdirSync } from "node:fs";
-import { basename } from "node:path";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import diff from "microdiff";
-import { z } from "zod";
-import { formatHarness, harnessCosts } from "../core/harness.ts";
-import { ID } from "../core/lanes.ts";
-import { listRuns } from "../core/runstore.ts";
-import { runsSummary } from "../core/status.ts";
-import { claudeAgentsDir, saveProfileAndAgents } from "../profile/agents.ts";
-import {
-  activeProfileName,
-  defaultProfile,
-  listProfiles,
-  loadProfile,
-  patchProfile,
-  type ProfilePatch,
-  validateProfile,
-} from "../profile/profile.ts";
-import { capableFor, loadCatalog } from "../routing/catalog.ts";
-import { type Backend, type Profile, ROLES, splitRung } from "../types.ts";
-import { json } from "./out.ts";
-
-const isolation = z.object({ isolated: z.boolean() });
-
-const PATCH = z.object({
-  objective: z.enum(["cost", "speed"]).optional(),
-  roles: z
-    .partialRecord(
-      z.enum(ROLES),
-      z.object({
-        enabled: z.boolean().optional(),
-        models: z.record(z.string(), z.array(z.string())).optional(),
-        defaultRung: z.string().optional(),
-      }),
-    )
-    .optional(),
-  harness: z.object({ codex: isolation.optional(), opencode: isolation.optional() }).optional(),
-  lock: z.object({ heavy: z.union([z.number().int().positive(), z.literal("cpus/2")]) }).optional(),
-  notify: z.array(z.enum(["milestone", "finish", "blocked"])).optional(),
-});
-
-/** Whether each backend's CLI is on PATH. Claude is always available: it needs no CLI, only agent files. */
-function installedBackends(): Record<Backend, boolean> {
-  const probe = (bin: string) =>
-    Bun.which(bin) !== null &&
-    Bun.spawnSync([bin, "--version"], { stdout: "ignore", stderr: "ignore" }).success;
-  return { codex: probe("codex"), opencode: probe("opencode"), claude: true };
-}
-
-const profileOrNew = (name: string): Profile =>
-  listProfiles().includes(name) ? loadProfile(name) : { ...defaultProfile(), name };
-
-export function registerSetupTools(server: McpServer): void {
-  server.registerTool(
-    "catalog_query",
-    {
-      description:
-        "Models catherd can place, with their capabilities, the roles they are capable for, their scored rungs, any 'treat like', and whether their backend is installed. Scored models first.",
-      inputSchema: {
-        role: z.enum(ROLES).optional(),
-        backend: z.enum(["codex", "opencode", "claude"]).optional(),
-        text: z.string().optional(),
-        scored_only: z.boolean().default(false),
-        limit: z.number().int().min(1).max(500).default(50),
-      },
-    },
-    async (a) => {
-      const c = loadCatalog();
-      const installed = installedBackends();
-      const needle = a.text?.toLowerCase();
-      const models = c.models
-        .filter(
-          (m) =>
-            (!a.role || capableFor(a.role, m)) &&
-            (!a.backend || m.backend === a.backend) &&
-            (!needle || m.id.toLowerCase().includes(needle)),
-        )
-        .map((m) => ({
-          id: m.id,
-          backend: m.backend,
-          installed: installed[m.backend],
-          efforts: m.efforts,
-          capabilities: m.capabilities,
-          roles: ROLES.filter((r) => capableFor(r, m)),
-          scored: c.entries.filter((e) => splitRung(e.rung).model === m.id),
-          treatLike: Object.fromEntries(
-            Object.entries(c.treatLike).filter(([k]) => splitRung(k).model === m.id),
-          ),
-        }))
-        .filter((m) => !a.scored_only || m.scored.length > 0 || Object.keys(m.treatLike).length > 0)
-        .sort((x, y) => y.scored.length - x.scored.length || x.id.localeCompare(y.id));
-      return json({ total: models.length, models: models.slice(0, a.limit) });
-    },
-  );
-
-  server.registerTool(
-    "profile_get",
-    {
-      description:
-        "A profile (the active one without a name), the active profile's name, and every profile name.",
-      inputSchema: { name: z.string().regex(ID).optional() },
-    },
-    async (a) => {
-      const active = activeProfileName();
-      return json({ active, profiles: listProfiles(), profile: loadProfile(a.name ?? active) });
-    },
-  );
-
-  server.registerTool(
-    "profile_validate",
-    {
-      description:
-        "Check a profile (the active one without a name): every enabled role has a capable model, the worker's ladder is non-empty for every kind, and no unscored model is enabled without its 'treat like'.",
-      inputSchema: { name: z.string().regex(ID).optional() },
-    },
-    async (a) => {
-      const errors = validateProfile(loadProfile(a.name ?? activeProfileName()), loadCatalog());
-      return json({ valid: errors.length === 0, errors });
-    },
-  );
-
-  server.registerTool(
-    "profile_set",
-    {
-      description:
-        "Apply a patch to a profile (the active one without a name). It validates first and writes nothing when invalid; otherwise it saves the profile and regenerates the Claude agent files. Returns the diff and the agents that need a new Claude Code session.",
-      inputSchema: { name: z.string().regex(ID).optional(), patch: PATCH },
-    },
-    async (a) => {
-      const c = loadCatalog();
-      const before = profileOrNew(a.name ?? activeProfileName());
-      const { harness, ...rest } = a.patch;
-      const patched = patchProfile(before, rest as ProfilePatch);
-      const after: Profile = harness ? { ...patched, harness: { ...patched.harness, ...harness } } : patched;
-      const errors = validateProfile(after, c);
-      if (errors.length) return json({ saved: false, errors });
-      const dir = claudeAgentsDir();
-      const had = new Set(existsSync(dir) ? readdirSync(dir) : []);
-      const agents = saveProfileAndAgents(after, c);
-      return json({
-        saved: true,
-        diff: diff(before as unknown as Record<string, unknown>, after as unknown as Record<string, unknown>),
-        agents,
-        new_session_needed_for: agents.linked
-          .filter((l) => !had.has(basename(l)))
-          .map((l) => basename(l, ".md")),
-      });
-    },
-  );
-
-  server.registerTool(
-    "runs_summary",
-    {
-      description:
-        "Per role and rung over past runs: runs, ok, refusals, climbs from that rung, seconds and tokens; plus what the user's harness customizations cost per run.",
-      inputSchema: {
-        run: z.string().optional(),
-        repo: z.string().optional(),
-        role: z.enum(ROLES).optional(),
-        since_days: z.number().positive().optional(),
-      },
-    },
-    async (a) => {
-      const harness = harnessCosts(listRuns().map((r) => r.dir)).map((h) => ({
-        ...h,
-        line: formatHarness(h),
-      }));
-      return json({
-        rungs: runsSummary({ run: a.run, repo: a.repo, role: a.role, sinceDays: a.since_days }),
-        harness,
-      });
-    },
-  );
-}

package/src/paths.ts

@@ -1,20 +0,0 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-function root(kind: "config" | "data"): string {
-  const home = process.env.CATHERD_HOME;
-  if (home) return join(home, kind);
-  if (kind === "config") return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "catherd");
-  return join(process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "catherd");
-}
-
-export const configDir = (): string => root("config");
-export const dataDir = (): string => root("data");
-
-export function repoSlug(repoRoot: string): string {
-  return repoRoot.replace(/^\/+/, "").replaceAll("/", "-");
-}
-
-export function runsRoot(repoRoot: string): string {
-  return join(dataDir(), repoSlug(repoRoot));
-}

package/src/profile/agents.ts

@@ -1,130 +0,0 @@
-import { lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, join, sep } from "node:path";
-import { configDir } from "../paths.ts";
-import { modelOf } from "../routing/catalog.ts";
-import { type Catalog, type Profile, ROLES, type Role, type RungId, rungOf, splitRung } from "../types.ts";
-import { activeProfileName, saveProfile } from "./profile.ts";
-import { ROLE_PROMPTS } from "./role-prompts.ts";
-
-const slug = (s: string) =>
-  s
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-|-$/g, "");
-
-export function agentName(role: Role, rung: RungId): string {
-  const { model, effort } = splitRung(rung);
-  return `catherd-${role}-${slug(model)}-${effort}`;
-}
-
-export function claudeAgentsDir(): string {
-  return process.env.CATHERD_CLAUDE_AGENTS_DIR ?? join(homedir(), ".claude", "agents");
-}
-
-function render(role: Role, rung: RungId): string {
-  const { model, effort } = splitRung(rung);
-  const p = ROLE_PROMPTS[role];
-  return [
-    "---",
-    `name: ${agentName(role, rung)}`,
-    `description: Internal ${role} role of the catherd orchestrator, on ${model} at ${effort} effort. Dispatched only by the catherd skill while a run is in flight. Never for a plain request, even one that names this role.`,
-    `model: ${model}`,
-    `effort: ${effort}`,
-    `disallowedTools: ${p.disallowedTools.join(", ")}`,
-    "---",
-    "",
-    p.body,
-    "",
-  ].join("\n");
-}
-
-const lstatOrNull = (p: string) => {
-  try {
-    return lstatSync(p);
-  } catch {
-    return null;
-  }
-};
-
-export function writeClaudeAgents(
-  p: Profile,
-  c: Catalog,
-): { written: string[]; linked: string[]; pruned: string[] } {
-  const root = join(configDir(), "agents");
-  const dir = join(root, p.name);
-  const files = new Map<string, string>();
-  for (const role of ROLES) {
-    const rc = p.roles[role];
-    if (!rc?.enabled) continue;
-    for (const [model, efforts] of Object.entries(rc.models)) {
-      if (modelOf(c, model)?.backend !== "claude") continue;
-      for (const effort of efforts) {
-        const rung = rungOf(model, effort);
-        files.set(join(dir, `${agentName(role, rung)}.md`), render(role, rung));
-      }
-    }
-  }
-
-  const active = p.name === activeProfileName();
-  const target = claudeAgentsDir();
-  const ours = `${root}${sep}`;
-  const isOurs = (link: string) => {
-    const st = lstatOrNull(link);
-    return !st || (st.isSymbolicLink() && readlinkSync(link).startsWith(ours));
-  };
-  if (active) {
-    for (const f of files.keys()) {
-      const link = join(target, basename(f));
-      if (!isOurs(link))
-        throw new Error(`catherd: ${link} exists and is not catherd's; move it away and save again`);
-    }
-  }
-
-  mkdirSync(dir, { recursive: true });
-  for (const [f, text] of files) writeFileSync(f, text);
-  for (const f of readdirSync(dir)) if (!files.has(join(dir, f))) rmSync(join(dir, f));
-  const written = [...files.keys()];
-  if (!active) return { written, linked: [], pruned: [] };
-
-  mkdirSync(target, { recursive: true });
-  const linked: string[] = [];
-  for (const f of written) {
-    const link = join(target, basename(f));
-    rmSync(link, { force: true });
-    symlinkSync(f, link);
-    linked.push(link);
-  }
-  const pruned: string[] = [];
-  for (const name of readdirSync(target)) {
-    const link = join(target, name);
-    if (!lstatOrNull(link)?.isSymbolicLink()) continue;
-    const to = readlinkSync(link);
-    if (to.startsWith(ours) && !files.has(to)) {
-      rmSync(link);
-      pruned.push(link);
-    }
-  }
-  return { written, linked, pruned };
-}
-
-export function saveProfileAndAgents(
-  p: Profile,
-  c: Catalog,
-): { written: string[]; linked: string[]; pruned: string[] } {
-  const r = writeClaudeAgents(p, c);
-  saveProfile(p);
-  return r;
-}
-
-/** Read-only count of catherd's own symlinks in `claudeAgentsDir()`, for the dashboard's
- * "Claude agents" status row — unlike `writeClaudeAgents`, this never touches the filesystem. */
-export function countLinkedAgents(): number {
-  const target = claudeAgentsDir();
-  const ours = `${join(configDir(), "agents")}${sep}`;
-  if (!lstatOrNull(target)) return 0;
-  return readdirSync(target).filter((name) => {
-    const st = lstatOrNull(join(target, name));
-    return st?.isSymbolicLink() && readlinkSync(join(target, name)).startsWith(ours);
-  }).length;
-}

package/src/profile/profile.ts

@@ -1,228 +0,0 @@
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { z } from "zod";
-import { readJsonFile } from "../files.ts";
-import { configDir } from "../paths.ts";
-import { capableFor, isScored, modelOf } from "../routing/catalog.ts";
-import { candidates, clearsBar } from "../routing/select.ts";
-import {
-  type Catalog,
-  DIFFICULTIES,
-  type HarnessConfig,
-  KINDS,
-  type NotifyMoment,
-  type Profile,
-  ROLE_NEEDS,
-  ROLES,
-  type Role,
-  type RoleConfig,
-  type RungId,
-  rungOf,
-  splitRung,
-} from "../types.ts";
-
-const NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
-
-const Harness = z.object({ isolated: z.boolean() }).default(() => ({ isolated: false }));
-
-const ProfileSchema = z.object({
-  name: z.string().regex(NAME),
-  objective: z.enum(["cost", "speed"]),
-  roles: z.record(
-    z.enum(ROLES),
-    z.object({
-      enabled: z.boolean(),
-      models: z.record(z.string().min(1), z.array(z.string().min(1))),
-      defaultRung: z.string().optional(),
-    }),
-  ),
-  // Profiles written before the harness toggle existed load as native, which is the default.
-  harness: z
-    .object({ codex: Harness, opencode: Harness })
-    .default(() => ({ codex: { isolated: false }, opencode: { isolated: false } })),
-  lock: z.object({ heavy: z.union([z.number().int().min(1), z.literal("cpus/2")]) }),
-  notify: z.array(z.enum(["milestone", "finish", "blocked"])),
-  // spec §11b: quota failover and the run budget. Both optional, so old profile files still load.
-  failover: z.record(z.string(), z.string()).optional(),
-  budget: z
-    .object({ minutes: z.number().optional(), tokens: z.number().optional(), usd: z.number().optional() })
-    .optional(),
-});
-const ConfigSchema = z.looseObject({ activeProfile: z.string().optional() });
-const ProjectsSchema = z.record(z.string(), z.string());
-
-export type ProfilePatch = {
-  objective?: Profile["objective"];
-  /** A role's `models` map is replaced whole, so a patch can drop an entry. */
-  roles?: Partial<Record<Role, Partial<RoleConfig>>>;
-  harness?: Partial<Record<"codex" | "opencode", Partial<HarnessConfig>>>;
-  lock?: Profile["lock"];
-  notify?: NotifyMoment[];
-};
-
-const profilesDir = () => join(configDir(), "profiles");
-const configFile = () => join(configDir(), "config.json");
-const projectsFile = () => join(configDir(), "projects.json");
-
-function checkName(name: string): string {
-  if (!NAME.test(name))
-    throw new Error(`catherd: bad profile name "${name}": use letters, digits, "-" and "_"`);
-  return name;
-}
-
-function readOr<T>(schema: z.ZodType<T>, file: string, fallback: T): T {
-  return existsSync(file) ? readJsonFile(schema, file) : fallback;
-}
-
-function writeJson(file: string, value: unknown): void {
-  mkdirSync(dirname(file), { recursive: true });
-  writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
-}
-
-export function defaultProfile(): Profile {
-  return {
-    name: "default",
-    objective: "cost",
-    roles: {
-      architect: { enabled: true, models: { "claude-opus-5-5": ["high"] } },
-      verifier: { enabled: true, models: { "claude-opus-5-5": ["low"] } },
-      worker: {
-        enabled: true,
-        defaultRung: "gpt-6-sol#medium",
-        models: { "gpt-6-luna": ["high"], "gpt-6-sol": ["medium", "high", "xhigh"] },
-      },
-      reviewer: { enabled: true, models: { "gpt-6-sol": ["high"] } },
-      "ui-reviewer": { enabled: true, models: { "gpt-6-sol": ["medium"] } },
-      artist: { enabled: true, models: { "gpt-6-sol": ["medium"] } },
-      writer: { enabled: true, models: { "gpt-6-luna": ["high"] } },
-      researcher: { enabled: true, models: { "gpt-6-luna": ["high"] } },
-    },
-    harness: { codex: { isolated: false }, opencode: { isolated: false } },
-    lock: { heavy: "cpus/2" },
-    notify: ["milestone", "finish", "blocked"],
-  };
-}
-
-export function loadProfile(name?: string): Profile {
-  const n = checkName(name ?? activeProfileName());
-  const file = join(profilesDir(), `${n}.json`);
-  if (existsSync(file)) return { ...readJsonFile(ProfileSchema, file), name: n };
-  if (n === "default") return defaultProfile();
-  throw new Error(`catherd: no profile named "${n}" (looked for ${file})`);
-}
-
-export function saveProfile(p: Profile): void {
-  const file = join(profilesDir(), `${checkName(p.name)}.json`);
-  const r = ProfileSchema.safeParse(p);
-  if (!r.success) throw new Error(`catherd: profile "${p.name}" is invalid:\n${z.prettifyError(r.error)}`);
-  writeJson(file, r.data);
-}
-
-export function listProfiles(): string[] {
-  const onDisk = existsSync(profilesDir())
-    ? readdirSync(profilesDir())
-        .filter((f) => f.endsWith(".json"))
-        .map((f) => f.slice(0, -".json".length))
-        .filter((n) => NAME.test(n))
-    : [];
-  return [...new Set(["default", ...onDisk])].sort();
-}
-
-export function activeProfileName(repo?: string): string {
-  const bound = repo === undefined ? undefined : readOr(ProjectsSchema, projectsFile(), {})[resolve(repo)];
-  return bound ?? readOr(ConfigSchema, configFile(), {}).activeProfile ?? "default";
-}
-
-export function setActiveProfile(name: string, repo?: string): void {
-  if (!listProfiles().includes(name)) throw new Error(`catherd: no profile named "${name}"`);
-  if (repo === undefined)
-    writeJson(configFile(), { ...readOr(ConfigSchema, configFile(), {}), activeProfile: name });
-  else writeJson(projectsFile(), { ...readOr(ProjectsSchema, projectsFile(), {}), [resolve(repo)]: name });
-}
-
-export function patchProfile(p: Profile, patch: ProfilePatch): Profile {
-  const roles = { ...p.roles };
-  for (const role of ROLES) {
-    const rc = patch.roles?.[role];
-    if (rc) roles[role] = { ...roles[role], ...rc };
-  }
-  return {
-    ...p,
-    objective: patch.objective ?? p.objective,
-    roles,
-    harness: {
-      codex: { ...p.harness.codex, ...patch.harness?.codex },
-      opencode: { ...p.harness.opencode, ...patch.harness?.opencode },
-    },
-    lock: patch.lock ?? p.lock,
-    notify: patch.notify ?? p.notify,
-  };
-}
-
-const backendOf = (c: Catalog, rung: RungId): string | undefined =>
-  modelOf(c, splitRung(rung).model)?.backend;
-
-export function validateProfile(p: Profile, c: Catalog): string[] {
-  const errors: string[] = [];
-  if (!p.roles.worker.enabled) errors.push("worker: cannot be disabled");
-  for (const role of ROLES) {
-    const rc = p.roles[role];
-    if (!rc.enabled) continue;
-    const usable: RungId[] = [];
-    for (const [id, efforts] of Object.entries(rc.models)) {
-      const m = modelOf(c, id);
-      if (!m) {
-        errors.push(`${role}: ${id} is not in the catalog`);
-        continue;
-      }
-      if (!capableFor(role, m)) {
-        errors.push(
-          `${role}: ${id} cannot fill this role (it needs ${Object.keys(ROLE_NEEDS[role]).join(" + ")})`,
-        );
-        continue;
-      }
-      for (const effort of efforts) {
-        const rung = rungOf(id, effort);
-        if (!m.efforts.includes(effort)) {
-          errors.push(`${role}: ${id} has no effort "${effort}" (it has ${m.efforts.join(", ")})`);
-        } else if (!isScored(c, rung)) {
-          errors.push(
-            `${role}: ${rung} is unscored; declare it "treat like" a scored entry in catalog.override.json`,
-          );
-        } else {
-          usable.push(rung);
-        }
-      }
-    }
-    if (usable.length === 0) errors.push(`${role}: no usable model is enabled`);
-    else if (rc.defaultRung && !usable.includes(rc.defaultRung)) {
-      errors.push(`${role}: defaultRung ${rc.defaultRung} is not one of its enabled entries`);
-    }
-  }
-  const worker = candidates(p, c, "worker");
-  if (worker.length > 1) {
-    for (const kind of KINDS) {
-      for (const d of DIFFICULTIES) {
-        if (!worker.some((r) => clearsBar(c, r, kind, d))) {
-          errors.push(`worker: no enabled entry clears the ${kind}/${d} bar`);
-        }
-      }
-    }
-  }
-  // spec §11b: a failover stand-in must be usable on its own, and on a different backend, so
-  // a quota outage on one backend cannot fail over onto the very backend that is out of quota.
-  for (const [from, to] of Object.entries(p.failover ?? {})) {
-    if (!isScored(c, to)) {
-      errors.push(`failover: ${to} (stand-in for ${from}) is unscored`);
-      continue;
-    }
-    const fromBackend = backendOf(c, from);
-    const toBackend = backendOf(c, to);
-    if (fromBackend && toBackend && fromBackend === toBackend) {
-      errors.push(
-        `failover: ${to} is on the same backend (${toBackend}) as ${from}; a stand-in must be on another backend`,
-      );
-    }
-  }
-  return errors;
-}