@cerkel/cli 0.0.0-stage → 1.0.0

package/dist/commands/promo.js

@@ -0,0 +1,140 @@
+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 PROMO_OPTIONS = {
+    percent: { type: "string" }, amount: { type: "string" }, "free-delivery": { type: "boolean" },
+    min: { type: "string" }, starts: { type: "string" }, expires: { type: "string" }, limit: { type: "string" },
+    once: { type: "boolean" }, "any-customer": { type: "boolean" }, note: { type: "string" }, active: { type: "boolean" }, inactive: { type: "boolean" },
+};
+const none = (v) => v !== undefined && ["", "none", "null", "-"].includes(v.trim().toLowerCase());
+/** Flags → create/update_promo_code arguments. Amounts go to the server as typed (it parses them in the store's currency). */
+function promoArgs(v, creating) {
+    const kinds = [str(v, "percent") !== undefined, str(v, "amount") !== undefined, bool(v, "free-delivery")].filter(Boolean).length;
+    if (kinds > 1)
+        throw new CliError("Pick one of --percent, --amount or --free-delivery.");
+    if (creating && kinds === 0)
+        throw new CliError("Say what the code gives: --percent <1-100>, --amount <money> or --free-delivery.");
+    if (bool(v, "active") && bool(v, "inactive"))
+        throw new CliError("--active or --inactive, not both.");
+    if (bool(v, "once") && bool(v, "any-customer"))
+        throw new CliError("--once or --any-customer, not both.");
+    const out = {};
+    if (str(v, "percent") !== undefined) {
+        out["type"] = "percent";
+        out["value"] = str(v, "percent").trim().replace(/%$/, "");
+    }
+    if (str(v, "amount") !== undefined) {
+        out["type"] = "fixed";
+        out["value"] = str(v, "amount").trim();
+    }
+    if (bool(v, "free-delivery"))
+        out["type"] = "free_delivery";
+    const min = moneyFlag(str(v, "min"));
+    if (min !== undefined)
+        out["minSubtotal"] = min;
+    for (const [flag, key] of [["starts", "startsOn"], ["expires", "expiresOn"]]) {
+        const d = str(v, flag);
+        if (d !== undefined)
+            out[key] = none(d) ? null : d.trim();
+    }
+    const limit = str(v, "limit");
+    if (limit !== undefined) {
+        if (none(limit))
+            out["usageLimit"] = null;
+        else {
+            const n = Number(limit);
+            if (!Number.isInteger(n) || n < 1)
+                throw new CliError("--limit is a whole number of uses (or none).");
+            out["usageLimit"] = n;
+        }
+    }
+    if (bool(v, "once"))
+        out["oncePerCustomer"] = true;
+    if (bool(v, "any-customer"))
+        out["oncePerCustomer"] = false;
+    const note = str(v, "note");
+    if (note !== undefined)
+        out["note"] = none(note) ? null : note;
+    if (bool(v, "active"))
+        out["active"] = true;
+    if (bool(v, "inactive"))
+        out["active"] = false;
+    return out;
+}
+const valueText = (p) => (p.type === "percent" ? `${p.percent}%` : p.type === "fixed" ? show(p.amountOff) : "free delivery");
+/** `cerkel promo …` — promo codes (list_promo_codes, create / update / delete_promo_code). */
+export const PROMO_COMMANDS = {
+    "promo list": {
+        usage: "cerkel promo list [--state active|inactive|scheduled|expired|used_up] [--store <slug>] [--json]",
+        summary: "List the store's promo codes and what each gives today",
+        help: [READ_HELP],
+        options: { ...READ_OPTIONS, state: { type: "string" } },
+        run: (s, v) => runRead(s, flagsOf(v), "list_promo_codes", str(v, "state") ? { state: str(v, "state") } : {}, (d) => table([["CODE", "GIVES", "MIN", "FROM", "UNTIL", "USED", "STATE"], ...d.promoCodes.map((p) => [
+                p.code, valueText(p), show(p.minSubtotal), p.startsOn ?? "—", p.expiresOn ?? "—", `${p.used}${p.usageLimit ? `/${p.usageLimit}` : ""}`, p.state,
+            ])])),
+    },
+    "promo create": {
+        usage: "cerkel promo create <code> (--percent <n> | --amount <money> | --free-delivery) [--min <money>] [--starts YYYY-MM-DD] [--expires YYYY-MM-DD] [--limit <n>] [--once] [--note <text>] [--inactive] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Create a promo code",
+        help: ["Amounts in the store's currency: 2.000 (JOD), 5000 (IQD, steps of 250). Days are the shop's local days.", WRITE_HELP],
+        options: { ...WRITE_OPTIONS, ...PROMO_OPTIONS },
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel promo create <code> --percent <n> | --amount <money> | --free-delivery");
+            return runWrite(s, flagsOf(v), "create_promo_code", { code: pos[0], ...promoArgs(v, true) });
+        },
+    },
+    "promo update": {
+        usage: "cerkel promo update <code> [--new-code <code>] [--percent <n> | --amount <money> | --free-delivery] [--min <money|none>] [--starts <day|none>] [--expires <day|none>] [--limit <n|none>] [--once | --any-customer] [--note <text|none>] [--active | --inactive] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Change a promo code",
+        help: [WRITE_HELP],
+        options: { ...WRITE_OPTIONS, ...PROMO_OPTIONS, "new-code": { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel promo update <code> [options]");
+            const args = { ...promoArgs(v, false), ...(str(v, "new-code") ? { newCode: str(v, "new-code") } : {}) };
+            if (!Object.keys(args).length)
+                throw new CliError("Nothing to change: pass at least one option (see cerkel promo update --help).");
+            return runWrite(s, flagsOf(v), "update_promo_code", { code: pos[0], ...args });
+        },
+    },
+    "promo activate": {
+        usage: "cerkel promo activate <code> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Switch a promo code on",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel promo activate <code>");
+            return runWrite(s, flagsOf(v), "update_promo_code", { code: pos[0], active: true });
+        },
+    },
+    "promo deactivate": {
+        usage: "cerkel promo deactivate <code> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Switch a promo code off (customers can no longer use it)",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel promo deactivate <code>");
+            return runWrite(s, flagsOf(v), "update_promo_code", { code: pos[0], active: false });
+        },
+    },
+    "promo delete": {
+        usage: "cerkel promo delete <code> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Delete a promo code",
+        help: ["To pause a code instead, use cerkel promo deactivate.", WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel promo delete <code>");
+            return runWrite(s, flagsOf(v), "delete_promo_code", { code: pos[0] });
+        },
+    },
+};

package/dist/commands/redirect.js

@@ -0,0 +1,94 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { bool, str } from "../command.js";
+import { READ_HELP, READ_OPTIONS, WRITE_HELP, WRITE_OPTIONS, flagsOf, runRead, runWrite } from "../commerce.js";
+import { CliError } from "../errors.js";
+import { table } from "../format.js";
+const statusOf = (v) => {
+    const raw = typeof v["status"] === "string" ? v["status"] : undefined;
+    if (bool(v, "temporary"))
+        return 302;
+    if (raw === undefined)
+        return undefined;
+    if (raw === "301" || raw === "302")
+        return Number(raw);
+    throw new CliError("--status is 301 (permanent) or 302 (temporary).");
+};
+/** `cerkel redirect …` — the store's URL redirects (list_redirects, create/update/delete_redirect, import_redirects). */
+export const REDIRECT_COMMANDS = {
+    "redirect list": {
+        usage: "cerkel redirect list [--search <text>] [--sort path|hits|updated] [--store <slug>] [--json]",
+        summary: "List the store's URL redirects with how many visitors each caught",
+        help: [READ_HELP],
+        options: { ...READ_OPTIONS, search: { type: "string" }, sort: { type: "string" } },
+        run: (s, v) => {
+            const sort = str(v, "sort");
+            if (sort && !["path", "hits", "updated"].includes(sort))
+                throw new CliError("--sort is path, hits or updated.");
+            return runRead(s, flagsOf(v), "list_redirects", { limit: 200, ...(sort ? { sort } : {}), ...(str(v, "search") ? { q: str(v, "search") } : {}) }, (d) => [
+                ...table([["FROM", "TO", "STATUS", "HITS", "SOURCE"], ...d.redirects.map((r) => [r.from, r.to, String(r.status), String(r.hits), r.source])]),
+                ...(d.total > d.redirects.length ? [`… ${d.total - d.redirects.length} more (use --search)`] : []),
+            ]);
+        },
+    },
+    "redirect add": {
+        usage: "cerkel redirect add <from> <to> [--temporary] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Send visitors of an old path to a new one (301; --temporary for 302)",
+        help: ["<to> is a path (/collections/all) or an https:// URL. Paths are stored lower-case, without a language prefix.", WRITE_HELP],
+        options: { ...WRITE_OPTIONS, temporary: { type: "boolean" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 2)
+                throw new CliError("Usage: cerkel redirect add <from> <to> [--temporary]");
+            const status = statusOf(v);
+            return runWrite(s, flagsOf(v), "create_redirect", { from: pos[0], to: pos[1], ...(status ? { status } : {}) });
+        },
+    },
+    "redirect update": {
+        usage: "cerkel redirect update <from> [--to <path|url>] [--from <new path>] [--status 301|302] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Change a redirect's target, path or status",
+        help: [WRITE_HELP],
+        options: { ...WRITE_OPTIONS, to: { type: "string" }, from: { type: "string" }, status: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel redirect update <from> [--to …] [--from …] [--status 301|302]");
+            const status = statusOf(v);
+            const args = { redirect: pos[0], ...(str(v, "to") ? { to: str(v, "to") } : {}), ...(str(v, "from") ? { from: str(v, "from") } : {}), ...(status ? { status } : {}) };
+            if (Object.keys(args).length === 1)
+                throw new CliError("Nothing to change: pass --to, --from or --status.");
+            return runWrite(s, flagsOf(v), "update_redirect", args);
+        },
+    },
+    "redirect delete": {
+        usage: "cerkel redirect delete <from> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Delete a redirect",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel redirect delete <from>");
+            return runWrite(s, flagsOf(v), "delete_redirect", { redirect: pos[0] });
+        },
+    },
+    "redirect import": {
+        usage: "cerkel redirect import <file.csv> [--skip-existing] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Add or update many redirects from a CSV file (from,to[,301|302] per line)",
+        help: ["Lines that would loop or are otherwise refused are listed by line number; the rest import. --skip-existing leaves paths that already have a rule alone.", WRITE_HELP],
+        options: { ...WRITE_OPTIONS, "skip-existing": { type: "boolean" } },
+        positionals: true,
+        run: async (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel redirect import <file.csv>");
+            let csv;
+            try {
+                csv = await fs.readFile(path.resolve(s.ctx.cwd, pos[0]), "utf8");
+            }
+            catch {
+                throw new CliError(`Cannot read ${pos[0]}.`);
+            }
+            return runWrite(s, flagsOf(v), "import_redirects", { csv, ...(bool(v, "skip-existing") ? { skip_existing: true } : {}) });
+        },
+    },
+};

package/dist/commands/report.js

@@ -0,0 +1,93 @@
+import { bool, str } from "../command.js";
+import { READ_OPTIONS, flagsOf, runRead, show } from "../commerce.js";
+import { CliError } from "../errors.js";
+import { table } from "../format.js";
+const REPORT_OPTIONS = {
+    ...READ_OPTIONS,
+    since: { type: "string" }, until: { type: "string" }, preset: { type: "string" }, grain: { type: "string" },
+    compare: { type: "boolean" }, variants: { type: "boolean" }, "delivered-only": { type: "boolean" }, csv: { type: "boolean" },
+};
+const n = (v) => (typeof v === "number" ? (Number.isInteger(v) ? String(v) : v.toFixed(2)) : show(v));
+const pct = (v) => (typeof v === "number" ? `${(v * 100).toFixed(1)}%` : "—");
+const rows = (v) => (Array.isArray(v) ? v : []);
+/** A short human rendering per report; --json has everything. */
+function render(report, d) {
+    const head = [`${report} — ${String(d["range"]?.["since"] ?? d["window"]?.["since"] ?? "")} … ${String(d["range"]?.["until"] ?? d["window"]?.["until"] ?? "")} (${String(d["currency"] ?? "")})`];
+    const t = (d["totals"] ?? {});
+    switch (report) {
+        case "sales":
+            return [...head, ...table([["PERIOD", "ORDERS", "REVENUE", "DELIVERED", "DELIVERED REVENUE", "REFUSED"], ...rows(d["buckets"]).map((b) => [String(b["bucket"]), n(b["orders"]), n(b["revenue"]), n(b["delivered"]), n(b["deliveredRevenue"]), n(b["refused"])]),
+                    ["TOTAL", n(t["orders"]), n(t["revenue"]), n(t["delivered"]), n(t["deliveredRevenue"]), n(t["refused"])]])];
+        case "products":
+            return [...head, ...table([["PRODUCT", "SKU", "UNITS", "REVENUE", "DELIVERED UNITS", "REFUSED UNITS"], ...rows(d["rows"]).map((r) => [`${String(r["title"])}${r["variantTitle"] ? ` — ${String(r["variantTitle"])}` : ""}`, String(r["sku"] ?? "—"), n(r["units"]), n(r["revenue"]), n(r["deliveredUnits"]), n(r["refusedUnits"])])])];
+        case "governorates":
+            return [...head, ...table([["GOVERNORATE", "ORDERS", "REVENUE", "DELIVERED", "REFUSED"], ...rows(d["rows"]).map((r) => [String(r["name"]), n(r["orders"]), n(r["revenue"]), n(r["delivered"]), n(r["refused"])])])];
+        case "funnel":
+            return [...head, ...table([["STEP", "ORDERS", "OF CREATED", "OF PREVIOUS"], ...rows(d["steps"]).map((r) => [String(r["step"]), n(r["orders"]), pct(r["ofCreated"]), pct(r["ofPrevious"])])]),
+                "", ...table([["GOVERNORATE", "DECIDED", "REFUSED", "REFUSAL RATE"], ...rows(d["byGovernorate"]).map((r) => [String(r["label"]), n(r["decided"]), n(r["refused"]), pct(r["refusalRate"])])])];
+        case "couriers":
+            return [...head, ...table([["COURIER", "DISPATCHED", "DELIVERED", "REFUSED", "DELIVERY RATE", "AVG DAYS", ...(rows(d["rows"]).some((r) => "cashInTransit" in r) ? ["CASH WITH COURIER"] : [])],
+                    ...rows(d["rows"]).map((r) => [String(r["courier"] ?? "(none)"), n(r["dispatched"]), n(r["delivered"]), n(r["refused"]), pct(r["deliveryRate"]), r["avgDaysToDeliver"] == null ? "—" : n(r["avgDaysToDeliver"]), ...("cashInTransit" in r ? [n(r["cashInTransit"])] : [])])])];
+        case "customers":
+            return [...head, `Customers ${n(t["customers"])} (new ${n(t["newCustomers"])}, returning ${n(t["returningCustomers"])}), orders ${n(t["orders"])}, revenue ${n(t["revenue"])}`, "",
+                ...table([["CUSTOMER", "PHONE", "ORDERS", "DELIVERED", "ORDERED", "COLLECTED"], ...rows(d["top"]).map((c) => [String(c["name"] ?? "—"), String(c["phone"]), n(c["orders"]), n(c["delivered"]), n(c["ordered"]), n(c["collected"])])])];
+        case "discounts":
+            return [...head, ...table([["CODE", "ORDERS", "DELIVERED", "REFUSED", "REVENUE"], ...rows(d["rows"]).map((r) => [String(r["code"]), n(r["orders"]), n(r["delivered"]), n(r["refused"]), n(r["revenue"])])])];
+        case "growth": {
+            const roas = (t["roas"] ?? {});
+            return [...head, `Spend ${n(t["spend"])} · orders ${n(t["orders"])} (${n(t["revenue"])}) · delivered ${n(t["delivered"])} (${n(t["deliveredRevenue"])}) · ROAS ordered ${n(roas["ordered"])}, delivered ${n(roas["delivered"])} · CAC ${n(t["cac"])}`, "",
+                ...table([["CAMPAIGN", "PROVIDER", "SPEND", "ORDERS", "DELIVERED", "ROAS (DELIVERED)"], ...rows(d["campaigns"]).map((c) => [String(c["campaignName"] ?? c["campaignId"]), String(c["provider"]), n(c["spend"]), n(c["orders"]), n(c["delivered"]), n(c["roas"]?.["delivered"])])])];
+        }
+    }
+}
+function reportArgs(report, v) {
+    const out = { report };
+    for (const k of ["since", "until", "preset", "grain"])
+        if (str(v, k) !== undefined)
+            out[k] = str(v, k);
+    if (bool(v, "compare"))
+        out["compare"] = true;
+    if (bool(v, "variants"))
+        out["level"] = "variant";
+    if (bool(v, "delivered-only"))
+        out["deliveredOnly"] = true;
+    if (bool(v, "csv"))
+        out["format"] = "csv";
+    return out;
+}
+const reportCommand = (report, summary) => ({
+    usage: `cerkel report ${report} [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--preset last7|last30|this_month|…]${report === "sales" || report === "customers" ? " [--grain day|week|month] [--compare]" : ""}${report === "products" ? " [--variants] [--delivered-only]" : ""} [--csv] [--store <slug>] [--json]`,
+    summary,
+    help: [
+        "Days are the shop's days (Asia/Amman). Default: the last 30 days. Money is the value stamped on each order when it was placed.",
+        "--csv prints the same CSV the admin downloads (needs the report download permission). --json prints everything.",
+    ],
+    options: REPORT_OPTIONS,
+    run: async (s, v) => {
+        const flags = flagsOf(v);
+        if (bool(v, "csv") && flags.json)
+            throw new CliError("--csv or --json, not both.");
+        if (bool(v, "csv"))
+            return runRead(s, flags, "run_report", reportArgs(report, v), (d) => [d.csv.replace(/\r\n$/, "")]);
+        return runRead(s, flags, "run_report", reportArgs(report, v), (d) => render(report, d));
+    },
+});
+export const REPORT_COMMANDS = {
+    "report sales": reportCommand("sales", "Sales: ordered, delivered and refused revenue per day, week or month"),
+    "report products": reportCommand("products", "Units and revenue per product (or variant)"),
+    "report governorates": reportCommand("governorates", "Orders, delivery and refusals per governorate"),
+    "report funnel": reportCommand("funnel", "The order funnel and refusals by governorate, product and channel"),
+    "report couriers": reportCommand("couriers", "Delivery and refusal rates per courier (cash with couriers with finance access)"),
+    "report customers": reportCommand("customers", "New vs returning customers, repeat rate and top customers"),
+    "report discounts": reportCommand("discounts", "Orders and revenue per promo code"),
+    "report growth": reportCommand("growth", "Ad spend, ROAS and cost per new customer (finance access)"),
+    "report live": {
+        usage: "cerkel report live [--store <slug>] [--json]",
+        summary: "Who is on the store's website right now",
+        help: ["Counted only when the store's website runs on Cerkel."],
+        options: READ_OPTIONS,
+        run: (s, v) => runRead(s, flagsOf(v), "get_live_visitors", {}, (d) => d["tracked"] === false
+            ? [String(d["reason"] ?? "Visits are not counted for this store.")]
+            : [`${n(d["count"])} visitor(s) in the last ${n(d["windowMinutes"])} minutes`, "", ...table([["PAGE", "VISITORS"], ...rows(d["pages"]).map((p) => [String(p["path"]), n(p["visitors"])])])]),
+    },
+};

package/dist/commands/section.js

@@ -0,0 +1,233 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { deleteThemeFiles, getThemeFiles, listSectionStarters, listThemeFileVersions, nameOf, restoreThemeFileVersion, } from "../api.js";
+import { CliError } from "../errors.js";
+import { table } from "../format.js";
+import { SECTION_TYPE_RE, bytesOf, hashBytes, isDeletablePath, isGeneratedPath, isLayoutPath, sectionPath, textOf, toDiskPath, toLayoutPath } from "../layout.js";
+import { readLocal, writeState } from "../state.js";
+/**
+ * Sections are theme files (docs/liquid-themes.md): ONE `sections/<type>.liquid` per type, holding the
+ * Liquid, its `{% stylesheet %}` and its `{% schema %}`, belonging to the checkout's draft theme. These
+ * commands are shortcuts over that file; `cerkel theme history|restore` do the same for any file.
+ */
+function checkType(type, what = "Which section? Pass its type, e.g. `cerkel section new promo-strip`.") {
+    if (!type)
+        throw new CliError(what);
+    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;
+}
+/** The starter as ONE section file. Older servers sent only the parts; assemble them the same way the server does. */
+export function starterFile(st) {
+    if (typeof st.content === "string" && st.content.length > 0)
+        return st.content;
+    const schema = typeof st.schema === "string" ? st.schema : JSON.stringify({ ...st.schema, name: st.name, ...(st.group ? { group: st.group } : {}) }, null, 2);
+    const body = (st.template ?? "").replace(/\s+$/, "");
+    const css = typeof st.css === "string" && st.css.trim() ? `\n\n{% stylesheet %}\n${st.css.replace(/\s+$/, "")}\n{% endstylesheet %}` : "";
+    return `${body}${css}\n\n{% schema %}\n${schema}\n{% endschema %}\n`;
+}
+async function writeNew(s, root, p, content) {
+    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}`);
+}
+// --- 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 p = sectionPath(type);
+    if (state.files[p] || (await readLocal(root, p)))
+        throw new CliError(`Section "${type}" already exists (${p}). Pick another type, or edit that file.`);
+    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, nameOf(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).`);
+        }
+    }
+    await writeNew(s, root, p, starterFile(starter));
+    s.out(`Section "${type}" created locally from "${starter.key}". Set its "name" in the {% schema %} of ${p}, then \`cerkel theme push\` (or keep \`cerkel theme dev\` running) to add it to "${state.themeName}".`);
+    s.out("It belongs to this draft theme: it goes live when the draft is approved and published.");
+    return 0;
+}
+// --- duplicate ---------------------------------------------------------------
+/** Marks the copy's display name so "Add section" does not show two identical entries. */
+export function renameCopy(content) {
+    const m = /(\{%-?\s*schema\s*-?%\})([\s\S]*?)(\{%-?\s*endschema\s*-?%\})/.exec(content);
+    if (!m)
+        return content;
+    let schema;
+    try {
+        const parsed = JSON.parse(m[2]);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return content;
+        schema = parsed;
+    }
+    catch {
+        return content; // the server will say what is wrong with it on push
+    }
+    const suffix = { ar: " (نسخة)", en: " (copy)", ckb: " (کۆپی)" };
+    const name = schema["name"];
+    if (typeof name === "string")
+        schema["name"] = `${name} (copy)`;
+    else if (name && typeof name === "object") {
+        schema["name"] = Object.fromEntries(Object.entries(name).map(([k, v]) => [k, typeof v === "string" ? `${v}${suffix[k] ?? " (copy)"}` : v]));
+    }
+    else
+        return content;
+    return content.slice(0, m.index) + `${m[1]}\n${JSON.stringify(schema, null, 2)}\n${m[3]}` + content.slice(m.index + m[0].length);
+}
+/**
+ * `cerkel section duplicate <from> <to>`: a new section type that starts as a copy of another — the way
+ * to redesign a section without touching the one the templates place today. Local only, like `new`.
+ */
+export async function sectionDuplicate(s, rawFrom, rawTo) {
+    const from = checkType(rawFrom, "Which section to copy? e.g. `cerkel section duplicate promo-strip promo-strip-v2`.");
+    const to = checkType(rawTo, "What is the new section's type? e.g. `cerkel section duplicate promo-strip promo-strip-v2`.");
+    if (from === to)
+        throw new CliError("The copy needs a different type than the section it copies.");
+    const { root, state } = await s.requireCheckout({ editable: true });
+    const src = await readLocal(root, sectionPath(from));
+    if (!src) {
+        throw new CliError(`There is no ${sectionPath(from)} in this checkout. Only sections that are files of this theme can be copied; built-in sections are not files (yet).`);
+    }
+    const dst = sectionPath(to);
+    if (state.files[dst] || (await readLocal(root, dst)))
+        throw new CliError(`Section "${to}" already exists (${dst}). Pick another type.`);
+    await writeNew(s, root, dst, renameCopy(textOf(src)));
+    s.out(`Copied "${from}" to "${to}". Edit ${dst}, push it, then place it with the visual editor (or in a template) instead of "${from}".`);
+    return 0;
+}
+// --- delete ------------------------------------------------------------------
+/** Delete files from the checkout's draft on the server, then locally. */
+export async function deleteFiles(s, paths) {
+    const { root, state } = await s.requireCheckout({ editable: true });
+    for (const p of paths) {
+        if (isGeneratedPath(p))
+            throw new CliError(`${p} is generated by Cerkel and cannot be deleted.`);
+        if (!isDeletablePath(p))
+            throw new CliError(`${p} cannot be deleted: only sections/, blocks/, snippets/ and assets/ files can (templates, layout, config/settings.json, assets/custom.css and locales always exist).`);
+    }
+    const r = await deleteThemeFiles(await s.client(state), state.store, state.themeId, paths.map((p) => ({ path: p, baseTag: state.files[p]?.tag ?? null })));
+    let failed = 0;
+    for (const res of r.results ?? []) {
+        if (res.status === "deleted" || res.status === "unchanged") {
+            await fs.rm(toDiskPath(root, res.path), { force: true });
+            delete state.files[res.path];
+            s.out(`  ${res.status === "deleted" ? "deleted" : "gone    "}  ${res.path}${res.status === "unchanged" ? " (the draft did not have it)" : ""}`);
+        }
+        else if (res.status === "in_use") {
+            failed++;
+            s.out(`  in use   ${res.path} — still placed by ${(res.usedIn ?? []).join(", ") || "a template"}. Remove it from there (and push) first.`);
+        }
+        else if (res.status === "conflict") {
+            failed++;
+            s.out(`  conflict ${res.path} — changed on the server since you last synced it. Pull first, then delete.`);
+        }
+        else {
+            failed++;
+            s.out(`  refused  ${res.path}${res.message ? ` — ${res.message}` : ""}`);
+        }
+    }
+    await writeState(root, state);
+    if (failed === 0)
+        s.out("Deleted files stay in their history: `cerkel theme history <file>` and `cerkel theme restore <file> <version>` bring them back.");
+    return failed > 0 ? 1 : 0;
+}
+export async function sectionDelete(s, rawType) {
+    return deleteFiles(s, [sectionPath(checkType(rawType))]);
+}
+// --- history / restore --------------------------------------------------------
+/** A command-line file argument → layout path (relative to the cwd, or already a layout path). */
+export function fileArg(s, root, raw) {
+    if (!raw)
+        throw new CliError("Which file? e.g. `sections/promo-strip.liquid`.");
+    const viaDisk = toLayoutPath(root, path.resolve(s.ctx.cwd, raw));
+    const p = viaDisk && isLayoutPath(viaDisk) ? viaDisk : raw.split(path.sep).join("/");
+    if (!isLayoutPath(p))
+        throw new CliError(`${raw} is not a theme file path.`);
+    return p;
+}
+export async function fileHistory(s, p, opts) {
+    const { state } = await s.requireCheckout({ editable: false });
+    const r = await listThemeFileVersions(await s.client(state), state.store, p, opts.limit);
+    if (r.versions.length === 0) {
+        s.out(`${p} has no saved versions in ${state.store}.`);
+        return 0;
+    }
+    s.out(`${p} — newest first, across every theme of ${state.store}:`);
+    const rows = r.versions.map((v) => [
+        `v${v.version}`,
+        v.op + (v.restoredFrom ? ` (from v${v.restoredFrom})` : ""),
+        v.theme ?? "—",
+        v.createdAt,
+        v.author ?? "—",
+        v.tag && state.files[p]?.tag === v.tag ? "← your checkout" : "",
+    ]);
+    for (const line of table([["VERSION", "WHAT", "THEME", "WHEN", "WHO", ""], ...rows]))
+        s.out(line);
+    return 0;
+}
+export async function fileRestore(s, p, rawVersion, opts) {
+    const version = Number(rawVersion?.replace(/^v/i, ""));
+    if (!rawVersion || !Number.isInteger(version) || version < 1)
+        throw new CliError(`Which version? e.g. \`cerkel theme restore ${p} 3\` (see \`cerkel theme history ${p}\`).`);
+    const { root, state } = await s.requireCheckout({ editable: true });
+    // Restoring rewrites the local file; do not silently discard edits made to it.
+    if (!opts.force) {
+        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 restoreThemeFileVersion(client, state.store, state.themeId, p, version);
+    s.out(`Restored ${p} from v${r.restoredFrom} into "${state.themeName}" as a new version (history is kept).`);
+    const all = await getThemeFiles(client, state.store, state.themeId);
+    const fresh = all.files.find((f) => f.path === p);
+    const disk = toDiskPath(root, p);
+    if (fresh) {
+        await fs.mkdir(path.dirname(disk), { recursive: true });
+        await fs.writeFile(disk, bytesOf(fresh.content));
+        state.files[p] = { tag: fresh.tag, hash: hashBytes(bytesOf(fresh.content)) };
+        s.out(`  updated  ${p}`);
+    }
+    await writeState(root, state);
+    return 0;
+}
+export async function sectionHistory(s, rawType, opts) {
+    return fileHistory(s, sectionPath(checkType(rawType)), opts);
+}
+export async function sectionRestore(s, rawType, rawVersion, opts) {
+    return fileRestore(s, sectionPath(checkType(rawType)), rawVersion, opts);
+}

package/dist/commands/store.js

@@ -0,0 +1,23 @@
+import {} from "../command.js";
+import { READ_HELP, READ_OPTIONS, flagsOf, runRead, show } from "../commerce.js";
+import { table } from "../format.js";
+/** `cerkel store info` — get_shop_info. */
+export const STORE_COMMANDS = {
+    "store info": {
+        usage: "cerkel store info [--store <slug>] [--json]",
+        summary: "Show the store's currency, languages, domains, cash-on-delivery policy and order numbering",
+        help: ["Every amount the other commands take is in this currency (IQD prices in steps of 250).", READ_HELP],
+        options: READ_OPTIONS,
+        run: (s, v) => runRead(s, flagsOf(v), "get_shop_info", {}, (d) => table([
+            ["Store", `${d.store.name} (${d.store.slug})`],
+            ["Status", d.store.status],
+            ["Currency", `${d.currency.code} — ${d.currency.decimals} decimals${d.currency.cashStep > 1 ? `, prices in steps of ${d.currency.cashStep}` : ""}`],
+            ["Languages", d.locales.join(", ") + ` (default ${d.defaultLocale})`],
+            ["Domain", d.domains.primary ?? "—"],
+            ["Next order", `${d.orderNumbering.next}${d.orderNumbering.continuesShopify ? " (continues Shopify's numbering)" : ""}`],
+            ["Delivery", `${d.deliveryEtaDays} days`],
+            ["COD caps", `new customers ${show(d.cashOnDelivery["newCustomerCap"])}, high risk ${show(d.cashOnDelivery["highRiskCap"])} (${String(d.cashOnDelivery["highRiskAction"])})`],
+            ["You may", d.you.permissions.join(", ") || "—"],
+        ])),
+    },
+};