@cerkel/cli 0.0.0-stage → 1.0.0

package/dist/commands/order.js

@@ -0,0 +1,219 @@
+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";
+import { discountFlag, listFlag, need, pairsFlag, textOf } from "./order-args.js";
+const day = (iso) => iso.slice(0, 16).replace("T", " ");
+const pct = (r) => (r === null ? "—" : `${Math.round(r * 100)}%`);
+const LIST_OPTIONS = {
+    ...READ_OPTIONS,
+    status: { type: "string", multiple: true }, q: { type: "string" }, phone: { type: "string" }, number: { type: "string" },
+    tag: { type: "string", multiple: true }, risk: { type: "string", multiple: true }, fulfillment: { type: "string", multiple: true },
+    since: { type: "string" }, until: { type: "string" }, archived: { type: "boolean" }, test: { type: "boolean" },
+    sort: { type: "string" }, asc: { type: "boolean" }, limit: { type: "string" }, page: { type: "string" },
+};
+const intFlag = (v, name) => {
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 1)
+        throw new CliError(`--${name} takes a whole number.`);
+    return n;
+};
+const EDIT_OPTIONS = {
+    ...WRITE_OPTIONS,
+    qty: { type: "string", multiple: true }, remove: { type: "string", multiple: true }, add: { type: "string", multiple: true },
+    "add-offer": { type: "string", multiple: true }, "add-addon": { type: "string", multiple: true },
+    "delivery-fee": { type: "string" }, discount: { type: "string" },
+    name: { type: "string" }, phone: { type: "string" }, "phone-alt": { type: "string" }, governorate: { type: "string" }, city: { type: "string" },
+    district: { type: "string" }, landmark: { type: "string" }, address: { type: "string" },
+    reason: { type: "string" }, notify: { type: "boolean" },
+};
+export const ORDER_COMMANDS = {
+    "order list": {
+        usage: "cerkel order list [--status <s>]… [--q <text>] [--phone <phone>] [--number <n>] [--tag <t>]… [--risk <band>]… [--since <day>] [--until <day>] [--archived] [--limit <n>] [--page <n>] [--store <slug>] [--json]",
+        summary: "Search the store's orders",
+        help: [
+            "--status takes cash-on-delivery statuses (new, confirming, confirmed, packed, dispatched, out_for_delivery, delivered, …), repeatable or comma-separated.",
+            "--fulfillment unfulfilled|in_progress|on_hold|fulfilled. Phones are masked unless your login may see customer details.",
+            READ_HELP,
+        ],
+        options: LIST_OPTIONS,
+        run: (s, v) => {
+            const sort = str(v, "sort");
+            return runRead(s, flagsOf(v), "search_orders", {
+                ...(listFlag(v, "status") ? { status: listFlag(v, "status") } : {}),
+                ...(str(v, "q") ? { q: str(v, "q") } : {}), ...(str(v, "phone") ? { phone: str(v, "phone") } : {}), ...(str(v, "number") ? { number: str(v, "number") } : {}),
+                ...(listFlag(v, "tag") ? { tags: listFlag(v, "tag") } : {}), ...(listFlag(v, "risk") ? { risk: listFlag(v, "risk") } : {}),
+                ...(listFlag(v, "fulfillment") ? { fulfillment: listFlag(v, "fulfillment") } : {}),
+                ...(str(v, "since") ? { since: str(v, "since") } : {}), ...(str(v, "until") ? { until: str(v, "until") } : {}),
+                ...(bool(v, "archived") ? { archived: true } : {}), ...(bool(v, "test") ? { test: true } : {}),
+                ...(sort ? { sort } : {}), ...(bool(v, "asc") ? { dir: "asc" } : {}),
+                ...(intFlag(str(v, "limit"), "limit") ? { limit: intFlag(str(v, "limit"), "limit") } : {}),
+                ...(intFlag(str(v, "page"), "page") ? { page: intFlag(str(v, "page"), "page") } : {}),
+            }, (d) => [
+                ...table([
+                    ["Number", "Placed", "Status", "Total", "Items", "Customer", "Phone", "Governorate", "Tags"],
+                    ...d.orders.map((o) => [o.number, day(o.placedAt), o.status + (o.held ? " (held)" : ""), o.total.formatted, String(o.items), o.customer.name ?? "—", o.customer.phone ?? "—", o.governorate ?? "—", o.tags.join(", ")]),
+                ]),
+                `${d.orders.length} of ${d.total} (page ${d.page}).`,
+            ]);
+        },
+    },
+    "order get": {
+        usage: "cerkel order get <number|id> [--store <slug>] [--json]",
+        summary: "Show one order: items, totals, status, customer, courier and timeline",
+        help: [READ_HELP],
+        options: READ_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 1, "cerkel order get <number|id>");
+            return runRead(s, flagsOf(v), "get_order", { order: pos[0] }, (d) => [
+                `${d.number} — ${d.status}${d.hold ? ` (on hold: ${d.hold.reason}${d.hold.until ? ` until ${d.hold.until}` : ""})` : ""}`,
+                ...table([
+                    ["Placed", day(d.placedAt)],
+                    ["Payment / fulfillment / delivery", `${d.payment} / ${d.fulfillment ?? "—"} / ${d.delivery ?? "—"}`],
+                    ["Customer", `${d.customer.name ?? "—"}  ${d.customer.phone ?? ""}${d.customer.phoneAlt ? ` / ${d.customer.phoneAlt}` : ""}`],
+                    ["Address", [d.address.governorate, d.address.city, d.address.district, d.address.landmark, d.address.address].filter(Boolean).join(", ") || "—"],
+                    ["Courier", d.courier.name ? `${d.courier.name}${d.courier.trackingNumber ? ` · ${d.courier.trackingNumber}` : ""}` : "—"],
+                    ["Refusal rate", d.refusal ? `${pct(d.refusal.rate)} (${d.refusal.refused} refused, ${d.refusal.delivered} delivered)` : "—"],
+                    ["Risk", d.risk ? `${d.risk.band} (${d.risk.score})` : "—"],
+                    ["Tags", d.tags.join(", ") || "—"],
+                ]),
+                "",
+                ...table([["Line", "Item", "SKU", "Qty", "Total"], ...d.lines.map((l) => [l.id, l.variant && !/^default/i.test(l.variant) ? `${l.title} — ${l.variant}` : l.title, l.sku ?? "—", String(l.quantity), l.total.formatted])]),
+                `Subtotal ${show(d.totals.subtotal)} · discount ${show(d.totals.discount)} · delivery ${show(d.totals.delivery)} · total ${show(d.totals.total)}`,
+                ...(d.editWaitingForApproval ? [`An edit is waiting for an admin's approval: ${d.editWaitingForApproval.reason}`] : []),
+                `Next steps: ${d.allowedTransitions.map((t) => (t.permitted ? t.to : `${t.to} (not allowed for you)`)).join(", ") || "none"}`,
+                "",
+                ...d.timeline.slice(0, 15).map((e) => `  ${day(e.at)}  ${e.type === "status" ? `${e.from ?? "—"} → ${e.to}` : e.type === "comment" ? `comment: ${e.body}` : e.type === "call" ? `call: ${e.outcome}` : e.type}${e.by ? `  (${e.by})` : ""}`),
+            ]);
+        },
+    },
+    "order transition": {
+        usage: "cerkel order transition <number|id> <status> [--note <reason>] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Move an order one cash-on-delivery step (confirmed, cancelled, delivered, …)",
+        help: [
+            "The admin's rules: confirming / confirmed / unreachable need permission to confirm, cancelled needs permission to cancel and --note.",
+            "Handing an order to the courier (dispatched) happens on a hand-over list in the admin, and cash steps in the courier payments — never here.",
+            WRITE_HELP,
+        ],
+        options: { ...WRITE_OPTIONS, note: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 2, "cerkel order transition <number> <status> [--note <reason>]");
+            return runWrite(s, flagsOf(v), "transition_order", { order: pos[0], to: pos[1], ...(str(v, "note") ? { note: str(v, "note") } : {}) });
+        },
+    },
+    "order note": {
+        usage: "cerkel order note <number|id> <text…> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Add a staff comment to an order's timeline",
+        help: ["Never shown to the customer.", WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 2, "cerkel order note <number> <text…>");
+            return runWrite(s, flagsOf(v), "add_order_note", { order: pos[0], body: textOf(pos, 1) });
+        },
+    },
+    "order tag": {
+        usage: "cerkel order tag <number|id> [--add <t>]… [--remove <t>]… [--set <t,t>] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Add, remove or replace an order's tags",
+        help: ["--set replaces every staff tag (--set \"\" clears them).", WRITE_HELP],
+        options: { ...WRITE_OPTIONS, add: { type: "string", multiple: true }, remove: { type: "string", multiple: true }, set: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 1, "cerkel order tag <number> --add <tag> | --remove <tag> | --set <tags>");
+            const set = str(v, "set");
+            return runWrite(s, flagsOf(v), "set_order_tags", {
+                order: pos[0],
+                ...(set !== undefined ? { tags: set.split(",").map((t) => t.trim()).filter(Boolean) } : {}),
+                ...(listFlag(v, "add") ? { add: listFlag(v, "add") } : {}), ...(listFlag(v, "remove") ? { remove: listFlag(v, "remove") } : {}),
+            });
+        },
+    },
+    "order hold": {
+        usage: "cerkel order hold <number|id> --reason <reason> [--note <text>] [--until <YYYY-MM-DD>] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Put an order's fulfillment on hold",
+        help: [
+            "Reasons: incorrect_address, out_of_stock, high_risk, awaiting_deposit, customer_later (with --until), other (with --note).",
+            "A held order cannot be packed or handed to the courier until `cerkel order release`.",
+            WRITE_HELP,
+        ],
+        options: { ...WRITE_OPTIONS, reason: { type: "string" }, note: { type: "string" }, until: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 1, "cerkel order hold <number> --reason <reason>");
+            if (!str(v, "reason"))
+                throw new CliError("--reason is required: incorrect_address, out_of_stock, high_risk, awaiting_deposit, customer_later or other.");
+            return runWrite(s, flagsOf(v), "hold_order", {
+                order: pos[0], reason: str(v, "reason"), ...(str(v, "note") ? { note: str(v, "note") } : {}), ...(str(v, "until") ? { until: str(v, "until") } : {}),
+            });
+        },
+    },
+    "order release": {
+        usage: "cerkel order release <number|id> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Release an order's fulfillment hold",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 1, "cerkel order release <number>");
+            return runWrite(s, flagsOf(v), "release_order", { order: pos[0] });
+        },
+    },
+    "order call": {
+        usage: "cerkel order call <number|id> <outcome> [--note <text>] [--at <ISO time>] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Log a confirmation call (answered_confirmed, no_answer, busy, wrong_number, reschedule, cancelled)",
+        help: [
+            "no_answer / busy schedule the next call (+2 h, then +24 h; the third makes the order unreachable). reschedule needs --at.",
+            "cancelled cancels the order and needs --note with the reason.",
+            WRITE_HELP,
+        ],
+        options: { ...WRITE_OPTIONS, note: { type: "string" }, at: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 2, "cerkel order call <number> <outcome>");
+            return runWrite(s, flagsOf(v), "record_call_attempt", {
+                order: pos[0], outcome: pos[1], ...(str(v, "note") ? { note: str(v, "note") } : {}), ...(str(v, "at") ? { reschedule_at: str(v, "at") } : {}),
+            });
+        },
+    },
+    "order edit": {
+        usage: "cerkel order edit <number|id> [--qty <sku|line>=<n>]… [--remove <sku|line>]… [--add <sku>=<n>]… [--add-offer <id>=<n>]… [--add-addon <id>=<n>]… [--delivery-fee <amount|zone>] [--discount <amount|n%|none>] [--name …] [--phone …] [--phone-alt …] [--governorate <code>] [--city …] [--district …] [--landmark …] [--address …] [--reason <text>] [--notify] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Edit an order's items, discount, delivery fee or address (the admin's Edit order)",
+        help: [
+            "Name a line by its SKU (when only one line has it) or by its line id from `cerkel order get` (the first 8 characters are enough).",
+            "Once the courier has the order, nothing can be added and the edit needs an admin's approval: without that right it is submitted for approval (--reason required).",
+            "--delivery-fee zone puts the fee back under the delivery zone; --notify sends the customer the WhatsApp update when the total changes.",
+            WRITE_HELP,
+        ],
+        options: EDIT_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 1, "cerkel order edit <number> [changes…]");
+            const lines = [
+                ...pairsFlag(v, "qty", "<sku|line>").map((p) => ({ line_id: p.key, quantity: p.quantity })),
+                ...(listFlag(v, "remove") ?? []).map((id) => ({ line_id: id, quantity: 0 })),
+            ];
+            const add = [
+                ...pairsFlag(v, "add", "<sku>").map((p) => ({ variant: p.key, quantity: p.quantity })),
+                ...pairsFlag(v, "add-offer", "<offer id>").map((p) => ({ offer: p.key, quantity: p.quantity })),
+                ...pairsFlag(v, "add-addon", "<add-on id>").map((p) => ({ addon: p.key, quantity: p.quantity })),
+            ];
+            const fee = str(v, "delivery-fee");
+            const discount = discountFlag(v);
+            const contactKeys = [["name", "name"], ["phone", "phone"], ["phone-alt", "phone_alt"], ["governorate", "governorate"], ["city", "city"], ["district", "district"], ["landmark", "landmark"], ["address", "address"]];
+            const contact = Object.fromEntries(contactKeys.filter(([flag]) => str(v, flag) !== undefined).map(([flag, key]) => [key, str(v, flag).trim() || null]));
+            return runWrite(s, flagsOf(v), "edit_order", {
+                order: pos[0],
+                ...(lines.length ? { lines } : {}), ...(add.length ? { add } : {}),
+                ...(fee !== undefined ? { delivery_fee: fee.trim().toLowerCase() === "zone" ? null : moneyFlag(fee) } : {}),
+                ...(discount !== undefined ? { discount } : {}),
+                ...(Object.keys(contact).length ? { contact } : {}),
+                ...(str(v, "reason") ? { reason: str(v, "reason") } : {}),
+                ...(bool(v, "notify") ? { notify_customer: true } : {}),
+            });
+        },
+    },
+};

package/dist/commands/price.js

@@ -0,0 +1,55 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { str } from "../command.js";
+import { WRITE_HELP, WRITE_OPTIONS, flagsOf, moneyFlag, runWrite } from "../commerce.js";
+import { CliError } from "../errors.js";
+/** `cerkel price …` — set_variant_price and bulk_set_prices. */
+export const PRICE_COMMANDS = {
+    "price set": {
+        usage: "cerkel price set <sku|barcode|variant-id> <price> [--compare-at <amount|none>] [--cost <amount|none>] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Set a variant's price (and compare-at price / cost) in the store",
+        help: [
+            "Amounts are in the store's currency, as you would write them: 18.000 or 18 (JOD), 12500 (IQD, steps of 250).",
+            "Give the price as \"-\" to change only --compare-at or --cost. --compare-at none removes the compare-at price.",
+            WRITE_HELP,
+        ],
+        options: { ...WRITE_OPTIONS, "compare-at": { type: "string" }, cost: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            const [variant, price, extra] = pos;
+            if (!variant || price === undefined || extra !== undefined)
+                throw new CliError("Usage: cerkel price set <sku> <price> [--compare-at <amount>] [--cost <amount>]");
+            const compareAt = moneyFlag(str(v, "compare-at"));
+            const cost = moneyFlag(str(v, "cost"));
+            return runWrite(s, flagsOf(v), "set_variant_price", {
+                variant,
+                ...(price.trim() === "-" ? {} : { price: price.trim() }),
+                ...(compareAt !== undefined ? { compareAt } : {}),
+                ...(cost !== undefined ? { cost } : {}),
+            });
+        },
+    }, "price import": {
+        usage: "cerkel price import <prices.csv|-> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Set many prices from a CSV (sku, price, compare_at, cost)",
+        help: [
+            "Columns: sku (or barcode / variant_id), then any of price, compare_at, cost. A blank cell keeps that value; \"none\" clears compare_at or cost.",
+            "Commas, semicolons or tabs; Arabic headers work. All or nothing: one bad row refuses the whole file and the rows are listed. - reads the CSV from stdin.",
+            WRITE_HELP,
+        ],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: async (s, v, pos) => {
+            const [file, extra] = pos;
+            if (!file || extra !== undefined)
+                throw new CliError("Usage: cerkel price import <prices.csv>");
+            let csv;
+            try {
+                csv = file === "-" ? await s.ctx.io.readStdin() : await fs.readFile(path.resolve(s.ctx.cwd, file), "utf8");
+            }
+            catch {
+                throw new CliError(`Cannot read ${file}.`);
+            }
+            return runWrite(s, flagsOf(v), "bulk_set_prices", { csv });
+        },
+    },
+};

package/dist/commands/product.js

@@ -0,0 +1,265 @@
+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";
+import { LANG_OPTION, TEXT_HELP, csvList, defined, int, list, localized, nullable, pairs, textOf } from "./args.js";
+const one = (pos, usage) => {
+    if (pos.length !== 1 || !pos[0])
+        throw new CliError(`Usage: ${usage}`);
+    return pos[0];
+};
+const priceRange = (p) => !p?.min ? "—" : p.min.amount === p.max?.amount ? show(p.min) : `${show(p.min)} – ${show(p.max)}`;
+const PRODUCT_TEXT_OPTIONS = {
+    ...LANG_OPTION,
+    title: { type: "string", multiple: true },
+    description: { type: "string", multiple: true },
+    handle: { type: "string" },
+    vendor: { type: "string" },
+    type: { type: "string" },
+    tags: { type: "string" },
+};
+export const PRODUCT_COMMANDS = {
+    "product list": {
+        usage: "cerkel product list [search] [--status active|draft|archived] [--collection <handle>] [--category <path>] [--low|--out] [--published|--hidden] [--page N] [--store <slug>] [--json]",
+        summary: "Search the store's products",
+        help: ["Matches titles in any language, handles, SKUs, barcodes, vendor, type and tags.", READ_HELP],
+        options: {
+            ...READ_OPTIONS, status: { type: "string" }, collection: { type: "string" }, category: { type: "string" },
+            low: { type: "boolean" }, out: { type: "boolean" }, published: { type: "boolean" }, hidden: { type: "boolean" }, page: { type: "string" }, limit: { type: "string" },
+        },
+        positionals: true,
+        run: (s, v, pos) => runRead(s, flagsOf(v), "search_products", defined({
+            q: pos.join(" ").trim() || undefined,
+            status: str(v, "status"), collection: str(v, "collection"), category: str(v, "category"),
+            stock: bool(v, "low") && bool(v, "out") ? "low_or_out" : bool(v, "low") ? "low" : bool(v, "out") ? "out" : undefined,
+            published: bool(v, "published") ? true : bool(v, "hidden") ? false : undefined,
+            page: int(str(v, "page"), "--page"), limit: int(str(v, "limit"), "--limit"),
+        }), (d) => d.products.length === 0 ? ["No products match."] : [
+            ...table([["HANDLE", "STATUS", "SHOWN", "PRICE", "STOCK", "TITLE"], ...d.products.map((p) => [
+                    p.handle, p.status, p.published ? "yes" : "no", priceRange(p.price),
+                    p.stock ? (p.stock.out ? "out" : p.stock.available === null ? "—" : `${p.stock.available}${p.stock.low ? " (low)" : ""}`) : "—",
+                    textOf(p.title),
+                ])]),
+            `${d.products.length} of ${d.total} (page ${d.page})`,
+        ]),
+    },
+    "product get": {
+        usage: "cerkel product get <handle|id> [--store <slug>] [--json]",
+        summary: "Show a product: variants, this store's prices, stock, bundles and add-ons",
+        help: [READ_HELP],
+        options: READ_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => runRead(s, flagsOf(v), "get_product", { product: one(pos, "cerkel product get <handle>") }, (p) => [
+            ...table([
+                ["Product", `${textOf(p.title)} (${p.handle})`],
+                ["Status", `${p.status}, ${p.publication.published ? "shown in this store" : "hidden in this store"}`],
+                ["Vendor / type", `${p.vendor ?? "—"} / ${p.productType ?? "—"}`],
+                ["Category", p.category?.path ?? "—"],
+                ["Tags", p.tags.join(", ") || "—"],
+                ["Options", p.options.map((o) => `${textOf(o.name)}: ${o.values.map(textOf).join(", ")}`).join("; ") || "—"],
+                ["Images", String(p.images.length)],
+                ["Collections", p.collections.map((c) => c.handle).join(", ") || "—"],
+                ["Bundles / add-ons", `${p.offers.length} / ${p.addons.length}`],
+            ]),
+            "",
+            ...table([["SKU", "VARIANT", "PRICE", "COMPARE-AT", "COST", "AVAILABLE"], ...p.variants.map((x) => [
+                    x.sku ?? "—", x.title || "—", show(x.price), show(x.compareAt), show(x.cost), x.stock ? (x.stock.tracked ? String(x.stock.available) : "not tracked") : "—",
+                ])]),
+        ]),
+    },
+    "product create": {
+        usage: "cerkel product create --title <text> --price <amount> [--compare-at <amount>] [--cost <amount>] [--sku <sku>] [--quantity N] [--image <url>]… [--active] [--publish] [--yes] [--dry-run] [--json]",
+        summary: "Create a product with one variant (a hidden draft unless --active --publish)",
+        help: ["Amounts are in the store's currency (18.000 JOD, 12500 IQD in steps of 250). --quantity tracks stock from that number.", TEXT_HELP, WRITE_HELP],
+        options: {
+            ...WRITE_OPTIONS, ...PRODUCT_TEXT_OPTIONS, price: { type: "string" }, "compare-at": { type: "string" }, cost: { type: "string" },
+            sku: { type: "string" }, barcode: { type: "string" }, quantity: { type: "string" }, image: { type: "string", multiple: true },
+            active: { type: "boolean" }, publish: { type: "boolean" },
+        },
+        run: (s, v) => {
+            const title = localized(v, "title");
+            const price = str(v, "price");
+            if (!title || !price)
+                throw new CliError("cerkel product create needs --title and --price.");
+            return runWrite(s, flagsOf(v), "create_product", defined({
+                title, descriptionHtml: localized(v, "description"), handle: str(v, "handle"), price, compareAt: moneyFlag(str(v, "compare-at")) ?? undefined,
+                cost: moneyFlag(str(v, "cost")) ?? undefined, sku: str(v, "sku"), barcode: str(v, "barcode"), vendor: str(v, "vendor"), productType: str(v, "type"),
+                tags: csvList(str(v, "tags")), quantity: int(str(v, "quantity"), "--quantity"), images: list(v, "image").length ? list(v, "image") : undefined,
+                status: bool(v, "active") ? "active" : undefined, publish: bool(v, "publish") || undefined,
+            }));
+        },
+    },
+    "product update": {
+        usage: "cerkel product update <handle|id> [--title …] [--description …] [--seo-title …] [--seo-description …] [--handle <new>] [--vendor <v|none>] [--type <t|none>] [--tags a,b] [--category <path|none>] [--field key=value]… [--yes] [--dry-run] [--json]",
+        summary: "Change a product's title, description, SEO, handle, vendor, type, tags, category or custom fields",
+        help: ["Only what you pass changes. These details are shared by every store of the brand.", TEXT_HELP, "--field takes key=value (JSON values allowed; key=null clears it).", WRITE_HELP],
+        options: {
+            ...WRITE_OPTIONS, ...PRODUCT_TEXT_OPTIONS, "seo-title": { type: "string", multiple: true }, "seo-description": { type: "string", multiple: true },
+            category: { type: "string" }, field: { type: "string", multiple: true },
+        },
+        positionals: true,
+        run: (s, v, pos) => runWrite(s, flagsOf(v), "update_product", defined({
+            product: one(pos, "cerkel product update <handle> [flags]"),
+            title: localized(v, "title"), descriptionHtml: localized(v, "description"), seoTitle: localized(v, "seo-title"), seoDescription: localized(v, "seo-description"),
+            handle: str(v, "handle"), vendor: nullable(str(v, "vendor")), productType: nullable(str(v, "type")), tags: csvList(str(v, "tags")),
+            category: nullable(str(v, "category")), customFields: pairs(v, "field"),
+        })),
+    },
+    "product status": {
+        usage: "cerkel product status <active|draft|archived> <handle|id>… [--yes] [--dry-run] [--json]",
+        summary: "Set one or more products to active, draft or archived",
+        help: ["Applies in every store of the brand; several products are all-or-nothing.", WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            const [status, ...refs] = pos;
+            if (!status || !refs.length)
+                throw new CliError("Usage: cerkel product status <active|draft|archived> <handle>…");
+            return refs.length === 1
+                ? runWrite(s, flagsOf(v), "set_product_status", { product: refs[0], status })
+                : runWrite(s, flagsOf(v), "bulk_update_product_status", { products: refs, status });
+        },
+    },
+    "product publish": {
+        usage: "cerkel product publish <handle|id> [--yes] [--dry-run] [--json]",
+        summary: "Show a product in this store's storefront",
+        help: ["Customers see it while its status is active. Other stores are not touched.", WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => runWrite(s, flagsOf(v), "publish_product", { product: one(pos, "cerkel product publish <handle>") }),
+    },
+    "product unpublish": {
+        usage: "cerkel product unpublish <handle|id> [--yes] [--dry-run] [--json]",
+        summary: "Hide a product from this store's storefront",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => runWrite(s, flagsOf(v), "unpublish_product", { product: one(pos, "cerkel product unpublish <handle>") }),
+    },
+    "product duplicate": {
+        usage: "cerkel product duplicate <handle|id> [--yes] [--dry-run] [--json]",
+        summary: "Copy a product into a new draft (<handle>-copy)",
+        help: ["SKUs and barcodes are not copied; nothing is priced or published yet.", WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => runWrite(s, flagsOf(v), "duplicate_product", { product: one(pos, "cerkel product duplicate <handle>") }),
+    },
+    "variant set": {
+        usage: "cerkel variant set <sku|barcode|id> [--sku <new|none>] [--barcode <code|none>] [--weight <grams|none>] [--yes] [--dry-run] [--json]",
+        summary: "Change a variant's SKU, barcode or weight",
+        help: ["Prices: cerkel price set. Stock: cerkel inventory.", WRITE_HELP],
+        options: { ...WRITE_OPTIONS, sku: { type: "string" }, barcode: { type: "string" }, weight: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            const weight = nullable(str(v, "weight"));
+            return runWrite(s, flagsOf(v), "upsert_variant", defined({
+                variant: one(pos, "cerkel variant set <sku> [flags]"), sku: nullable(str(v, "sku")), barcode: nullable(str(v, "barcode")),
+                weightGrams: weight === undefined || weight === null ? weight : int(weight, "--weight"),
+            }));
+        },
+    },
+    "variant add": {
+        usage: "cerkel variant add <product> --option <Name=Value>… [--sku <sku>] [--barcode <code>] [--weight <grams>] [--yes] [--dry-run] [--json]",
+        summary: "Add a variant for a combination of existing option values",
+        help: ["e.g. cerkel variant add knee-support --option Size=L --option Color=Black --sku KS-L-BLK. New values: cerkel variant options first. Price it with cerkel price set.", WRITE_HELP],
+        options: { ...WRITE_OPTIONS, option: { type: "string", multiple: true }, sku: { type: "string" }, barcode: { type: "string" }, weight: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => runWrite(s, flagsOf(v), "upsert_variant", defined({
+            product: one(pos, "cerkel variant add <product> --option Name=Value"), optionValues: pairs(v, "option", { loose: false }),
+            sku: str(v, "sku"), barcode: str(v, "barcode"), weightGrams: int(str(v, "weight"), "--weight"),
+        })),
+    },
+    "variant delete": {
+        usage: "cerkel variant delete <sku|barcode|id> [--yes] [--dry-run] [--json]",
+        summary: "Delete a variant (refused while it is on an unfinished order)",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => runWrite(s, flagsOf(v), "delete_variant", { variant: one(pos, "cerkel variant delete <sku>") }),
+    },
+    "variant options": {
+        usage: "cerkel variant options <product> --option \"Size=S,M,L\" [--option \"Color=Red,Blue\"]… [--create-variants] [--lang en] [--yes] [--dry-run] [--json]",
+        summary: "Set a product's options and values (the variant matrix)",
+        help: [
+            "List every option with all its values, in order. Values you leave out must not be used by a variant. --create-variants adds a variant for every missing combination.",
+            "Names and values are in --lang (default ar); other languages stored on them are kept. Renames: use the admin or cerkel call set_product_options.",
+            WRITE_HELP,
+        ],
+        options: { ...WRITE_OPTIONS, ...LANG_OPTION, option: { type: "string", multiple: true }, "create-variants": { type: "boolean" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            const lang = str(v, "lang") ?? "ar";
+            const options = list(v, "option").map((o) => {
+                const i = o.indexOf("=");
+                if (i < 1)
+                    throw new CliError(`--option "${o}": write it as Name=Value1,Value2.`);
+                return { name: { [lang]: o.slice(0, i).trim() }, values: (csvList(o.slice(i + 1)) ?? []).map((x) => ({ label: { [lang]: x } })) };
+            });
+            return runWrite(s, flagsOf(v), "set_product_options", defined({
+                product: one(pos, "cerkel variant options <product> --option Name=V1,V2"), options, createVariants: bool(v, "create-variants") || undefined,
+            }));
+        },
+    },
+    "image add": {
+        usage: "cerkel image add <product> <https-url|media-id>… [--alt <text>] [--yes] [--dry-run] [--json]",
+        summary: "Add images to a product (by URL or media library id)",
+        help: ["Images are shared by every store of the brand and go after the existing ones.", WRITE_HELP],
+        options: { ...WRITE_OPTIONS, alt: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            const [product, ...refs] = pos;
+            if (!product || !refs.length)
+                throw new CliError("Usage: cerkel image add <product> <url>…");
+            const alt = str(v, "alt");
+            return runWrite(s, flagsOf(v), "add_product_images", {
+                product, images: refs.map((r) => ({ ...(/^[0-9a-f-]{36}$/i.test(r) ? { mediaId: r } : { url: r }), ...(alt ? { alt } : {}) })),
+            });
+        },
+    },
+    "image remove": {
+        usage: "cerkel image remove <product> <image-id|url>… [--yes] [--dry-run] [--json]",
+        summary: "Remove images from a product",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            const [product, ...images] = pos;
+            if (!product || !images.length)
+                throw new CliError("Usage: cerkel image remove <product> <image-id|url>…");
+            return runWrite(s, flagsOf(v), "remove_product_images", { product, images });
+        },
+    },
+    "image reorder": {
+        usage: "cerkel image reorder <product> <image-id|url>… [--yes] [--dry-run] [--json]",
+        summary: "Put a product's images in this order (the first is the main image)",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            const [product, ...images] = pos;
+            if (!product || !images.length)
+                throw new CliError("Usage: cerkel image reorder <product> <image-id|url>…");
+            return runWrite(s, flagsOf(v), "reorder_product_images", { product, images });
+        },
+    },
+    "category list": {
+        usage: "cerkel category list [--store <slug>] [--json]",
+        summary: "Show the category tree",
+        help: [READ_HELP],
+        options: READ_OPTIONS,
+        run: (s, v) => runRead(s, flagsOf(v), "list_categories", {}, (d) => d.categories.length === 0 ? ["No categories yet."] : table([["PATH", "NAME", "PRODUCTS"], ...d.categories.map((c) => [c.path, textOf(c.name), String(c.products.total)])])),
+    },
+    "category set": {
+        usage: "cerkel category set <product> <category-path|none> [--yes] [--dry-run] [--json]",
+        summary: "Put a product in a category (or none)",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            const [product, category, extra] = pos;
+            if (!product || category === undefined || extra !== undefined)
+                throw new CliError("Usage: cerkel category set <product> <category-path|none>");
+            return runWrite(s, flagsOf(v), "set_product_category", { product, category: nullable(category) ?? null });
+        },
+    },
+};