catherd-cli 0.2.1 → 1.0.0

package/src/entry/doctor-command.ts

@@ -0,0 +1,45 @@
+import { defineCommand } from "citty";
+import { VERSION } from "../infra/version.ts";
+import { type DoctorReport, doctor } from "../services/doctor.ts";
+import type { Check } from "../services/doctor-checks.ts";
+import { EXIT, JSON_ARG, mark, printJson } from "./cli-kit.ts";
+import { mcpHandshake } from "./mcp/handshake.ts";
+
+/**
+ * One row per check: `✓ ready  Bun — 1.4.2`, then the full fix on its own line; a fix of several lines
+ * (one command each) keeps them under the first.
+ */
+export function formatCheck(c: Check, plain = false): string[] {
+  return [
+    `${mark(c.state, plain)} ${c.word.padEnd(18)} ${c.label}${c.detail ? ` — ${c.detail}` : ""}`,
+    ...(c.fix ? c.fix.split("\n").map((l, i) => `${i ? "         " : "    fix: "}${l}`) : []),
+  ];
+}
+
+export function formatReport(r: DoctorReport, plain = false): string[] {
+  return [
+    ...r.checks.flatMap((c) => formatCheck(c, plain)),
+    "",
+    r.ready
+      ? `${mark("ok", plain)} ready`
+      : `${mark("fail", plain)} not ready: fix the rows marked ${mark("fail", plain)} above`,
+  ];
+}
+
+/** Spec §8, §10.3: `catherd doctor [--json]`, exit 3 when not ready. */
+export const doctorCommand = defineCommand({
+  meta: {
+    name: "doctor",
+    description: "Readiness report: Bun, backends, Jev, the plugin, agents, the MCP server, locks",
+  },
+  args: {
+    ...JSON_ARG,
+    plain: { type: "boolean", description: "ASCII glyphs (NO_COLOR drops only colour)" },
+  },
+  async run({ args }) {
+    const r = await doctor({ bunVersion: Bun.version, version: VERSION, handshake: () => mcpHandshake() });
+    if (args.json) printJson(r);
+    else for (const l of formatReport(r, args.plain === true)) console.log(l);
+    process.exitCode = r.ready ? EXIT.ok : EXIT.notReady;
+  },
+});

package/src/entry/glyphs.ts

@@ -0,0 +1,33 @@
+/**
+ * Spec §9.3's glyphs, each with its ASCII twin for `--plain`: the dashboard and every CLI command draw
+ * state with these. Free of OpenTUI, so `mcp`, `lock` and `_supervise` can load it (spec §3.1).
+ */
+const GLYPHS = {
+  ok: ["✓", "+"],
+  warn: ["!", "!"],
+  fail: ["✗", "x"],
+  skip: ["-", "-"],
+  live: ["●", "*"],
+  waiting: ["◌", "."],
+  on: ["[x]", "[x]"],
+  off: ["[ ]", "[ ]"],
+  open: ["▾", "v"],
+  shut: ["▸", ">"],
+  arrow: ["→", "->"],
+  dot: ["·", "-"],
+  more: ["…", "..."],
+  up: ["↑", "^"],
+  down: ["↓", "v"],
+  bar: ["┃", "|"],
+  rule: ["─", "-"],
+  current: ["●", "*"],
+  full: ["█", "#"],
+  empty: ["░", "."],
+} as const;
+export type Glyph = keyof typeof GLYPHS;
+export const GLYPH_NAMES = Object.keys(GLYPHS) as Glyph[];
+
+export const glyph = (g: Glyph, plain: boolean): string => GLYPHS[g][plain ? 1 : 0];
+
+/** The words state always travels with (spec §9.3: green/amber/red only for state, always with a word). */
+export type State = "ok" | "warn" | "fail" | "skip";

package/src/entry/init-command.ts

@@ -0,0 +1,142 @@
+import { defineCommand } from "citty";
+import { assertProfileName } from "../domain/profile.ts";
+import { errorMessage, isCatherdError } from "../domain/errors.ts";
+import { configDir } from "../infra/paths.ts";
+import { VERSION } from "../infra/version.ts";
+import { doctor } from "../services/doctor.ts";
+import { jevKey, saveJevKey, testJevKey } from "../services/jev-service.ts";
+import { hasProfileFile, type InitResult, initSetup, moveLegacy } from "../services/setup.ts";
+import { formatRefreshed } from "./catalog-command.ts";
+import { mark as markOf } from "./cli-kit.ts";
+import { formatReport } from "./doctor-command.ts";
+import { mcpHandshake } from "./mcp/handshake.ts";
+import type { State } from "./glyphs.ts";
+import { mascot } from "./tui/theme.ts";
+import { type Prompter, prompter } from "./prompt.ts";
+
+/** What `init` prints last (spec §9.1): the plugin install commands, to paste into a terminal. */
+export const PLUGIN_STEPS = [
+  "Install the Claude Code plugin:",
+  "  claude plugin marketplace add 47vigen/catherd",
+  "  claude plugin install catherd@catherd",
+  "Then start a new Claude Code session, so it loads the plugin and the catherd agents.",
+];
+
+/** Spec §9.3: the full mascot greets `init` (and the TUI's empty states), nowhere else. */
+export function welcomeLines(version: string): string[] {
+  const [ears, face, paws] = mascot("good");
+  return [ears, `${face}  catherd ${version}`, `${paws}  herds your coding agents`, ""];
+}
+
+/**
+ * The Jev key step. It never stops `init` (Ruling 11): a key that cannot be saved, say because
+ * credentials.json is unparsable, is reported with its fix and setup goes on.
+ */
+export async function jevStep(
+  ask: Prompter | null,
+  d: { testJevKey?: (key: string) => Promise<boolean>; saveJevKey?: (key: string) => void } = {},
+  plain = false,
+): Promise<void> {
+  const mark = (state: State) => markOf(state, plain);
+  if (process.env.TYPESAFE_API_KEY?.trim()) {
+    ask?.skip?.();
+    return console.log(`${mark("ok")} Jev: using TYPESAFE_API_KEY`);
+  }
+  if (jevKey()) {
+    ask?.skip?.();
+    return console.log(`${mark("ok")} Jev: using the saved key`);
+  }
+  const key = ask ? await ask.secret("TypeSafe API key for Jev (optional; Enter skips): ") : "";
+  if (!key)
+    return console.log(
+      `- Jev: no key; routing uses each lane's Kind and Difficulty (add one later with catherd init)`,
+    );
+  if (!(await (d.testJevKey ?? testJevKey)(key).catch(() => false)))
+    return console.log(`${mark("warn")} Jev: the key did not answer, so it was not saved`);
+  try {
+    (d.saveJevKey ?? saveJevKey)(key);
+    console.log(`${mark("ok")} Jev: the key answers; saved with mode 600`);
+  } catch (e) {
+    const message = errorMessage(e).split("\n").join(" ");
+    console.log(`${mark("warn")} Jev: could not save the key: ${message}`);
+    if (isCatherdError(e) && e.fix) console.log(`    fix: ${e.fix}`);
+  }
+}
+
+/** What happened to the profile: written, kept, or (when the defaults do not validate here) why not. */
+export function profileLines(r: InitResult, plain = false): string[] {
+  const mark = (state: State) => markOf(state, plain);
+  const out: string[] = [];
+  if (r.errors.length) {
+    out.push(
+      `${mark("warn")} profile ${r.profile}: the default profile does not validate here, so it was not written`,
+    );
+    for (const e of r.errors) {
+      out.push(`${mark("warn")} ${e.path}: ${e.message}`);
+      if (e.fix) out.push(`    fix: ${e.fix}`);
+    }
+  }
+  if (!r.active)
+    out.push(`${mark("warn")} no profile was made active: fix the rows above, then run catherd init again`);
+  else
+    out.push(
+      `${mark("ok")} profile ${r.profile} ${r.created ? "written from the defaults" : "kept as it was"}, and active`,
+    );
+  return out;
+}
+
+/** Spec §8 `catherd init [--no-input]`: first-run setup without the TUI (plan 6 adds the TUI wizard). */
+export const initCommand = defineCommand({
+  meta: {
+    name: "init",
+    description:
+      "First run: the Jev key, the default profile, its agents, and a readiness report. Piped, it reads the answers from stdin one per line, a line per question even when this machine skips it (the Jev key, the profile, whether to replace it), and waits for stdin to close; --no-input asks nothing",
+  },
+  args: {
+    // citty reads --no-input as input: false, whatever the flag is named; naming it no-input shows it as is
+    "no-input": { type: "boolean", description: "ask nothing: keep what exists, else write the defaults" },
+    profile: { type: "string", description: "the profile to set up and make active (default: default)" },
+    plain: { type: "boolean", description: "ASCII glyphs (NO_COLOR drops only colour)" },
+  },
+  async run({ args }) {
+    // a bad --profile is refused before any question is asked
+    if (args.profile !== undefined) assertProfileName(args.profile);
+    const ask = (args as { input?: boolean }).input === false ? null : await prompter();
+    const plain = args.plain === true;
+    const mark = (state: State) => markOf(state, plain);
+    try {
+      if (process.stdout.isTTY) for (const line of welcomeLines(VERSION)) console.log(line);
+      console.log(`catherd ${VERSION}: setting up in ${configDir()}`);
+      await jevStep(ask, {}, plain);
+      if (args.profile !== undefined) ask?.skip?.();
+      const name = assertProfileName(
+        args.profile ?? (ask ? (await ask.ask("Profile to set up [default]: ")) || "default" : "default"),
+      );
+      // 0.x files go first, so a legacy profile about to be moved aside is never asked about
+      const moved = moveLegacy();
+      const exists = hasProfileFile(name);
+      if (!exists) ask?.skip?.();
+      const overwrite =
+        ask !== null &&
+        exists &&
+        /^y(es)?$/i.test(await ask.ask(`Replace profile ${name} with the default profile? [y/N] `));
+      const r = await initSetup({ profile: name, overwrite });
+      for (const f of [...moved, ...r.moved]) console.log(`${mark("ok")} moved a 0.x file aside: ${f}`);
+      for (const l of profileLines(r, plain)) console.log(l);
+      if (r.synced?.linked.length)
+        console.log(`${mark("ok")} Claude agents linked: ${r.synced.linked.join(", ")}`);
+      for (const x of r.refreshed) console.log(formatRefreshed(x, plain));
+      console.log("");
+      const report = await doctor({
+        bunVersion: Bun.version,
+        version: VERSION,
+        handshake: () => mcpHandshake(),
+      });
+      for (const l of formatReport(report, plain)) console.log(l);
+      console.log("");
+      for (const l of PLUGIN_STEPS) console.log(l);
+    } finally {
+      ask?.close();
+    }
+  },
+});

package/src/entry/lock-command.ts

@@ -0,0 +1,123 @@
+import { defineCommand } from "citty";
+import { CatherdError } from "../domain/errors.ts";
+import { scrubSecrets } from "../infra/env.ts";
+import { gitToplevel } from "../infra/git.ts";
+import { heavySlots, withHeavySlot } from "../infra/heavy-lock.ts";
+import { killGroup } from "../infra/proc.ts";
+import { profileFor } from "../services/profile-store.ts";
+import { printError } from "./cli-kit.ts";
+
+/**
+ * --slots, then CATHERD_LOCK_SLOTS, then the profile's lock.heavy, then half the cores. `warn` hears why
+ * the profile could not say, so the fallback is never silent (plan-2 review m10).
+ */
+export function resolveSlots(
+  flag: string | undefined,
+  profile: () => number | "cpus/2",
+  warn: (message: string) => void = () => {},
+): number {
+  const raw = flag ?? process.env.CATHERD_LOCK_SLOTS;
+  if (raw) {
+    if (raw === "cpus/2") return heavySlots("cpus/2");
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1)
+      throw new CatherdError("E_INPUT_INVALID", `slots must be a number ≥ 1 or cpus/2, not "${raw}"`, {
+        fix: "catherd lock --slots 2 -- <command>",
+      });
+    return heavySlots(n);
+  }
+  try {
+    return heavySlots(profile());
+  } catch (e) {
+    const slots = heavySlots("cpus/2");
+    warn(`catherd lock: no profile to read lock.heavy from (${(e as Error).message}); using ${slots} slots`);
+    return slots;
+  }
+}
+
+/** How long a second Ctrl-C has to follow the first to kill the command outright. */
+export const DOUBLE_INTERRUPT_MS = 2_000;
+
+/**
+ * Runs `argv` in its own process group and forwards SIGINT, SIGTERM and SIGHUP to the whole group once:
+ * a terminal's Ctrl-C reaches catherd only, so the command sees it exactly once, and so does every
+ * process it started. A second Ctrl-C within 2 s kills the group. Resolves to the command's exit code.
+ */
+export async function runForwarding(argv: string[]): Promise<number> {
+  const child = Bun.spawn(argv, {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env: scrubSecrets(process.env),
+    detached: true,
+  });
+  let lastInt = 0;
+  const handlers: [NodeJS.Signals, () => void][] = [
+    [
+      "SIGINT",
+      () => {
+        const now = Date.now();
+        killGroup(child.pid, now - lastInt < DOUBLE_INTERRUPT_MS ? "SIGKILL" : "SIGINT");
+        lastInt = now;
+      },
+    ],
+    ["SIGTERM", () => killGroup(child.pid, "SIGTERM")],
+    ["SIGHUP", () => killGroup(child.pid, "SIGHUP")],
+  ];
+  for (const [sig, h] of handlers) process.on(sig, h);
+  // The command's own session is out of reach of a signal to catherd's group, and a SIGKILL (a
+  // supervisor's escalation) cannot be forwarded: the watchdog reads EOF when catherd dies, however it
+  // dies, and kills the command's group then.
+  const watchdog = Bun.spawn(
+    ["sh", "-c", 'read _ || kill -s KILL -- "-$1" 2>/dev/null', "sh", String(child.pid)],
+    {
+      stdin: "pipe",
+      stdout: "ignore",
+      stderr: "ignore",
+      detached: true,
+    },
+  );
+  try {
+    return await child.exited;
+  } finally {
+    watchdog.kill("SIGKILL");
+    for (const [sig, h] of handlers) process.off(sig, h);
+  }
+}
+
+/** Spec §8: what `--help` and the usage error show; the command runs after `--`. */
+export const LOCK_USAGE = "catherd lock [--slots N] -- <command> [args...]";
+
+export const lockCommand = defineCommand({
+  meta: {
+    name: "lock",
+    description:
+      "Run a heavy command behind the machine-wide semaphore, in its own process group and session: it gets no /dev/tty and no job control",
+  },
+  args: {
+    slots: {
+      type: "string",
+      description: "Slots (default: CATHERD_LOCK_SLOTS, else the profile's lock.heavy, else half the cores)",
+    },
+  },
+  async run({ args, rawArgs }) {
+    const sep = rawArgs.indexOf("--");
+    const argv = sep < 0 ? [] : rawArgs.slice(sep + 1);
+    if (argv.length === 0) {
+      printError(
+        new CatherdError("E_INPUT_INVALID", "no command to run", {
+          fix: LOCK_USAGE,
+        }),
+      );
+      process.exitCode = 2;
+      return;
+    }
+    const repo = await gitToplevel(process.cwd());
+    const slots = resolveSlots(
+      args.slots,
+      () => profileFor(repo).lock.heavy,
+      (m) => console.error(m),
+    );
+    process.exitCode = await withHeavySlot(slots, () => runForwarding(argv));
+  },
+});

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

@@ -0,0 +1,82 @@
+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 { cancel, dispatch, type Progress, wait } from "../../services/dispatch-service.ts";
+import type { Deps } from "../../services/ports.ts";
+import { handle } from "./result.ts";
+
+type Notify = (n: {
+  method: "notifications/progress";
+  params: { progressToken: string | number; progress: number; message: string };
+}) => Promise<void>;
+
+/** Progress notifications that can never fail a wait: the client may be gone (audit C8). */
+export function progressTo(token: string | number | undefined, send: Notify): Progress | undefined {
+  if (token === undefined) return undefined;
+  let n = 0;
+  return (message) => {
+    try {
+      send({
+        method: "notifications/progress",
+        params: { progressToken: token, progress: ++n, message },
+      }).catch(() => {}); // the client is gone: progress is best effort
+    } catch {
+      // the transport is closed
+    }
+  };
+}
+
+export function registerDispatchTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "dispatch",
+    {
+      description:
+        "Start one role on a process backend (codex, claude-code, opencode) and return at launch, in about a second, with { dispatched: { name, role, rung, dispatchId, admittedAt }, hints }; the role runs on, and wait(run) collects its record. Dispatch every independent role one after another, then call wait. The brief is the text itself. With lane, the lane file's Owns: paths guard against overlapping lanes. thread resumes that role's thread for its own fix round. Refused with a structured error (E_ADMIT_*, E_RUN_BUDGET, E_BACKEND_*) before anything starts. Call it from the main thread.",
+      inputSchema: {
+        run: z.string(),
+        role: z.enum(ROLES),
+        name: z.string().regex(ID_PATTERN),
+        brief: z.string().min(1),
+        rung: z.string().min(3),
+        thread: z.string().optional(),
+        lane: z.string().regex(ID_PATTERN).optional(),
+        next: z.string().optional(),
+      },
+    },
+    (a) => handle(() => dispatch(deps, a)),
+  );
+
+  server.registerTool(
+    "wait",
+    {
+      description:
+        "Block until at least one of the run's uncollected dispatches has finished (only those in names, when given; every one of them with all: true), reporting progress meanwhile, and return { records, started, running, hints }. records holds each finished role's { record, hints }, in the order they finished, each returned by one wait only; a role that hit a usage limit has its failover stand-in launched, listed in started. running names every uncollected role this call did not return, still running or already finished, stand-ins included: act on the records, then wait again while running is not empty. Returns at once, with a hint, when nothing is uncollected. Call it from the main thread.",
+      inputSchema: {
+        run: z.string(),
+        names: z.array(z.string().regex(ID_PATTERN)).optional(),
+        all: z.boolean().optional(),
+      },
+    },
+    (a, extra) =>
+      handle(() =>
+        wait(
+          deps,
+          a,
+          progressTo(extra._meta?.progressToken, (n) => extra.sendNotification(n)),
+          // a wait its caller cancelled collects nothing: the record would go to no one
+          extra.signal,
+        ),
+      ),
+  );
+
+  server.registerTool(
+    "cancel",
+    {
+      description:
+        "Stop a live dispatch (interrupt, then SIGTERM, then SIGKILL) and return its record, marked cancelled, and hints.",
+      inputSchema: { run: z.string(), name: z.string().regex(ID_PATTERN) },
+    },
+    (a) => handle(() => cancel(deps, a.run, a.name)),
+  );
+}

package/src/entry/mcp/handshake.ts

@@ -0,0 +1,48 @@
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { errorMessage } from "../../domain/errors.ts";
+import { scrubSecrets } from "../../infra/env.ts";
+import { VERSION } from "../../infra/version.ts";
+import type { Handshake } from "../../services/doctor.ts";
+
+const CLI = fileURLToPath(new URL("../../cli.ts", import.meta.url));
+const TIMEOUT_MS = 20_000;
+
+/** The env the doctor's MCP server starts with: catherd's own secrets scrubbed, as for every process it starts. */
+export const handshakeEnv = (
+  base: Record<string, string | undefined> = process.env,
+): Record<string, string> => scrubSecrets(base);
+
+/** Spec §10.3: starts `catherd mcp` over stdio, as Claude Code would, and asks it for tools/list. */
+export async function mcpHandshake(): Promise<Handshake> {
+  const client = new Client({ name: "catherd-doctor", version: VERSION });
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [CLI, "mcp"],
+    env: handshakeEnv(),
+    stderr: "ignore",
+  });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<Handshake>((resolve) => {
+    timer = setTimeout(
+      () => resolve({ ok: false, tools: [], error: `no answer within ${TIMEOUT_MS / 1000} s` }),
+      TIMEOUT_MS,
+    );
+  });
+  try {
+    return await Promise.race([
+      (async (): Promise<Handshake> => {
+        await client.connect(transport);
+        const r = await client.listTools();
+        return { ok: true, tools: r.tools.map((t) => t.name) };
+      })(),
+      late,
+    ]);
+  } catch (e) {
+    return { ok: false, tools: [], error: errorMessage(e) };
+  } finally {
+    clearTimeout(timer);
+    await client.close().catch(() => {}); // the answer (or the failure) is already in hand
+  }
+}

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

@@ -0,0 +1,83 @@
+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 { CLIMB_REASONS } from "../../domain/route.ts";
+import { ask, climb, land, route } from "../../services/lane-service.ts";
+import type { Deps } from "../../services/ports.ts";
+import { preflight } from "../../services/preflight.ts";
+import { handle } from "./result.ts";
+
+export function registerLaneTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "route",
+    {
+      description:
+        "The rung for a lane (from Jev, else the lane file's Kind/Difficulty lines, else the profile default) or, without a lane file, a role's default rung, with the ladder above it. Rungs are backend:model#effort; a claude: rung comes with the agent to run it as.",
+      inputSchema: {
+        run: z.string(),
+        lane_file: z.string().optional(),
+        role: z.enum(ROLES).default("worker"),
+      },
+    },
+    (a) => handle(() => route(deps, { run: a.run, laneFile: a.lane_file, role: a.role })),
+  );
+
+  server.registerTool(
+    "preflight",
+    {
+      description:
+        "Run each lane's fast check once, on the base tree, behind the heavy-command lock, with a 120 s timeout. Each lane is pass, fails-as-expected, skipped (it checks a file the lane creates) or cannot-start; only cannot-start blocks. When the profile asks for confirmation, the first call returns the commands to show the user; call again with confirmed: true.",
+      inputSchema: { run: z.string(), confirmed: z.boolean().optional() },
+    },
+    (a) => handle(() => preflight(deps, { run: a.run, confirmed: a.confirmed })),
+  );
+
+  server.registerTool(
+    "climb",
+    {
+      description:
+        "Move a routed lane one rung up its ladder and record why. Returns the next rung, or top: true, and any hints. Dispatch the lane again at that rung on a fresh thread. Pass env: true when the environment caused it (a missing service, a broken tool, a usage limit), not the rung.",
+      inputSchema: {
+        run: z.string(),
+        lane: z.string().regex(ID_PATTERN),
+        reason: z.enum(CLIMB_REASONS),
+        evidence: z.string().optional(),
+        env: z.boolean().optional(),
+      },
+    },
+    (a) => handle(() => climb(deps, a)),
+  );
+
+  server.registerTool(
+    "ask",
+    {
+      description:
+        "Ask Jev one fixed question. finding: state { lane_file, finding } → design | code | unclear. same-defect: state { before, after } → yes | no. Falls back to the default when Jev is unsure or absent. Keep the state short, in English, and free of secrets.",
+      inputSchema: {
+        run: z.string(),
+        question: z.enum(["finding", "same-defect"]),
+        state: z.record(z.string(), z.string()),
+      },
+    },
+    (a) => handle(() => ask(deps, a)),
+  );
+
+  server.registerTool(
+    "land",
+    {
+      description:
+        "Record a landed milestone after you commit it: its five-column ledger row (with the minutes it took) and state.md's last check and next step, with any hints. learned, when given, goes to this repo's knowledge.md.",
+      inputSchema: {
+        run: z.string(),
+        milestone: z.string().min(1),
+        what: z.string().min(1),
+        commit: z.string().regex(/^[0-9a-f]{7,40}$/),
+        evidence: z.string().min(1),
+        next: z.string().min(1),
+        learned: z.string().min(1).optional(),
+      },
+    },
+    (a) => handle(() => land(deps, a)),
+  );
+}

package/src/entry/mcp/result.ts

@@ -0,0 +1,51 @@
+import { type CallToolResult, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { CatherdError, errorMessage, isCatherdError } from "../../domain/errors.ts";
+
+/** A service's value as a tool result; its `hints`, when it has any, pass through as they are. */
+const ok = (v: unknown): CallToolResult => ({
+  content: [{ type: "text", text: typeof v === "string" ? v : JSON.stringify(v, null, 2) }],
+});
+
+/** Spec §4.8, §10.1: every failure is a structured tool error `{ code, message, fix }`. */
+function fail(e: unknown): CallToolResult {
+  const err = isCatherdError(e)
+    ? { fix: "", ...e.toJSON() }
+    : {
+        code: "E_IO_UNEXPECTED",
+        message: errorMessage(e),
+        fix: "this is a catherd bug: report it with the message",
+      };
+  return { isError: true, content: [{ type: "text", text: JSON.stringify(err) }], structuredContent: err };
+}
+
+/** Runs one service call and turns its value, or its error, into a tool result. */
+export async function handle(f: () => unknown): Promise<CallToolResult> {
+  try {
+    return ok(await f());
+  } catch (e) {
+    return fail(e);
+  }
+}
+
+const UNKNOWN_TOOL = /Tool (\S+) (?:not found|disabled)$/;
+
+/** The tool an SDK error message names ("Tool x not found", "… arguments for tool x: …"), else null. */
+export const toolOf = (message: string): string | null =>
+  (UNKNOWN_TOOL.exec(message) ?? /for tool (\S+?):/.exec(message))?.[1] ?? null;
+
+/**
+ * The SDK's own tool errors, raised before `handle` runs, in catherd's shape (spec §4.8): a call to a tool
+ * this server does not have, or input a tool's schema rejects, is E_INPUT_INVALID; anything else is
+ * unexpected.
+ */
+export function sdkToolError(message: string): CallToolResult {
+  if (!message.startsWith(`MCP error ${ErrorCode.InvalidParams}:`)) return fail(new Error(message));
+  const unknown = UNKNOWN_TOOL.exec(message)?.[1];
+  return fail(
+    new CatherdError("E_INPUT_INVALID", message, {
+      fix: unknown
+        ? `call a tool this server lists (tools/list); a skill that needs ${unknown} needs a newer catherd: claude plugin update catherd@catherd`
+        : "correct the argument the message names, then call again",
+    }),
+  );
+}