catherd-cli 0.2.1 → 1.0.0

package/src/entry/mcp/run-tools.ts

@@ -0,0 +1,144 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ID_PATTERN } from "../../domain/ids.ts";
+import { ROLES } from "../../domain/roles.ts";
+import { redact } from "../../infra/log.ts";
+import { registerSavedSecrets } from "../../services/jev-service.ts";
+import type { Deps } from "../../services/ports.ts";
+import {
+  readKnowledge,
+  readRunFile,
+  recordAgentRun,
+  result,
+  setNext,
+  startRun,
+  writeRunFile,
+} from "../../services/run-service.ts";
+import { runsSummary, status } from "../../services/summary.ts";
+import { handle } from "./result.ts";
+
+export function registerRunTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "run_start",
+    {
+      description:
+        "Start a catherd run for a git repository: creates its run folder (outside the repo) and state.md. Returns the run id and the folder, and hints when state.md could not be written yet.",
+      inputSchema: {
+        repo: z.string().min(1),
+        title: z.string().min(1),
+        a_lines: z.array(z.string().min(1)).min(1),
+      },
+    },
+    (a) => handle(() => startRun(deps, { repo: a.repo, title: a.title, aLines: a.a_lines })),
+  );
+
+  server.registerTool(
+    "write_run_file",
+    {
+      description:
+        "Write a file in the run folder: plan.md, lanes/Mx.Ly.md, a dossier or notes. The path is relative to the run folder; catherd's own files are refused.",
+      inputSchema: { run: z.string(), path: z.string().min(1), content: z.string() },
+    },
+    (a) => handle(() => writeRunFile(a)),
+  );
+
+  server.registerTool(
+    "read_run_file",
+    {
+      description: "Read a file in the run folder, by a path relative to it.",
+      inputSchema: { run: z.string(), path: z.string().min(1) },
+    },
+    (a) => handle(() => readRunFile(a)),
+  );
+
+  server.registerTool(
+    "status",
+    {
+      description:
+        "catherd's version, and one screen per run: the state.md tail, live roles, totals, reported Claude subagents, Jev fallbacks, per backend how many dispatches ran native and isolated, budget and landed milestones. Without a run: every run with live roles, else the newest. Reads only.",
+      inputSchema: { run: z.string().optional() },
+    },
+    (a) =>
+      handle(() => {
+        registerSavedSecrets();
+        return redact(status(deps, a.run));
+      }),
+  );
+
+  server.registerTool(
+    "result",
+    {
+      description: "A role's latest dispatch: its state, its record once finished, and its capped reply.",
+      inputSchema: { run: z.string(), name: z.string().regex(ID_PATTERN) },
+    },
+    (a) => handle(() => result(deps, a)),
+  );
+
+  server.registerTool(
+    "set_next",
+    {
+      description:
+        "Record the run's next step, the last line of state.md: when pausing, or when the plan changes. dispatch, climb and land write state.md themselves. Returns { state } (state.md's text), and hints ['state.md not refreshed: …'] with state null when git fails (the step is still recorded).",
+      inputSchema: { run: z.string(), next: z.string().min(1) },
+    },
+    (a) => handle(() => setNext(a)),
+  );
+
+  server.registerTool(
+    "record_agent_run",
+    {
+      description:
+        "After every native Claude subagent (Agent tool) of a run, record what the Agent result reported: total_tokens and duration_ms. The budget counts it. Pass lane (e.g. M1.L1) when the subagent worked a lane, so its time counts toward that lane's kind in the catalog timings.",
+      inputSchema: {
+        run: z.string(),
+        name: z.string().regex(ID_PATTERN),
+        role: z.enum(ROLES),
+        rung: z.string().min(3),
+        total_tokens: z.number().int().nonnegative(),
+        duration_ms: z.number().nonnegative().optional(),
+        cost_usd: z.number().nonnegative().optional(),
+        status: z.enum(["ok", "failed", "cancelled"]).default("ok"),
+        lane: z.string().regex(ID_PATTERN).optional(),
+      },
+    },
+    (a) =>
+      handle(() =>
+        recordAgentRun(deps, {
+          lane: a.lane,
+          run: a.run,
+          name: a.name,
+          role: a.role,
+          rung: a.rung,
+          totalTokens: a.total_tokens,
+          durationMs: a.duration_ms,
+          costUsd: a.cost_usd,
+          status: a.status,
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "read_knowledge",
+    {
+      description:
+        "What past runs of this repo learned, one line per landed milestone that said something. Read it before an architect plans a new run.",
+      inputSchema: { repo: z.string().min(1) },
+    },
+    (a) => handle(() => readKnowledge(a.repo)),
+  );
+
+  server.registerTool(
+    "runs_summary",
+    {
+      description:
+        "Per role and rung over past runs: runs, ok, refusals, climbs from that rung, seconds and tokens; reported Claude subagent runs; and what the user's harness customizations cost per run (median first-turn input, native against isolated; with a run, over that run's repo; null below 3 runs a side or when native is not dearer; none for Codex, which reports no per-request input). Reads only.",
+      inputSchema: {
+        run: z.string().optional(),
+        repo: z.string().optional(),
+        role: z.enum(ROLES).optional(),
+        since_days: z.number().positive().optional(),
+      },
+    },
+    (a) => handle(() => runsSummary({ run: a.run, repo: a.repo, role: a.role, sinceDays: a.since_days })),
+  );
+}

package/src/entry/mcp/server.ts

@@ -0,0 +1,72 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { errorMessage } from "../../domain/errors.ts";
+import { log } from "../../infra/log.ts";
+import type { Deps } from "../../services/ports.ts";
+import { reconcileAll } from "../../services/reconcile.ts";
+import { defaultDeps } from "../deps.ts";
+import { registerDispatchTools } from "./dispatch-tools.ts";
+import { registerLaneTools } from "./lane-tools.ts";
+import { sdkToolError, toolOf } from "./result.ts";
+import { registerRunTools } from "./run-tools.ts";
+import { registerSetupTools } from "./setup-tools.ts";
+
+type Handler = (...args: unknown[]) => CallToolResult | Promise<CallToolResult>;
+
+/** Spec §10.2: every tool call is logged with its duration and outcome (the error code), never its input. */
+function logToolCalls(server: McpServer): void {
+  const register = server.registerTool.bind(server) as unknown as (
+    n: string,
+    c: unknown,
+    h: Handler,
+  ) => unknown;
+  (server as unknown as { registerTool: typeof register }).registerTool = (name, config, handler) =>
+    register(name, config, async (...args: unknown[]) => {
+      const started = Date.now();
+      const r = await handler(...args);
+      const code = r.isError ? (r.structuredContent as { code?: string } | undefined)?.code : undefined;
+      log(r.isError ? "warn" : "info", "tool", {
+        tool: name,
+        ms: Date.now() - started,
+        ok: !r.isError,
+        code,
+      });
+      return r;
+    });
+}
+
+export function buildServer(deps: Deps = defaultDeps()): McpServer {
+  const server = new McpServer({ name: "catherd", version: deps.version });
+  logToolCalls(server);
+  // The SDK validates input before a tool's `handle` runs and reports a failure through this (private)
+  // method as plain text; test/entry/mcp.test.ts fails loudly if an SDK upgrade renames it. The wrapper
+  // above never sees such a call, so it is logged here (spec §10.2: every call), by the tool it names.
+  (server as unknown as { createToolError: typeof sdkToolError }).createToolError = (message) => {
+    const r = sdkToolError(message);
+    const code = (r.structuredContent as { code?: string } | undefined)?.code;
+    log("warn", "tool", { tool: toolOf(message), ok: false, code });
+    return r;
+  };
+  registerRunTools(server, deps);
+  registerLaneTools(server, deps);
+  registerDispatchTools(server, deps);
+  registerSetupTools(server, deps);
+  return server;
+}
+
+/** Spec §4.7: connect first, so the client never waits on a scan; then reconcile every run. */
+export async function startMcpServer(): Promise<void> {
+  const deps = defaultDeps();
+  await buildServer(deps).connect(new StdioServerTransport());
+  try {
+    const r = await reconcileAll(deps);
+    const shown = r.warnings.length;
+    for (const w of r.warnings) console.error(`catherd: ${w}`);
+    void r.done.then(() => {
+      for (const w of r.warnings.slice(shown)) console.error(`catherd: ${w}`);
+    });
+  } catch (e) {
+    console.error(`catherd: reconcile failed: ${errorMessage(e)}`);
+  }
+}

package/src/entry/mcp/setup-tools.ts

@@ -0,0 +1,81 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CatherdError } from "../../domain/errors.ts";
+import { PROFILE_NAME, ProfilePatchSchema } from "../../domain/profile.ts";
+import { ROLES } from "../../domain/roles.ts";
+import { gitToplevel } from "../../infra/git.ts";
+import type { Deps } from "../../services/ports.ts";
+import { handle } from "./result.ts";
+
+const PROFILE = z.string().regex(PROFILE_NAME).optional();
+const REPO = z.string().min(1).optional();
+
+/**
+ * The git toplevel of `repo` (default: this server's directory, null outside a repository). A `repo`
+ * given outside a repository is refused, as run_start does: never the global profile in its stead.
+ */
+const toplevel = async (repo: string | undefined): Promise<string | null> => {
+  const top = await gitToplevel(repo ?? process.cwd());
+  if (top === null && repo !== undefined)
+    throw new CatherdError("E_IO_PATH", `${repo} is not inside a git repository`, {
+      fix: "pass the path of the repository, or leave repo out for the active profile",
+    });
+  return top;
+};
+
+export function registerSetupTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "catalog_query",
+    {
+      description:
+        "Models catherd can place, with capabilities, the roles they can fill, their scored rungs (backend:model#effort), any 'treat like', their cost under the billing of `repo`'s profile, and whether this account's last listing offers them (`listed: false`: it does not); `enabled: false` rungs are unscored. Scored models first. opencode's models are as listed in `repo` (default: this server's directory), as route sees them there.",
+      inputSchema: {
+        repo: z.string().min(1).optional(),
+        role: z.enum(ROLES).optional(),
+        backend: z.string().optional(),
+        text: z.string().optional(),
+        scored_only: z.boolean().default(false),
+        limit: z.number().int().min(1).max(500).default(50),
+      },
+    },
+    (a) =>
+      handle(async () => {
+        // outside a git repository: the global listings and the active profile
+        const repo = (await gitToplevel(a.repo ?? process.cwd())) ?? undefined;
+        return deps.routing.catalog(
+          { role: a.role, backend: a.backend, text: a.text, scoredOnly: a.scored_only, limit: a.limit, repo },
+          deps.profiles.forRepo(repo ?? null).billing,
+        );
+      }),
+  );
+
+  server.registerTool(
+    "profile_get",
+    {
+      description:
+        "A profile (without a name: the profile this repo runs on, i.e. the one bound to `repo`, default this server's directory, else the active one) as the run engine reads it, with every default filled in: per role its access mode, rungs and default rung, and whether its backend enforces the access (enforcement); billing, jev, harness isolation, failover, budget, timeouts, preflight, lock and notify. Also `active` (the global active profile), `here` (the profile this repo runs on) and every name.",
+      inputSchema: { name: PROFILE, repo: REPO },
+    },
+    (a) => handle(async () => deps.profiles.get(a.name, await toplevel(a.repo))),
+  );
+
+  server.registerTool(
+    "profile_validate",
+    {
+      description:
+        "Check a profile (without a name: the profile this repo runs on, as in profile_get). errors block a save: the worker disabled, an enabled role with no usable rung, an unscored rung without a 'treat like', a failover stand-in unscored or on the same quota, a backend catherd cannot run. warnings do not: an access mode other than the role's default, a model the backend's listing lacks, a stand-in that never runs. Each has a path, a message and often a fix.",
+      inputSchema: { name: PROFILE, repo: REPO },
+    },
+    (a) => handle(async () => deps.profiles.validate(a.name, await toplevel(a.repo))),
+  );
+
+  server.registerTool(
+    "profile_set",
+    {
+      description:
+        "Apply a patch to a profile (without a name: the profile this repo runs on, as in profile_get; a new name starts from the default profile): objective, jev.use, billing, roles (enabled, access, rungs, defaultRung), harness isolation per backend, failover, budget, timeouts, preflight.confirm, lock.heavy and notify. Lists replace, maps merge, and null removes a key. An unknown key is refused. It validates first and writes nothing when invalid; otherwise it saves, rewrites the agent files and relinks them. Returns the errors and warnings, the diff, and newSessionNeededFor: the agents that apply from the next Claude Code session.",
+      inputSchema: { name: PROFILE, repo: REPO, patch: ProfilePatchSchema },
+    },
+    (a) => handle(async () => deps.profiles.set(a.name, a.patch, await toplevel(a.repo))),
+  );
+}

package/src/entry/profile-command.ts

@@ -0,0 +1,320 @@
+import { assertProfileName } from "../domain/profile.ts";
+import { defineCommand } from "citty";
+import type { Catalog } from "../domain/catalog.ts";
+import { rungInfo } from "../domain/catalog.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { type Change, patchAt, type Profile } from "../domain/profile.ts";
+import { inferredScores, type Issue } from "../domain/profile-rules.ts";
+import { ROLES, type Role } from "../domain/roles.ts";
+import { gitToplevel } from "../infra/git.ts";
+import { loadCatalog } from "../services/catalog-service.ts";
+import type { Synced } from "../services/agent-links.ts";
+import {
+  activate,
+  createProfile,
+  deleteProfile,
+  diffNamed,
+  patchProfile,
+  unbind,
+} from "../services/profile-service.ts";
+import {
+  activeName,
+  getProfile,
+  keyRunnable,
+  listProfiles,
+  profileExists,
+  readProjects,
+  requireProfile,
+  roleEnforcement,
+  runnableBackends,
+  validateNamed,
+} from "../services/profile-store.ts";
+import { EXIT, JSON_ARG, mark, printJson } from "./cli-kit.ts";
+
+const json = JSON_ARG;
+
+export interface StandIn {
+  from: string;
+  to: string;
+  inferred: boolean;
+  via: string | null;
+}
+
+/** Spec §7.2: each stand-in, marked inferred when its scores are catherd's guess. */
+export function standIns(p: Profile, c: Catalog): StandIn[] {
+  return Object.entries(p.failover).map(([from, to]) => {
+    try {
+      return { from, to, ...inferredScores(c, rungInfo(c, to)) };
+    } catch {
+      return { from, to, inferred: false, via: null };
+    }
+  });
+}
+
+const value = (v: unknown) => (v === null ? "none" : typeof v === "string" ? v : JSON.stringify(v));
+export const formatChange = (c: Change): string => `${c.path}: ${value(c.before)} → ${value(c.after)}`;
+export const formatIssue = (i: Issue, glyph: string): string[] => [
+  `${glyph} ${i.path}: ${i.message}`,
+  ...(i.fix ? [`  fix: ${i.fix}`] : []),
+];
+
+/** `profile show`: every setting, each role with its access and how strongly its backend holds it (spec D10). */
+export function formatProfile(
+  p: Profile,
+  o: {
+    active: boolean;
+    enforcement: Record<Role, "enforced" | "advisory">;
+    standIns: StandIn[];
+    /** the backends catherd can run: runnableBackends() */
+    backends: string[];
+  },
+): string[] {
+  const width = Math.max(...ROLES.map((r) => r.length));
+  const lines = [
+    `profile ${p.name}${o.active ? " (active)" : ""}`,
+    `objective ${p.objective} · jev ${p.jev.use} · heavy slots ${p.lock.heavy} · notify ${p.notify.join(", ") || "none"}`,
+    "roles",
+  ];
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    if (!rc.enabled) {
+      lines.push(`  ${role.padEnd(width)}  off`);
+      continue;
+    }
+    const ladder = rc.rungs.map((r) => (r === rc.defaultRung ? `${r} (default)` : r)).join(" → ");
+    lines.push(
+      `  ${role.padEnd(width)}  ${`${rc.access}, ${o.enforcement[role]}`.padEnd(27)}  ${ladder || "no rungs"}`,
+    );
+  }
+  // only what catherd can run today: a backend without an adapter has nothing to bill or isolate
+  const runs = ([key]: [string, unknown]) => keyRunnable(key, o.backends);
+  const billing = Object.entries(p.billing).filter(runs);
+  lines.push(`billing ${billing.map(([k, m]) => `${k} ${m}`).join(" · ")}`);
+  const harness = Object.entries(p.harness).filter(runs);
+  lines.push(`harness ${harness.map(([k, h]) => `${k} ${h.isolated ? "isolated" : "native"}`).join(" · ")}`);
+  lines.push(o.standIns.length ? "failover" : "failover none");
+  for (const s of o.standIns)
+    lines.push(
+      `  ${s.from} → ${s.to}${s.inferred ? ` (inferred${s.via ? `: treated like ${s.via}` : ""})` : ""}`,
+    );
+  const budget = Object.entries(p.budget).map(([k, v]) => (k === "usd" ? `$${v}` : `${v} ${k}`));
+  lines.push(`budget ${budget.join(" · ") || "no cap"}`);
+  lines.push(`timeouts idle ${p.timeouts.idleMin} min · wall ${p.timeouts.wallMin} min`);
+  lines.push(
+    `preflight ${p.preflight.confirm ? "shows its commands and asks first" : "runs the checks without asking"}`,
+  );
+  return lines;
+}
+
+function printSynced(r: Pick<Synced, "newSessionNeededFor">): void {
+  if (r.newSessionNeededFor.length)
+    console.log(`new Claude Code session needed for: ${r.newSessionNeededFor.join(", ")}`);
+}
+
+function printIssues(errors: Issue[], warnings: Issue[]): void {
+  for (const e of errors) for (const l of formatIssue(e, mark("fail"))) console.log(l);
+  for (const w of warnings) for (const l of formatIssue(w, mark("warn"))) console.log(l);
+}
+
+const refused = (errors: Issue[]) =>
+  new CatherdError(
+    "E_CONFIG_INVALID",
+    `the profile was not saved: ${errors.map((e) => `${e.path}: ${e.message}`).join("; ")}`,
+    { fix: errors.find((e) => e.fix)?.fix ?? "catherd profile validate lists what to change" },
+  );
+
+async function repoHere(): Promise<string> {
+  const top = await gitToplevel(process.cwd());
+  if (!top)
+    throw new CatherdError("E_INPUT_INVALID", `${process.cwd()} is not inside a git repository`, {
+      fix: "run it inside the repo to bind, or leave out --repo",
+    });
+  return top;
+}
+
+/** The profile this directory runs on: its repo's binding, else the active one (outside a repo too). */
+const activeHere = async (): Promise<string> => activeName(await gitToplevel(process.cwd()));
+
+const list = defineCommand({
+  meta: {
+    name: "list",
+    description: "Every profile, the one this repo runs on (*), and the repos bound to each",
+  },
+  args: json,
+  async run({ args }) {
+    const active = await activeHere();
+    const bindings = Object.entries(readProjects().bindings);
+    const rows = listProfiles().map((name) => ({
+      name,
+      active: name === active,
+      repos: bindings.filter(([, p]) => p === name).map(([r]) => r),
+    }));
+    if (args.json) return printJson(rows);
+    for (const r of rows)
+      console.log(
+        `${r.active ? "*" : " "} ${r.name}${r.repos.length ? `  bound to ${r.repos.join(", ")}` : ""}`,
+      );
+  },
+});
+
+const show = defineCommand({
+  meta: {
+    name: "show",
+    description: "A profile with every default filled in (without a name: the one this repo runs on)",
+  },
+  args: { name: { type: "positional", required: false, description: "profile name" }, ...json },
+  async run({ args }) {
+    const here = await activeHere();
+    const name = args.name === undefined ? here : requireProfile(args.name);
+    const p = getProfile(name);
+    const o = {
+      active: name === here,
+      enforcement: roleEnforcement(p),
+      standIns: standIns(p, loadCatalog({ timings: false })),
+    };
+    if (args.json) return printJson({ profile: p, ...o });
+    for (const l of formatProfile(p, { ...o, backends: runnableBackends() })) console.log(l);
+  },
+});
+
+const use = defineCommand({
+  meta: {
+    name: "use",
+    description:
+      "Make a profile active, bind it to this repo with --repo, or unbind this repo with --repo --clear",
+  },
+  args: {
+    name: { type: "positional", required: false, description: "profile name" },
+    repo: { type: "boolean", description: "bind it to the git repo you are in, instead of making it active" },
+    clear: { type: "boolean", description: "with --repo and no name: unbind the git repo you are in" },
+  },
+  async run({ args }) {
+    if (args.clear) {
+      if (!args.repo || args.name !== undefined)
+        throw new CatherdError("E_INPUT_INVALID", "--clear goes with --repo and no profile name", {
+          fix: "catherd profile use --repo --clear, inside the repo to unbind",
+        });
+      const r = unbind(await repoHere());
+      console.log(`${mark("ok")} ${r.repo} is unbound`);
+      printSynced(r);
+      return;
+    }
+    if (args.name === undefined)
+      throw new CatherdError("E_INPUT_INVALID", "which profile? name one", {
+        fix: "catherd profile use <name> [--repo], or catherd profile use --repo --clear",
+      });
+    const r = activate(args.name, args.repo ? await repoHere() : null);
+    console.log(`${mark("ok")} ${r.active} ${r.repo ? `is bound to ${r.repo}` : "is active"}`);
+    printSynced(r);
+  },
+});
+
+const create = defineCommand({
+  meta: { name: "new", description: "A new profile from the default one, or from --from <profile>" },
+  args: {
+    name: { type: "positional", required: true, description: "new profile name" },
+    from: { type: "string", description: "copy this profile instead of the default one" },
+  },
+  run({ args }) {
+    const r = createProfile(args.name, args.from);
+    if (!r.saved) throw refused(r.errors);
+    console.log(`${mark("ok")} created ${args.name}${args.from ? ` from ${args.from}` : ""}`);
+    printIssues([], r.warnings);
+  },
+});
+
+const copy = defineCommand({
+  meta: { name: "copy", description: "Copy a profile under a new name" },
+  args: {
+    from: { type: "positional", required: true, description: "profile to copy" },
+    to: { type: "positional", required: true, description: "new profile name" },
+  },
+  run({ args }) {
+    const r = createProfile(args.to, args.from);
+    if (!r.saved) throw refused(r.errors);
+    console.log(`${mark("ok")} copied ${args.from} to ${args.to}`);
+    printIssues([], r.warnings);
+  },
+});
+
+const rm = defineCommand({
+  meta: { name: "rm", description: "Delete a profile and its agent files (never the active or a bound one)" },
+  args: { name: { type: "positional", required: true, description: "profile name" } },
+  run({ args }) {
+    deleteProfile(args.name);
+    console.log(`${mark("ok")} deleted ${args.name}`);
+  },
+});
+
+const set = defineCommand({
+  meta: {
+    name: "set",
+    description:
+      "Set one field: e.g. roles.worker.access read-only, budget.usd 20, failover.<rung> <rung>, roles.worker.rungs a,b; null removes",
+  },
+  args: {
+    path: { type: "positional", required: true, description: "dotted path, e.g. roles.verifier.access" },
+    value: { type: "positional", required: true, description: "JSON, or a plain word; null removes the key" },
+    profile: { type: "string", description: "the profile to change (default: the one this repo runs on)" },
+  },
+  async run({ args }) {
+    // the CLI never creates a profile by setting a field of it: a typo would start a new one
+    if (args.profile !== undefined && !profileExists(assertProfileName(args.profile)))
+      throw new CatherdError("E_INPUT_INVALID", `no profile named "${args.profile}"`, {
+        fix: `catherd profile new ${args.profile}`,
+      });
+    const r = patchProfile(args.profile ?? (await activeHere()), patchAt(args.path, args.value));
+    if (!r.saved) throw refused(r.errors);
+    if (r.diff.length === 0) console.log("no change");
+    for (const c of r.diff) console.log(`${mark("ok")} ${formatChange(c)}`);
+    printIssues([], r.warnings);
+    printSynced(r);
+  },
+});
+
+const diff = defineCommand({
+  meta: {
+    name: "diff",
+    description: "What differs between two profiles (the second defaults to the one this repo runs on)",
+  },
+  args: {
+    a: { type: "positional", required: true, description: "profile" },
+    b: { type: "positional", required: false, description: "profile (default: the one this repo runs on)" },
+    ...json,
+  },
+  async run({ args }) {
+    const changes = diffNamed(
+      args.b === undefined ? await activeHere() : requireProfile(args.b),
+      requireProfile(args.a),
+    );
+    if (args.json) return printJson(changes);
+    if (changes.length === 0) console.log("no differences");
+    for (const c of changes) console.log(formatChange(c));
+  },
+});
+
+const validate = defineCommand({
+  meta: { name: "validate", description: "Errors that block a save, and warnings that do not" },
+  args: {
+    name: {
+      type: "positional",
+      required: false,
+      description: "profile name (default: the one this repo runs on)",
+    },
+    ...json,
+  },
+  async run({ args }) {
+    const repo = await gitToplevel(process.cwd());
+    const v = validateNamed(args.name === undefined ? activeName(repo) : requireProfile(args.name), repo);
+    if (args.json) printJson({ valid: v.errors.length === 0, ...v });
+    else if (v.errors.length === 0 && v.warnings.length === 0) console.log(`${mark("ok")} valid`);
+    else printIssues(v.errors, v.warnings);
+    if (v.errors.length) process.exitCode = EXIT.error;
+  },
+});
+
+/** Spec §8: `catherd profile list|show|use [--repo [--clear]]|new|copy|rm|set <path> <value>|diff|validate`. */
+export const profileCommand = defineCommand({
+  meta: { name: "profile", description: "Profiles: which models each role runs, and how" },
+  subCommands: { list, show, use, new: create, copy, rm, set, diff, validate },
+});