@capacms/cli 0.0.0-stage → 0.1.0

package/lib/session.mjs

@@ -0,0 +1,216 @@
+/**
+ * session.mjs — from "which key" to a tool's answer and an exit code.
+ *
+ * Which key: CAPA_KEY (or CAPA_API_KEY) in the environment wins, so CI and
+ * an agent's own env work with nothing saved. Otherwise the profile named by
+ * --profile, else CAPA_PROFILE, else the one `capa login` made current. The
+ * API address is CAPA_API_URL when set, else the profile's.
+ *
+ * Every content command then does what the MCP server does at startup
+ * (`connect`: `/api/me` and the deployment probes) and runs ONE tool through
+ * `runTool`, the function the server's `tools/call` runs. So a command
+ * answers what the tool answers, with the same argument checks and the same
+ * refusals; only the exit code is the CLI's own.
+ */
+import {
+  CapaApiError,
+  CapaTimeout,
+  CapaUnreachable,
+  TOOLS_BY_NAME,
+  apiNextGet,
+  connect,
+  keyFamily,
+  loadConfig,
+  probeUploads,
+  runTool,
+} from "@capacms/mcp";
+import { CliError, EXIT } from "./output.mjs";
+
+/** Where `capa login` sends a key when no --api-url names another host: the API, which serves reads and the agent writes. */
+export const DEFAULT_API_URL = "https://api.capacms.com";
+
+/**
+ * The environment `loadConfig` reads, built from the stored profile and the
+ * real environment. `{ env, source, profile }`; throws a CliError (exit 3)
+ * when there is no key at all.
+ */
+export function resolveEnv(io, credentials, profileName) {
+  const real = io.env;
+  const envKey = (real.CAPA_KEY || real.CAPA_API_KEY || "").trim();
+  let profile = null;
+  try {
+    profile = credentials.active(envKey ? null : profileName);
+  } catch (error) {
+    throw new CliError(error.exitCode ?? EXIT.config, error.message);
+  }
+  if (envKey) {
+    const url = real.CAPA_API_URL || real.CAPA_BASE_URL || profile?.meta.apiUrl || DEFAULT_API_URL;
+    return {
+      source: "env",
+      profile: null,
+      env: {
+        CAPA_API_URL: url,
+        CAPA_KEY: envKey,
+        CAPA_TENANT_ID: real.CAPA_TENANT_ID ?? "",
+        CAPA_API_VERSION: real.CAPA_API_VERSION ?? "",
+        ...uploadEnv(io, profile),
+      },
+    };
+  }
+  if (!profile) {
+    throw new CliError(EXIT.config, "Not logged in. Run capa login, or set CAPA_KEY (and CAPA_API_URL) in the environment.");
+  }
+  let secret;
+  try {
+    secret = credentials.secretFor(profile);
+  } catch (error) {
+    throw new CliError(error.exitCode ?? EXIT.config, error.message);
+  }
+  if (!secret) {
+    throw new CliError(EXIT.config, `The key for profile ${profile.name} is gone from ${profile.meta.store === "file" ? "its file" : "the keychain"}. Run capa login again.`);
+  }
+  return {
+    source: "profile",
+    profile,
+    env: {
+      CAPA_API_URL: real.CAPA_API_URL || real.CAPA_BASE_URL || profile.meta.apiUrl,
+      CAPA_KEY: secret,
+      CAPA_TENANT_ID: profile.meta.tenantId ?? "",
+      CAPA_API_VERSION: real.CAPA_API_VERSION || profile.meta.apiVersion || "",
+      ...uploadEnv(io, profile),
+    },
+  };
+}
+
+/**
+ * Where files go and which folder they may be read from: the uploader's
+ * address from the environment, else the one `capa login --upload-url` kept.
+ * The folder is the person's own choice only (CAPA_UPLOAD_ROOT), else the
+ * project Claude Code names (CLAUDE_PROJECT_DIR), else the folder capa runs
+ * in, which `configFrom` passes as `cwd` and which the upload tool refuses
+ * when it is the home folder or holds it (@capacms/mcp media-tools.mjs).
+ */
+function uploadEnv(io, profile) {
+  return {
+    CAPA_UPLOAD_URL: io.env.CAPA_UPLOAD_URL || profile?.meta.uploadUrl || "",
+    CAPA_UPLOAD_ROOT: io.env.CAPA_UPLOAD_ROOT || "",
+    CAPA_UPLOAD_ALLOW: io.env.CAPA_UPLOAD_ALLOW || "",
+    CLAUDE_PROJECT_DIR: io.env.CLAUDE_PROJECT_DIR || "",
+  };
+}
+
+/** `loadConfig`, with its refusals as the CLI's, and with `io` the folder capa runs in and the home folder. */
+export function configFrom(env, io = null) {
+  let config;
+  try {
+    config = loadConfig(env);
+  } catch (error) {
+    throw new CliError(EXIT.config, String(error.message).replace(/^capa-mcp: /, ""));
+  }
+  if (!io) return config;
+  return { ...config, cwd: io.cwd, ...(io.env.HOME ? { home: io.env.HOME } : {}) };
+}
+
+/** The exit code and the CLI's message for a transport or API failure. */
+export function failureOf(error) {
+  if (error instanceof CapaUnreachable || error instanceof CapaTimeout || error?.name === "TimeoutError") return EXIT.unreachable;
+  if (error instanceof CapaApiError && error.status === 401) return EXIT.config;
+  return EXIT.refused;
+}
+
+/**
+ * `whoAmI`, and whether this deployment takes uploads from the key
+ * (`probeUploads`), so what `keySees` says about uploading is what the MCP
+ * server will offer.
+ */
+export async function whoAmIAndUploads(config) {
+  const [who, media] = await Promise.all([whoAmI(config), probeUploads(config)]);
+  return { ...who, uploads: media.uploads };
+}
+
+/** `GET /api/me` for a config: `{ me, meta }`, or a CliError naming why not. */
+export async function whoAmI(config) {
+  try {
+    const body = await apiNextGet(config, "/api/me");
+    return { me: body?.data ?? null, meta: body?.meta ?? null };
+  } catch (error) {
+    const exitCode = failureOf(error);
+    const why =
+      exitCode === EXIT.config
+        ? `The API refused the key (401${error.code ? ` ${error.code}` : ""}). It may be mistyped, deactivated or expired.`
+        : error.message;
+    throw new CliError(exitCode, why, error instanceof CapaApiError ? { status: error.status, code: error.code ?? null } : {});
+  }
+}
+
+/**
+ * What a key reads and may write, in one or two sentences a person acts on.
+ * Uploading is named only where the deployment said it takes uploads from
+ * this key (`uploads`, from `whoAmIAndUploads`); a production key holding
+ * media:create may, as the API has it since #349.
+ */
+export function keySees(me, { uploads = null } = {}) {
+  if (!me) return null;
+  const scopes = Array.isArray(me.scopes) ? me.scopes : [];
+  const holds = (scope) => scopes.some((s) => s === scope || s.startsWith(`${scope}:`) || s === "*:*" || s === `${scope.split(":")[0]}:*`);
+  const reads =
+    me.environment === "production"
+      ? "A production key reads published entries only, exactly what visitors see; a draft it writes shows up in its reads once the entry is published."
+      : `A ${me.environment ?? "development"} key reads drafts and unpublished changes too.`;
+  const writes = [
+    holds("instance:create") && "create drafts",
+    holds("instance:update") && "update drafts",
+    holds("instance:publish") && "publish and unpublish",
+    uploads === true && holds("media:create") && "upload media",
+  ].filter(Boolean);
+  const agent = Array.isArray(me.surfaces) && me.surfaces.includes("/v2/agent");
+  const may = !writes.length
+    ? "It reads only."
+    : agent
+      ? `It may ${writes.join(", ").replace(/, ([^,]*)$/, " and $1")}.`
+      : `Its scopes would let it ${writes.join(", ").replace(/, ([^,]*)$/, " and $1")}, but this deployment does not accept cap_ keys on /v2/agent yet, so the write commands are not offered.`;
+  return `${reads} ${may}`;
+}
+
+/**
+ * A connected session: `{ ctx, me, notes, config, resolved }`. `ctx` is what
+ * `runTool` takes.
+ */
+export async function openSession(io, credentials, profileName) {
+  const resolved = resolveEnv(io, credentials, profileName);
+  const config = configFrom(resolved.env, io);
+  const { ctx, me, notes } = await connect(config);
+  return { ctx, me, notes, config, resolved };
+}
+
+/** Is `name` offered in this session? */
+export const offered = (session, name) => session.ctx.tools.some((tool) => tool.name === name);
+
+/**
+ * Runs one tool and prints its answer. Returns the exit code:
+ * 0 an answer, 1 an in-band `{ error }` or an API refusal, 2 arguments the
+ * tool refused, 3 a key the API does not know, 4 a tool not offered here,
+ * 5 no answer from Capa.
+ */
+export async function runAndPrint(out, session, name, args) {
+  if (!TOOLS_BY_NAME.has(name)) throw new CliError(EXIT.usage, `No tool ${name}. capa tools lists the ones this key is offered.`);
+  const run = await runTool(session.ctx, name, args);
+  if (run.ok) {
+    out.answer(run.answer);
+    const inBand = run.answer && typeof run.answer === "object" && !Array.isArray(run.answer) && "error" in run.answer && run.answer.error;
+    return inBand ? EXIT.refused : EXIT.ok;
+  }
+  if (run.reason === "unknown_tool") {
+    // The startup notes that name this tool say why; the rest are about other tools.
+    const notes = session.notes.map((n) => n.replace(/^capa-mcp: /, "")).map((n) => n[0].toUpperCase() + n.slice(1));
+    const naming = notes.filter((n) => n.includes(name));
+    const why = (naming.length ? naming : notes).map((n) => ` ${n}`).join("");
+    throw new CliError(EXIT.notOffered, `${name} is not offered for this key here.${why}`, { tool: name, family: keyFamily(session.config.apiKey) });
+  }
+  if (run.reason === "invalid_arguments") throw new CliError(EXIT.usage, run.text, { tool: name });
+  const error = run.error;
+  throw new CliError(failureOf(error), run.text, {
+    tool: name,
+    ...(error instanceof CapaApiError ? { status: error.status, code: error.code ?? null } : {}),
+  });
+}

package/lib/toml.mjs

@@ -0,0 +1,100 @@
+/**
+ * toml.mjs — replacing one `[mcp_servers.<name>]` section of a Codex
+ * config.toml, and nothing else.
+ *
+ * Not a TOML parser. Codex's config is a person's file, with their comments,
+ * their other servers and their own order, and a parse-and-print round trip
+ * would rewrite all of it. So this works on lines: the section is its header
+ * and every line up to the next header that is not one of its own subtables
+ * (`[mcp_servers.capa.env]`, `[mcp_servers.capa.tools.x]`). An existing
+ * section is replaced where it stands; a new one is appended. Headers inside a
+ * multi-line string are not headers.
+ *
+ * A server defined any other way (a dotted key `mcp_servers.capa.command = `,
+ * or `capa = { ... }` under `[mcp_servers]`) is refused, not guessed at.
+ */
+
+/** The dotted path of a header's key: `mcp_servers."capa".env` → ["mcp_servers", "capa", "env"]. */
+export function keyPath(key) {
+  const parts = [];
+  let current = "";
+  let quote = null;
+  for (const char of key.trim()) {
+    if (quote) {
+      if (char === quote) quote = null;
+      else current += char;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+    } else if (char === ".") {
+      parts.push(current.trim());
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  parts.push(current.trim());
+  return parts;
+}
+
+const HEADER = /^\s*\[(\[)?\s*(.+?)\s*\]?\]\s*(#.*)?$/;
+
+/** Each line, with the table it belongs to (`null` before the first header) and whether it is a header. */
+function scan(lines) {
+  let table = null;
+  let multiline = null;
+  return lines.map((line) => {
+    if (multiline) {
+      if (line.includes(multiline)) multiline = null;
+      return { line, table, header: false };
+    }
+    const header = HEADER.exec(line);
+    if (header && !line.trim().startsWith("#")) {
+      table = keyPath(header[2]);
+      return { line, table, header: true };
+    }
+    for (const fence of ['"""', "'''"]) {
+      const count = line.split(fence).length - 1;
+      if (count % 2 === 1) multiline = fence;
+    }
+    return { line, table, header: false };
+  });
+}
+
+const within = (table, name) => Array.isArray(table) && table[0] === "mcp_servers" && table[1] === name;
+
+/** A TOML basic string. JSON's escapes are TOML's for every character a path or a command holds. */
+export const tomlString = (value) => JSON.stringify(String(value));
+export const tomlArray = (values) => `[${values.map(tomlString).join(", ")}]`;
+
+/**
+ * `text` with the section for server `name` set to `block` (its header and
+ * body, ending in a newline). `{ text, replaced }`; throws when the server is
+ * defined in a form this cannot edit safely.
+ */
+export function setServerSection(text, name, block) {
+  const lines = text.split("\n");
+  const rows = scan(lines);
+  for (const row of rows) {
+    if (row.header || /^\s*(#|$)/.test(row.line)) continue;
+    const dotted = new RegExp(`^\\s*mcp_servers\\s*\\.\\s*["']?${name}["']?\\s*[.=]`);
+    const inline = new RegExp(`^\\s*["']?${name}["']?\\s*=`);
+    const atRoot = row.table === null || row.table.length === 0;
+    if ((atRoot && dotted.test(row.line)) || (row.table?.length === 1 && row.table[0] === "mcp_servers" && inline.test(row.line))) {
+      throw new Error(`mcp_servers.${name} is defined inline in this file. Remove that definition by hand (or rename it), then run capa init codex again.`);
+    }
+  }
+  const start = rows.findIndex((row) => row.header && within(row.table, name));
+  if (start === -1) {
+    const body = text.replace(/\s*$/, "");
+    return { text: `${body}${body ? "\n\n" : ""}${block}`, replaced: false };
+  }
+  let end = rows.findIndex((row, i) => i > start && row.header && !within(row.table, name));
+  if (end === -1) end = rows.length;
+  // Blank lines and comments right above the next header belong to it, not to the section being replaced.
+  let cut = end;
+  while (cut > start + 1 && /^\s*(#.*)?$/.test(lines[cut - 1]) && end !== rows.length) cut--;
+  const before = lines.slice(0, start).join("\n");
+  const after = lines.slice(cut).join("\n");
+  const joined = `${before}${before ? "\n" : ""}${block}${after ? `\n${after.replace(/^\n+/, "")}` : ""}`;
+  return { text: joined.endsWith("\n") ? joined : `${joined}\n`, replaced: true };
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@capacms/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The capa command line: Capa content, models and keys from a terminal, a script or an agent, and capa init for Claude Code, Codex and Cursor.",
+  "license": "UNLICENSED",
+  "homepage": "https://docs.capacms.com/cli",
+  "type": "module",
+  "bin": {
+    "capa": "bin/capa.mjs"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.3"
+  },
+  "dependencies": {
+    "@capacms/mcp": "0.3.0"
+  },
+  "scripts": {
+    "test": "node --test test/argv.test.mjs test/credentials.test.mjs test/init.test.mjs test/commands.test.mjs test/media.test.mjs test/sdk.test.mjs"
+  }
 }