@capacms/cli 0.0.0-stage → 0.1.0

package/lib/init.mjs

@@ -0,0 +1,365 @@
+/**
+ * init.mjs — `capa init claude|codex|cursor`: register `capa mcp` with an
+ * agent, in that agent's own config format, and nothing else in the file.
+ *
+ * What each writes (checked against each client's docs and its installed CLI
+ * on 2026-10-02: Claude Code 2.1.288, Codex 0.159.3, Cursor Agent 2026.01.23):
+ *
+ *   claude   ./.mcp.json, `mcpServers.capa` = { type: "stdio", command, args },
+ *            which `claude` loads for this project (and asks once before
+ *            trusting). --scope user or local runs `claude mcp add-json`
+ *            instead, since those scopes live in Claude's own ~/.claude.json.
+ *   codex    $CODEX_HOME/config.toml (~/.codex/config.toml), the section
+ *            `[mcp_servers.capa]`; --project writes ./.codex/config.toml,
+ *            which Codex reads for trusted projects only.
+ *   cursor   ./.cursor/mcp.json, `mcpServers.capa` = { type: "stdio", command, args };
+ *            --global writes ~/.cursor/mcp.json.
+ *
+ * NO KEY IS EVER WRITTEN. The server is `capa mcp`, which reads the key
+ * `capa login` stored in the keychain (or CAPA_KEY from its environment), so a
+ * config file holds a command and nothing secret, and a project file is safe
+ * to commit. Codex starts servers with a cleared environment, so its section
+ * lists the CAPA_ variables it may pass through (`env_vars`): names, never
+ * values. Cursor passes HOME and PATH and none of the CAPA_ variables, and
+ * this version of cursor-agent sends `${env:NAME}` through as those literal
+ * characters, so its entry carries no `env` at all: `capa mcp` there reads the
+ * saved profile, which `--profile` can pin in the arguments.
+ *
+ * Every other server in the file is kept, and the file's own formatting with
+ * it where the format allows (TOML is edited by lines; JSON is re-printed with
+ * two-space indentation). The change is printed first, as a diff, and written
+ * only with --yes or a "y" at the prompt; --dry-run prints and stops.
+ *
+ * A config file that is a symlink is written through, and the plan names the
+ * file the link points at. A file in the project (.mcp.json, .codex/,
+ * .cursor/, CLAUDE.md, AGENTS.md) must land in the project: a cloned
+ * repository can carry a link to any file of the person's, so one whose link
+ * or folder points outside it is refused before it is read.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { lineDiff } from "./diff.mjs";
+import { CliError, EXIT } from "./output.mjs";
+import { setServerSection, tomlArray, tomlString } from "./toml.mjs";
+
+export const CLIENTS = ["claude", "codex", "cursor"];
+
+/**
+ * The CAPA_ variables Codex may hand to `capa mcp`. It starts an MCP server
+ * with only HOME, PATH, USER and a few others, so without these a key in the
+ * environment, a profile choice or a config dir would not arrive.
+ */
+export const CODEX_ENV_VARS = [
+  "CAPA_KEY",
+  "CAPA_API_URL",
+  "CAPA_API_VERSION",
+  "CAPA_TENANT_ID",
+  "CAPA_PROFILE",
+  "CAPA_CONFIG_DIR",
+  "XDG_CONFIG_HOME",
+  "CAPA_CREDENTIAL_STORE",
+  "CAPA_KEYCHAIN",
+  "CAPA_UPLOAD_URL",
+  "CAPA_UPLOAD_ROOT",
+  "CAPA_UPLOAD_ALLOW",
+];
+
+/**
+ * Tools a headless Codex run must still ask about when --approve lets it run
+ * the rest: a publish changes what the site shows, and an upload sends a file
+ * from this machine to the project's media.
+ */
+export const ASK_BEFORE = ["capa_publish_entry", "capa_unpublish_entry", "capa_upload_media"];
+
+/**
+ * A PATH entry that is there only for this run: npx's temporary install
+ * (`.../_npx/<hash>/node_modules/.bin`) and `npm run`'s project bin. A
+ * `capa` found there is gone, or off PATH, when an agent starts the server.
+ */
+function borrowedBin(dir) {
+  const parts = path.resolve(dir).split(path.sep);
+  return parts.includes("_npx") || (parts.at(-1) === ".bin" && parts.at(-2) === "node_modules");
+}
+
+/** An executable `name` on `PATH`, skipping the entries npx and npm run add for one run, or null. */
+function onPath(name, env) {
+  const exts = process.platform === "win32" ? (env.PATHEXT || ".CMD;.EXE").split(";") : [""];
+  for (const dir of String(env.PATH || "").split(path.delimiter).filter(Boolean)) {
+    if (borrowedBin(dir)) continue;
+    for (const ext of exts) {
+      const candidate = path.join(dir, `${name}${ext}`);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch {
+        // not here
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The command a client runs: --command when given, else `capa` when a global
+ * install put it on PATH, else `npx -y @capacms/cli`, which fetches it.
+ */
+export function serverCommand(io, flags) {
+  const args = ["mcp", ...(flags.profile ? ["--profile", flags.profile] : [])];
+  if (typeof flags.command === "string" && flags.command) return { command: flags.command, args };
+  if (onPath("capa", io.env)) return { command: "capa", args };
+  return { command: "npx", args: ["-y", "@capacms/cli", ...args] };
+}
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw new CliError(EXIT.config, `could not read ${file}: ${error.message}`);
+  }
+}
+
+/** `text` with `mcpServers[name]` set to `entry`, every other key kept in its place. */
+export function mergeMcpJson(text, name, entry, file) {
+  let doc = {};
+  if (text && text.trim()) {
+    try {
+      doc = JSON.parse(text);
+    } catch (error) {
+      throw new CliError(EXIT.config, `${file} is not plain JSON (${error.message}), so it is left alone. Add this under "mcpServers" by hand: "${name}": ${JSON.stringify(entry)}`);
+    }
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw new CliError(EXIT.config, `${file} is not a JSON object, so it is left alone.`);
+  if (doc.mcpServers !== undefined && (typeof doc.mcpServers !== "object" || doc.mcpServers === null || Array.isArray(doc.mcpServers))) {
+    throw new CliError(EXIT.config, `${file} has an "mcpServers" that is not an object, so it is left alone.`);
+  }
+  const next = { ...doc, mcpServers: { ...(doc.mcpServers ?? {}), [name]: entry } };
+  return `${JSON.stringify(next, null, 2)}\n`;
+}
+
+/** The Codex section: the server, the variables it may receive, and with --approve which tools still ask. */
+export function codexSection(name, server, { approve = false } = {}) {
+  const lines = [
+    `[mcp_servers.${name}]`,
+    `command = ${tomlString(server.command)}`,
+    `args = ${tomlArray(server.args)}`,
+    `env_vars = ${tomlArray(CODEX_ENV_VARS)}`,
+  ];
+  if (approve) {
+    lines.push(`default_tools_approval_mode = "approve"`);
+    for (const tool of ASK_BEFORE) lines.push("", `[mcp_servers.${name}.tools.${tool}]`, `approval_mode = "prompt"`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * What `capa init <client>` would change: a list of steps, each a file write
+ * (`{ file, before, after }`) or a command to run (`{ run: [cmd, ...args] }`).
+ * Pure apart from reading the files it would change.
+ */
+export function planInit(client, io, flags) {
+  const name = typeof flags.name === "string" && flags.name ? flags.name : "capa";
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new CliError(EXIT.usage, `--name ${name}: use letters, digits, dashes and underscores.`);
+  const server = serverCommand(io, flags);
+  const home = io.env.HOME || os.homedir();
+  if (client === "claude") {
+    const scope = flags.scope ?? "project";
+    if (!["project", "user", "local"].includes(scope)) throw new CliError(EXIT.usage, `--scope ${scope}: Claude Code's scopes are project, user and local.`);
+    const entry = { type: "stdio", command: server.command, args: server.args };
+    if (scope !== "project") {
+      return {
+        name,
+        server,
+        steps: [
+          { run: ["claude", "mcp", "remove", name, "--scope", scope], quiet: true, why: `drops an earlier ${name} server in that scope, if there is one` },
+          { run: ["claude", "mcp", "add-json", name, JSON.stringify(entry), "--scope", scope] },
+        ],
+      };
+    }
+    const file = path.join(io.cwd, ".mcp.json");
+    return { name, server, steps: [fileStep(file, io.cwd, (before) => mergeMcpJson(before, name, entry, file))] };
+  }
+  if (client === "codex") {
+    const dir = flags.project ? path.join(io.cwd, ".codex") : io.env.CODEX_HOME || path.join(home, ".codex");
+    const file = path.join(dir, "config.toml");
+    const step = fileStep(file, flags.project ? io.cwd : null, (before) => {
+      try {
+        return setServerSection(before ?? "", name, codexSection(name, server, { approve: Boolean(flags.approve) })).text;
+      } catch (error) {
+        throw new CliError(EXIT.config, `${file}: ${error.message}`);
+      }
+    });
+    return { name, server, steps: [step] };
+  }
+  if (client === "cursor") {
+    const file = flags.global ? path.join(home, ".cursor", "mcp.json") : path.join(io.cwd, ".cursor", "mcp.json");
+    const entry = { type: "stdio", command: server.command, args: server.args };
+    return { name, server, steps: [fileStep(file, flags.global ? null : io.cwd, (before) => mergeMcpJson(before, name, entry, file))] };
+  }
+  throw new CliError(EXIT.usage, `capa init takes ${CLIENTS.join(", ")}${client ? `, not ${client}` : ""}.`);
+}
+
+const START = "<!-- capa:start -->";
+const END = "<!-- capa:end -->";
+
+/** The section `--instructions` writes, between markers so a second run replaces it. */
+export function instructionsSection(me, sees) {
+  const models = (Array.isArray(me?.models) ? me.models : []).map((m) => `\`${m.namespace}\`${Array.isArray(m.can) ? ` (${m.can.join(", ")})` : ""}`);
+  return [
+    START,
+    "## Capa content",
+    "",
+    `This project's content lives in Capa${me?.tenant?.name ? `, in the project "${me.tenant.name}"` : ""}. The \`capa\` MCP server reaches it with the key \`capa login\` stored; the \`capa\` command line takes the same key.`,
+    "",
+    models.length ? `Models this key reaches: ${models.join(", ")}.` : "Run `capa models` for the models this key reaches.",
+    "",
+    "- Before writing an entry, read the model: `capa_get_model { namespace }` names its fields.",
+    "- `capa_create_entry` and `capa_update_entry` save drafts. Read the result back with `capa_read_entries { model, id }`.",
+    "- Publish (`capa_publish_entry`) only when asked to. It changes what the site shows.",
+    sees ? `- ${sees}` : null,
+    "- From a shell: `capa entries list <model> --json`, `capa entries create <model> --data '{...}' --json`.",
+    END,
+    "",
+  ]
+    .filter((line) => line !== null)
+    .join("\n");
+}
+
+/** `text` with the capa section set to `section`: replaced between its markers, else appended. */
+export function setInstructions(text, section) {
+  const body = text ?? "";
+  const start = body.indexOf(START);
+  const end = body.indexOf(END);
+  if (start !== -1 && end > start) return `${body.slice(0, start)}${section.replace(/\n$/, "")}${body.slice(end + END.length)}`;
+  const trimmed = body.replace(/\s*$/, "");
+  return `${trimmed}${trimmed ? "\n\n" : ""}${section}`;
+}
+
+/** The step that writes the instructions file: CLAUDE.md for Claude Code, AGENTS.md for Codex and Cursor. */
+export function planInstructions(client, io, me, sees) {
+  const file = path.join(io.cwd, client === "claude" ? "CLAUDE.md" : "AGENTS.md");
+  return fileStep(file, io.cwd, (before) => setInstructions(before, instructionsSection(me, sees)));
+}
+
+/** Prints the plan. Answers whether there is anything to do. */
+export function showPlan(out, steps) {
+  let changes = 0;
+  for (const step of steps) {
+    if (step.run) {
+      changes++;
+      out.note(`Will run: ${step.run.map((a) => (/^[\w./:@=-]+$/.test(a) ? a : `'${a.replace(/'/g, "'\\''")}'`)).join(" ")}${step.why ? `  (${step.why})` : ""}`);
+      continue;
+    }
+    const shown = step.target ? `${step.file} (a link to ${step.target})` : step.file;
+    if (step.before === step.after) {
+      out.note(`${shown}: already set up, no change.`);
+      continue;
+    }
+    changes++;
+    out.note(`${shown}${step.created ? " (new file)" : ""}:`);
+    out.note(lineDiff(step.before, step.after));
+  }
+  return changes > 0;
+}
+
+/**
+ * The file a write lands in: `file` itself, or, when it is a symlink (a
+ * dotfiles repo linking ~/.codex/config.toml), the file the link points at,
+ * so the link stays a link. A link to a file not made yet resolves too.
+ */
+function writeTarget(file) {
+  let target = file;
+  for (let hops = 0; hops < 32; hops++) {
+    let stat;
+    try {
+      stat = fs.lstatSync(target);
+    } catch (error) {
+      if (error.code === "ENOENT") return target;
+      throw error;
+    }
+    if (!stat.isSymbolicLink()) return target;
+    // Relative to the folder the link is in, as the disk has it (that folder may be a link too).
+    target = path.resolve(fs.realpathSync.native(path.dirname(target)), fs.readlinkSync(target));
+  }
+  throw new CliError(EXIT.config, `${file} is a symlink that loops, so it is left alone.`);
+}
+
+/** Where a write to `file` lands: through its links, and through links among the folders on the way. */
+function landsAt(file) {
+  const target = writeTarget(file);
+  let dir = path.dirname(target);
+  let rest = path.basename(target);
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync.native(dir), rest);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const up = path.dirname(dir);
+      if (up === dir) return target;
+      rest = path.join(path.basename(dir), rest);
+      dir = up;
+    }
+  }
+}
+
+/** Is `inner` the folder `outer`, or inside it? */
+const within = (inner, outer) => {
+  const relative = path.relative(outer, inner);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+/**
+ * The step that writes `file`, its new text made by `after(before)`. `target`
+ * is set when the file is a link, and the plan prints it. A file of the project (`project` is its folder)
+ * whose write lands outside the project is refused before it is read: a
+ * cloned repository can link .mcp.json to any file of the person's, which
+ * would be printed as a diff and then written.
+ */
+function fileStep(file, project, after) {
+  const lands = landsAt(file);
+  if (project && !within(lands, fs.realpathSync.native(project))) {
+    throw new CliError(
+      EXIT.config,
+      `${file} points outside this project, to ${lands}, so capa init leaves it alone: a link in a project can point at any of your files. Remove the link, or add the server to ${lands} yourself.`,
+    );
+  }
+  const before = readText(file);
+  const linked = writeTarget(file) !== file;
+  return { file, ...(linked ? { target: lands } : {}), before: before ?? "", after: after(before), created: before === null };
+}
+
+/** Writes each file (keeping an existing file's mode, and writing through a symlink) and runs each command. */
+export function applyPlan(steps, io) {
+  const done = [];
+  for (const step of steps) {
+    if (step.run) {
+      const [command, ...args] = step.run;
+      const result = io.run(command, args);
+      if (result.error) {
+        if (step.quiet) continue;
+        throw new CliError(EXIT.config, `could not run ${command}: ${result.error.code === "ENOENT" ? `${command} is not on PATH` : result.error.message}.`);
+      }
+      if (result.status !== 0 && !step.quiet) {
+        throw new CliError(EXIT.refused, `${command} ${args.slice(0, 2).join(" ")} failed: ${(result.stderr || result.stdout).trim()}`);
+      }
+      done.push({ ran: step.run.slice(0, 3).join(" ") });
+      continue;
+    }
+    if (step.before === step.after) continue;
+    fs.mkdirSync(path.dirname(step.file), { recursive: true });
+    const file = writeTarget(step.file);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    let mode = 0o644;
+    try {
+      mode = fs.statSync(file).mode & 0o777;
+    } catch {
+      // new file
+    }
+    const temp = `${file}.capa-${process.pid}.tmp`;
+    fs.writeFileSync(temp, step.after, { mode });
+    fs.renameSync(temp, file);
+    done.push({ wrote: step.file });
+  }
+  return done;
+}