@capacms/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @capacms/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`capa`: Capa content from a terminal, a script or an AI agent, and one command
+to plug Capa into Claude Code, Codex or Cursor.
+
+```bash
+npm install -g @capacms/cli
+capa login                 # paste a key from Developers > Keys; it goes to the OS keychain
+capa init claude           # or codex, or cursor: registers `capa mcp`, with no key in the file
+capa entries list articles --json
+capa entries create articles --data '{"title":"Hello"}'
+```
+
+Without installing, name the package: `npx @capacms/cli login`. Never
+`npx capa`, which fetches an unrelated npm package of that name. `@capacms/sdk`
+also ships a `capa` command, so npm refuses to install both globally
+(`EEXIST`): install this one globally and keep the SDK in your project.
+
+Every content command is one tool of [`@capacms/mcp`](../mcp/README.md), run
+by name. The CLI and the MCP server take the same arguments and refuse the
+same way. `capa tool <name>` runs any of them.
+
+Every command takes `--json` and `--profile NAME`. None prompts when stdin is
+not a terminal. The exit codes are documented: 0 done, 1 refused, 2 usage,
+3 no key, 4 not offered for this key, 5 Capa did not answer.
+
+The full reference, with what each key reads and writes, is
+[docs/cli.md](../../docs/cli.md).
+
+## Layout
+
+| File | What it holds |
+|---|---|
+| `bin/capa.mjs` | the Node check, then `lib/main.mjs` |
+| `lib/main.mjs` | the command table, help, login, whoami, projects, tools, mcp, init |
+| `lib/commands.mjs` | the content commands: each one a tool, its flags typed from the tool's input schema |
+| `lib/session.mjs` | which key (`CAPA_KEY`, else the profile), `connect`, `runTool`, exit codes |
+| `lib/credentials.mjs` | profiles in `config.json`; the key in the keychain (`security`, `secret-tool`) or a 0600 file |
+| `lib/init.mjs`, `lib/toml.mjs`, `lib/diff.mjs` | `capa init`: the clients' config formats, the Codex TOML section, the diff it shows |
+| `lib/sdk.mjs` | `capa codegen` and `capa persist`, run from the project's `@capacms/sdk` |
+
+## Tests
+
+```bash
+pnpm -F @capacms/cli test
+```
+
+They run the real commands in-process against `packages/mcp`'s stand-in
+deployment and check what it stored. One test creates a throwaway macOS
+keychain (`CAPA_KEYCHAIN`) and never touches the login keychain. The Codex
+format test runs `codex mcp get` where Codex is installed and is skipped
+elsewhere.

package/bin/capa.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * capa: the Capa command line. lib/main.mjs has the commands; this file
+ * checks Node first, so an old Node is told what it needs instead of failing
+ * on syntax it cannot read, and exits only once stdout has drained (a piped
+ * answer is never cut short).
+ */
+const [major, minor] = process.versions.node.split(".").map(Number);
+if (major < 20 || (major === 20 && minor < 3)) {
+  process.stderr.write(`capa needs Node 20.3 or later; this is ${process.versions.node}.\n`);
+  process.exit(2);
+}
+
+import("../lib/main.mjs")
+  .then(({ main }) => main(process.argv.slice(2)))
+  .then(
+    (code) => {
+      // null: `capa mcp`, which exits on its own when the client goes away.
+      if (code === null || code === undefined) return;
+      process.stdout.write("", () => process.exit(code));
+    },
+    (error) => {
+      process.stderr.write(`capa: ${error?.message ?? error}\n`);
+      process.stdout.write("", () => process.exit(1));
+    },
+  );

package/lib/argv.mjs

@@ -0,0 +1,76 @@
+/**
+ * argv.mjs — the command line, read without a library.
+ *
+ *   --name value   --name=value   --flag (a boolean)   --no-flag (false)
+ *   -h  -y         the two short forms: --help and --yes
+ *   --             everything after it is positional
+ *
+ * A flag is a boolean only when the command says so, which is how
+ * `--sdl articles` can never swallow `articles`. Flag names are read in
+ * kebab-case or camelCase and stored camelCase, the case tool arguments use:
+ * `--version-id` and `--versionId` are both `versionId`.
+ */
+import { CliError, EXIT } from "./output.mjs";
+
+/** The flags every command takes, wherever they appear. */
+export const GLOBAL_BOOLEANS = new Set(["json", "help", "version"]);
+export const GLOBAL_VALUES = new Set(["profile"]);
+
+export const camel = (name) => name.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+export const kebab = (name) => name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+
+/**
+ * `{ positionals, flags }`. `booleans` are the flags that take no value.
+ * A flag given twice keeps the last value.
+ */
+export function parseArgv(argv, { booleans = new Set() } = {}) {
+  const positionals = [];
+  const flags = {};
+  const isBoolean = (name) => GLOBAL_BOOLEANS.has(name) || booleans.has(name);
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (token === "-h") {
+      flags.help = true;
+      continue;
+    }
+    if (token === "-y") {
+      flags.yes = true;
+      continue;
+    }
+    if (token === "-V") {
+      flags.version = true;
+      continue;
+    }
+    if (!token.startsWith("--") || token === "-") {
+      positionals.push(token);
+      continue;
+    }
+    const eq = token.indexOf("=");
+    const raw = eq === -1 ? token.slice(2) : token.slice(2, eq);
+    if (!raw) throw new CliError(EXIT.usage, `${token} is not a flag.`);
+    let name = camel(raw);
+    if (eq !== -1) {
+      flags[name] = token.slice(eq + 1);
+      continue;
+    }
+    if (name.startsWith("no") && /^no[A-Z]/.test(name) && isBoolean(name[2].toLowerCase() + name.slice(3))) {
+      flags[name[2].toLowerCase() + name.slice(3)] = false;
+      continue;
+    }
+    if (isBoolean(name)) {
+      flags[name] = true;
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next === undefined || (next.startsWith("--") && next !== "--")) {
+      throw new CliError(EXIT.usage, `--${kebab(name)} needs a value.`);
+    }
+    flags[name] = next;
+    i++;
+  }
+  return { positionals, flags };
+}

package/lib/commands.mjs

@@ -0,0 +1,215 @@
+/**
+ * commands.mjs — the content commands, each one an MCP tool by name.
+ *
+ * A command names its tool and which positionals fill which arguments; every
+ * other argument of the tool is a flag of the same name (`--max-chars` or
+ * `--maxChars` for `maxChars`), typed from the tool's own input schema. So a
+ * tool that gains an argument gains the flag with no change here, and a
+ * misspelt flag reaches the tool's argument check and gets its answer:
+ * "Unknown argument modle. Did you mean model?".
+ *
+ * Where two tools answer one question for different keys (a `cap_` key reads
+ * entries with capa_read_entries, a legacy key on a GraphQL deployment with
+ * capa_list_content), the command takes the first one this key is offered.
+ * `capa tool <name>` runs any tool directly, so nothing the MCP server offers
+ * is out of reach of the CLI.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { TOOLS_BY_NAME } from "@capacms/mcp";
+import { kebab } from "./argv.mjs";
+import { CliError, EXIT } from "./output.mjs";
+
+/**
+ * Each command: its words, a one-line summary, the positionals it takes, and
+ * `pick(offered)` → `{ tool, args }` from the positionals. `offered(name)`
+ * says whether the session offers a tool.
+ */
+export const COMMANDS = [
+  {
+    words: ["models"],
+    usage: "capa models [<model>]",
+    summary: "List the models, or show one model's fields (the names entries are written with).",
+    positionals: ["model?"],
+    tools: ["capa_get_model", "capa_graphql_schema", "capa_list_models"],
+    pick: ([model], offered) => {
+      if (model) return offered("capa_get_model") ? { tool: "capa_get_model", args: { namespace: model } } : { tool: "capa_graphql_schema", args: { model } };
+      return !offered("capa_graphql_schema") && offered("capa_list_models") ? { tool: "capa_list_models", args: {} } : { tool: "capa_graphql_schema", args: {} };
+    },
+  },
+  {
+    words: ["schema"],
+    usage: "capa schema [<model>] [--sdl]",
+    summary: "What this key can read: models, fields, relations, filters and sorts; --sdl for the GraphQL SDL.",
+    positionals: ["model?"],
+    tools: ["capa_graphql_schema"],
+    pick: ([model]) => ({ tool: "capa_graphql_schema", args: model ? { model } : {} }),
+  },
+  {
+    words: ["entries", "list"],
+    usage: "capa entries list <model> [--where JSON] [--sort field] [--limit n] [--select fields]",
+    summary: "List a model's entries.",
+    positionals: ["model"],
+    tools: ["capa_read_entries", "capa_list_content"],
+    pick: ([model], offered) =>
+      !offered("capa_read_entries") && offered("capa_list_content")
+        ? { tool: "capa_list_content", args: { namespace: model } }
+        : { tool: "capa_read_entries", args: { model } },
+  },
+  {
+    words: ["entries", "get"],
+    usage: "capa entries get <model> <id>",
+    summary: "Read one entry.",
+    positionals: ["model", "id"],
+    tools: ["capa_read_entries", "capa_get_content"],
+    pick: ([model, id], offered) =>
+      !offered("capa_read_entries") && offered("capa_get_content")
+        ? { tool: "capa_get_content", args: { namespace: model, id } }
+        : { tool: "capa_read_entries", args: { model, id } },
+  },
+  {
+    words: ["entries", "create"],
+    usage: "capa entries create <model> --data JSON|@file|-",
+    summary: "Create an entry, saved as a draft.",
+    positionals: ["model"],
+    tools: ["capa_create_entry"],
+    pick: ([model]) => ({ tool: "capa_create_entry", args: { model } }),
+  },
+  {
+    words: ["entries", "update"],
+    usage: "capa entries update <id> --data JSON|@file|-",
+    summary: "Change fields of an entry, saved as a new draft version. Fields left out keep their values.",
+    positionals: ["id"],
+    tools: ["capa_update_entry"],
+    pick: ([id]) => ({ tool: "capa_update_entry", args: { id } }),
+  },
+  {
+    words: ["entries", "publish"],
+    usage: "capa entries publish <id> [--version-id id]",
+    summary: "Publish an entry: its newest draft becomes what sites read.",
+    positionals: ["id"],
+    tools: ["capa_publish_entry"],
+    pick: ([id]) => ({ tool: "capa_publish_entry", args: { id } }),
+  },
+  {
+    words: ["entries", "unpublish"],
+    usage: "capa entries unpublish <id>",
+    summary: "Unpublish an entry: sites stop reading it, and it stays as a draft.",
+    positionals: ["id"],
+    tools: ["capa_unpublish_entry"],
+    pick: ([id]) => ({ tool: "capa_unpublish_entry", args: { id } }),
+  },
+  {
+    words: ["media", "list"],
+    usage: "capa media list [--search text] [--type image|video|file|audio|document|pdf] [--page n] [--size n]",
+    summary: "List the project's files, newest first, as the values image, video and file fields take.",
+    positionals: [],
+    tools: ["capa_list_media"],
+    pick: () => ({ tool: "capa_list_media", args: {} }),
+  },
+  {
+    words: ["media", "upload"],
+    usage: "capa media upload <path> [--folder-id id] [--is-public]",
+    summary: "Upload a file from this folder; answers the value an image, video or file field takes.",
+    positionals: ["path"],
+    tools: ["capa_upload_media"],
+    pick: ([file]) => ({ tool: "capa_upload_media", args: { path: file } }),
+  },
+];
+
+/** The command whose words start `positionals`, longest first, and the positionals left after them. */
+export function findCommand(positionals) {
+  const matches = COMMANDS.filter((c) => c.words.every((w, i) => positionals[i] === w)).sort((a, b) => b.words.length - a.words.length);
+  return matches[0] ? { command: matches[0], rest: positionals.slice(matches[0].words.length) } : null;
+}
+
+/** The boolean flags of these tools, which take no value on the command line. */
+export function booleanFlags(toolNames) {
+  const out = new Set();
+  for (const name of toolNames) {
+    for (const [prop, schema] of Object.entries(TOOLS_BY_NAME.get(name)?.inputSchema?.properties ?? {})) {
+      if (schema.type === "boolean") out.add(prop);
+    }
+  }
+  return out;
+}
+
+const typesOf = (schema) => (Array.isArray(schema?.type) ? schema.type : schema?.type ? [schema.type] : []);
+
+/** `@file` reads a file, `-` reads stdin; anything else is the value itself. */
+function readValue(flag, value, io) {
+  if (value === "-") {
+    if (io.stdinUsed) throw new CliError(EXIT.usage, `--${flag} - reads stdin, and another flag already read it.`);
+    io.stdinUsed = true;
+    return io.readStdin();
+  }
+  if (typeof value === "string" && value.startsWith("@") && value.length > 1) {
+    const file = path.resolve(io.cwd, value.slice(1));
+    try {
+      return fs.readFileSync(file, "utf8");
+    } catch (error) {
+      throw new CliError(EXIT.usage, `--${flag} ${value}: ${error.code === "ENOENT" ? "no such file" : error.message}.`);
+    }
+  }
+  return value;
+}
+
+/**
+ * A flag's value as the tool's schema types it. Objects and arrays are JSON
+ * (inline, `@file` or `-` for stdin); numbers and booleans are parsed; a string
+ * stays a string. A value that does not parse is passed through as given, so
+ * the tool's own check refuses it with the tool's own words.
+ */
+async function coerce(flag, value, schema, io) {
+  const types = typesOf(schema);
+  if (value === true || value === false) return value;
+  if (types.includes("object") || types.includes("array") || types.includes("null")) {
+    const text = await readValue(flag, value, io);
+    const trimmed = String(text).trim();
+    const looksJson = /^[[{"]/.test(trimmed) || trimmed === "null" || /^-?\d/.test(trimmed) || trimmed === "true" || trimmed === "false";
+    if (looksJson) {
+      try {
+        return JSON.parse(trimmed);
+      } catch (error) {
+        if (!types.includes("string")) throw new CliError(EXIT.usage, `--${flag} is not JSON: ${error.message}.`);
+      }
+    }
+    if (!types.includes("string") && (types.includes("object") || types.includes("array"))) {
+      // Not JSON at all: hand it over as a string, and the tool says what it wanted.
+      return trimmed;
+    }
+    return text;
+  }
+  if ((types.includes("integer") || types.includes("number")) && /^-?\d+(\.\d+)?$/.test(String(value))) return Number(value);
+  if (types.includes("boolean") && (value === "true" || value === "false")) return value === "true";
+  return value;
+}
+
+/** Tool arguments from the command's own arguments, then every flag that is not one of the CLI's. */
+export async function toolArgs(toolName, base, flags, io, { reserved = new Set() } = {}) {
+  const tool = TOOLS_BY_NAME.get(toolName);
+  const props = tool?.inputSchema?.properties ?? {};
+  const args = { ...base };
+  for (const [name, value] of Object.entries(flags)) {
+    if (reserved.has(name)) continue;
+    // An alias (`--namespace` for `model`) is typed as what it stands for and
+    // passed under its own name: the tool resolves it, as it does for MCP.
+    args[name] = await coerce(kebab(name), value, props[name] ?? props[tool?.aliases?.[name]], io);
+  }
+  return args;
+}
+
+/** The flags a tool takes, for help: `--name <type>  description`. */
+export function flagHelp(toolName, skip = []) {
+  const tool = TOOLS_BY_NAME.get(toolName);
+  const props = tool?.inputSchema?.properties ?? {};
+  const required = new Set(tool?.inputSchema?.required ?? []);
+  return Object.entries(props)
+    .filter(([name]) => !skip.includes(name))
+    .map(([name, schema]) => {
+      const types = typesOf(schema);
+      const shape = types.includes("boolean") && types.length === 1 ? "" : types.some((t) => t === "object" || t === "array") ? " <json|@file|->" : types.includes("integer") || types.includes("number") ? " <n>" : " <text>";
+      const first = String(schema.description ?? "").split(/(?<=\.)\s(?=[A-Z])/)[0];
+      return `  --${kebab(name)}${shape}${required.has(name) ? " (required)" : ""}\n      ${first}`;
+    });
+}