catherd-cli 0.2.1 → 1.0.0

package/src/services/doctor-backends.ts

@@ -0,0 +1,185 @@
+import type { Probe } from "../adapters/backend.ts";
+import { adapterFor } from "../adapters/registry.ts";
+import "../adapters/all.ts";
+import { ADAPTER_IDS, tryParseRung } from "../domain/ids.ts";
+import type { Profile } from "../domain/profile.ts";
+import { ROLES, type Role } from "../domain/roles.ts";
+import { refreshDiscovery } from "./catalog-service.ts";
+import { type Check, errText, fixOf } from "./doctor-checks.ts";
+
+// The backend rows of `catherd doctor` (spec §10.3) and the backends the linked profiles use.
+
+/** A rung's backend; null for a malformed rung, which validate reports. */
+const backendOf = (rung: string): string | null => tryParseRung(rung)?.backend ?? null;
+
+/** Every backend a linked profile runs a role on ("role"), or only fails over to ("failover"). */
+export function usedBackends(profiles: Profile[]): Map<string, "role" | "failover"> {
+  const used = new Map<string, "role" | "failover">();
+  const note = (rung: string, how: "role" | "failover") => {
+    const b = backendOf(rung);
+    if (b && used.get(b) !== "role") used.set(b, how);
+  };
+  for (const p of profiles) {
+    for (const role of ROLES) if (p.roles[role].enabled) for (const r of p.roles[role].rungs) note(r, "role");
+    for (const to of Object.values(p.failover)) note(to, "failover");
+  }
+  return used;
+}
+
+/**
+ * Spec §10.3: the backends that run an enabled workspace-write role, or stand in for one of its rungs,
+ * whose sandbox must let such a worker take the heavy lock.
+ */
+export function workspaceWriteBackends(profiles: Profile[]): Set<string> {
+  const out = new Set<string>();
+  for (const p of profiles)
+    for (const role of ROLES) {
+      const rc = p.roles[role];
+      if (!rc.enabled || rc.access !== "workspace-write") continue;
+      for (const r of [...rc.rungs, ...rc.rungs.flatMap((x) => p.failover[x] ?? [])]) {
+        const b = backendOf(r);
+        if (b) out.add(b);
+      }
+    }
+  return out;
+}
+
+const PROBLEM_WORD: Record<string, string> = {
+  E_BACKEND_MISSING: "missing",
+  E_BACKEND_TOO_OLD: "too old",
+  E_BACKEND_NOT_LOGGED_IN: "not logged in",
+};
+
+/**
+ * Spec §7.2 keeps the default profile Codex-first. When a backend a role runs on is missing and another is
+ * ready, its fix also offers to move those roles there, onto a rung the shipped catalog scores.
+ */
+const MOVE_TO: Record<string, string> = {
+  "claude-code": "claude-code:claude-opus-5-5#medium",
+  opencode: "opencode:opencode-go/gpt-6-luna#high",
+  codex: "codex:gpt-6-sol#medium",
+};
+
+/** `w` as one shell word: bare when plainly safe, else single-quoted (zsh can glob a bare `#`). */
+const shellWord = (w: string): string => (/^[\w./:=@,+-]+$/.test(w) ? w : `'${w.replaceAll("'", `'\\''`)}'`);
+
+/**
+ * Install `id`, or move the roles that run on it to `to`: one runnable `catherd profile set` per line, for
+ * each linked profile, any default rung the new ladder would not hold reset first. The artist draws, which only Codex does, so
+ * off Codex it is turned off instead.
+ */
+export function moveRolesFix(install: string, id: string, to: string, profiles: Profile[]): string {
+  const onIt = (r: string | undefined) => r !== undefined && backendOf(r) === id;
+  const set = (p: Profile, path: string, v: string) =>
+    `catherd profile set ${path} ${shellWord(v)} --profile ${shellWord(p.name)}`;
+  const stuck = new Set<Role>();
+  const commands: string[] = [];
+  for (const p of profiles)
+    for (const role of ROLES) {
+      const rc = p.roles[role];
+      if (!rc.enabled || !rc.rungs.some(onIt)) continue;
+      if (role === "artist" && to !== "codex") {
+        stuck.add(role);
+        commands.push(set(p, `roles.${role}.enabled`, "false"));
+        continue;
+      }
+      const target = MOVE_TO[to] as string;
+      // the new ladder holds only `target`, so any other default would fail validation: reset it first
+      if (rc.defaultRung !== undefined && rc.defaultRung !== null && rc.defaultRung !== target)
+        commands.push(set(p, `roles.${role}.defaultRung`, "null"));
+      commands.push(set(p, `roles.${role}.rungs`, target));
+    }
+  if (!commands.length) return install;
+  const off = stuck.size ? ` (${[...stuck].join(", ")} needs ${id}, so it is turned off)` : "";
+  return [
+    install,
+    `or move its roles to ${to}: /catherd-setup in Claude Code, or run${off}`,
+    ...commands,
+  ].join("\n");
+}
+
+export async function backendChecks(
+  used: Map<string, "role" | "failover">,
+  profiles: Profile[],
+): Promise<Check[]> {
+  const checks: Check[] = [];
+  const ready: string[] = [];
+  for (const id of ADAPTER_IDS) {
+    const a = adapterFor(id);
+    if (!a) continue;
+    const probe: Probe = await a.probe().catch((e: unknown) => ({
+      installed: false,
+      version: null,
+      versionOk: false,
+      loggedIn: null,
+      problems: [
+        { code: "E_IO_UNEXPECTED" as const, message: errText(e), fix: `run ${id} --version to see why` },
+      ],
+    }));
+    const problem = probe.problems[0];
+    const use = used.get(id);
+    if (!problem) {
+      ready.push(id);
+      const detail = [probe.version, probe.login && `${probe.login} login`].filter(Boolean).join(" · ");
+      // a login billed apart from what a profile says (a plan, or per token) ranks that backend's cost wrongly;
+      // only a profile that routes something to this backend is ranked by it
+      const billed =
+        probe.billing &&
+        profiles.find((p) => p.billing[id] && p.billing[id] !== probe.billing && usedBackends([p]).has(id));
+      checks.push(
+        billed
+          ? {
+              id: `backend:${id}`,
+              label: id,
+              state: "warn",
+              word: "billing",
+              detail: `${detail} · profile ${billed.name} bills ${id} as ${billed.billing[id]}, but this login is ${probe.billing}`,
+              fix: `catherd profile set billing.${id} ${probe.billing} --profile ${billed.name}`,
+            }
+          : { id: `backend:${id}`, label: id, state: "ok", word: "ready", detail },
+      );
+      continue;
+    }
+    checks.push({
+      id: `backend:${id}`,
+      label: id,
+      state: use === "role" ? "fail" : use === "failover" ? "warn" : "skip",
+      word: PROBLEM_WORD[problem.code] ?? "not ready",
+      detail: `${problem.message}${use === "failover" ? " (a failover stand-in uses it)" : use ? "" : " (no profile uses it)"}`,
+      fix: problem.fix,
+    });
+  }
+  const to = Object.keys(MOVE_TO).find((b) => ready.includes(b));
+  for (const c of checks) {
+    const id = c.id.slice("backend:".length);
+    if (to && c.state === "fail" && c.word === PROBLEM_WORD.E_BACKEND_MISSING && c.fix && id !== to)
+      c.fix = moveRolesFix(c.fix, id, to, profiles);
+  }
+  // spec §5.2: doctor refreshes discovery; a listing that fails keeps the last one
+  let refreshed: Awaited<ReturnType<typeof refreshDiscovery>> = [];
+  try {
+    refreshed = await refreshDiscovery({ backends: ready });
+  } catch (e) {
+    checks.push({
+      id: "discovery",
+      label: "model discovery",
+      state: "fail",
+      word: "unreadable",
+      detail: errText(e),
+      fix: fixOf(e) ?? "catherd catalog refresh --verbose",
+    });
+  }
+  for (const r of refreshed) {
+    const c = checks.find((x) => x.id === `backend:${r.backend}`);
+    if (!c) continue;
+    if (r.error)
+      Object.assign(c, {
+        state: "warn",
+        word: "no listing",
+        detail: `${c.detail} · ${r.error}`,
+        fix: "catherd catalog refresh",
+      });
+    else c.detail = `${c.detail} · ${r.models} models`;
+  }
+  return checks;
+}

package/src/services/doctor-checks.ts

@@ -0,0 +1,103 @@
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { errorMessage, isCatherdError } from "../domain/errors.ts";
+import { claudeHome, locksDir } from "../infra/paths.ts";
+import { ensurePrivateDir, PRIVATE_FILE } from "../infra/store.ts";
+import { agentLinkState } from "./agent-links.ts";
+import { activeName } from "./profile-store.ts";
+
+// The rows of `catherd doctor` and the checks that stand alone; doctor.ts assembles the report.
+
+type CheckState = "ok" | "warn" | "fail" | "skip";
+
+/** One row of `catherd doctor` (spec §10.3): its state, one word, the detail and the full fix. */
+export interface Check {
+  id: string;
+  label: string;
+  state: CheckState;
+  word: string;
+  detail: string;
+  fix?: string;
+}
+
+export const PLUGIN_INSTALL =
+  "claude plugin marketplace add 47vigen/catherd && claude plugin install catherd@catherd";
+const PLUGIN_UPDATE = "claude plugin marketplace update catherd && claude plugin update catherd@catherd";
+
+export const errText = (e: unknown): string => errorMessage(e).split("\n")[0] as string;
+export const fixOf = (e: unknown) => (isCatherdError(e) ? e.fix : undefined);
+
+/** A check whose reads can throw (a corrupt or newer-schema file): the throw becomes its `fail` row. */
+export function guarded(id: string, label: string, fallbackFix: string, check: () => Check): Check {
+  try {
+    return check();
+  } catch (e) {
+    return { id, label, state: "fail", word: "unreadable", detail: errText(e), fix: fixOf(e) ?? fallbackFix };
+  }
+}
+
+export function pluginCheck(version: string): Check {
+  const base = { id: "plugin", label: "Claude Code plugin" };
+  const file = join(claudeHome(), "plugins", "installed_plugins.json");
+  let installed: string | null = null;
+  try {
+    const j = JSON.parse(readFileSync(file, "utf8")) as { plugins?: Record<string, { version?: string }[]> };
+    const entry = Object.entries(j.plugins ?? {}).find(([k]) => k.startsWith("catherd@"))?.[1]?.[0];
+    installed = entry ? (entry.version ?? "unknown") : null;
+  } catch {
+    installed = null;
+  }
+  if (installed === null)
+    return {
+      ...base,
+      state: "fail",
+      word: "missing",
+      detail: "not installed in Claude Code",
+      fix: PLUGIN_INSTALL,
+    };
+  if (installed !== version)
+    return {
+      ...base,
+      state: "fail",
+      word: "stale",
+      detail: `plugin ${installed}, catherd ${version}`,
+      fix: PLUGIN_UPDATE,
+    };
+  return { ...base, state: "ok", word: "ready", detail: installed };
+}
+
+export function locksCheck(): Check {
+  const base = { id: "locks", label: "heavy-lock dir" };
+  try {
+    ensurePrivateDir(locksDir());
+    const probe = join(locksDir(), `.doctor-${process.pid}`);
+    writeFileSync(probe, "", { mode: PRIVATE_FILE });
+    rmSync(probe, { force: true });
+    return { ...base, state: "ok", word: "ready", detail: locksDir() };
+  } catch (e) {
+    return {
+      ...base,
+      state: "fail",
+      word: "not writable",
+      detail: `${locksDir()}: ${errText(e)}`,
+      fix: `chmod -R u+w ${locksDir()}`,
+    };
+  }
+}
+
+export function agentsCheck(): Check {
+  const base = { id: "agents", label: "Claude agents" };
+  const links = agentLinkState();
+  const broken = [...links.missing, ...links.stale];
+  if (broken.length)
+    return {
+      ...base,
+      state: "fail",
+      word: links.missing.length ? "missing" : "stale",
+      detail: broken.join(", "),
+      fix: `catherd profile use ${activeName()}`,
+    };
+  return links.ok.length
+    ? { ...base, state: "ok", word: "ready", detail: `${links.ok.length} linked` }
+    : { ...base, state: "skip", word: "none", detail: "no profile uses a native Claude rung" };
+}

package/src/services/doctor.ts

@@ -0,0 +1,358 @@
+import { existsSync, statSync } from "node:fs";
+import { adapterFor } from "../adapters/registry.ts";
+import "../adapters/all.ts";
+import type { Profile } from "../domain/profile.ts";
+import { ROLES } from "../domain/roles.ts";
+import { bunTooOld, MIN_BUN } from "../domain/runtime.ts";
+import type { JevTransport } from "../infra/jev-client.ts";
+import { locksDir } from "../infra/paths.ts";
+import { linkedProfiles } from "./agent-links.ts";
+import { backendChecks, usedBackends, workspaceWriteBackends } from "./doctor-backends.ts";
+import {
+  agentsCheck,
+  type Check,
+  errText,
+  fixOf,
+  guarded,
+  locksCheck,
+  pluginCheck,
+} from "./doctor-checks.ts";
+import { credentialsPath, jevKey, savedJevKey, testJevKey } from "./jev-service.ts";
+import {
+  activeName,
+  enforcementOf,
+  getProfile,
+  profileExists,
+  readConfig,
+  readProjects,
+  validateNamed,
+} from "./profile-store.ts";
+import { listRuns } from "./run-store.ts";
+
+export interface DoctorReport {
+  /** false when any check failed: `catherd doctor` exits 3 */
+  ready: boolean;
+  version: string;
+  checks: Check[];
+}
+
+export interface Handshake {
+  ok: boolean;
+  tools: string[];
+  error?: string;
+}
+
+export interface DoctorDeps {
+  bunVersion: string;
+  /** the package version, which the Claude Code plugin must pin */
+  version: string;
+  /** starts `catherd mcp` over stdio and asks it for tools/list */
+  handshake: () => Promise<Handshake>;
+  jev?: JevTransport;
+}
+
+/**
+ * Spec §10.3: the readiness report. Reads and probes; it writes discovery and a lock probe itself, and the
+ * handshake starts `catherd mcp`, which reconciles runs as it starts. A check that throws becomes a `fail` row.
+ */
+export async function doctor(d: DoctorDeps): Promise<DoctorReport> {
+  const checks: Check[] = [];
+  checks.push(
+    bunTooOld(d.bunVersion)
+      ? {
+          id: "bun",
+          label: "Bun",
+          state: "fail",
+          word: "too old",
+          detail: `${d.bunVersion}, needs ${MIN_BUN}`,
+          fix: "bun upgrade",
+        }
+      : { id: "bun", label: "Bun", state: "ok", word: "ready", detail: d.bunVersion },
+  );
+
+  let profiles: Profile[] = [];
+  let linked: string[] = [];
+  let active: Profile | null = null;
+  try {
+    readConfig();
+    readProjects();
+    active = getProfile(activeName());
+    linked = linkedProfiles();
+    checks.push({
+      id: "config",
+      label: "config",
+      state: "ok",
+      word: "ready",
+      detail: `active profile ${active.name}`,
+    });
+  } catch (e) {
+    checks.push({
+      id: "config",
+      label: "config",
+      state: "fail",
+      word: "invalid",
+      detail: errText(e),
+      fix: fixOf(e) ?? "catherd init",
+    });
+  }
+  // one unreadable linked profile must not hide the others' backends: its own row below reports it
+  profiles = linked.flatMap((n) => {
+    try {
+      return [getProfile(n)];
+    } catch {
+      return [];
+    }
+  });
+  // a repo bound to a profile whose file is gone: every command run in that repo fails to load it
+  try {
+    for (const [repo, name] of Object.entries(readProjects().bindings))
+      if (!profileExists(name))
+        checks.push({
+          id: `binding:${repo}`,
+          label: `binding ${repo}`,
+          state: "fail",
+          word: "missing",
+          detail: `bound to profile ${name}, which does not exist`,
+          fix: `cd ${repo} && catherd profile use --repo --clear`,
+        });
+  } catch {
+    // the config row above already reports an unreadable projects.json
+  }
+  // every linked profile: the active one (row `profile`) and each repo-bound one (row `profile:<name>`).
+  // Each fix names its profile: without one, the CLI acts on the profile of the repo doctor runs in.
+  const names = active ? [active.name, ...linked.filter((n) => n !== active?.name)] : [];
+  for (const name of names) {
+    const id = name === active?.name ? "profile" : `profile:${name}`;
+    const validate = `catherd profile validate ${name}`;
+    const named = (fix: string) =>
+      fix.replaceAll("catherd profile set ", `catherd profile set --profile ${name} `);
+    checks.push(
+      guarded(id, `profile ${name}`, validate, () => {
+        const v = validateNamed(name);
+        const first = v.errors[0] ?? v.warnings[0];
+        return {
+          id,
+          label: `profile ${name}`,
+          state: v.errors.length ? "fail" : v.warnings.length ? "warn" : "ok",
+          word: v.errors.length ? "invalid" : v.warnings.length ? "warning" : "ready",
+          detail: first
+            ? `${first.path}: ${first.message}${v.errors.length + v.warnings.length > 1 ? " (and more)" : ""}`
+            : "valid",
+          ...(first ? { fix: first.fix ? named(first.fix) : validate } : {}),
+        };
+      }),
+    );
+  }
+
+  const used = usedBackends(profiles);
+  checks.push(...(await backendChecks(used, profiles)));
+
+  if (active && [active, ...profiles].every((p) => p.jev.use === "off"))
+    checks.push({
+      id: "jev",
+      label: "Jev",
+      state: "skip",
+      word: "off",
+      detail: profiles.length > 1 ? "off in every linked profile" : "off in the profile",
+    });
+  else {
+    const key = jevKey();
+    if (!key)
+      checks.push({
+        id: "jev",
+        label: "Jev",
+        state: "warn",
+        word: "no key",
+        detail: "optional: routing uses each lane's Kind and Difficulty instead",
+        fix: "catherd init, or export TYPESAFE_API_KEY=<key>",
+      });
+    else {
+      const ok = await testJevKey(key, d.jev).catch(() => false);
+      checks.push(
+        ok
+          ? { id: "jev", label: "Jev", state: "ok", word: "ready", detail: "the key answers" }
+          : {
+              id: "jev",
+              label: "Jev",
+              state: "warn",
+              word: "no answer",
+              detail: "the key did not answer; routing falls back to the lanes",
+              fix: "catherd init to enter a new key",
+            },
+      );
+    }
+  }
+
+  checks.push(pluginCheck(d.version));
+
+  checks.push(
+    active
+      ? guarded("agents", "Claude agents", `catherd profile use ${activeName()}`, agentsCheck)
+      : {
+          id: "agents",
+          label: "Claude agents",
+          state: "skip",
+          word: "not checked",
+          detail: "the config cannot be read",
+        },
+  );
+
+  const h = await d
+    .handshake()
+    .catch((e: unknown): Handshake => ({ ok: false, tools: [], error: errText(e) }));
+  checks.push(
+    h.ok && h.tools.includes("status")
+      ? {
+          id: "mcp",
+          label: "MCP server",
+          state: "ok",
+          word: "ready",
+          detail: `answers tools/list with ${h.tools.length} tools`,
+        }
+      : {
+          id: "mcp",
+          label: "MCP server",
+          state: "fail",
+          word: "no answer",
+          detail: h.error ?? "tools/list has no status tool",
+          fix: "run catherd mcp to see why it does not start",
+        },
+  );
+
+  checks.push(locksCheck());
+  for (const id of workspaceWriteBackends(profiles)) {
+    const a = adapterFor(id);
+    if (!a?.canWrite) continue;
+    const r = await a.canWrite(locksDir()).catch(() => null);
+    const base = { id: `sandbox:${id}`, label: `heavy-lock dir from ${id}'s sandbox` };
+    checks.push(
+      r === null
+        ? {
+            ...base,
+            state: "skip",
+            word: "not tested",
+            detail: `no ${id} sandbox to test with on this machine`,
+          }
+        : r.ok
+          ? {
+              ...base,
+              state: "ok",
+              word: "ready",
+              detail: "a workspace-write worker can take the heavy lock",
+            }
+          : {
+              ...base,
+              state: "warn",
+              word: "not writable",
+              detail: `a workspace-write ${id} worker cannot write ${locksDir()}, so catherd lock fails inside it`,
+              ...(r.fix ? { fix: r.fix } : {}),
+            },
+    );
+  }
+
+  const full: string[] = [];
+  const advisory: string[] = [];
+  for (const p of profiles)
+    for (const role of ROLES) {
+      const rc = p.roles[role];
+      if (!rc.enabled) continue;
+      if (rc.access === "full") full.push(`${role} (${p.name})`);
+      const soft = [
+        ...new Set(
+          rc.rungs
+            .filter((r) => enforcementOf(r, rc.access) === "advisory")
+            .map((r) => r.slice(0, r.indexOf(":"))),
+        ),
+      ];
+      if (soft.length) advisory.push(`${role} on ${soft.join(", ")} (${p.name})`);
+    }
+  if (full.length)
+    checks.push({
+      id: "access:full",
+      label: "full access",
+      state: "warn",
+      word: "warning",
+      detail: `no sandbox for: ${full.join(", ")}`,
+    });
+  if (advisory.length)
+    checks.push({
+      id: "access:advisory",
+      label: "advisory access",
+      state: "warn",
+      word: "warning",
+      detail: `the backend asks but cannot force: ${advisory.join(", ")}`,
+    });
+  for (const id of used.keys()) {
+    const note = adapterFor(id)?.isolationNote;
+    if (note)
+      checks.push({
+        id: `isolation:${id}`,
+        label: `${id} isolation`,
+        state: "warn",
+        word: "weak",
+        detail: note,
+      });
+  }
+
+  const creds = credentialsPath();
+  if (existsSync(creds)) {
+    const mode = statSync(creds).mode & 0o777;
+    // Jev reads an unreadable file as no key (it is optional): here is where the user learns why
+    const unreadable = savedJevKey().problem;
+    checks.push(
+      mode & 0o077
+        ? {
+            id: "credentials",
+            label: "credentials.json",
+            state: "fail",
+            word: "readable by others",
+            detail: `mode ${mode.toString(8)}`,
+            fix: `chmod 600 ${creds}`,
+          }
+        : unreadable
+          ? {
+              id: "credentials",
+              label: "credentials.json",
+              state: "warn",
+              word: "unreadable",
+              detail: unreadable.message,
+              fix: unreadable.fix ?? `fix or delete ${creds}, then catherd init`,
+            }
+          : { id: "credentials", label: "credentials.json", state: "ok", word: "ready", detail: "mode 600" },
+    );
+  }
+
+  if (!Bun.which("bunx", { PATH: process.env.PATH ?? "" }))
+    checks.push({
+      id: "bunx",
+      label: "bunx",
+      state: "warn",
+      word: "missing",
+      detail: "the plugin starts the MCP server with bunx",
+      fix: "put Bun's bin folder (~/.bun/bin) on PATH",
+    });
+  let corrupt: ReturnType<typeof listRuns>["corrupt"] = [];
+  try {
+    corrupt = listRuns().corrupt;
+  } catch (e) {
+    checks.push({
+      id: "runs",
+      label: "run data",
+      state: "fail",
+      word: "unreadable",
+      detail: errText(e),
+      fix: fixOf(e) ?? "catherd runs list --verbose",
+    });
+  }
+  if (corrupt.length)
+    checks.push({
+      id: "runs",
+      label: "run data",
+      state: "warn",
+      word: "unreadable",
+      detail: corrupt.map((c) => `${c.id}: ${c.reason}`).join("; "),
+      fix: `fix or delete ${corrupt[0]?.dir}`,
+    });
+
+  return { ready: !checks.some((c) => c.state === "fail"), version: d.version, checks };
+}