@cerkel/cli 0.0.0-stage → 1.0.1

package/dist/commands/theme.js

@@ -0,0 +1,388 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { apiOrigin } from "../api-url.js";
+import { createDraft, getPreviewUrl, getThemeFiles, listThemes, submitForApproval, validateThemeFiles, } from "../api.js";
+import { chunkFiles } from "../chunk.js";
+import { diffStats } from "../diff.js";
+import { CliError } from "../errors.js";
+import { formatIssue, plural, table } from "../format.js";
+import { bytesOf, hashBytes, isGeneratedPath, isLayoutPath, legacySectionPartOf, textOf, toDiskPath, toLayoutPath } from "../layout.js";
+import { findRoot, listLegacySectionParts, listLocalFiles, localChanges, readLocal, readState, writeState } from "../state.js";
+import { conflictAdvice, pushChanges, pushDeletes } from "../sync.js";
+const byNewest = (a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? "");
+// --- list --------------------------------------------------------------------
+export async function themeList(s, opts) {
+    const co = await s.checkout();
+    // --store, else this folder's store, else the store of your one login.
+    const store = opts.store ?? co?.state.store ?? (await s.defaultStore());
+    // The folder's recorded API (its theme ids only mean something there), and the login for `store`.
+    const themes = await listThemes(await s.client(co?.state, store), store);
+    const rank = (t) => (t.role === "live" ? 0 : t.role === "draft" ? 1 : 2);
+    const rows = [...themes].sort((a, b) => rank(a) - rank(b) || byNewest(a, b));
+    if (rows.length === 0) {
+        s.err(`${store} has no themes.`);
+        return 0;
+    }
+    for (const line of table([["ID", "NAME", "ROLE", "UPDATED"], ...rows.map((t) => [t.id, t.name, t.role, t.updatedAt ?? "—"])]))
+        s.out(line);
+    return 0;
+}
+export async function themePull(s, opts) {
+    const root = opts.dir ? path.resolve(s.ctx.cwd, opts.dir) : ((await findRoot(s.ctx.cwd)) ?? s.ctx.cwd);
+    const existing = await readState(root);
+    if (opts.live) {
+        if (!opts.dir) {
+            throw new CliError("--live needs --dir <folder>. The live theme is only ever pulled as a read-only reference, into a folder of its own.");
+        }
+        const enclosing = await findRoot(root);
+        const enclosingState = enclosing ? await readState(enclosing) : null;
+        if (enclosingState && !enclosingState.readOnly) {
+            throw new CliError(`${enclosing} is an editable draft checkout. Pull the live theme into a different folder, e.g. --dir ../live-reference.`);
+        }
+        if (opts.theme)
+            throw new CliError("--live and --theme cannot be combined: --live always means the store's live theme.");
+    }
+    else if (existing?.readOnly) {
+        throw new CliError(`${root} holds a read-only copy of the live theme. Pull a draft into a different folder (--dir <folder>).`);
+    }
+    // --store, else this folder's store, else the store of your one login.
+    const store = opts.store ?? existing?.store ?? (await s.defaultStore());
+    // One theme folder is bound to one store (and so to that store's login): another store gets its own folder.
+    if (existing && existing.store !== store) {
+        throw new CliError(`${root} is the theme folder of ${existing.store}. Pull ${store} into a folder of its own: \`cerkel theme pull --store ${store} --dir <folder>\`.`);
+    }
+    const client = await s.client(existing, store);
+    let files;
+    if (opts.live) {
+        files = await getThemeFiles(client, store);
+    }
+    else {
+        const themeId = await chooseDraft(s, client, store, opts, existing);
+        files = await getThemeFiles(client, store, themeId);
+        if (files.theme.role === "live") {
+            // The server decides what a theme is; if it says live, we will not open it for editing.
+            throw new CliError(`Theme ${themeId} is the LIVE theme. It is never pulled for editing; use --live --dir <folder> for a read-only copy.`);
+        }
+    }
+    // Refuse before touching anything if local work would be overwritten.
+    const incoming = new Map();
+    const skipped = [];
+    for (const f of files.files) {
+        if (!isLayoutPath(f.path)) {
+            skipped.push(f.path);
+            continue;
+        }
+        incoming.set(f.path, { content: f.content, tag: f.tag, hash: hashBytes(bytesOf(f.content)) });
+    }
+    const { changes } = await localChanges(root, existing);
+    const atRisk = changes.filter((c) => incoming.get(c.path)?.hash !== c.hash);
+    if (atRisk.length > 0 && !opts.force) {
+        const list = atRisk.slice(0, 20).map((c) => `  ${c.kind === "new" ? "new     " : "modified"}  ${c.path}`);
+        throw new CliError([
+            `${root} has ${plural(atRisk.length, "local change")} that pulling would overwrite or leave behind:`,
+            ...list,
+            ...(atRisk.length > 20 ? [`  … and ${atRisk.length - 20} more`] : []),
+            "Push them first (`cerkel theme push`), or re-run with --force to replace them with the server's copy.",
+        ].join("\n"));
+    }
+    let written = 0;
+    let same = 0;
+    const nextFiles = {};
+    for (const [p, f] of incoming) {
+        const disk = toDiskPath(root, p);
+        const current = await readLocal(root, p);
+        if (current && hashBytes(current) === f.hash)
+            same++;
+        else {
+            await fs.mkdir(path.dirname(disk), { recursive: true });
+            await fs.writeFile(disk, bytesOf(f.content));
+            written++;
+        }
+        nextFiles[p] = { tag: f.tag, hash: f.hash };
+    }
+    // Files the server no longer has: remove only what we can prove is ours and untouched.
+    let removed = 0;
+    const kept = [];
+    const known = existing?.files ?? {};
+    const candidates = new Set([...Object.keys(known), ...changes.map((c) => c.path)]);
+    for (const p of candidates) {
+        if (incoming.has(p))
+            continue;
+        const bytes = await readLocal(root, p);
+        if (!bytes)
+            continue;
+        if (known[p] && known[p].hash === hashBytes(bytes)) {
+            await fs.rm(toDiskPath(root, p), { force: true });
+            removed++;
+        }
+        else
+            kept.push(p);
+    }
+    const readOnly = opts.live;
+    await writeState(root, {
+        version: 1,
+        api: client.url.href,
+        store,
+        themeId: files.theme.id,
+        themeName: files.theme.name,
+        role: files.theme.role,
+        readOnly,
+        pulledAt: s.ctx.now().toISOString(),
+        files: nextFiles,
+    });
+    s.out(`Pulled "${files.theme.name}" (${files.theme.role}, ${files.theme.id}) from ${store} into ${root}`);
+    s.out(`  ${plural(incoming.size, "file")}: ${written} written, ${same} already up to date${removed ? `, ${removed} removed` : ""}`);
+    for (const p of skipped)
+        s.err(`  skipped ${p}: not a theme file path this CLI knows how to store`);
+    for (const p of kept) {
+        const legacy = legacySectionPartOf(p);
+        if (legacy)
+            s.err(`  kept ${p}: sections are ONE file now — move your changes into the {% ${p.endsWith(".css") ? "stylesheet" : "schema"} %} of sections/${legacy}.liquid, then delete ${p}`);
+        else
+            s.err(`  kept ${p}: the server no longer has it, but your copy has changes`);
+    }
+    if (readOnly) {
+        s.out("This is a READ-ONLY copy of the live theme, for reference. push, dev and submit refuse to run here.");
+    }
+    else {
+        s.out("Next: `cerkel theme dev` to edit with a live preview, then `cerkel theme submit -m \"…\"`.");
+    }
+    return 0;
+}
+async function chooseDraft(s, client, store, opts, existing) {
+    const themes = await listThemes(client, store);
+    const live = themes.find((t) => t.role === "live");
+    if (opts.theme) {
+        const t = themes.find((x) => x.id === opts.theme);
+        if (!t)
+            throw new CliError(`No theme ${opts.theme} on ${store}. See \`cerkel theme list --store ${store}\`.`);
+        if (t.role === "live") {
+            throw new CliError(`Theme ${t.id} ("${t.name}") is the LIVE theme. It is never pulled for editing. Pull a draft (or omit --theme to create one), or use --live --dir <folder> for a read-only copy.`);
+        }
+        if (t.role !== "draft")
+            throw new CliError(`Theme ${t.id} is ${t.role}; only drafts can be pulled for editing.`);
+        return t.id;
+    }
+    // Re-running pull in a checkout refreshes the draft it already tracks.
+    if (existing && existing.store === store && themes.some((t) => t.id === existing.themeId && t.role === "draft"))
+        return existing.themeId;
+    const drafts = themes.filter((t) => t.role === "draft").sort(byNewest);
+    if (drafts[0]) {
+        if (drafts.length > 1)
+            s.err(`Using the newest draft "${drafts[0].name}" (${drafts[0].id}); pass --theme <id> for another.`);
+        return drafts[0].id;
+    }
+    const from = live ? ` from the live theme "${live.name}"` : "";
+    if (!opts.yes) {
+        if (!s.ctx.io.isTTY) {
+            throw new CliError(`${store} has no draft theme. Re-run with --yes to create one${from}.`);
+        }
+        const answer = (await s.ctx.io.prompt(`${store} has no draft theme. Create a draft${from}? [y/N] `)).trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes")
+            throw new CliError("No draft created; nothing pulled.");
+    }
+    const name = live ? `${live.name} (draft)` : "Draft";
+    const made = await createDraft(client, store, name, live?.id);
+    s.err(`Created draft "${made.name}" (${made.themeId}).`);
+    return made.themeId;
+}
+// --- check -------------------------------------------------------------------
+export async function themeCheck(s, opts) {
+    const co = await s.checkout();
+    let root;
+    let store;
+    let themeId;
+    let paths;
+    if (co) {
+        root = co.root;
+        store = opts.store ?? co.state.store;
+        themeId = store === co.state.store ? co.state.themeId : undefined;
+        paths = opts.all ? await listLocalFiles(root) : (await localChanges(root, co.state)).changes.map((c) => c.path);
+    }
+    else {
+        // CI: a plain git checkout of theme files, no state — validate everything against the store.
+        if (!opts.store)
+            throw new CliError("This folder is not a theme checkout. Pass --store <slug> to validate every theme file in it.");
+        root = s.ctx.cwd;
+        store = opts.store;
+        paths = await listLocalFiles(root);
+    }
+    if (paths.length === 0) {
+        s.out(co && !opts.all ? "Nothing to check: no changed files. Use --all to check every file." : "No theme files found in this folder.");
+        return 0;
+    }
+    const files = [];
+    for (const p of paths) {
+        const bytes = await readLocal(root, p);
+        if (bytes)
+            files.push({ path: p, content: textOf(bytes) });
+    }
+    const client = await s.client(co?.state, store);
+    let errors = 0;
+    let warnings = 0;
+    for (const chunk of chunkFiles(files)) {
+        const r = await validateThemeFiles(client, store, themeId, chunk);
+        for (const res of r.results ?? []) {
+            for (const issue of res.errors ?? []) {
+                s.out(formatIssue(res.path, issue));
+                if (issue.severity === "error")
+                    errors++;
+                else
+                    warnings++;
+            }
+        }
+    }
+    s.err(`Checked ${plural(files.length, "file")}: ${plural(errors, "error")}, ${plural(warnings, "warning")}.`);
+    return errors > 0 ? 1 : 0;
+}
+// --- push --------------------------------------------------------------------
+export async function themePush(s, opts) {
+    const { root, state } = await s.requireCheckout({ editable: true });
+    const legacy = await listLegacySectionParts(root);
+    if (legacy.length > 0) {
+        throw new CliError([
+            "This checkout still has section files in the old three-file layout:",
+            ...legacy.map((p) => `  ${p}`),
+            "A section is ONE file now: sections/<type>.liquid holds its Liquid, its {% stylesheet %} and its {% schema %}.",
+            "Run `cerkel theme pull` to get the new layout (it removes the old files you did not change), move any changes into the .liquid file, then push.",
+        ].join("\n"));
+    }
+    let only;
+    if (opts.files.length > 0) {
+        only = [];
+        for (const f of opts.files) {
+            const p = toLayoutPath(root, path.resolve(s.ctx.cwd, f));
+            if (!p || !isLayoutPath(p))
+                throw new CliError(`${f} is not a theme file in this checkout (${root}).`);
+            only.push(p);
+        }
+    }
+    const found = await localChanges(root, state, only);
+    const changes = found.changes.filter((c) => !isGeneratedPath(c.path));
+    for (const c of found.changes)
+        if (isGeneratedPath(c.path))
+            s.err(`  ${c.path} is generated by Cerkel from your theme's files; your edit to it is not pushed.`);
+    const deleted = opts.noDelete ? [] : found.deleted;
+    if (opts.noDelete)
+        for (const p of found.deleted)
+            s.err(`  ${p} was deleted locally; kept on the server (--nodelete).`);
+    if (changes.length === 0 && deleted.length === 0) {
+        s.out("Nothing to push.");
+        return 0;
+    }
+    // The folder's store login first: without one there is nothing to push with.
+    const client = await s.client(state);
+    // Writes first, deletes last: a template that stops placing a section must land before that
+    // section's file can be deleted (the server refuses deleting a section a template still places).
+    const del = async () => {
+        if (deleted.length === 0)
+            return { deleted: 0, failed: 0 };
+        const d = await pushDeletes(s, client, root, state, deleted);
+        return { deleted: d.deleted, failed: d.failed.length };
+    };
+    if (changes.length === 0) {
+        const d = await del();
+        s.err(`${d.deleted} deleted, ${d.failed} failed.`);
+        return d.failed > 0 ? 1 : 0;
+    }
+    s.err(`Pushing ${plural(changes.length, "file")} to "${state.themeName}" on ${state.store}${opts.force ? " (--force: server changes in conflicting files are listed and confirmed before they are overwritten)" : ""}…`);
+    // Even with --force, the first attempt is a normal one: files nobody else touched land as
+    // usual, and each conflict comes back with the server's copy, so we can say what would be lost.
+    const r = await pushChanges(s, client, root, state, changes, { force: false });
+    let saved = r.saved;
+    let unchanged = r.unchanged;
+    let failed = r.invalid.length + r.refused.length;
+    if (opts.force && r.conflicts.length > 0) {
+        const targets = changes.filter((c) => r.conflicts.includes(c.path));
+        await confirmOverwrite(s, targets, r.serverCopies, opts.yes === true);
+        // Claim the exact server version that was shown: if it changes again while the person was
+        // reading, that is a new conflict, not one more silent loss. Only a server that sent no copy
+        // at all leaves us with a plain force.
+        const blind = targets.some((c) => r.serverCopies.get(c.path) === undefined);
+        const baseTags = new Map(targets.map((c) => [c.path, r.serverCopies.get(c.path)?.tag ?? null]));
+        const r2 = await pushChanges(s, client, root, state, targets, blind ? { force: true } : { force: false, baseTags });
+        conflictAdvice(s, r2.conflicts);
+        saved += r2.saved;
+        unchanged += r2.unchanged;
+        failed += r2.conflicts.length + r2.invalid.length + r2.refused.length;
+    }
+    else {
+        conflictAdvice(s, r.conflicts);
+        failed += r.conflicts.length;
+    }
+    const d = await del();
+    failed += d.failed;
+    s.err(`${saved} saved, ${unchanged} unchanged${d.deleted ? `, ${d.deleted} deleted` : ""}, ${failed} failed.`);
+    return failed > 0 ? 1 : 0;
+}
+/** One line per file: what overwriting the server's copy with ours throws away. */
+export function overwriteSummary(server, local) {
+    if (server === null)
+        return "deleted on the server since you last synced it; pushing puts your copy back";
+    if (server === undefined)
+        return "the server did not send its copy; every server change to it since you last synced will be lost";
+    const d = diffStats(server.content, local);
+    if (d.removed === 0)
+        return `no server lines will be lost (your file adds ${plural(d.added, "line")} the server's copy does not have)`;
+    return `${plural(d.removed, "server line")} not in your file will be lost (${plural(d.places, "place")})`;
+}
+async function confirmOverwrite(s, targets, serverCopies, yes) {
+    s.err(`--force would overwrite the server's copy of ${plural(targets.length, "file")} (diffs above: - is the server's, + is yours):`);
+    for (const c of targets)
+        s.err(`  ${c.path}: ${overwriteSummary(serverCopies.get(c.path), textOf(c.bytes))}`);
+    if (yes)
+        return;
+    if (!s.ctx.io.isTTY) {
+        throw new CliError(`Not overwritten: --force needs confirmation, and there is no terminal to ask in. Re-run with --force --yes to discard those server changes, or merge them into your files and push again.`);
+    }
+    const answer = (await s.ctx.io.prompt(`Overwrite ${targets.length === 1 ? "it" : "them"} and lose those server changes? [y/N] `)).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+        throw new CliError("Nothing overwritten. Merge the server's changes into your files and push again, or `cerkel theme pull --force` to take the server's version.");
+    }
+}
+// --- preview -----------------------------------------------------------------
+export async function themePreview(s, opts) {
+    const { state } = await s.requireCheckout({ editable: false });
+    const r = await getPreviewUrl(await s.client(state), state.store, state.themeId);
+    s.out(r.url);
+    if (r.expiresAt)
+        s.err(`Signed link; expires ${r.expiresAt}.`);
+    if (opts.open)
+        await s.ctx.openUrl(r.url);
+    return 0;
+}
+// --- submit ------------------------------------------------------------------
+export async function themeSubmit(s, opts) {
+    const title = opts.title?.trim();
+    if (!title)
+        throw new CliError('A title is required: cerkel theme submit -m "What this change does".');
+    const { root, state } = await s.requireCheckout({ editable: true });
+    const { changes } = await localChanges(root, state);
+    if (changes.length > 0) {
+        throw new CliError([
+            `You have ${plural(changes.length, "unpushed change")}; the approval would not include them:`,
+            ...changes.slice(0, 20).map((c) => `  ${c.path}`),
+            "Run `cerkel theme push` first, then submit.",
+        ].join("\n"));
+    }
+    const client = await s.client(state);
+    const r = await submitForApproval(client, state.store, state.themeId, title, opts.description);
+    const link = `${apiOrigin(client.url)}/themes/requests/${encodeURIComponent(r.requestId)}`;
+    // The theme's own files that differ from the live theme (sections, blocks, snippets, assets…).
+    const files = r.files && r.files.length > 0 ? r.files.map((x) => `${x.path} (${x.change})`).join(", ") : null;
+    if (r.published) {
+        // The store's owner/admin (a login carrying themes.publish, held in this store) and Raizn's own
+        // team skip review: the server approved and published it in the same step.
+        s.out(`Published "${state.themeName}" — it is LIVE now (you can publish in this store, so it skipped review). Request ${r.requestId}`);
+        if (files)
+            s.out(`Files that went live with it: ${files}.`);
+        s.out(`Something wrong? Roll it back in one click: ${link}`);
+        return 0;
+    }
+    s.out(`Submitted "${state.themeName}" for approval: request ${r.requestId}`);
+    s.out(`Review it: ${link}`);
+    if (files)
+        s.out(`Files in this request: ${files}.`);
+    s.out("Nothing is live yet. Someone with publish rights approves and publishes it in the Cerkel admin.");
+    return 0;
+}

package/dist/commands/whatsapp.js

@@ -0,0 +1,39 @@
+import { str } from "../command.js";
+import { WRITE_HELP, WRITE_OPTIONS, flagsOf, runWrite } from "../commerce.js";
+import { CliError } from "../errors.js";
+/** `cerkel whatsapp test` — one approved template to a phone, from the store's number (send_whatsapp_test). */
+export const WHATSAPP_COMMANDS = {
+    "whatsapp test": {
+        usage: "cerkel whatsapp test <template> --to <+962…> [--values \"v1|v2|…\"] [--language ar] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Send an approved WhatsApp template to a phone, to try it",
+        help: [
+            "Sends the template from the store's WhatsApp number with the values in {{1}}, {{2}}… order, separated by | (a value may contain commas).",
+            "The template needs no mapping on the store and no order; the store's Enable sending switch does not apply. A tap on the",
+            "test message's buttons moves no order. Review buttons still rate that phone's latest real review request (72 h): tap them",
+            "only from a phone with no recent order.",
+            "WhatsApp's answer is printed: the message id, or its error (132001 = no such template in that language, 132000 = wrong number of values).",
+            WRITE_HELP,
+        ],
+        options: { ...WRITE_OPTIONS, to: { type: "string" }, values: { type: "string" }, language: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel whatsapp test <template> --to <+962…> [--values \"v1|v2\"]");
+            const to = str(v, "to");
+            if (!to)
+                throw new CliError("--to is required: the phone to send to, e.g. +962791234567.");
+            const values = (str(v, "values") ?? "").split("|").map((x) => x.trim()).filter(Boolean);
+            const language = str(v, "language");
+            return runWrite(s, flagsOf(v), "send_whatsapp_test", { template: pos[0], to: to.replace(/\s+/g, ""), values, ...(language ? { language } : {}) }, {
+                after: (a) => {
+                    const r = a.afterCommit;
+                    if (!r)
+                        throw new CliError("The server did not say whether WhatsApp accepted the message. Check the store's WhatsApp thread.");
+                    if (!r.ok)
+                        throw new CliError(`WhatsApp refused it${r.code !== undefined ? ` (${r.code})` : ""}: ${r.message ?? r.error}`);
+                    return [`Sent: ${a.summary}`, `WhatsApp message id: ${r.waMessageId ?? "—"}`];
+                },
+            });
+        },
+    },
+};

package/dist/commands/zone.js

@@ -0,0 +1,90 @@
+import { bool, str } from "../command.js";
+import { READ_HELP, READ_OPTIONS, WRITE_HELP, WRITE_OPTIONS, flagsOf, moneyFlag, runRead, runWrite, show } from "../commerce.js";
+import { CliError } from "../errors.js";
+import { table } from "../format.js";
+const ZONE_OPTIONS = {
+    "name-ar": { type: "string" }, "name-en": { type: "string" }, "name-ckb": { type: "string" },
+    governorates: { type: "string" }, fee: { type: "string" }, "free-over": { type: "string" }, eta: { type: "string" },
+    active: { type: "boolean" }, inactive: { type: "boolean" },
+};
+function zoneArgs(v) {
+    const out = {};
+    const name = {};
+    for (const l of ["ar", "en", "ckb"]) {
+        const n = str(v, `name-${l}`);
+        if (n !== undefined)
+            name[l] = n;
+    }
+    if (Object.keys(name).length)
+        out["name"] = name;
+    const govs = str(v, "governorates");
+    if (govs !== undefined)
+        out["governorates"] = govs.split(",").map((g) => g.trim()).filter(Boolean);
+    if (str(v, "fee") !== undefined)
+        out["fee"] = str(v, "fee").trim();
+    const free = moneyFlag(str(v, "free-over"));
+    if (free !== undefined)
+        out["freeOver"] = free;
+    const eta = str(v, "eta");
+    if (eta !== undefined) {
+        if (["", "none", "null", "-"].includes(eta.trim().toLowerCase()))
+            out["etaDays"] = null;
+        else {
+            const n = Number(eta);
+            if (!Number.isInteger(n) || n < 0 || n > 30)
+                throw new CliError("--eta is a whole number of days, 0–30 (or none).");
+            out["etaDays"] = n;
+        }
+    }
+    if (bool(v, "active") && bool(v, "inactive"))
+        throw new CliError("--active or --inactive, not both.");
+    if (bool(v, "active"))
+        out["active"] = true;
+    if (bool(v, "inactive"))
+        out["active"] = false;
+    return out;
+}
+/** `cerkel zone …` — delivery zones (list_delivery_zones, upsert_delivery_zone, delete_delivery_zone). */
+export const ZONE_COMMANDS = {
+    "zone list": {
+        usage: "cerkel zone list [--store <slug>] [--json]",
+        summary: "List the store's delivery zones and fees",
+        help: ["--json also lists every governorate of the store's country and the zone that prices it.", READ_HELP],
+        options: READ_OPTIONS,
+        run: (s, v) => runRead(s, flagsOf(v), "list_delivery_zones", {}, (d) => table([["ID", "NAME", "GOVERNORATES", "FEE", "FREE OVER", "DAYS", "ON"], ...d.zones.map((z) => [
+                z.id, z.name["en"] ?? z.name["ar"] ?? "", z.governorates.map((g) => g.code).join(","), show(z.fee), show(z.freeOver), z.etaDays == null ? "—" : String(z.etaDays), z.active ? "yes" : "no",
+            ])])),
+    },
+    "zone set": {
+        usage: "cerkel zone set [<zone-id>] [--name-ar <name>] [--name-en <name>] [--governorates JO-AM,JO-IR|*] [--fee <money>] [--free-over <money|none>] [--eta <days|none>] [--active|--inactive] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Create a delivery zone, or change one (with its id)",
+        help: [
+            "Without an id: creates a zone (needs --name-ar, --governorates and --fee). With an id: changes only what you pass.",
+            "Governorates are ISO codes of the store's country (JO-AM, IQ-BG…; cerkel zone list --json shows them) or * for every other governorate.",
+            "Fees in the store's currency: 2.000 (JOD), 5000 (IQD, steps of 250).",
+            WRITE_HELP,
+        ],
+        options: { ...WRITE_OPTIONS, ...ZONE_OPTIONS },
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length > 1)
+                throw new CliError("Usage: cerkel zone set [<zone-id>] [options]");
+            const args = zoneArgs(v);
+            if (!Object.keys(args).length)
+                throw new CliError("Nothing to set: pass --fee, --governorates, --name-ar … (see cerkel zone set --help).");
+            return runWrite(s, flagsOf(v), "upsert_delivery_zone", { ...(pos[0] ? { zone: pos[0] } : {}), ...args });
+        },
+    },
+    "zone delete": {
+        usage: "cerkel zone delete <zone-id> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Delete a delivery zone",
+        help: ["Its governorates fall to the * zone, or can no longer check out without one. To pause it: cerkel zone set <id> --inactive.", WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel zone delete <zone-id>");
+            return runWrite(s, flagsOf(v), "delete_delivery_zone", { zone: pos[0] });
+        },
+    },
+};

package/dist/commerce.js

@@ -0,0 +1,138 @@
+import { listStores } from "./api.js";
+import { bool, str } from "./command.js";
+import { CliError } from "./errors.js";
+// ---------------------------------------------------------------------------
+// The commerce command framework (`cerkel product …`, `cerkel price …`, `cerkel inventory …`, and the
+// phase B/C groups). Every command is a thin layer over ONE MCP tool:
+//
+//   * reads  — `runRead`: call the tool, print a table or `--json`;
+//   * writes — `runWrite`: call the tool with `dry_run: true`, print the diff the SERVER computed,
+//     ask to confirm on a terminal (`--yes` answers for you; `--dry-run` stops after the diff), then
+//     call it for real. Without a terminal a write needs `--yes` and is refused before anything is
+//     sent. The server decides everything — permission, store, money rules — and its refusal is
+//     shown verbatim; the CLI never does money arithmetic (amounts go to the server as typed and
+//     are parsed there by @raizn/money; what comes back is shown by its `formatted`).
+//
+// The store is the login's own store (one store per login), or `--store`, or the theme folder's.
+// ---------------------------------------------------------------------------
+/** Flags every commerce command takes. */
+export const READ_OPTIONS = {
+    store: { type: "string" },
+    json: { type: "boolean" },
+};
+/** Flags every commerce WRITE command takes. */
+export const WRITE_OPTIONS = {
+    ...READ_OPTIONS,
+    yes: { type: "boolean", short: "y" },
+    "dry-run": { type: "boolean" },
+};
+export const READ_HELP = "--store <slug> (default: your login's store), --json for machine-readable output.";
+export const WRITE_HELP = "Shows the change and asks before applying it. --yes applies without asking (required without a terminal), --dry-run only shows it. --json prints the server's answer as JSON.";
+export const flagsOf = (v) => ({
+    ...(str(v, "store") ? { store: str(v, "store") } : {}),
+    json: bool(v, "json"),
+    yes: bool(v, "yes"),
+    dryRun: bool(v, "dry-run"),
+});
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** A value as a person reads it: money by its `formatted`, nothing as "—", text as is. */
+export function show(v) {
+    if (v === null || v === undefined)
+        return "—";
+    if (isRecord(v) && typeof v["formatted"] === "string" && typeof v["amount"] === "number")
+        return v["formatted"];
+    if (typeof v === "string")
+        return v === "" ? '""' : v;
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    return JSON.stringify(v);
+}
+/** `  price: 15.000 JOD → 18.000 JOD` per changed field. */
+export const diffLines = (diff) => diff.map((d) => `  ${d.path}: ${show(d.before)} → ${show(d.after)}`);
+/**
+ * The store a command acts on, and a client for it. `--store`, else the theme folder's store, else
+ * the login's store when it has exactly one. Never lists stores in an error: the server is the
+ * authority on what this login may reach, and other stores are not this command's business.
+ */
+export async function storeAndClient(s, flags) {
+    const state = (await s.checkout())?.state ?? null;
+    const client = await s.client(state);
+    if (flags.store)
+        return { client, store: flags.store };
+    if (state?.store)
+        return { client, store: state.store };
+    const who = await listStores(client);
+    if (who.stores.length === 1)
+        return { client, store: who.stores[0].slug };
+    if (who.stores.length === 0)
+        throw new CliError("This login cannot reach any store. Run `cerkel login --store <slug>`.");
+    throw new CliError("Which store? Pass --store <slug>.");
+}
+/** A read command: one tool call, then a table (or `--json`). */
+export async function runRead(s, flags, tool, args, render) {
+    const { client, store } = await storeAndClient(s, flags);
+    const data = await client.call(tool, { store, ...args });
+    if (flags.json)
+        s.out(JSON.stringify(data, null, 2));
+    else
+        for (const line of render(data, store))
+            s.out(line);
+    return 0;
+}
+/**
+ * A write command: dry run → diff → confirm → apply. Returns the exit code.
+ * `after` renders the applied outcome (default: "Done." plus the summary).
+ */
+export async function runWrite(s, flags, tool, args, opts = {}) {
+    // Scripts: refuse before sending anything, so a forgotten flag never half-runs.
+    if (!flags.yes && !flags.dryRun && !s.ctx.io.isTTY) {
+        throw new CliError("This changes the store, and there is no terminal to confirm in. Re-run with --yes to apply it, or --dry-run to only see the change.");
+    }
+    const { client, store } = await storeAndClient(s, flags);
+    const preview = await client.call(tool, { store, ...args, dry_run: true });
+    if (!preview.changed) {
+        if (flags.json)
+            s.out(JSON.stringify(preview, null, 2));
+        else
+            s.out(`Nothing to change: ${preview.summary}`);
+        return 0;
+    }
+    if (flags.json && (flags.dryRun || !flags.yes)) {
+        // JSON callers see the server's own preview; only --yes applies in JSON mode.
+        s.out(JSON.stringify(preview, null, 2));
+        if (flags.dryRun)
+            return 0;
+    }
+    else {
+        s.out(preview.summary);
+        for (const line of diffLines(preview.diff))
+            s.out(line);
+        if (flags.dryRun) {
+            s.err("Dry run: nothing was changed.");
+            return 0;
+        }
+    }
+    if (!flags.yes) {
+        const answer = (await s.ctx.io.prompt(`Apply this change to ${store}? [y/N] `)).trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes") {
+            s.err("Cancelled. Nothing was changed.");
+            return 1;
+        }
+    }
+    const applied = await client.call(tool, { store, ...args, dry_run: false });
+    if (flags.json) {
+        s.out(JSON.stringify(applied, null, 2));
+        return 0;
+    }
+    if (JSON.stringify(applied.diff) !== JSON.stringify(preview.diff)) {
+        // Someone changed the same thing while this was waiting for an answer: say what really happened.
+        s.err("The store changed while you were confirming. This is what was applied:");
+        for (const line of diffLines(applied.diff))
+            s.err(line);
+    }
+    for (const line of opts.after ? opts.after(applied) : [applied.changed ? `Done: ${applied.summary}` : `Nothing to change: ${applied.summary}`])
+        s.out(line);
+    return 0;
+}
+/** `--compare-at none` / `--cost none` / an empty value → null (remove it); anything else is sent as typed. */
+export const moneyFlag = (v) => v === undefined ? undefined : ["", "none", "null", "-"].includes(v.trim().toLowerCase()) ? null : v.trim();