@raizn/cli 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+# @raizn/cli — the `raizn` theme CLI
+
+Edit a Raizn Commerce store's theme as local files, by hand or with Claude Code. Preview it on the
+store's real domain and send it for approval. It works like Shopify CLI, with one difference:
+**it can never make anything live.** There is no publish, unpublish or rollback command, and there
+never will be. A person with publish rights approves and publishes in the Raizn admin.
+
+Requires Node.js 20 or newer.
+
+## Install and log in
+
+```sh
+npm i -g @raizn/cli       # or run any command with npx @raizn/cli …
+raizn login               # opens the browser: sign in to Raizn, press Allow, done
+```
+
+Like Shopify CLI, the package is public and holds no secrets. Everything is decided by the server:
+what you can do follows your staff role and stores in the Raizn admin, on every call. Removing
+someone in Settings → Staff cuts their CLI off on the next command.
+
+`raizn login` opens `/cli/authorize` on ecom.raizn.com. You sign in as usual (WhatsApp code or
+password + authenticator) and press **Allow**. The browser then hands a one-time code back to
+`raizn` on this computer (127.0.0.1 only), and `raizn` trades it for your token. The code is
+useless to anyone else, because it needs a secret that never leaves this process (PKCE). The token
+lasts 90 days and appears in Settings → AI assistant connection (MCP) as "raizn CLI — <computer>",
+where you can revoke it.
+
+No browser on this machine (a server over SSH)? Create a token by hand in that Settings page and run
+`raizn login --token`, or pipe it in with `echo "$TOKEN" | raizn login`.
+
+**Releasing a new version** (maintainers): bump `version` in `packages/cli/package.json` in a PR,
+merge it, then run the **Publish raizn CLI** workflow (GitHub → Actions). It needs the repository
+secret `NPM_TOKEN`: an npm granular access token with read-and-write access to the `@raizn` scope.
+
+Either way, `login` checks the token with the server before saving it, and prints who you are, the
+stores the token can reach and its permissions. A token the server rejects is not saved.
+
+The token is stored in your OS keychain (service `raizn-cli`, account = the API origin). If there is
+no keychain, it goes to `~/.config/raizn/credentials` (`%APPDATA%\raizn\credentials` on Windows)
+with `0600` permissions. `raizn logout` removes it from both places.
+
+
+## Workflow
+
+```sh
+raizn stores                              # which stores this token can reach
+raizn theme list --store nahleh           # live + draft themes
+mkdir nahleh-theme && cd nahleh-theme
+raizn theme pull --store nahleh           # newest draft (offers to create one from live if none)
+raizn theme dev                           # push on save + preview link on the real store domain
+raizn theme check                         # validate changed files (nothing saved)
+raizn theme submit -m "Ramadan homepage"  # send for approval; prints the admin link
+```
+
+- **pull** downloads a draft into the current folder (or `--dir`). Use `--theme <id>` to choose a
+  specific draft. If the store has no draft, `pull` asks whether to create one from the live theme
+  (`--yes` answers for you, and scripts must pass it). If you have local changes, `pull` refuses
+  unless you pass `--force`.
+- **dev** pushes pending changes first, then watches the folder. A burst of saves goes to the server
+  as one request, about a second after you stop typing. Errors show inline as
+  `path:line:col message`. It prints a signed preview link and fetches a fresh one before the
+  30-minute link expires. Ctrl-C stops it.
+- **push** uploads only the files you changed since the last pull or push. If someone else changed
+  a file on the server in the meantime (a teammate, or the admin editor), `push` refuses that file,
+  prints a diff (server vs yours) and exits 1. Merge the changes and push again, or use `--force`
+  to overwrite the server's copy.
+- **preview** prints the signed preview link, and `--open` opens it in your browser.
+- **submit** refuses while you have unpushed changes. It prints the request id and
+  `https://ecom.raizn.com/themes/requests/<id>`.
+
+### Custom sections
+
+```sh
+raizn section new promo-strip --starter blank   # writes sections/promo-strip.* locally
+raizn theme push                                # creates it on the store
+raizn section history promo-strip
+raizn section restore promo-strip 3             # old body becomes a NEW version; history kept
+raizn section delete promo-strip                # refused while any template uses it
+```
+
+Custom sections belong to the **store**, not to one draft. Every draft previews the same draft copy
+of a section. Customers keep seeing the published copy until a theme approval that uses the section
+is published (the request pins the section versions at submission), or until someone presses
+Publish in the admin. `submit` lists the custom sections that will go live with the request.
+
+## Folder layout
+
+```
+templates/index.json            templates/<name>.json (product, product.<suffix>, collection…, page…, …)
+layout/header.json              layout/footer.json
+config/settings.json            theme settings (merged on write: deleting a key does not remove it)
+assets/custom.css               the theme's custom CSS
+sections/<type>.liquid          custom section template
+sections/<type>.schema.json     its schema (name and group live inside)
+sections/<type>.css             its CSS, when it has any
+.raizn/state.json               what was pulled: api, store, theme, and each file's server tag + local hash
+.raizn/.gitignore               "*", so .raizn never lands in git
+```
+
+Anything else in the folder, such as a README or a `.git` directory, is ignored. Files are written
+exactly as the server sends them, so Arabic text round-trips byte for byte. A git checkout with
+`core.autocrlf` does not count as modified, because line endings are normalised to LF before
+comparing and sending. `push` never deletes a file on the server. Use `raizn section delete` for
+sections.
+
+A read-only reference copy of the **live** theme can be pulled into its own folder:
+
+```sh
+raizn theme pull --store nahleh --live --dir ../nahleh-live
+```
+
+`push`, `dev`, `submit` and the section write commands refuse to run in that folder. The live theme
+is never pulled for editing.
+
+## What this can never do
+
+- Publish, unpublish or roll back a theme or a section. `raizn theme publish` explains that
+  publishing happens in the admin after approval.
+- Write to the live theme. The server refuses it (`not_a_draft`), and the CLI refuses first.
+- Reach anything but the theme: no orders, customers, staff or payments.
+- Talk to any host but the configured API. `*.vercel.app` is refused (Jordanian ISPs reset those
+  connections), and plain `http` is only allowed for `localhost`.
+
+The server authorises every call. The CLI's own checks are there for convenience, and when the
+server refuses (`permission_denied`, `store_not_allowed`, `not_a_draft`, …), its message is shown
+verbatim. A 401 (revoked or expired token) is never retried. On a 429, the CLI prints when you can
+retry: `dev` waits it out and keeps your queued changes, and other commands exit 1.
+
+## CI
+
+```yaml
+- run: npx @raizn/cli theme check --store nahleh
+  env:
+    RAIZN_TOKEN: ${{ secrets.RAIZN_TOKEN }}
+```
+
+When `RAIZN_TOKEN` is set, it is used instead of any stored token and is never saved. Without a
+`.raizn/state.json`, `theme check --store <slug>` validates every theme file in the folder. It exits
+1 on any error; warnings alone exit 0.
+
+## Options
+
+| | |
+|---|---|
+| `--api <url>` / `RAIZN_API_URL` | API endpoint. The default is `https://ecom.raizn.com/api/mcp`. The URL a folder was pulled from is recorded in its state, and later commands in that folder reuse it. |
+| `RAIZN_TOKEN` | Token for CI; takes precedence over the stored one. |
+| `raizn <command> --help` | Help for any command. |
+
+The token is never printed, logged or written to project files. Every line the CLI prints passes
+through a redactor.
+
+## Development
+
+```sh
+pnpm --filter @raizn/cli build       # tsc → dist/, bin = dist/bin.js
+pnpm --filter @raizn/cli test        # vitest, against a mocked endpoint (no network, no keychain)
+node packages/cli/dist/bin.js --help
+```
+
+The wire contract with the server is in `docs/theme-cli/contract.md`.

package/dist/api-url.js

@@ -0,0 +1,42 @@
+/** Where the CLI is allowed to send a token, decided once, before any request is built. */
+export const DEFAULT_API_URL = "https://ecom.raizn.com/api/mcp";
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+export class ApiUrlError extends Error {
+    name = "ApiUrlError";
+}
+/**
+ * Parse and vet an API URL. Refuses:
+ * - `*.vercel.app` — Jordanian ISPs reset any connection whose SNI or Host names it, so the
+ *   command would hang or fail in the market we serve; custom domains only.
+ * - plain http anywhere but loopback — the token rides in a header and must not cross a network
+ *   in clear text. Loopback http is allowed for local development against `pnpm dev:admin`.
+ * - credentials embedded in the URL, which would be sent alongside (and logged with) the request.
+ */
+export function parseApiUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        throw new ApiUrlError(`"${raw}" is not a valid URL. Expected something like ${DEFAULT_API_URL}.`);
+    }
+    const host = url.hostname.toLowerCase().replace(/\.$/, "");
+    if (host === "vercel.app" || host.endsWith(".vercel.app")) {
+        throw new ApiUrlError(`Refusing ${url.origin}: *.vercel.app addresses are blocked by Jordanian ISPs. Use the store platform's custom domain (default ${DEFAULT_API_URL}).`);
+    }
+    if (url.username || url.password) {
+        throw new ApiUrlError("Refusing an API URL with a username or password in it. Use `raizn login` for the token.");
+    }
+    if (url.protocol === "http:") {
+        if (!LOOPBACK.has(host)) {
+            throw new ApiUrlError(`Refusing ${url.origin}: the API must use https (plain http is only allowed for localhost).`);
+        }
+    }
+    else if (url.protocol !== "https:") {
+        throw new ApiUrlError(`Refusing ${url.protocol} URL: the API must use https.`);
+    }
+    url.hash = "";
+    return url;
+}
+/** Credentials are keyed by origin so `/api/mcp` vs `/api/mcp/` never splits one login in two. */
+export const apiOrigin = (url) => url.origin;

package/dist/api.js

@@ -0,0 +1,29 @@
+import { ServerError } from "./errors.js";
+export const listStores = (c) => c.call("list_stores", {});
+/**
+ * The server answers `list_themes` with a bare array today; accept `{ themes }` too so a later
+ * server that wraps it (structuredContent is meant to be an object) does not break old CLIs.
+ */
+export async function listThemes(c, store) {
+    const r = await c.call("list_themes", { store });
+    if (Array.isArray(r))
+        return r;
+    if (r && typeof r === "object" && Array.isArray(r.themes))
+        return r.themes;
+    throw new ServerError("Unexpected list_themes answer from the server.", 200);
+}
+export const createDraft = (c, store, name, fromThemeId) => c.call("create_draft", { store, name, ...(fromThemeId ? { fromThemeId } : {}) });
+export const getThemeFiles = (c, store, themeId) => c.call("get_theme_files", { store, ...(themeId ? { themeId } : {}) });
+export const putThemeFiles = (c, store, themeId, files, force) => c.call("put_theme_files", { store, themeId, files, ...(force ? { force: true } : {}) });
+export const validateThemeFiles = (c, store, themeId, files) => c.call("validate_theme_files", { store, ...(themeId ? { themeId } : {}), files });
+export const getPreviewUrl = (c, store, themeId) => c.call("get_preview_url", { store, themeId });
+export const submitForApproval = (c, store, themeId, title, description) => c.call("submit_for_approval", {
+    store,
+    themeId,
+    title,
+    ...(description ? { description } : {}),
+});
+export const listSectionStarters = (c) => c.call("list_section_starters", {});
+export const deleteCustomSection = (c, store, type) => c.call("delete_custom_section", { store, type });
+export const listCustomSectionVersions = (c, store, type, limit) => c.call("list_custom_section_versions", { store, type, ...(limit ? { limit } : {}) });
+export const restoreCustomSectionVersion = (c, store, type, version) => c.call("restore_custom_section_version", { store, type, version });

package/dist/bin.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { hostname } from "node:os";
+import { watch } from "node:fs";
+import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+import { main } from "./cli.js";
+import { globalTimers } from "./context.js";
+import { FileCredentialStore, SystemCredentialStore, credentialsFilePath } from "./credentials.js";
+function version() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+async function ask(question, hidden) {
+    // Prompts go to stderr so `raizn … > out.txt` still shows them and never captures them.
+    let muted = false;
+    const output = new Writable({
+        write(chunk, _enc, cb) {
+            if (!muted)
+                process.stderr.write(chunk);
+            cb();
+        },
+    });
+    const rl = createInterface({ input: process.stdin, output, terminal: process.stdin.isTTY === true });
+    try {
+        const pending = rl.question(question);
+        // Mute only after the prompt itself is written, so the question shows but keystrokes do not.
+        muted = hidden;
+        return await pending;
+    }
+    finally {
+        rl.close();
+        if (hidden)
+            process.stderr.write("\n");
+    }
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const c of process.stdin)
+        chunks.push(typeof c === "string" ? Buffer.from(c) : c);
+    return Buffer.concat(chunks).toString("utf8");
+}
+const io = {
+    out: (line) => process.stdout.write(line + "\n"),
+    err: (line) => process.stderr.write(line + "\n"),
+    isTTY: process.stdin.isTTY === true && process.stderr.isTTY === true,
+    prompt: (q) => ask(q, false),
+    promptSecret: (q) => ask(q, true),
+    readStdin,
+};
+function openUrl(url) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", '""', url.replace(/&/g, "^&")]] : ["xdg-open", [url]];
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true, windowsVerbatimArguments: process.platform === "win32" });
+        child.on("error", () => {
+            process.stderr.write(`Could not open a browser; open the link above yourself.\n`);
+            resolve();
+        });
+        child.unref();
+        resolve();
+    });
+}
+const CALLBACK_PAGE = `<!doctype html><meta charset="utf-8"><title>raizn</title>
+<body style="font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;line-height:1.5">
+<h1 style="font-size:1.25rem">You can close this tab</h1><p>Go back to your terminal — raizn has what it needs.</p></body>`;
+/**
+ * The browser half of `raizn login` lands here: 127.0.0.1 only (never 0.0.0.0, so nothing on the
+ * network can reach it), a random free port, one callback, then it closes.
+ */
+function listenLoopback() {
+    return new Promise((resolve, reject) => {
+        let deliver = null;
+        let got = null;
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (req.method !== "GET" || url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" }).end(CALLBACK_PAGE);
+            if (!got) {
+                got = url.searchParams;
+                deliver?.(got);
+            }
+        });
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            resolve({
+                port,
+                waitForCallback: (timeoutMs) => new Promise((res, rej) => {
+                    if (got)
+                        return res(got);
+                    const t = setTimeout(() => rej(new Error("timeout")), timeoutMs);
+                    deliver = (q) => { clearTimeout(t); res(q); };
+                }),
+                close: () => { server.close(); server.closeAllConnections?.(); },
+            });
+        });
+    });
+}
+const ctx = {
+    cwd: process.cwd(),
+    env: process.env,
+    fetch: (input, init) => fetch(input, init),
+    credentials: new SystemCredentialStore(new FileCredentialStore(credentialsFilePath())),
+    io,
+    now: () => new Date(),
+    timers: globalTimers,
+    watch: (dir, onChange) => {
+        const w = watch(dir, { recursive: true }, (_event, filename) => onChange(filename ? filename.toString() : null));
+        w.on("error", (e) => process.stderr.write(`Watch error: ${e.message}\n`));
+        return w;
+    },
+    openUrl,
+    listenLoopback,
+    hostname: hostname(),
+    onInterrupt: (handler) => {
+        process.on("SIGINT", handler);
+        return () => process.off("SIGINT", handler);
+    },
+    version: version(),
+};
+main(process.argv.slice(2), ctx).then((code) => {
+    process.exitCode = code;
+}, (e) => {
+    // main() already redacts and reports every expected failure; this is the last-ditch net.
+    process.stderr.write(`Unexpected error: ${e instanceof Error ? e.message.replace(/rzn_[A-Za-z0-9_-]{16,}/g, "***") : "unknown"}\n`);
+    process.exitCode = 1;
+});

package/dist/chunk.js

@@ -0,0 +1,31 @@
+import { writeRank } from "./layout.js";
+/**
+ * The server refuses bodies over 1,000,000 bytes. Aim well under it so the envelope, JSON
+ * escaping of Arabic text and a proxy's own headers never tip a request over.
+ */
+export const MAX_CHUNK_BYTES = 800_000;
+const ENVELOPE_BYTES = 512;
+/**
+ * Split files into requests, keeping the server's write order across requests: every section
+ * goes out before any settings/CSS, and those before any template. A single file larger than
+ * the limit travels alone and the server's 413 explains itself.
+ */
+export function chunkFiles(files, limit = MAX_CHUNK_BYTES) {
+    const ordered = [...files].sort((a, b) => writeRank(a.path) - writeRank(b.path) || a.path.localeCompare(b.path));
+    const chunks = [];
+    let current = [];
+    let size = ENVELOPE_BYTES;
+    for (const f of ordered) {
+        const bytes = Buffer.byteLength(JSON.stringify(f), "utf8") + 1;
+        if (current.length > 0 && size + bytes > limit) {
+            chunks.push(current);
+            current = [];
+            size = ENVELOPE_BYTES;
+        }
+        current.push(f);
+        size += bytes;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}

package/dist/cli.js

@@ -0,0 +1,262 @@
+import { parseArgs } from "node:util";
+import { ApiUrlError } from "./api-url.js";
+import { login, logout, stores, whoami } from "./commands/auth.js";
+import { themeDev } from "./commands/dev.js";
+import { sectionDelete, sectionHistory, sectionNew, sectionRestore } from "./commands/section.js";
+import { themeCheck, themeList, themePreview, themePull, themePush, themeSubmit } from "./commands/theme.js";
+import { AuthError, CliError, RateLimitError, ToolRefusal, retryAt } from "./errors.js";
+import { makeRedactor } from "./redact.js";
+import { Session } from "./session.js";
+const GLOBAL = {
+    api: { type: "string" },
+    help: { type: "boolean", short: "h" },
+};
+const str = (v, k) => (typeof v[k] === "string" ? v[k] : undefined);
+const bool = (v, k) => v[k] === true;
+const COMMANDS = {
+    login: {
+        usage: "raizn login [--token]",
+        summary: "Sign in through the browser (or paste a token with --token)",
+        help: [
+            "Opens ecom.raizn.com in your browser: sign in as usual, press Allow, and you are logged in.",
+            "The token is saved to the system keychain, or to ~/.config/raizn/credentials (0600) when there",
+            "is no keychain. It follows your staff access and can be revoked in Settings → AI assistant",
+            "connection (MCP).",
+            "--token: paste a token created by hand instead (e.g. on a server with no browser).",
+            "In scripts: echo \"$TOKEN\" | raizn login. With RAIZN_TOKEN set, it verifies that token and saves nothing.",
+        ],
+        options: { token: { type: "boolean" } },
+        run: (s, v) => login(s, { token: bool(v, "token") }),
+    },
+    logout: { usage: "raizn logout", summary: "Remove the stored token", help: [], options: {}, run: (s) => logout(s) },
+    whoami: { usage: "raizn whoami", summary: "Show who the token belongs to and what it can reach", help: [], options: {}, run: (s) => whoami(s) },
+    stores: { usage: "raizn stores", summary: "List the stores this token can reach", help: [], options: {}, run: (s) => stores(s) },
+    "theme list": {
+        usage: "raizn theme list --store <slug>",
+        summary: "List the store's live and draft themes",
+        help: [],
+        options: { store: { type: "string" } },
+        run: (s, v) => themeList(s, { ...(str(v, "store") ? { store: str(v, "store") } : {}) }),
+    },
+    "theme pull": {
+        usage: "raizn theme pull --store <slug> [--theme <id>] [--yes] [--dir <path>] [--force]\n       raizn theme pull --store <slug> --live --dir <path>",
+        summary: "Download a draft theme into this folder",
+        help: [
+            "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: "raizn 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: "raizn theme push [files…] [--force]",
+        summary: "Upload changed files to the 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; --force overwrites the server's copy.",
+        ],
+        options: { force: { type: "boolean" } },
+        run: (s, v, pos) => themePush(s, { files: pos, force: bool(v, "force") }),
+    },
+    "theme dev": {
+        usage: "raizn 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."],
+        options: {},
+        run: (s) => themeDev(s),
+    },
+    "theme preview": {
+        usage: "raizn 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: 'raizn theme submit -m "title" [--description "…"]',
+        summary: "Send the draft for approval (a person publishes it in the admin)",
+        help: ["Refuses while there are unpushed changes. Prints the request id and its admin link."],
+        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") } : {}),
+        }),
+    },
+    "section new": {
+        usage: "raizn section new <type> [--starter <key>]",
+        summary: "Create a custom section's files locally from a starter",
+        help: ["Writes sections/<type>.liquid, .schema.json and .css (when the starter has CSS). The next push creates it on the store."],
+        options: { starter: { type: "string" } },
+        run: (s, v, pos) => sectionNew(s, pos[0], { ...(str(v, "starter") ? { starter: str(v, "starter") } : {}) }),
+    },
+    "section delete": {
+        usage: "raizn section delete <type>",
+        summary: "Delete a custom section from the store",
+        help: ["Refused by the server while any theme's template still places it."],
+        options: {},
+        run: (s, _v, pos) => sectionDelete(s, pos[0]),
+    },
+    "section history": {
+        usage: "raizn section history <type> [--limit <n>]",
+        summary: "List a custom section's versions",
+        help: [],
+        options: { limit: { type: "string" } },
+        run: (s, v, pos) => {
+            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 sectionHistory(s, pos[0], { ...(limit ? { limit } : {}) });
+        },
+    },
+    "section restore": {
+        usage: "raizn section restore <type> <version> [--force]",
+        summary: "Restore an old version as a new draft version",
+        help: ["History is never rewritten: the old body becomes a new version. Local files are refreshed."],
+        options: { force: { type: "boolean" } },
+        run: (s, v, pos) => sectionRestore(s, pos[0], pos[1], { force: bool(v, "force") }),
+    },
+};
+const GROUPS = new Set(["theme", "section"]);
+/** 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 can never make anything live: publishing happens in the Raizn admin after approval.\n" +
+    'Run `raizn theme submit -m "…"`, then someone with publish rights reviews and publishes it in the admin.';
+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 [
+        `raizn ${version} — edit a Raizn Commerce store's theme as local files.`,
+        "",
+        "Usage: raizn <command> [options]",
+        "",
+        "Commands:",
+        ...rows.map(([a, b]) => `${a.padEnd(w)}  ${b}`),
+        "",
+        "Global options:",
+        "  --api <url>    API endpoint (env RAIZN_API_URL; default https://ecom.raizn.com/api/mcp)",
+        "  -h, --help     Help for any command, e.g. raizn theme pull --help",
+        "  --version      Print the version",
+        "",
+        "Environment: RAIZN_TOKEN is used instead of a stored token (CI).",
+        "",
+        "Workflow: raizn login → raizn theme pull --store <slug> → raizn theme dev → raizn theme submit -m \"…\"",
+        "Nothing here can publish. A person approves and publishes in the Raizn 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(() => [ctx.env["RAIZN_TOKEN"]]);
+    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;
+    }
+    if (words.some((w) => NEVER.has(w)))
+        return fail(`\`raizn ${words.join(" ")}\` ${NEVER_MESSAGE}`);
+    const name = words.join(" ");
+    const command = COMMANDS[name];
+    if (!command) {
+        if (words.length === 1 && GROUPS.has(words[0])) {
+            const subs = Object.keys(COMMANDS).filter((k) => k.startsWith(`${words[0]} `));
+            return fail(`Usage: raizn ${words[0]} <${subs.map((k) => k.split(" ")[1]).join("|")}>. See raizn --help.`);
+        }
+        return fail(`Unknown command "${name}". See raizn --help.`);
+    }
+    let values;
+    let positionals;
+    try {
+        ({ values, positionals } = parseArgs({ args: [...rest], options: { ...GLOBAL, ...command.options }, allowPositionals: true, strict: true }));
+    }
+    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.startsWith("section ");
+    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) {
+    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);