@capacms/cli 0.0.0-stage → 0.1.0

package/lib/main.mjs

@@ -0,0 +1,477 @@
+/**
+ * main.mjs — `capa`: read the command line, run one command, answer an exit
+ * code. Everything a command touches comes in through `io` (streams, env,
+ * cwd, the process runner), so the tests run the real commands in-process.
+ */
+import fs from "node:fs";
+import { createInterface } from "node:readline";
+import { TOOLS, TOOLS_BY_NAME, connect, keyFamily, serveStdio } from "@capacms/mcp";
+import { parseArgv } from "./argv.mjs";
+import { COMMANDS, booleanFlags, findCommand, flagHelp, toolArgs } from "./commands.mjs";
+import { createCredentials, systemRunner } from "./credentials.mjs";
+import { CLIENTS, applyPlan, planInit, planInstructions, showPlan } from "./init.mjs";
+import { CliError, EXIT, createOutput } from "./output.mjs";
+import { SDK_COMMANDS, runSdk } from "./sdk.mjs";
+import { DEFAULT_API_URL, configFrom, keySees, offered, openSession, resolveEnv, runAndPrint, whoAmIAndUploads } from "./session.mjs";
+
+const VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+/** Flags the CLI reads itself; never passed to a tool. */
+const RESERVED = new Set(["json", "profile", "help", "version"]);
+
+const LOCAL_COMMANDS = {
+  login: { usage: "capa login [--key-stdin] [--api-url URL] [--upload-url URL] [--profile NAME] [--tenant-id ID]", summary: "Check a key against Capa and keep it in the keychain.", booleans: ["keyStdin"] },
+  logout: { usage: "capa logout [--profile NAME] [--all]", summary: "Forget a key: the profile and its keychain entry.", booleans: ["all"] },
+  whoami: { usage: "capa whoami", summary: "The key in use: its project, environment, scopes, and what it reads." },
+  projects: { usage: "capa projects [use <profile>]", summary: "The saved profiles, one per key and project; `use` picks the current one." },
+  tools: { usage: "capa tools", summary: "The MCP tools this key is offered here, each one runnable with capa tool." },
+  tool: { usage: "capa tool <name> [--args JSON|@file|-] [--<argument> value ...]", summary: "Run any MCP tool by name, with its arguments as flags or one JSON object." },
+  mcp: { usage: "capa mcp", summary: "Serve the MCP server on stdio with the stored key (what capa init registers)." },
+  init: {
+    usage: "capa init claude|codex|cursor [--dry-run] [--yes] [--instructions] [--scope project|user|local] [--project] [--global] [--approve] [--command CMD]",
+    summary: "Register capa mcp with Claude Code, Codex or Cursor, showing the change first.",
+    booleans: ["yes", "dryRun", "instructions", "project", "global", "approve"],
+  },
+  codegen: { usage: "capa codegen [--graphql] [--out file]", summary: "Generate types (from @capacms/sdk, run as is)." },
+  persist: { usage: "capa persist [--documents src] [--manifest file]", summary: "Register persisted GraphQL documents (from @capacms/sdk, run as is)." },
+};
+
+const HELP = () =>
+  [
+    `capa ${VERSION}: Capa from a terminal, a script or an agent.`,
+    "",
+    "Account",
+    ...["login", "logout", "whoami", "projects"].map((c) => `  ${LOCAL_COMMANDS[c].usage}\n      ${LOCAL_COMMANDS[c].summary}`),
+    "",
+    "Content (each runs one MCP tool, with the same arguments and errors)",
+    ...COMMANDS.map((c) => `  ${c.usage}\n      ${c.summary}`),
+    `  ${LOCAL_COMMANDS.tools.usage}\n      ${LOCAL_COMMANDS.tools.summary}`,
+    `  ${LOCAL_COMMANDS.tool.usage}\n      ${LOCAL_COMMANDS.tool.summary}`,
+    "",
+    "Agents",
+    `  ${LOCAL_COMMANDS.init.usage}\n      ${LOCAL_COMMANDS.init.summary}`,
+    `  ${LOCAL_COMMANDS.mcp.usage}\n      ${LOCAL_COMMANDS.mcp.summary}`,
+    "",
+    "Code",
+    `  ${LOCAL_COMMANDS.codegen.usage}\n      ${LOCAL_COMMANDS.codegen.summary}`,
+    `  ${LOCAL_COMMANDS.persist.usage}\n      ${LOCAL_COMMANDS.persist.summary}`,
+    "",
+    "Every command takes --json (stdout is one JSON document, errors included) and --profile NAME.",
+    "Nothing prompts when stdin is not a terminal: pass the flag instead.",
+    "",
+    "The key: CAPA_KEY (and CAPA_API_URL) in the environment, else the profile capa login saved.",
+    "",
+    "Exit codes",
+    "  0  done",
+    "  1  the API refused, or answered with an error",
+    "  2  usage: unknown command or flag, a bad argument, or a write that needs --yes",
+    "  3  no key, a key the API does not know, or a config file capa cannot use",
+    "  4  the tool behind the command is not offered for this key here",
+    "  5  Capa did not answer",
+    "codegen and persist exit as @capacms/sdk documents.",
+  ].join("\n");
+
+function commandHelp(name, command) {
+  if (command) {
+    const skip = command.pick(command.positionals.map((p) => p.replace("?", "")), () => true).args;
+    const flags = command.tools.flatMap((tool) => (TOOLS_BY_NAME.has(tool) ? flagHelp(tool, Object.keys(skip)) : []));
+    const seen = new Set();
+    const unique = flags.filter((line) => {
+      const flag = line.split("\n")[0].trim().split(" ")[0];
+      if (seen.has(flag)) return false;
+      seen.add(flag);
+      return true;
+    });
+    return [command.usage, `  ${command.summary}`, "", `Runs ${command.tools.join(", or else ")}.`, "", "Flags", ...unique, "  --json\n      Print one JSON document."].join("\n");
+  }
+  const local = LOCAL_COMMANDS[name];
+  return local ? `${local.usage}\n  ${local.summary}` : HELP();
+}
+
+async function readAll(stream) {
+  let text = "";
+  stream.setEncoding?.("utf8");
+  for await (const chunk of stream) text += chunk;
+  return text;
+}
+
+/** A key typed at a terminal, not echoed. */
+function promptHidden(io, question) {
+  return new Promise((resolve, reject) => {
+    const input = io.stdin;
+    io.stderr.write(question);
+    input.setRawMode?.(true);
+    input.setEncoding?.("utf8");
+    input.resume();
+    let value = "";
+    const finish = (error) => {
+      input.setRawMode?.(false);
+      input.pause();
+      input.off("data", onData);
+      io.stderr.write("\n");
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const onData = (chunk) => {
+      for (const char of String(chunk)) {
+        if (char === "\r" || char === "\n") return finish();
+        if (char === "\u0003") return finish(new CliError(EXIT.usage, "Cancelled; nothing was saved."));
+        if (char === "\u007f" || char === "\b") value = value.slice(0, -1);
+        else value += char;
+      }
+    };
+    input.on("data", onData);
+  });
+}
+
+/** y/N at a terminal. */
+async function confirm(io, question) {
+  const rl = createInterface({ input: io.stdin, output: io.stderr });
+  const answer = await new Promise((resolve) => rl.question(`${question} [y/N] `, resolve));
+  rl.close();
+  return /^y(es)?$/i.test(String(answer).trim());
+}
+
+const slug = (text) =>
+  String(text ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+
+export function defaultProfileName(me) {
+  const project = slug(me?.tenant?.name) || slug(me?.tenant?.id) || "capa";
+  return `${project}-${slug(me?.environment) || "key"}`;
+}
+
+const mask = (prefix) => (prefix ? `${prefix}...` : "prefix not reported");
+
+async function login(io, out, credentials, flags) {
+  let key;
+  if (flags.keyStdin) key = await io.readStdin();
+  else if (io.isTTY) key = await promptHidden(io, "Paste a Capa key (Developers > Keys): ");
+  key = String(key ?? "").trim();
+  if (!key) {
+    throw new CliError(
+      EXIT.usage,
+      "No key given. Pipe it in (capa login --key-stdin < key.txt, or printf %s \"$CAPA_KEY\" | capa login --key-stdin), or run capa login in a terminal to paste it. A key is never taken as an argument, where the process list shows it.",
+    );
+  }
+  const apiUrl = (flags.apiUrl || io.env.CAPA_API_URL || DEFAULT_API_URL).replace(/\/+$/, "");
+  const family = keyFamily(key);
+  if (family === "legacy" && !flags.tenantId) {
+    throw new CliError(EXIT.usage, "That is a legacy key (pk_, sk_ or no prefix), which also needs --tenant-id <project id>. A cap_ key from Developers > Keys needs nothing else.");
+  }
+  const uploadUrl = typeof flags.uploadUrl === "string" ? flags.uploadUrl.trim().replace(/\/+$/, "") : "";
+  const config = configFrom({
+    CAPA_API_URL: apiUrl,
+    CAPA_KEY: key,
+    CAPA_TENANT_ID: flags.tenantId ?? "",
+    CAPA_API_VERSION: flags.apiVersion ?? "",
+    CAPA_UPLOAD_URL: uploadUrl,
+  });
+  const { me, uploads } = await whoAmIAndUploads(config);
+  if (!me) throw new CliError(EXIT.refused, `${apiUrl}/api/me answered without describing the key. Nothing was saved.`);
+  const name = typeof flags.profile === "string" && flags.profile ? flags.profile : defaultProfileName(me);
+  let saved;
+  try {
+    saved = credentials.add(
+      name,
+      {
+        apiUrl,
+        family,
+        project: me.tenant ? { id: me.tenant.id, name: me.tenant.name ?? null } : null,
+        environment: me.environment ?? null,
+        keyPrefix: me.keyPrefix ?? null,
+        ...(flags.tenantId ? { tenantId: flags.tenantId } : {}),
+        ...(flags.apiVersion ? { apiVersion: flags.apiVersion } : {}),
+        ...(uploadUrl ? { uploadUrl } : {}),
+      },
+      key,
+    );
+  } catch (error) {
+    throw new CliError(error.exitCode ?? EXIT.config, `${error.message} Nothing was saved.`);
+  }
+  const sees = keySees(me, { uploads });
+  out.answer(
+    out.json
+      ? { profile: name, project: me.tenant ?? null, environment: me.environment ?? null, keyPrefix: me.keyPrefix ?? null, apiUrl, store: saved.store, sees }
+      : [
+          `Logged in to ${me.tenant?.name ? `"${me.tenant.name}"` : "the project"} with a ${me.environment ?? ""} key (${mask(me.keyPrefix)}) as profile ${name}.`,
+          `The key is in ${saved.where}. ${credentials.file} holds the profile and nothing secret.`,
+          sees,
+        ]
+          .filter(Boolean)
+          .join("\n"),
+  );
+  return EXIT.ok;
+}
+
+async function logout(io, out, credentials, flags) {
+  const { current, profiles } = credentials.list();
+  const names = flags.all ? profiles.map((p) => p.name) : [flags.profile || io.env.CAPA_PROFILE || current].filter(Boolean);
+  if (!names.length) throw new CliError(EXIT.config, "Not logged in: there is nothing to forget.");
+  const removed = names.map((name) => credentials.remove(name)).filter(Boolean);
+  if (!removed.length) throw new CliError(EXIT.config, `No profile ${names.join(", ")}.`);
+  out.answer(out.json ? { removed: removed.map((r) => r.name) } : removed.map((r) => `Forgot profile ${r.name} and deleted its key.`).join("\n"));
+  return EXIT.ok;
+}
+
+async function whoami(io, out, credentials, flags) {
+  const resolved = resolveEnv(io, credentials, flags.profile);
+  const config = configFrom(resolved.env, io);
+  const { me, uploads } = await whoAmIAndUploads(config);
+  const sees = keySees(me, { uploads });
+  const doc = {
+    profile: resolved.profile?.name ?? null,
+    source: resolved.source === "env" ? "CAPA_KEY" : "profile",
+    apiUrl: config.baseUrl,
+    project: me?.tenant ?? null,
+    environment: me?.environment ?? null,
+    keyPrefix: me?.keyPrefix ?? null,
+    scopes: me?.scopes ?? [],
+    surfaces: me?.surfaces ?? [],
+    reads: me?.environment === "production" ? "published" : "drafts",
+    sees,
+  };
+  out.answer(
+    out.json
+      ? doc
+      : [
+          `${doc.project?.name ? `"${doc.project.name}"` : "Project"} (${doc.project?.id ?? "unknown id"}) at ${doc.apiUrl}`,
+          `A ${doc.environment} key (${mask(doc.keyPrefix)}), from ${doc.source === "CAPA_KEY" ? "CAPA_KEY in the environment" : `profile ${doc.profile}`}.`,
+          `Scopes: ${doc.scopes.join(", ") || "none listed"}.`,
+          `Surfaces: ${doc.surfaces.join(", ") || "not reported"}.`,
+          sees,
+        ].join("\n"),
+  );
+  return EXIT.ok;
+}
+
+async function projects(io, out, credentials, positionals) {
+  if (positionals[0] === "use") {
+    if (!positionals[1]) throw new CliError(EXIT.usage, "capa projects use <profile>: name the profile.");
+    try {
+      credentials.use(positionals[1]);
+    } catch (error) {
+      throw new CliError(error.exitCode ?? EXIT.config, error.message);
+    }
+    out.answer(out.json ? { current: positionals[1] } : `Now using profile ${positionals[1]}.`);
+    return EXIT.ok;
+  }
+  if (positionals.length) throw new CliError(EXIT.usage, `capa projects takes no argument but use <profile>, not ${positionals[0]}.`);
+  const { current, profiles } = credentials.list();
+  if (out.json) {
+    out.answer({ current, profiles: profiles.map(({ name, project, environment, keyPrefix, apiUrl, store }) => ({ name, current: name === current, project, environment, keyPrefix, apiUrl, store })) });
+    return EXIT.ok;
+  }
+  if (!profiles.length) {
+    out.answer("No profiles yet. capa login adds one.");
+    return EXIT.ok;
+  }
+  out.answer(
+    profiles
+      .map((p) => `${p.name === current ? "*" : " "} ${p.name}  ${p.project?.name ?? p.project?.id ?? ""}  ${p.environment ?? ""}  ${mask(p.keyPrefix)}  ${p.apiUrl}  (${p.store})`)
+      .join("\n"),
+  );
+  return EXIT.ok;
+}
+
+async function listTools(io, out, credentials, flags) {
+  const session = await openSession(io, credentials, flags.profile);
+  for (const note of session.notes) out.note(note.replace(/^capa-mcp: /, "capa: "));
+  const tools = session.ctx.tools.map((t) => ({ name: t.name, title: t.annotations?.title ?? t.title ?? null, writes: t.annotations?.readOnlyHint === false }));
+  out.answer(out.json ? { tools } : tools.map((t) => `${t.name}${t.writes ? "  (writes)" : ""}  ${t.title ?? ""}`).join("\n"));
+  return EXIT.ok;
+}
+
+async function runToolCommand(io, out, credentials, positionals, flags) {
+  const [name, ...extra] = positionals;
+  if (!name) throw new CliError(EXIT.usage, "capa tool <name>: name the tool. capa tools lists them.");
+  if (extra.length) throw new CliError(EXIT.usage, `capa tool takes one tool name; ${extra.join(" ")} is extra. Pass arguments as --flags or --args.`);
+  if (!TOOLS_BY_NAME.has(name)) {
+    const near = TOOLS.map((t) => t.name).filter((n) => n.includes(name.replace(/^capa_/, "")) || name.includes(n.replace(/^capa_/, "")));
+    throw new CliError(EXIT.usage, `No tool ${name}.${near.length ? ` Did you mean ${near.join(" or ")}?` : ""} capa tools lists the ones this key is offered.`);
+  }
+  let base = {};
+  if (flags.args !== undefined) {
+    const text = flags.args === "-" ? await io.readStdin() : String(flags.args).startsWith("@") ? fs.readFileSync(String(flags.args).slice(1), "utf8") : flags.args;
+    try {
+      base = JSON.parse(text);
+    } catch (error) {
+      throw new CliError(EXIT.usage, `--args is not JSON: ${error.message}.`);
+    }
+    if (!base || typeof base !== "object" || Array.isArray(base)) throw new CliError(EXIT.usage, "--args is one JSON object of the tool's arguments.");
+    if (flags.args === "-") io.stdinUsed = true;
+  }
+  const args = await toolArgs(name, base, flags, io, { reserved: new Set([...RESERVED, "args"]) });
+  const session = await openSession(io, credentials, flags.profile);
+  return runAndPrint(out, session, name, args);
+}
+
+async function content(io, out, credentials, command, rest, flags) {
+  const required = command.positionals.filter((p) => !p.endsWith("?")).length;
+  if (rest.length < required || rest.length > command.positionals.length) {
+    throw new CliError(EXIT.usage, `usage: ${command.usage}`);
+  }
+  const session = await openSession(io, credentials, flags.profile);
+  const { tool, args: base } = command.pick(rest, (name) => offered(session, name));
+  const args = await toolArgs(tool, base, flags, io, { reserved: RESERVED });
+  return runAndPrint(out, session, tool, args);
+}
+
+async function mcp(io, out, credentials, flags) {
+  const resolved = resolveEnv(io, credentials, flags.profile);
+  const config = configFrom(resolved.env, io);
+  const { ctx, notes } = await connect(config);
+  for (const note of notes) io.stderr.write(`${note}\n`);
+  await serveStdio(ctx, { input: io.stdin, output: io.stdout, error: io.stderr, exit: io.exit });
+  return null;
+}
+
+async function init(io, out, credentials, positionals, flags) {
+  const [client, ...extra] = positionals;
+  if (!CLIENTS.includes(client) || extra.length) throw new CliError(EXIT.usage, `usage: ${LOCAL_COMMANDS.init.usage}`);
+  const plan = planInit(client, io, flags);
+  let me = null;
+  let uploads = null;
+  let whoNote = null;
+  try {
+    const resolved = resolveEnv(io, credentials, flags.profile);
+    ({ me, uploads } = await whoAmIAndUploads(configFrom(resolved.env, io)));
+    whoNote = `capa mcp will use ${resolved.source === "env" ? "CAPA_KEY from its environment" : `profile ${resolved.profile.name}`}: ${me?.tenant?.name ? `"${me.tenant.name}", ` : ""}a ${me?.environment} key. ${keySees(me, { uploads }) ?? ""}`;
+  } catch (error) {
+    if (flags.instructions) throw new CliError(error.exitCode ?? EXIT.config, `--instructions names the models, so it needs a key that works: ${error.message}`);
+    whoNote = `Run capa login before starting ${client}: capa mcp needs a key (${error.message})`;
+  }
+  const steps = [...plan.steps, ...(flags.instructions ? [planInstructions(client, io, me, keySees(me, { uploads }))] : [])];
+  const changes = showPlan(out, steps);
+  const report = (written) =>
+    out.answer(
+      out.json
+        ? { client, server: plan.server, written, steps: steps.map((s) => (s.run ? { run: s.run } : { file: s.file, ...(s.target ? { target: s.target } : {}), created: s.created, changed: s.before !== s.after })), note: whoNote }
+        : written
+          ? `Done. ${whoNote}`
+          : whoNote,
+    );
+  if (!changes) {
+    report(false);
+    return EXIT.ok;
+  }
+  if (flags.dryRun) {
+    out.note("Dry run: nothing was written.");
+    report(false);
+    return EXIT.ok;
+  }
+  if (!flags.yes) {
+    if (!io.isTTY) throw new CliError(EXIT.usage, "Nothing was written. Pass --yes to make this change, or --dry-run to only show it.");
+    if (!(await confirm(io, "Make this change?"))) {
+      out.note("Nothing was written.");
+      return EXIT.usage;
+    }
+  }
+  applyPlan(steps, io);
+  report(true);
+  return EXIT.ok;
+}
+
+/**
+ * Runs `capa <argv>`. Answers the exit code, or null when the command keeps
+ * the process (`capa mcp`) and exits on its own.
+ */
+export async function main(argv, given = {}) {
+  const io = {
+    env: given.env ?? process.env,
+    stdin: given.stdin ?? process.stdin,
+    stdout: given.stdout ?? process.stdout,
+    stderr: given.stderr ?? process.stderr,
+    cwd: given.cwd ?? process.cwd(),
+    run: given.run ?? systemRunner,
+    platform: given.platform ?? process.platform,
+    exit: given.exit ?? ((code) => process.exit(code)),
+    sdkBin: given.sdkBin,
+  };
+  io.isTTY = given.isTTY ?? Boolean(io.stdin.isTTY);
+  io.readStdin = () => readAll(io.stdin);
+
+  // codegen and persist are the SDK's, and get their arguments exactly as typed.
+  if (SDK_COMMANDS.has(argv[0])) {
+    const out = createOutput(io, { json: false });
+    try {
+      return runSdk(argv[0], argv.slice(1), io);
+    } catch (error) {
+      return out.fail(error);
+    }
+  }
+
+  // The command's words decide which of its flags take no value, so find them first.
+  const words = [];
+  for (let i = 0; i < argv.length && words.length < 2; i++) {
+    if (argv[i] === "--profile") i++;
+    else if (!argv[i].startsWith("-")) words.push(argv[i]);
+    else if (words.length) break;
+  }
+  const found = findCommand(words);
+  const local = LOCAL_COMMANDS[words[0]];
+  let booleans = new Set(local?.booleans ?? []);
+  if (found) booleans = booleanFlags(found.command.tools);
+  if (words[0] === "tool" && words[1]) booleans = booleanFlags([words[1]]);
+
+  let parsed;
+  try {
+    parsed = parseArgv(argv, { booleans });
+  } catch (error) {
+    return createOutput(io, { json: argv.includes("--json") }).fail(error);
+  }
+  const { flags } = parsed;
+  const out = createOutput(io, { json: Boolean(flags.json) });
+  const credentials = createCredentials({ env: io.env, platform: io.platform, run: io.run });
+
+  try {
+    if (flags.version && !parsed.positionals.length) {
+      out.answer(out.json ? { version: VERSION } : VERSION);
+      return EXIT.ok;
+    }
+    const [name, ...rest] = parsed.positionals;
+    if (!name || name === "help") {
+      const topic = rest.length ? findCommand(rest)?.command ?? null : null;
+      out.answer(rest.length ? commandHelp(rest[0], topic) : HELP());
+      return name || flags.help ? EXIT.ok : EXIT.usage;
+    }
+    if (flags.help) {
+      out.answer(commandHelp(name, found?.command ?? null));
+      return EXIT.ok;
+    }
+    if (found) return await content(io, out, credentials, found.command, parsed.positionals.slice(found.command.words.length), flags);
+    switch (name) {
+      case "login":
+        return await login(io, out, credentials, flags);
+      case "logout":
+        return await logout(io, out, credentials, flags);
+      case "whoami":
+        return await whoami(io, out, credentials, flags);
+      case "projects":
+        return await projects(io, out, credentials, rest);
+      case "tools":
+        return await listTools(io, out, credentials, flags);
+      case "tool":
+        return await runToolCommand(io, out, credentials, rest, flags);
+      case "mcp":
+        return await mcp(io, out, credentials, flags);
+      case "init":
+        return await init(io, out, credentials, rest, flags);
+      case "entries":
+      case "media":
+        throw new CliError(EXIT.usage, `capa ${name} ${rest[0] ?? ""}: unknown. ${COMMANDS.filter((c) => c.words[0] === name).map((c) => c.usage.split(" ").slice(0, 3).join(" ")).join(", ") || "capa help lists the commands."}`);
+      default:
+        throw new CliError(EXIT.usage, `Unknown command ${name}. capa help lists the commands.`);
+    }
+  } catch (error) {
+    if (!(error instanceof CliError) && typeof error?.exitCode !== "number") {
+      // A bug, not a refusal: say so plainly, with the stack where a person can find it.
+      if (io.env.CAPA_DEBUG) io.stderr.write(`${error?.stack ?? error}\n`);
+      return out.fail(new CliError(EXIT.refused, `${error?.message ?? error}`));
+    }
+    return out.fail(error);
+  }
+}

package/lib/output.mjs

@@ -0,0 +1,59 @@
+/**
+ * output.mjs — exit codes, errors, and what goes to stdout and stderr.
+ *
+ * With --json, stdout carries exactly one JSON document and nothing else: the
+ * answer, or `{ "error": { "message", "exitCode", ... } }`. Without it, an
+ * answer is printed as indented JSON (answers are documents, and a table would
+ * drop fields), and errors and notes go to stderr. Either way the exit code
+ * says what happened, so a script never has to parse a sentence.
+ */
+
+/** The documented exit codes (docs/cli.md, `capa help`). */
+export const EXIT = Object.freeze({
+  ok: 0,
+  /** The API refused the request, or answered with an in-band `{ error }`. */
+  refused: 1,
+  /** A usage error: an unknown command or flag, a missing or invalid argument, or a write that needs --yes. */
+  usage: 2,
+  /** No credentials, a key the API does not know, or a config file that cannot be used. */
+  config: 3,
+  /** The tool behind the command is not offered for this key on this deployment. */
+  notOffered: 4,
+  /** Capa did not answer: unreachable, or no answer in time. */
+  unreachable: 5,
+});
+
+export class CliError extends Error {
+  constructor(exitCode, message, details = {}) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+
+export function createOutput(io, { json }) {
+  const write = (stream, text) => stream.write(text.endsWith("\n") ? text : `${text}\n`);
+  return {
+    json,
+    /** The command's answer, on stdout. */
+    answer(value) {
+      write(io.stdout, json ? JSON.stringify(value) : typeof value === "string" ? value : JSON.stringify(value, null, 2));
+    },
+    /** A line for a person (never in --json mode, where stdout is the document). */
+    say(text) {
+      if (!json) write(io.stdout, text);
+    },
+    /** A line on stderr, in either mode: progress, notes, warnings. */
+    note(text) {
+      write(io.stderr, text);
+    },
+    fail(error) {
+      const exitCode = error instanceof CliError || typeof error?.exitCode === "number" ? error.exitCode : EXIT.refused;
+      const details = error instanceof CliError ? error.details : {};
+      if (json) write(io.stdout, JSON.stringify({ error: { message: error.message, exitCode, ...details } }));
+      else write(io.stderr, `capa: ${error.message}`);
+      return exitCode;
+    },
+  };
+}

package/lib/sdk.mjs

@@ -0,0 +1,47 @@
+/**
+ * sdk.mjs — `capa codegen` and `capa persist` are @capacms/sdk's, run as is.
+ *
+ * Both packages ship a `capa` bin. Rather than fight over the name, each
+ * hands the other's commands across: this CLI runs the project's own SDK bin
+ * for codegen and persist, with the same arguments, the same output and the
+ * same exit codes, and the SDK's bin hands every other command to this CLI
+ * when the project has it. So whichever `capa` a package manager links,
+ * every command does the same thing.
+ *
+ * The SDK is resolved from the working directory, the project's own
+ * node_modules, since codegen writes types for the SDK version the project
+ * builds with.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+import { CliError, EXIT } from "./output.mjs";
+
+export const SDK_COMMANDS = new Set(["codegen", "persist"]);
+
+/** The project's @capacms/sdk `capa` bin, or null. */
+export function sdkBin(cwd) {
+  try {
+    const require = createRequire(path.join(cwd, "package.json"));
+    const manifest = require.resolve("@capacms/sdk/package.json");
+    const bin = JSON.parse(fs.readFileSync(manifest, "utf8")).bin?.capa;
+    return bin ? path.join(path.dirname(manifest), bin) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Runs `capa <command> ...args` from the project's SDK. Answers its exit code. */
+export function runSdk(command, args, io) {
+  const bin = (io.sdkBin ?? sdkBin)(io.cwd);
+  if (!bin) {
+    throw new CliError(
+      EXIT.config,
+      `capa ${command} comes from @capacms/sdk, which this project does not have. Install it (npm i @capacms/sdk), then run capa ${command} again.`,
+    );
+  }
+  const result = spawnSync(process.execPath, [bin, command, ...args], { cwd: io.cwd, env: io.env, stdio: "inherit" });
+  if (result.error) throw new CliError(EXIT.config, `could not run ${bin}: ${result.error.message}`);
+  return result.status ?? 1;
+}