@cerkel/cli 0.0.0-stage → 1.0.1

package/dist/cli.js

@@ -0,0 +1,497 @@
+import { parseArgs } from "node:util";
+import { ApiUrlError, DEFAULT_API_URL } from "./api-url.js";
+import { bool, str } from "./command.js";
+import { login, logins, logout, stores, whoami } from "./commands/auth.js";
+import { themeDev } from "./commands/dev.js";
+import { COMMERCE_COMMANDS } from "./commands/index.js";
+import { deleteFiles, fileArg, fileHistory, fileRestore, sectionDelete, sectionDuplicate, sectionHistory, sectionNew, sectionRestore } from "./commands/section.js";
+import { themeCheck, themeList, themePreview, themePull, themePush, themeSubmit } from "./commands/theme.js";
+import { themeConsole, themeDeleteTheme, themeInfo, themeInit, themeOpen, themePackage, themeProfile, themePushNew, themeRename, themeShare } from "./commands/theme-tools.js";
+import { AuthError, CliError, RateLimitError, StoreLoginError, ToolRefusal, retryAt } from "./errors.js";
+import { envTokenSecrets } from "./env.js";
+import { makeRedactor } from "./redact.js";
+import { Session } from "./session.js";
+const GLOBAL = {
+    api: { type: "string" },
+    help: { type: "boolean", short: "h" },
+};
+/** --theme / --store, when given. */
+const themeFlags = (v) => ({
+    ...(str(v, "theme") ? { theme: str(v, "theme") } : {}),
+    ...(str(v, "store") ? { store: str(v, "store") } : {}),
+});
+function limitOf(v) {
+    const limit = str(v, "limit") ? Number(str(v, "limit")) : undefined;
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1))
+        throw new CliError("--limit must be a positive whole number.");
+    return limit ? { limit } : {};
+}
+const COMMANDS = {
+    login: {
+        usage: "cerkel login --store <slug> [--token]",
+        summary: "Sign in to one store through the browser (or paste a token with --token)",
+        help: [
+            `Opens the Cerkel admin in your browser (${new URL(DEFAULT_API_URL).host}, or the host this command uses: --api, the theme`,
+            "folder's recorded API, or CERKEL_API_URL): sign in as usual, choose the store (--store picks it for you),",
+            "press Allow, and you are logged in to that store. A login is for ONE store: to work on another",
+            "store, run `cerkel login --store <its slug>` too — your other logins are kept. Inside a theme folder,",
+            "`cerkel login` signs in to the folder's store.",
+            "Logins are saved to the system keychain, or to ~/.config/cerkel/credentials (0600) when there",
+            "is no keychain. They follow your staff access and can be revoked in Settings → AI assistant",
+            "connection (MCP).",
+            "--token: paste a token created by hand for one store instead (e.g. on a server with no browser).",
+            "In scripts: echo \"$TOKEN\" | cerkel login. With CERKEL_TOKEN set, it verifies that token and saves nothing.",
+        ],
+        options: { token: { type: "boolean" }, store: { type: "string" } },
+        run: (s, v) => login(s, { token: bool(v, "token"), ...(str(v, "store") ? { store: str(v, "store") } : {}) }),
+    },
+    logout: {
+        usage: "cerkel logout [--store <slug> | --all]",
+        summary: "Remove a stored login",
+        help: [
+            "Removes this folder's store login inside a theme folder, the one given with --store, or your only",
+            "login. --all removes every login for this API. The token itself is revoked in Settings → MCP.",
+        ],
+        options: { store: { type: "string" }, all: { type: "boolean" } },
+        run: (s, v) => logout(s, { all: bool(v, "all"), ...(str(v, "store") ? { store: str(v, "store") } : {}) }),
+    },
+    logins: {
+        usage: "cerkel logins",
+        summary: "List your own logins on this computer, one per store",
+        help: ["Each one is checked with the server using that login's own token, and shown with its status."],
+        options: {},
+        run: (s) => logins(s),
+    },
+    whoami: {
+        usage: "cerkel whoami [--store <slug>] [--all]",
+        summary: "Show who the login belongs to and the one store it is for",
+        help: ["Uses this folder's store login, the one given with --store, or your only login. --all is `cerkel logins`."],
+        options: { store: { type: "string" }, all: { type: "boolean" } },
+        run: (s, v) => whoami(s, { all: bool(v, "all"), ...(str(v, "store") ? { store: str(v, "store") } : {}) }),
+    },
+    stores: {
+        usage: "cerkel stores [--store <slug>]",
+        summary: "Show the store this login is for",
+        help: ["A login reaches exactly one store. Uses this folder's store login, the one given with --store, or your only login."],
+        options: { store: { type: "string" } },
+        run: (s, v) => stores(s, { ...(str(v, "store") ? { store: str(v, "store") } : {}) }),
+    },
+    "theme list": {
+        usage: "cerkel theme list [--store <slug>]",
+        summary: "List the store's live and draft themes",
+        help: ["The store is --store, else this folder's store, else the store of your only login."],
+        options: { store: { type: "string" } },
+        run: (s, v) => themeList(s, { ...(str(v, "store") ? { store: str(v, "store") } : {}) }),
+    },
+    "theme pull": {
+        usage: "cerkel theme pull [--store <slug>] [--theme <id>] [--yes] [--dir <path>] [--force]\n       cerkel theme pull [--store <slug>] --live --dir <path>",
+        summary: "Download a draft theme into this folder",
+        help: [
+            "The store is --store, else this folder's store, else the store of your only login. A folder holds",
+            "one store's theme: pull another store into a folder of its own (--dir).",
+            "Picks the newest draft unless --theme is given; offers to create one from the live theme",
+            "when there is none (--yes answers for you). The live theme is never pulled for editing:",
+            "--live writes a READ-ONLY reference copy into --dir, where push, dev and submit refuse to run.",
+            "Refuses to overwrite local changes unless --force.",
+        ],
+        options: {
+            store: { type: "string" },
+            theme: { type: "string" },
+            live: { type: "boolean" },
+            yes: { type: "boolean", short: "y" },
+            dir: { type: "string" },
+            force: { type: "boolean" },
+        },
+        run: (s, v) => themePull(s, {
+            ...(str(v, "store") ? { store: str(v, "store") } : {}),
+            ...(str(v, "theme") ? { theme: str(v, "theme") } : {}),
+            ...(str(v, "dir") ? { dir: str(v, "dir") } : {}),
+            live: bool(v, "live"),
+            yes: bool(v, "yes"),
+            force: bool(v, "force"),
+        }),
+    },
+    "theme check": {
+        usage: "cerkel theme check [--all] [--store <slug>]",
+        summary: "Validate theme files on the server (nothing is saved)",
+        help: [
+            "Checks changed files by default, every file with --all. Prints path:line:col  severity  message",
+            "and exits 1 on any error (warnings exit 0). Outside a checkout (CI), --store <slug> checks every file.",
+        ],
+        options: { all: { type: "boolean" }, store: { type: "string" } },
+        run: (s, v) => themeCheck(s, { all: bool(v, "all"), ...(str(v, "store") ? { store: str(v, "store") } : {}) }),
+    },
+    "theme push": {
+        usage: "cerkel theme push [files…] [--force [--yes]] [--nodelete]\n       cerkel theme push --new [--name \"…\"] [--store <slug>]",
+        summary: "Upload changed files to the draft (--new: this folder → a new draft)",
+        help: [
+            "Sends only files that changed since the last pull/push. A file someone else changed on the",
+            "server is refused as a conflict and shown as a diff.",
+            "A section, block, snippet or asset file you deleted locally is deleted from the draft too",
+            "(only the copy you last synced; a newer server copy is a conflict). --nodelete keeps them.",
+            "--force overwrites the server's copy of those files. It first lists, per file, how many server",
+            "lines would be lost and asks y/N; --yes answers for you (required when there is no terminal).",
+            "--new (in a folder of theme files that is not a checkout yet, e.g. after `cerkel theme init`):",
+            "creates a NEW draft copied from the live theme, pushes every theme file in the folder onto it",
+            "and makes the folder that draft's checkout. --name names the draft (default: the folder's name).",
+        ],
+        options: { force: { type: "boolean" }, yes: { type: "boolean", short: "y" }, nodelete: { type: "boolean" }, new: { type: "boolean" }, name: { type: "string" }, store: { type: "string" } },
+        run: (s, v, pos) => {
+            if (bool(v, "new")) {
+                if (pos.length > 0 || bool(v, "force") || bool(v, "nodelete"))
+                    throw new CliError("--new pushes every theme file in this folder to a new draft; it takes no file names, --force or --nodelete.");
+                return themePushNew(s, { ...(str(v, "store") ? { store: str(v, "store") } : {}), ...(str(v, "name") ? { name: str(v, "name") } : {}) });
+            }
+            if (str(v, "name") || str(v, "store"))
+                throw new CliError("--name and --store go with --new. A checkout always pushes to its own draft.");
+            return themePush(s, { files: pos, force: bool(v, "force"), yes: bool(v, "yes"), noDelete: bool(v, "nodelete") });
+        },
+    },
+    "theme dev": {
+        usage: "cerkel theme dev",
+        summary: "Push on save and print a preview link on the real store domain",
+        help: [
+            "Pushes pending changes, then watches the folder and pushes each burst of saves as one batch. Ctrl-C stops.",
+            "Deleting a section, block, snippet or asset file deletes it from the draft (--nodelete keeps them).",
+        ],
+        options: { nodelete: { type: "boolean" } },
+        run: (s, v) => themeDev(s, { noDelete: bool(v, "nodelete") }),
+    },
+    "theme preview": {
+        usage: "cerkel theme preview [--open]",
+        summary: "Print a signed preview link (valid 30 minutes)",
+        help: [],
+        options: { open: { type: "boolean" } },
+        run: (s, v) => themePreview(s, { open: bool(v, "open") }),
+    },
+    "theme submit": {
+        usage: 'cerkel theme submit -m "title" [--description "…"]',
+        summary: "Send the draft for approval (for the store owner's login it publishes immediately)",
+        help: [
+            "Refuses while there are unpushed changes. Prints the request id and its admin link.",
+            "Sends the draft for approval; someone with publish rights publishes it in the Cerkel admin.",
+            "For the store owner's or an admin's login (it may publish in this store) and for logins of",
+            "Cerkel's own team (a @raizn.net or @raizn.com email) it",
+            "publishes immediately, and a rollback link is printed.",
+        ],
+        options: { message: { type: "string", short: "m" }, description: { type: "string" } },
+        run: (s, v) => themeSubmit(s, {
+            ...(str(v, "message") ? { title: str(v, "message") } : {}),
+            ...(str(v, "description") ? { description: str(v, "description") } : {}),
+        }),
+    },
+    "theme history": {
+        usage: "cerkel theme history <file> [--limit <n>]",
+        summary: "List a theme file's saved versions",
+        help: ["Every save, delete, restore and rollback of that path in any theme of the store, newest first."],
+        options: { limit: { type: "string" } },
+        run: async (s, v, pos) => {
+            const co = await s.requireCheckout({ editable: false });
+            return fileHistory(s, fileArg(s, co.root, pos[0]), limitOf(v));
+        },
+    },
+    "theme restore": {
+        usage: "cerkel theme restore <file> <version> [--force]",
+        summary: "Bring an old version of a file back into the draft",
+        help: ["History is never rewritten: the old content becomes a new version. The local file is refreshed."],
+        options: { force: { type: "boolean" } },
+        run: async (s, v, pos) => {
+            const co = await s.requireCheckout({ editable: true });
+            return fileRestore(s, fileArg(s, co.root, pos[0]), pos[1], { force: bool(v, "force") });
+        },
+    },
+    "theme delete": {
+        usage: "cerkel theme delete <file…>\n       cerkel theme delete --theme <id> [--yes] [--store <slug>] [--json]",
+        summary: "Delete files from the draft, or (--theme) a whole draft theme",
+        help: [
+            "With file names: deletes those section, block, snippet or asset files from this folder's draft.",
+            "Refused for a section still placed by one of the draft's templates. Deleted files stay in their history.",
+            "With --theme <id>: deletes that DRAFT theme (never the live one, never one waiting for review).",
+            "On a terminal you type the theme's name to confirm; --yes skips that (required without a terminal).",
+        ],
+        options: { theme: { type: "string" }, yes: { type: "boolean", short: "y" }, store: { type: "string" }, json: { type: "boolean" } },
+        run: async (s, v, pos) => {
+            if (str(v, "theme")) {
+                if (pos.length > 0)
+                    throw new CliError("Either delete files (`cerkel theme delete <file…>`) or a whole draft (`cerkel theme delete --theme <id>`), not both.");
+                return themeDeleteTheme(s, { theme: str(v, "theme"), yes: bool(v, "yes"), json: bool(v, "json"), ...(str(v, "store") ? { store: str(v, "store") } : {}) });
+            }
+            if (pos.length === 0)
+                throw new CliError("Which files? e.g. `cerkel theme delete snippets/old-badge.liquid`. To delete a whole draft: `cerkel theme delete --theme <id>`.");
+            const co = await s.requireCheckout({ editable: true });
+            return deleteFiles(s, pos.map((p) => fileArg(s, co.root, p)));
+        },
+    },
+    "theme info": {
+        usage: "cerkel theme info [--theme <id>] [--store <slug>] [--json]",
+        summary: "Show a theme: role, preset, templates, files, review state and its editor link",
+        help: ["The theme is --theme, else this folder's, else the store's live theme."],
+        options: { theme: { type: "string" }, store: { type: "string" }, json: { type: "boolean" } },
+        run: (s, v) => themeInfo(s, { json: bool(v, "json"), ...themeFlags(v) }),
+    },
+    "theme open": {
+        usage: "cerkel theme open [--theme <id>] [--code] [--print] [--store <slug>]",
+        summary: "Open the theme in the admin's visual editor (--code: the code editor)",
+        help: ["Prints the link and opens it in your browser (--print only prints it). The theme is --theme, else this folder's, else the live one."],
+        options: { theme: { type: "string" }, store: { type: "string" }, code: { type: "boolean" }, print: { type: "boolean" } },
+        run: (s, v) => themeOpen(s, { code: bool(v, "code"), print: bool(v, "print"), ...themeFlags(v) }),
+    },
+    "theme rename": {
+        usage: 'cerkel theme rename "<new name>" [--theme <id>] [--store <slug>] [--json]',
+        summary: "Rename a theme (this folder's draft, or --theme)",
+        help: ["The name is only shown to staff, so any theme may be renamed. A folder tracking that theme records the new name."],
+        options: { theme: { type: "string" }, store: { type: "string" }, json: { type: "boolean" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length > 1)
+                throw new CliError('Put the name in quotes: cerkel theme rename "Ramadan 2027".');
+            return themeRename(s, pos[0], { json: bool(v, "json"), ...themeFlags(v) });
+        },
+    },
+    "theme share": {
+        usage: "cerkel theme share [--theme <id>] [--days <1-14>] [--path /products/<handle>] [--store <slug>] [--json]",
+        summary: "A preview link of the draft for someone else (7 days by default)",
+        help: [
+            "Anyone with the link sees the draft on the store's own domain until it expires (default 7 days, at most 14);",
+            "deleting the draft revokes it. It shows what is on the server: push first. The live theme needs no link.",
+        ],
+        options: { theme: { type: "string" }, store: { type: "string" }, days: { type: "string" }, path: { type: "string" }, json: { type: "boolean" } },
+        run: (s, v) => themeShare(s, { json: bool(v, "json"), ...themeFlags(v), ...(str(v, "days") ? { days: str(v, "days") } : {}), ...(str(v, "path") ? { path: str(v, "path") } : {}) }),
+    },
+    "theme console": {
+        usage: 'cerkel theme console [--path /products/<handle>] [--locale en] [--theme <id>] [-e "<liquid>"] [--json]',
+        summary: "A Liquid console against the store's real data",
+        help: [
+            "Evaluates Liquid on the store's own storefront with the objects a section on --path gets",
+            "(product, collection, page, article, the catalogue, menus, settings). Default page: the home page;",
+            "default theme: this folder's draft, else the live one. Type .help inside for its commands.",
+            "-e evaluates one expression and exits; piped stdin is evaluated as one template. Reads only.",
+        ],
+        options: { theme: { type: "string" }, store: { type: "string" }, path: { type: "string" }, locale: { type: "string" }, eval: { type: "string", short: "e" }, json: { type: "boolean" } },
+        run: (s, v) => themeConsole(s, {
+            json: bool(v, "json"), ...themeFlags(v),
+            ...(str(v, "path") ? { path: str(v, "path") } : {}), ...(str(v, "locale") ? { locale: str(v, "locale") } : {}), ...(str(v, "eval") !== undefined ? { eval: str(v, "eval") } : {}),
+        }),
+    },
+    "theme profile": {
+        usage: "cerkel theme profile [--path /products/<handle>] [--locale en] [--runs <1-5>] [--theme <id>] [--json]",
+        summary: "Server render time of each section on a page",
+        help: [
+            "Renders the page on the store's own storefront with the theme (this folder's draft, else the live one)",
+            "and lists every section in page order with its server time and what rendered it. --runs repeats it",
+            "and shows medians. Exits 1 when a section failed (its error is printed).",
+        ],
+        options: { theme: { type: "string" }, store: { type: "string" }, path: { type: "string" }, locale: { type: "string" }, runs: { type: "string" }, json: { type: "boolean" } },
+        run: (s, v) => themeProfile(s, {
+            json: bool(v, "json"), ...themeFlags(v),
+            ...(str(v, "path") ? { path: str(v, "path") } : {}), ...(str(v, "locale") ? { locale: str(v, "locale") } : {}), ...(str(v, "runs") ? { runs: str(v, "runs") } : {}),
+        }),
+    },
+    "theme package": {
+        usage: "cerkel theme package [--output <file>.zip] [--force] [--json]",
+        summary: "Zip this folder's theme files",
+        help: ["Packages the theme files of this folder as they are on disk (unpushed changes included) into a .zip. Nothing is sent."],
+        options: { output: { type: "string", short: "o" }, force: { type: "boolean" }, json: { type: "boolean" } },
+        run: (s, v) => themePackage(s, { force: bool(v, "force"), json: bool(v, "json"), ...(str(v, "output") ? { output: str(v, "output") } : {}) }),
+    },
+    "theme init": {
+        usage: "cerkel theme init [<folder>] [--starter <key>] [--list] [--json]",
+        summary: "Start a new theme folder from a starter theme",
+        help: [
+            "Writes a complete starter theme (Liquid sections, assets, templates and a README) into <folder>",
+            "(default ./cerkel-theme). Nothing is sent: `cerkel theme push --new` puts it on a new draft.",
+            "--list shows the starters.",
+        ],
+        options: { starter: { type: "string" }, list: { type: "boolean" }, store: { type: "string" }, json: { type: "boolean" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length > 1)
+                throw new CliError("One folder at a time: cerkel theme init <folder>.");
+            return themeInit(s, pos[0], { list: bool(v, "list"), json: bool(v, "json"), ...(str(v, "starter") ? { starter: str(v, "starter") } : {}), ...(str(v, "store") ? { store: str(v, "store") } : {}) });
+        },
+    },
+    "section new": {
+        usage: "cerkel section new <type> [--starter <key>]",
+        summary: "Create a new kind of section locally from a starter",
+        help: [
+            "Writes sections/<type>.liquid — its Liquid, {% stylesheet %} and {% schema %} in ONE file.",
+            "The next push adds it to the draft; it goes live when the draft is approved and published.",
+        ],
+        options: { starter: { type: "string" } },
+        run: (s, v, pos) => sectionNew(s, pos[0], { ...(str(v, "starter") ? { starter: str(v, "starter") } : {}) }),
+    },
+    "section duplicate": {
+        usage: "cerkel section duplicate <type> <new-type>",
+        summary: "Copy a section file to a new type, to redesign it side by side",
+        help: ["Local only: the copy's name gets \"(copy)\". Push it, then place it instead of the original."],
+        options: {},
+        run: (s, _v, pos) => sectionDuplicate(s, pos[0], pos[1]),
+    },
+    "section delete": {
+        usage: "cerkel section delete <type>",
+        summary: "Delete a section file from the draft",
+        help: ["Refused while one of the draft's templates still places it. Its history stays."],
+        options: {},
+        run: (s, _v, pos) => sectionDelete(s, pos[0]),
+    },
+    "section history": {
+        usage: "cerkel section history <type> [--limit <n>]",
+        summary: "List a section file's versions",
+        help: ["Same as cerkel theme history sections/<type>.liquid."],
+        options: { limit: { type: "string" } },
+        run: (s, v, pos) => sectionHistory(s, pos[0], limitOf(v)),
+    },
+    "section restore": {
+        usage: "cerkel section restore <type> <version> [--force]",
+        summary: "Restore an old version of a section file into the draft",
+        help: ["History is never rewritten: the old file becomes a new version. The local file is refreshed."],
+        options: { force: { type: "boolean" } },
+        run: (s, v, pos) => sectionRestore(s, pos[0], pos[1], { force: bool(v, "force") }),
+    },
+    // The commerce commands (store, price, product, inventory, collection, … — commands/index.ts).
+    ...COMMERCE_COMMANDS,
+};
+/** Every word that starts a two-word command (`theme pull`, `price set`, …). */
+const GROUPS = new Set(Object.keys(COMMANDS).filter((k) => k.includes(" ")).map((k) => k.split(" ")[0]));
+/** Commands people type without their group (`cerkel pull`), and `cerkel help`. */
+const HINTS = {
+    help: "cerkel --help",
+    ...Object.fromEntries(["pull", "push", "dev", "submit", "check", "preview", "list", "info", "open", "rename", "share", "console", "profile", "package", "init"].map((c) => [c, `cerkel theme ${c}`])),
+    ...Object.fromEntries(["new", "duplicate"].map((c) => [c, `cerkel section ${c}`])),
+    ...Object.fromEntries(["delete", "history", "restore"].map((c) => [c, `cerkel theme ${c}`])),
+};
+/** Words people reach for that this tool deliberately does not have. */
+const NEVER = new Set(["publish", "unpublish", "rollback", "go-live", "golive", "release", "deploy"]);
+const NEVER_MESSAGE = "does not exist: this CLI has no publish, rollback or deploy command.\n" +
+    '`cerkel theme submit -m "…"` sends the draft for approval; for the store owner\'s login it publishes immediately (a rollback link is printed).\n' +
+    "For everyone else, publishing happens in the Cerkel admin after approval, by someone with publish rights. Rollback is in the admin too.";
+function mainHelp(version) {
+    const rows = Object.entries(COMMANDS).map(([name, c]) => [`  ${name}`, c.summary]);
+    const w = Math.max(...rows.map((r) => r[0].length));
+    return [
+        `cerkel ${version} — run a Cerkel store from the terminal: its theme, pages and menus as local files, its catalogue, prices, stock, promo codes, delivery zones and reports.`,
+        "",
+        "Usage: cerkel <command> [options]",
+        "",
+        "Commands:",
+        ...rows.map(([a, b]) => `${a.padEnd(w)}  ${b}`),
+        "",
+        "Global options:",
+        `  --api <url>    API endpoint (env CERKEL_API_URL; default ${DEFAULT_API_URL})`,
+        "  -h, --help     Help for any command, e.g. cerkel theme pull --help",
+        "  --version      Print the version",
+        "",
+        "Environment: CERKEL_TOKEN is used instead of a stored login (CI). The old names RAIZN_TOKEN and",
+        "RAIZN_API_URL still work. `raizn` still runs this tool for now (it prints that it is now cerkel).",
+        "",
+        "Workflow: cerkel login --store <slug> → cerkel theme pull → cerkel theme dev → cerkel theme submit -m \"…\"",
+        "A new theme: cerkel theme init <folder> → cd <folder> → cerkel theme push --new → cerkel theme dev.",
+        "Each login is for one store, and each theme folder uses its own store's login. `cerkel logins` lists yours.",
+        "There is no theme publish command. submit sends the draft for approval; for the store owner's login it",
+        "publishes immediately (a rollback link is printed). Otherwise the owner approves and publishes it",
+        "in the Cerkel admin.",
+    ];
+}
+function commandHelp(c) {
+    return [`Usage: ${c.usage}`, "", c.summary + ".", ...(c.help.length ? ["", ...c.help] : []), "", "Global: --api <url>, -h/--help"];
+}
+/** Find the command words (`theme pull`) among argv, skipping flags and the value of `--api`. */
+function splitCommand(argv) {
+    const words = [];
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const wanted = words.length === 0 || (words.length === 1 && GROUPS.has(words[0]));
+        if (!wanted || a.startsWith("-")) {
+            rest.push(a);
+            if (a === "--api" && i + 1 < argv.length)
+                rest.push(argv[++i]);
+            continue;
+        }
+        words.push(a);
+    }
+    return { words, rest };
+}
+export async function main(argv, ctx) {
+    // Before a Session exists, still never echo anything token-shaped.
+    const redact = makeRedactor(() => envTokenSecrets(ctx.env));
+    const fail = (msg, code = 1) => {
+        ctx.io.err(redact(msg));
+        return code;
+    };
+    if (argv.includes("--version") || (argv.length === 1 && argv[0] === "-v")) {
+        ctx.io.out(ctx.version);
+        return 0;
+    }
+    const { words, rest } = splitCommand(argv);
+    if (words.length === 0) {
+        for (const line of mainHelp(ctx.version))
+            ctx.io.out(line);
+        return rest.includes("--help") || rest.includes("-h") || argv.length === 0 ? 0 : 1;
+    }
+    const name = words.join(" ");
+    const command = Object.hasOwn(COMMANDS, name) ? COMMANDS[name] : undefined;
+    // `cerkel product publish` is a real command; `cerkel theme publish` / `cerkel publish` never are.
+    if (!command && words.some((w) => NEVER.has(w)))
+        return fail(`\`cerkel ${words.join(" ")}\` ${NEVER_MESSAGE}`);
+    if (!command) {
+        if (words.length === 1 && GROUPS.has(words[0])) {
+            const subs = Object.keys(COMMANDS).filter((k) => k.startsWith(`${words[0]} `));
+            return fail(`Usage: cerkel ${words[0]} <${subs.map((k) => k.split(" ")[1]).join("|")}>. See cerkel --help.`);
+        }
+        const hint = Object.hasOwn(HINTS, name) ? HINTS[name] : undefined;
+        return fail(`Unknown command "${name}".${hint ? ` Did you mean \`${hint}\`?` : ""} See cerkel --help.`);
+    }
+    let values;
+    let positionals;
+    // A negative number (`cerkel inventory adjust JL-90 -2`) is an argument, not a flag: shield it from
+    // parseArgs, then hand it back unchanged (as a positional or as an option's value).
+    const NEG = /^-\d+(\.\d+)?$/;
+    const SHIELD = "\u0000";
+    const unshield = (x) => (x.startsWith(SHIELD) ? x.slice(1) : x);
+    try {
+        ({ values, positionals } = parseArgs({ args: rest.map((a) => (NEG.test(a) ? SHIELD + a : a)), options: { ...GLOBAL, ...command.options }, allowPositionals: true, strict: true }));
+        positionals = positionals.map(unshield);
+        values = Object.fromEntries(Object.entries(values).map(([k, x]) => [k, typeof x === "string" ? unshield(x) : Array.isArray(x) ? x.map((y) => (typeof y === "string" ? unshield(y) : y)) : x]));
+    }
+    catch (e) {
+        return fail(`${e instanceof Error ? e.message : String(e)}\nUsage: ${command.usage}`);
+    }
+    if (values["help"] === true) {
+        for (const line of commandHelp(command))
+            ctx.io.out(line);
+        return 0;
+    }
+    const takesFiles = name === "theme push" || name === "theme history" || name === "theme restore" || name === "theme delete" || name.startsWith("section ") || command.positionals === true;
+    if (!takesFiles && positionals.length > 0)
+        return fail(`Unexpected argument "${positionals[0]}".\nUsage: ${command.usage}`);
+    const s = new Session(ctx, typeof values["api"] === "string" ? values["api"] : undefined);
+    try {
+        return await command.run(s, values, positionals);
+    }
+    catch (e) {
+        return fail(s.redact(describeError(e, ctx.now())));
+    }
+}
+/** One friendly prefix, then the server's own words — never paraphrased, never swallowed. */
+export function describeError(e, now) {
+    // Already one line that says what to run ("This login is for X — run `cerkel login --store Y`.").
+    if (e instanceof StoreLoginError)
+        return e.message;
+    if (e instanceof AuthError)
+        return `Not authorised: ${e.message}`;
+    if (e instanceof RateLimitError) {
+        return `Rate limited: ${e.message} Try again in ${e.retryAfterSeconds}s (after ${retryAt(e.retryAfterSeconds, now)}).`;
+    }
+    if (e instanceof ToolRefusal) {
+        const detail = e.details === undefined ? "" : `\n${JSON.stringify(e.details, null, 2)}`;
+        return `The server refused this (${e.tool}): ${e.code}: ${e.serverMessage}${detail}`;
+    }
+    if (e instanceof ApiUrlError || e instanceof CliError)
+        return e.message;
+    if (e instanceof Error)
+        return `Unexpected error: ${e.message}`;
+    return `Unexpected error: ${String(e)}`;
+}
+/** For tests and docs: every command this CLI has. */
+export const COMMAND_NAMES = Object.keys(COMMANDS);

package/dist/client.js

@@ -0,0 +1,125 @@
+import { AuthError, RateLimitError, ServerError, ToolRefusal } from "./errors.js";
+/**
+ * The whole wire protocol: one JSON-RPC `tools/call` per POST, bearer token in the header,
+ * `structuredContent` back. See docs/theme-cli/contract.md.
+ */
+export const PROTOCOL_VERSION = "2025-06-18";
+const REQUEST_TIMEOUT_MS = 120_000;
+const DEFAULT_RETRY_SECONDS = 60;
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Tools that report per-file outcomes: `isError` there means "some file failed", not "refused". */
+const BATCH_TOOLS = new Set(["put_theme_files", "validate_theme_files"]);
+export class McpClient {
+    opts;
+    nextId = 1;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get url() {
+        return this.opts.url;
+    }
+    /** `tools/list`: every tool with its input schema and annotations (`readOnlyHint` decides `cerkel call`'s write gate). */
+    async listTools() {
+        const result = await this.rpc("tools/list", {});
+        const tools = isRecord(result) && Array.isArray(result["tools"]) ? result["tools"] : null;
+        if (!tools)
+            throw new ServerError(`Unexpected response from ${this.opts.url.origin}: tools/list returned no tools.`, null);
+        return tools;
+    }
+    async call(tool, args) {
+        const result = (await this.rpc("tools/call", { name: tool, arguments: args }));
+        const structured = result.structuredContent ?? fromText(result);
+        if (isRecord(structured) && typeof structured["error"] === "string") {
+            throw new ToolRefusal(tool, structured["error"], typeof structured["message"] === "string" ? structured["message"] : "", structured["details"]);
+        }
+        if (result.isError && !BATCH_TOOLS.has(tool)) {
+            const msg = result.content?.find((c) => typeof c.text === "string")?.text ?? "the tool reported an error";
+            throw new ToolRefusal(tool, "error", msg, undefined);
+        }
+        return structured;
+    }
+    /** One JSON-RPC request → its `result`, or the error the person should see. */
+    async rpc(method, params) {
+        const body = JSON.stringify({ jsonrpc: "2.0", id: this.nextId++, method, params });
+        let res;
+        try {
+            res = await this.opts.fetch(this.opts.url.href, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${this.opts.token}`,
+                    "content-type": "application/json",
+                    accept: "application/json",
+                    "mcp-protocol-version": PROTOCOL_VERSION,
+                    ...(this.opts.userAgent ? { "user-agent": this.opts.userAgent } : {}),
+                },
+                body,
+                // A redirect could carry the request (and our Authorization header) somewhere other than
+                // the URL the person configured. The endpoint never redirects, so one is a misconfiguration.
+                redirect: "error",
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (e) {
+            const cause = e instanceof Error ? (e.cause instanceof Error ? e.cause.message : e.message) : String(e);
+            throw new ServerError(`Could not reach ${this.opts.url.origin}: ${cause}`, null);
+        }
+        const text = await res.text();
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // A proxy's HTML error page: fall through to the status-based messages below.
+            parsed = null;
+        }
+        const rpcError = isRecord(parsed) && isRecord(parsed["error"]) ? parsed["error"] : null;
+        const serverMessage = typeof rpcError?.message === "string" ? rpcError.message : null;
+        if (res.status === 401) {
+            const reason = typeof rpcError?.data?.["reason"] === "string" ? rpcError.data["reason"] : null;
+            throw new AuthError(serverMessage ?? "The server rejected this token (401). Run `cerkel login --store <slug>` to sign in again.", reason);
+        }
+        if (res.status === 429) {
+            throw new RateLimitError(serverMessage ?? "Rate limit exceeded for this token.", retryAfterFrom(res, rpcError));
+        }
+        if (res.status === 413) {
+            throw new ServerError(serverMessage ?? "The request was too large for the server (413).", 413);
+        }
+        if (!res.ok) {
+            throw new ServerError(serverMessage ? `Server error ${res.status}: ${serverMessage}` : `Server error ${res.status} from ${this.opts.url.origin}.`, res.status);
+        }
+        if (rpcError) {
+            throw new ServerError(`Server error ${rpcError.code ?? ""}: ${serverMessage ?? "unknown error"}`.replace(/ {2,}/g, " "), res.status);
+        }
+        if (!isRecord(parsed) || !isRecord(parsed["result"])) {
+            throw new ServerError(`Unexpected response from ${this.opts.url.origin}: not a JSON-RPC result.`, res.status);
+        }
+        return parsed["result"];
+    }
+}
+/** Older servers put the JSON only in `content[0].text`; read it from there when that is all we have. */
+function fromText(result) {
+    const text = result.content?.find((c) => c.type === "text" && typeof c.text === "string")?.text;
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function retryAfterFrom(res, err) {
+    const header = res.headers.get("retry-after");
+    if (header) {
+        const n = Number(header);
+        if (Number.isFinite(n) && n >= 0)
+            return Math.ceil(n);
+        const at = Date.parse(header);
+        if (Number.isFinite(at))
+            return Math.max(1, Math.ceil((at - Date.now()) / 1000));
+    }
+    const fromBody = err?.data?.retryAfterSeconds;
+    if (typeof fromBody === "number" && Number.isFinite(fromBody) && fromBody >= 0)
+        return Math.ceil(fromBody);
+    return DEFAULT_RETRY_SECONDS;
+}

package/dist/command.js

@@ -0,0 +1,2 @@
+export const str = (v, k) => (typeof v[k] === "string" ? v[k] : undefined);
+export const bool = (v, k) => v[k] === true;