@raizn/cli 0.1.0

package/dist/client.js

@@ -0,0 +1,112 @@
+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;
+    }
+    async call(tool, args) {
+        const body = JSON.stringify({ jsonrpc: "2.0", id: this.nextId++, method: "tools/call", params: { name: tool, arguments: args } });
+        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) {
+            throw new AuthError(serverMessage ?? "The server rejected this token (401). Run `raizn login` with a valid token.");
+        }
+        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);
+        }
+        const result = parsed["result"];
+        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;
+    }
+}
+/** 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/commands/auth.js

@@ -0,0 +1,141 @@
+import { createHash, randomBytes } from "node:crypto";
+import { apiOrigin } from "../api-url.js";
+import { listStores } from "../api.js";
+import { AuthError, CliError } from "../errors.js";
+import { table } from "../format.js";
+function describe(s, who, origin) {
+    const you = who.you;
+    const name = [you?.name, you?.email ? `<${you.email}>` : null].filter(Boolean).join(" ");
+    s.out(`Logged in to ${origin}${name ? ` as ${name}` : ""}`);
+    if (who.token?.prefix || who.token?.name) {
+        s.out(`Token: ${who.token.prefix ?? ""}…${who.token.name ? ` (${who.token.name})` : ""}`);
+    }
+    s.out(`Permissions: ${who.grantedPermissions.length ? who.grantedPermissions.join(", ") : "(none)"}`);
+    if (who.stores.length === 0) {
+        s.out("Stores: none — this token cannot reach any store yet.");
+        return;
+    }
+    s.out("Stores:");
+    for (const line of table(who.stores.map((st) => [`  ${st.slug}`, st.name])))
+        s.out(line);
+}
+/** How long the browser half may take: signing in with a WhatsApp code and an authenticator included. */
+export const BROWSER_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const b64url = (b) => b.toString("base64url");
+/**
+ * Shopify-CLI-style login: open the admin in the browser, the person signs in as they always do
+ * and presses Allow, and the admin hands a token back to a listener on 127.0.0.1. PKCE means the
+ * one-time code in that redirect is useless to anyone but this process (see the admin's
+ * lib/cli-login.ts for the server half).
+ */
+async function browserLogin(s, origin) {
+    const verifier = b64url(randomBytes(32));
+    const challenge = b64url(createHash("sha256").update(verifier).digest());
+    const state = b64url(randomBytes(24));
+    const lb = await s.ctx.listenLoopback();
+    let q;
+    try {
+        const url = new URL("/cli/authorize", origin);
+        url.search = new URLSearchParams({ port: String(lb.port), state, challenge, device: s.ctx.hostname.slice(0, 60) }).toString();
+        s.err("Opening your browser to sign in to Raizn. Press Allow there, then come back here.");
+        s.err(`If it does not open, visit: ${url.href}`);
+        await s.ctx.openUrl(url.href);
+        try {
+            q = await lb.waitForCallback(BROWSER_LOGIN_TIMEOUT_MS);
+        }
+        catch {
+            throw new CliError("Timed out waiting for the browser (5 minutes). Run `raizn login` again.");
+        }
+    }
+    finally {
+        lb.close();
+    }
+    if (q.get("state") !== state)
+        throw new CliError("The browser answered a different login request. Run `raizn login` again.");
+    if (q.get("error"))
+        throw new CliError(q.get("error") === "access_denied" ? "Sign-in was cancelled in the browser." : `Sign-in failed in the browser (${q.get("error")}).`);
+    const code = q.get("code");
+    if (!code)
+        throw new CliError("The browser returned no sign-in code. Run `raizn login` again.");
+    let res;
+    try {
+        res = await s.ctx.fetch(new URL("/api/cli/token", origin).href, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ code, verifier }),
+            redirect: "error",
+        });
+    }
+    catch (e) {
+        throw new CliError(`Could not reach ${origin}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || typeof body.token !== "string") {
+        throw new CliError(typeof body.message === "string" ? body.message : `Sign-in failed (HTTP ${res.status}). Run \`raizn login\` again.`);
+    }
+    return body.token;
+}
+export async function login(s, opts = {}) {
+    const url = s.api();
+    const origin = apiOrigin(url);
+    const env = s.ctx.env["RAIZN_TOKEN"]?.trim();
+    let token;
+    if (env) {
+        // CI: verify what the pipeline will use, but never copy an injected secret into a keychain.
+        s.err("RAIZN_TOKEN is set; verifying it. It is used instead of any stored token, so nothing is saved.");
+        token = env;
+    }
+    else if (!s.ctx.io.isTTY) {
+        token = (await s.ctx.io.readStdin()).trim();
+    }
+    else if (opts.token) {
+        s.err(`Create a token in the Raizn admin at Settings → AI assistant connection (MCP) (${origin}).`);
+        token = (await s.ctx.io.promptSecret("Paste your token (input hidden): ")).trim();
+    }
+    else {
+        token = await browserLogin(s, origin);
+    }
+    if (!token)
+        throw new CliError("No token entered.");
+    s.addSecret(token);
+    let who;
+    try {
+        who = await listStores(s.clientWith(url, token));
+    }
+    catch (e) {
+        if (e instanceof AuthError)
+            throw new AuthError(`Token not saved: ${e.message}`);
+        throw e;
+    }
+    if (!env) {
+        const where = await s.ctx.credentials.set(origin, token);
+        s.err(where === "keychain" ? "Token saved to the system keychain." : "Token saved to the credentials file (no system keychain available).");
+    }
+    describe(s, who, origin);
+    return 0;
+}
+export async function logout(s) {
+    const origin = apiOrigin(s.api((await s.checkout())?.state));
+    const removed = await s.ctx.credentials.delete(origin);
+    s.out(removed ? `Logged out of ${origin}.` : `No stored token for ${origin}.`);
+    if (s.ctx.env["RAIZN_TOKEN"])
+        s.err("Note: RAIZN_TOKEN is still set in this environment, and commands will keep using it.");
+    return 0;
+}
+export async function whoami(s) {
+    const state = (await s.checkout())?.state;
+    const c = await s.client(state);
+    describe(s, await listStores(c), apiOrigin(c.url));
+    return 0;
+}
+export async function stores(s) {
+    const state = (await s.checkout())?.state;
+    const r = await listStores(await s.client(state));
+    if (r.stores.length === 0) {
+        s.err("This token cannot reach any store.");
+        return 0;
+    }
+    for (const line of table([["SLUG", "NAME"], ...r.stores.map((st) => [st.slug, st.name])]))
+        s.out(line);
+    return 0;
+}

package/dist/commands/dev.js

@@ -0,0 +1,228 @@
+import path from "node:path";
+import { getPreviewUrl } from "../api.js";
+import { AuthError, CliError, RateLimitError, ToolRefusal, retryAt } from "../errors.js";
+import { plural } from "../format.js";
+import { isLayoutPath } from "../layout.js";
+import { localChanges } from "../state.js";
+import { conflictAdvice, pushChanges } from "../sync.js";
+export const DEBOUNCE_MS = 1000;
+/** Signed preview links live 30 minutes; fetch the next one with five to spare. */
+export const PREVIEW_REFRESH_MS = 25 * 60 * 1000;
+const PREVIEW_MARGIN_MS = 5 * 60 * 1000;
+const PREVIEW_RETRY_MS = 5 * 60 * 1000;
+/**
+ * Editors save through temp files and swap files; none of them are theme files, and pushing
+ * them would only earn a `refused`. Anything outside the layout is ignored for the same reason.
+ */
+export function watchedPath(filename) {
+    const p = filename.split(path.sep).join("/").replace(/^\.\//, "");
+    const parts = p.split("/");
+    if (parts.some((seg) => seg.startsWith(".")))
+        return null; // .raizn/, .git/, .#emacs-lock, .DS_Store
+    const base = parts[parts.length - 1] ?? "";
+    if (base.endsWith("~") || /\.sw[a-p]$/.test(base) || base === "4913" || base.startsWith("#"))
+        return null;
+    return isLayoutPath(p) ? p : null;
+}
+/**
+ * The watch → debounce → push loop. One `put_theme_files` call per quiet second, never two in
+ * flight, and after a 429 nothing is sent until the server's retry time has passed — saves made
+ * meanwhile simply join the queue.
+ */
+export class DevLoop {
+    s;
+    client;
+    root;
+    state;
+    debounceMs;
+    pending = new Set();
+    rescanAll = false;
+    timer = null;
+    previewTimer = null;
+    inFlight = null;
+    blockedUntil = 0;
+    stopped = false;
+    finish = null;
+    done;
+    constructor(s, client, root, state, debounceMs = DEBOUNCE_MS) {
+        this.s = s;
+        this.client = client;
+        this.root = root;
+        this.state = state;
+        this.debounceMs = debounceMs;
+        this.done = new Promise((resolve) => (this.finish = resolve));
+    }
+    get timers() {
+        return this.s.ctx.timers;
+    }
+    stamp() {
+        return `[${this.s.ctx.now().toLocaleTimeString("en-GB", { hour12: false })}]`;
+    }
+    /** A filesystem event. `null` = the OS did not say which file, so rescan everything. */
+    notify(filename) {
+        if (this.stopped)
+            return;
+        if (filename === null)
+            this.rescanAll = true;
+        else {
+            const p = watchedPath(filename);
+            if (!p)
+                return;
+            this.pending.add(p);
+        }
+        this.schedule(this.debounceMs);
+    }
+    schedule(ms) {
+        if (this.stopped)
+            return;
+        if (this.timer !== null)
+            this.timers.clearTimeout(this.timer);
+        const wait = Math.max(ms, this.blockedUntil - this.s.ctx.now().getTime());
+        this.timer = this.timers.setTimeout(() => {
+            this.timer = null;
+            void this.flush();
+        }, wait);
+    }
+    async flush() {
+        if (this.stopped)
+            return;
+        if (this.inFlight) {
+            // A push is running; the files stay queued and go in the next batch once it lands.
+            await this.inFlight;
+            return;
+        }
+        const waitMs = this.blockedUntil - this.s.ctx.now().getTime();
+        if (waitMs > 0) {
+            this.schedule(waitMs);
+            return;
+        }
+        const paths = [...this.pending];
+        const all = this.rescanAll;
+        this.pending.clear();
+        this.rescanAll = false;
+        this.inFlight = this.pushBatch(paths, all);
+        try {
+            await this.inFlight;
+        }
+        finally {
+            this.inFlight = null;
+        }
+        if (!this.stopped && (this.pending.size > 0 || this.rescanAll) && this.timer === null)
+            this.schedule(this.debounceMs);
+    }
+    requeue(paths, all) {
+        for (const p of paths)
+            this.pending.add(p);
+        if (all)
+            this.rescanAll = true;
+    }
+    async pushBatch(paths, all) {
+        const { changes } = await localChanges(this.root, this.state, all ? undefined : paths);
+        if (changes.length === 0)
+            return;
+        try {
+            const r = await pushChanges(this.s, this.client, this.root, this.state, changes, { force: false, compact: true });
+            const failed = r.conflicts.length + r.invalid.length + r.refused.length;
+            this.s.err(`${this.stamp()} ${r.saved} saved${failed ? `, ${failed} not saved` : ""}${r.unchanged ? `, ${r.unchanged} unchanged` : ""}`);
+            conflictAdvice(this.s, r.conflicts);
+        }
+        catch (e) {
+            if (e instanceof RateLimitError) {
+                this.requeue(paths, all);
+                this.blockedUntil = this.s.ctx.now().getTime() + e.retryAfterSeconds * 1000;
+                this.s.err(`${this.stamp()} Rate limited: ${e.message} Waiting ${e.retryAfterSeconds}s (until ${retryAt(e.retryAfterSeconds, this.s.ctx.now())}); ${plural(this.pending.size || changes.length, "queued change")} will be sent then.`);
+                this.schedule(e.retryAfterSeconds * 1000);
+                return;
+            }
+            if (e instanceof AuthError || e instanceof ToolRefusal) {
+                // A revoked token or a theme that is no longer a draft will not fix itself; stop.
+                this.s.err(e instanceof ToolRefusal ? `The server refused the push: ${e.code}: ${e.serverMessage}` : e.message);
+                this.stop(1);
+                return;
+            }
+            this.requeue(paths, all);
+            this.s.err(`${this.stamp()} ${e instanceof Error ? e.message : String(e)} — your changes stay queued and go with your next save.`);
+        }
+    }
+    /** Print the preview link now and a fresh one before each expires. */
+    async startPreview() {
+        await this.fetchPreview(true);
+    }
+    async fetchPreview(first) {
+        if (this.stopped)
+            return;
+        let next = PREVIEW_RETRY_MS;
+        try {
+            const r = await getPreviewUrl(this.client, this.state.store, this.state.themeId);
+            this.s.out(first ? `Preview: ${r.url}` : `${this.stamp()} New preview link (the previous one is about to expire): ${r.url}`);
+            const expires = r.expiresAt ? Date.parse(r.expiresAt) : NaN;
+            next = Number.isFinite(expires)
+                ? Math.max(60_000, Math.min(PREVIEW_REFRESH_MS, expires - this.s.ctx.now().getTime() - PREVIEW_MARGIN_MS))
+                : PREVIEW_REFRESH_MS;
+        }
+        catch (e) {
+            if (e instanceof AuthError) {
+                this.s.err(e.message);
+                this.stop(1);
+                return;
+            }
+            if (e instanceof RateLimitError)
+                next = Math.max(e.retryAfterSeconds * 1000, 1000);
+            this.s.err(`${this.stamp()} Could not get a preview link: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (this.stopped)
+            return;
+        this.previewTimer = this.timers.setTimeout(() => void this.fetchPreview(false), next);
+    }
+    /** Resolves once no push is in flight — lets tests (and a clean exit) wait for the network. */
+    async idle() {
+        while (this.inFlight)
+            await this.inFlight;
+    }
+    stop(code = 0) {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.timer !== null)
+            this.timers.clearTimeout(this.timer);
+        if (this.previewTimer !== null)
+            this.timers.clearTimeout(this.previewTimer);
+        this.timer = null;
+        this.previewTimer = null;
+        this.finish?.(code);
+    }
+}
+export async function themeDev(s) {
+    const { root, state } = await s.requireCheckout({ editable: true });
+    const client = await s.client(state);
+    const { changes } = await localChanges(root, state);
+    if (changes.length > 0) {
+        s.err(`Pushing ${plural(changes.length, "pending change")} first…`);
+        const r = await pushChanges(s, client, root, state, changes, { force: false, compact: true });
+        if (r.conflicts.length > 0) {
+            conflictAdvice(s, r.conflicts);
+            throw new CliError("Resolve the conflicts above, then run `raizn theme dev` again.");
+        }
+    }
+    const loop = new DevLoop(s, client, root, state);
+    await loop.startPreview();
+    let watcher;
+    try {
+        watcher = s.ctx.watch(root, (f) => loop.notify(f));
+    }
+    catch (e) {
+        loop.stop(1);
+        throw new CliError(`Could not watch ${root}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const offInterrupt = s.ctx.onInterrupt(() => {
+        s.err("\nStopped watching. Your pushed changes are on the draft; nothing went live.");
+        loop.stop(0);
+    });
+    s.err(`Watching ${root} for changes to "${state.themeName}" on ${state.store}. Ctrl-C to stop.`);
+    const code = await loop.done;
+    watcher.close();
+    // Let a push that was mid-flight at Ctrl-C finish and record its tags before we exit.
+    await loop.idle();
+    offInterrupt();
+    return code;
+}

package/dist/commands/section.js

@@ -0,0 +1,155 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { deleteCustomSection, getThemeFiles, listCustomSectionVersions, listSectionStarters, restoreCustomSectionVersion, } from "../api.js";
+import { CliError, ToolRefusal } from "../errors.js";
+import { table } from "../format.js";
+import { SECTION_TYPE_RE, bytesOf, hashBytes, sectionPaths, sectionTypeOf, toDiskPath } from "../layout.js";
+import { readLocal, writeState } from "../state.js";
+function checkType(type) {
+    if (!type)
+        throw new CliError("Which section? Pass its type, e.g. `raizn section new promo-strip`.");
+    if (!SECTION_TYPE_RE.test(type)) {
+        throw new CliError(`"${type}" is not a valid section type: use 2–80 lowercase letters, digits, "-" or "_", starting with a letter or digit.`);
+    }
+    return type;
+}
+const schemaText = (schema) => (typeof schema === "string" ? schema : JSON.stringify(schema ?? {}, null, 2) + "\n");
+// --- new ---------------------------------------------------------------------
+/**
+ * Local only. The section reaches the server with the next push or dev, like any other edit —
+ * so it gets validated, conflict-checked and audited on the same path as everything else.
+ */
+export async function sectionNew(s, rawType, opts) {
+    const type = checkType(rawType);
+    const { root, state } = await s.requireCheckout({ editable: true });
+    const paths = sectionPaths(type);
+    for (const p of Object.values(paths)) {
+        if (state.files[p] || (await readLocal(root, p)))
+            throw new CliError(`Section "${type}" already exists (${p}). Pick another type, or edit its files.`);
+    }
+    const { starters } = await listSectionStarters(await s.client(state));
+    if (!starters || starters.length === 0)
+        throw new CliError("The server offered no section starters.");
+    let starter;
+    if (opts.starter) {
+        starter = starters.find((x) => x.key === opts.starter);
+        if (!starter)
+            throw new CliError(`No starter "${opts.starter}". Available: ${starters.map((x) => x.key).join(", ")}.`);
+    }
+    else {
+        const fallback = starters.find((x) => x.key === "blank") ?? starters[0];
+        if (s.ctx.io.isTTY) {
+            s.err("Starters:");
+            for (const line of table(starters.map((x, i) => [`  ${i + 1}.`, x.key, x.name, x.group ?? ""])))
+                s.err(line);
+            const answer = (await s.ctx.io.prompt(`Start from which? [${fallback.key}] `)).trim();
+            if (!answer)
+                starter = fallback;
+            else {
+                const n = Number(answer);
+                starter = Number.isInteger(n) && n >= 1 ? starters[n - 1] : starters.find((x) => x.key === answer);
+                if (!starter)
+                    throw new CliError(`No starter "${answer}".`);
+            }
+        }
+        else {
+            starter = fallback;
+            s.err(`Using the "${starter.key}" starter (pass --starter <key> to choose).`);
+        }
+    }
+    const writes = [
+        [paths.liquid, starter.template ?? ""],
+        [paths.schema, schemaText(starter.schema)],
+    ];
+    if (typeof starter.css === "string" && starter.css.length > 0)
+        writes.push([paths.css, starter.css]);
+    for (const [p, content] of writes) {
+        const disk = toDiskPath(root, p);
+        await fs.mkdir(path.dirname(disk), { recursive: true });
+        await fs.writeFile(disk, bytesOf(content), { flag: "wx" });
+        s.out(`  created  ${p}`);
+    }
+    s.out(`Section "${type}" created locally from "${starter.key}". Set its "name" in ${paths.schema}, then \`raizn theme push\` (or keep \`raizn theme dev\` running) to create it on the store.`);
+    s.out("Custom sections belong to the store: they go live with the first approval that uses them, once it is published.");
+    return 0;
+}
+// --- delete ------------------------------------------------------------------
+export async function sectionDelete(s, rawType) {
+    const type = checkType(rawType);
+    const { root, state } = await s.requireCheckout({ editable: true });
+    try {
+        await deleteCustomSection(await s.client(state), state.store, type);
+    }
+    catch (e) {
+        if (e instanceof ToolRefusal && e.code === "section_in_use") {
+            const usedIn = e.details?.usedIn;
+            const where = Array.isArray(usedIn) ? usedIn.map(String) : [];
+            throw new CliError([`The server refused to delete "${type}": ${e.code}: ${e.serverMessage}`, ...where.map((w) => `  used in ${w}`), "Remove it from those templates (and push) first."].join("\n"));
+        }
+        throw e;
+    }
+    for (const p of Object.values(sectionPaths(type))) {
+        await fs.rm(toDiskPath(root, p), { force: true });
+        delete state.files[p];
+    }
+    await writeState(root, state);
+    s.out(`Deleted custom section "${type}" from ${state.store} and removed its local files.`);
+    return 0;
+}
+// --- history / restore --------------------------------------------------------
+export async function sectionHistory(s, rawType, opts) {
+    const type = checkType(rawType);
+    const { state } = await s.requireCheckout({ editable: false });
+    const r = await listCustomSectionVersions(await s.client(state), state.store, type, opts.limit);
+    s.out(`${r.type}: draft v${r.version}, ${r.publishedVersion ? `live v${r.publishedVersion}` : "never published"}`);
+    const rows = r.versions.map((v) => [
+        `v${v.version}`,
+        v.createdAt,
+        v.author ?? "—",
+        [v.version === r.version ? "draft" : "", v.version === r.publishedVersion ? "live" : ""].filter(Boolean).join(", "),
+    ]);
+    for (const line of table([["VERSION", "CREATED", "AUTHOR", ""], ...rows]))
+        s.out(line);
+    return 0;
+}
+export async function sectionRestore(s, rawType, rawVersion, opts) {
+    const type = checkType(rawType);
+    const version = Number(rawVersion?.replace(/^v/i, ""));
+    if (!rawVersion || !Number.isInteger(version) || version < 1)
+        throw new CliError("Which version? e.g. `raizn section restore promo-strip 3` (see `raizn section history`).");
+    const { root, state } = await s.requireCheckout({ editable: true });
+    const paths = Object.values(sectionPaths(type));
+    // Restoring rewrites the local files; do not silently discard edits made to them.
+    if (!opts.force) {
+        for (const p of paths) {
+            const bytes = await readLocal(root, p);
+            const known = state.files[p];
+            if (bytes && (!known || known.hash !== hashBytes(bytes))) {
+                throw new CliError(`${p} has local changes that restoring would overwrite. Push or discard them, or re-run with --force.`);
+            }
+        }
+    }
+    const client = await s.client(state);
+    const r = await restoreCustomSectionVersion(client, state.store, type, version);
+    s.out(`Restored "${type}" v${r.restoredFrom} as new draft version v${r.version} (history is kept).`);
+    const all = await getThemeFiles(client, state.store, state.themeId);
+    const fresh = new Map(all.files.filter((f) => sectionTypeOf(f.path) === type).map((f) => [f.path, f]));
+    for (const p of paths) {
+        const f = fresh.get(p);
+        const disk = toDiskPath(root, p);
+        if (f) {
+            await fs.mkdir(path.dirname(disk), { recursive: true });
+            await fs.writeFile(disk, bytesOf(f.content));
+            state.files[p] = { tag: f.tag, hash: hashBytes(bytesOf(f.content)) };
+            s.out(`  updated  ${p}`);
+        }
+        else if (state.files[p] || (await readLocal(root, p))) {
+            // e.g. the restored version has no CSS.
+            await fs.rm(disk, { force: true });
+            delete state.files[p];
+            s.out(`  removed  ${p}`);
+        }
+    }
+    await writeState(root, state);
+    return 0;
+}