@cerkel/cli 0.0.0-stage → 1.0.1

package/dist/commands/content.js

@@ -0,0 +1,281 @@
+import { rm } from "node:fs/promises";
+import path from "node:path";
+import { bool, str } from "../command.js";
+import { READ_HELP, READ_OPTIONS, WRITE_HELP, WRITE_OPTIONS, diffLines, flagsOf, runRead, runWrite, storeAndClient } from "../commerce.js";
+import { addressOf, hashText, listContentFiles, menuPathOf, pageCreateArgs, pageFileOf, pagePathOf, pageUpdateArgs, parseMenu, parsePage, readContentState, readText, serializeMenu, serializePage, writeContentState, writeText, } from "../content-files.js";
+import { CliError } from "../errors.js";
+import { plural, table } from "../format.js";
+const SYNC_OPTIONS = { ...WRITE_OPTIONS, dir: { type: "string" }, force: { type: "boolean" } };
+const dirOf = (s, v) => path.resolve(s.ctx.cwd, typeof v["dir"] === "string" ? v["dir"] : ".");
+async function fetchPages(client, store) {
+    const out = [];
+    for (let page = 1;; page++) {
+        const r = await client.call("search_pages", { store, include_body: true, limit: 200, page });
+        out.push(...r.pages);
+        if (out.length >= r.total || r.pages.length === 0)
+            break;
+    }
+    return out;
+}
+/** `cerkel page pull` / `cerkel menu pull`: write every page (or menu) of the store into the folder. */
+async function pull(s, v, kind) {
+    const flags = flagsOf(v);
+    const dir = dirOf(s, v);
+    const prior = await readContentState(dir);
+    const { client, store } = await storeAndClient(s, { ...(flags.store ?? prior?.store ? { store: flags.store ?? prior.store } : {}) });
+    if (prior && prior.store !== store)
+        throw new CliError(`${dir} holds ${prior.store}'s content, not ${store}'s. Pull into another folder.`);
+    const files = new Map();
+    if (kind === "page")
+        for (const p of await fetchPages(client, store))
+            files.set(pagePathOf(p), { id: p.id, text: serializePage(pageFileOf(p)) });
+    else
+        for (const m of (await client.call("search_menus", { store })).menus)
+            files.set(menuPathOf(m.handle), { id: m.id, text: serializeMenu(m) });
+    // Never overwrite local edits silently: a file changed since the last pull/push needs --force.
+    const state = { version: 1, api: s.api().href, store, pulledAt: s.ctx.now().toISOString(), files: { ...(prior?.files ?? {}) } };
+    const mine = (rel) => { const a = addressOf(rel); return !!a && a.type === kind; };
+    const edited = [];
+    for (const rel of new Set([...files.keys(), ...Object.keys(state.files).filter(mine)])) {
+        const local = await readText(dir, rel);
+        if (local === null)
+            continue;
+        const base = state.files[rel]?.hash;
+        const incoming = files.get(rel)?.text;
+        if (hashText(local) !== base && (incoming === undefined || hashText(local) !== hashText(incoming)))
+            edited.push(rel);
+    }
+    if (edited.length && !bool(v, "force")) {
+        throw new CliError(`These files have local changes that pulling would overwrite:\n${edited.map((f) => `  ${f}`).join("\n")}\nPush them first, or pull with --force to discard them.`);
+    }
+    for (const rel of Object.keys(state.files).filter(mine)) {
+        if (!files.has(rel)) {
+            delete state.files[rel];
+            await rm(path.join(dir, ...rel.split("/")), { force: true });
+        }
+    }
+    for (const [rel, f] of files) {
+        await writeText(dir, rel, f.text);
+        state.files[rel] = { id: f.id, hash: hashText(f.text) };
+    }
+    await writeContentState(dir, state);
+    if (flags.json)
+        s.out(JSON.stringify({ store, dir, files: [...files.keys()] }, null, 2));
+    else
+        s.out(`Pulled ${plural(files.size, kind)} of ${store} into ${path.relative(s.ctx.cwd, dir) || "."}.`);
+    return 0;
+}
+/** `cerkel page push` / `cerkel menu push`: send the files changed since the last pull or push. */
+async function push(s, v, kind, only) {
+    const flags = flagsOf(v);
+    const force = bool(v, "force");
+    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 dir = dirOf(s, v);
+    const state = await readContentState(dir);
+    if (!state)
+        throw new CliError(`${dir} has no pulled content. Run \`cerkel ${kind} pull --store <slug>\` first.`);
+    if (flags.store && flags.store !== state.store)
+        throw new CliError(`${dir} holds ${state.store}'s content, not ${flags.store}'s.`);
+    const { client, store } = await storeAndClient(s, { store: state.store });
+    const wanted = only.map((f) => path.relative(dir, path.resolve(s.ctx.cwd, f)).split(path.sep).join("/"));
+    for (const w of wanted)
+        if (!addressOf(w) || addressOf(w).type !== kind)
+            throw new CliError(`${w} is not a ${kind} file (${kind === "page" ? "pages/<handle>.html, policies/<handle>.html or blogs/<blog>/<handle>.html" : "menus/<handle>.json"}).`);
+    const local = wanted.length ? wanted : await listContentFiles(dir, [kind]);
+    const plans = [];
+    const conflicts = [];
+    for (const rel of local) {
+        const text = await readText(dir, rel);
+        if (text === null)
+            throw new CliError(`${rel} does not exist.`);
+        const entry = state.files[rel];
+        if (entry && hashText(text) === entry.hash)
+            continue;
+        const a = addressOf(rel);
+        if (a.type === "page") {
+            const file = parsePage(text, rel);
+            if (!entry) {
+                plans.push({ rel, tool: "create_page", args: pageCreateArgs(a.page, file) });
+                continue;
+            }
+            const server = await client.call("get_page", { store, page: entry.id });
+            if (hashText(serializePage(pageFileOf(server))) !== entry.hash && !force) {
+                conflicts.push(rel);
+                continue;
+            }
+            plans.push({ rel, tool: "update_page", args: pageUpdateArgs(entry.id, a.page, file, server) });
+        }
+        else {
+            const file = parseMenu(text, rel);
+            if (!entry) {
+                plans.push({ rel, tool: "create_menu", args: { handle: a.handle, title: file.title, items: file.items } });
+                continue;
+            }
+            const server = await client.call("get_menu", { store, menu: entry.id });
+            if (hashText(serializeMenu(server)) !== entry.hash && !force) {
+                conflicts.push(rel);
+                continue;
+            }
+            plans.push({ rel, tool: "update_menu", args: { menu: entry.id, ...(a.handle !== server.handle ? { newHandle: a.handle } : {}), title: file.title, items: file.items } });
+        }
+    }
+    if (conflicts.length) {
+        throw new CliError(`Someone changed these on the server since your last pull:\n${conflicts.map((f) => `  ${f}`).join("\n")}\nPull them again (cerkel ${kind} pull --force overwrites your copy), or push with --force to overwrite the server's.`);
+    }
+    if (!wanted.length) {
+        const gone = Object.keys(state.files).filter((rel) => addressOf(rel)?.type === kind && !local.includes(rel));
+        for (const rel of gone)
+            s.err(`${rel} was removed locally; it stays on the store. Delete it there with \`cerkel ${kind} delete ${kind === "page" ? `/${rel.replace(/\.html$/, "")}` : rel.replace(/^menus\/|\.json$/g, "")}\`.`);
+    }
+    if (!plans.length) {
+        s.out("Nothing to push: no file changed since the last pull or push.");
+        return 0;
+    }
+    for (const p of plans)
+        p.preview = await client.call(p.tool, { store, ...p.args, dry_run: true });
+    const changing = plans.filter((p) => p.preview.changed);
+    if (flags.json && (flags.dryRun || !flags.yes))
+        s.out(JSON.stringify(changing.map((p) => ({ file: p.rel, ...p.preview })), null, 2));
+    else
+        for (const p of changing) {
+            s.out(`${p.rel}: ${p.preview.summary}`);
+            for (const line of diffLines(p.preview.diff))
+                s.out(line);
+        }
+    if (flags.dryRun) {
+        if (!flags.json)
+            s.err("Dry run: nothing was changed.");
+        return 0;
+    }
+    if (!flags.yes) {
+        const answer = (await s.ctx.io.prompt(`Push ${plural(changing.length, "change")} to ${store}? [y/N] `)).trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes") {
+            s.err("Cancelled. Nothing was changed.");
+            return 1;
+        }
+    }
+    const results = [];
+    for (const p of plans) {
+        const applied = await client.call(p.tool, { store, ...p.args, dry_run: false });
+        results.push({ file: p.rel, ...applied });
+        // Record the server's version of what was just written, and write it back so the file is exactly it.
+        const id = (p.args["page"] ?? p.args["menu"] ?? applied.result?.["pageId"] ?? applied.result?.["menuId"]);
+        if (!id)
+            continue;
+        if (kind === "page") {
+            const server = await client.call("get_page", { store, page: id });
+            const rel = pagePathOf(server);
+            const text = serializePage(pageFileOf(server));
+            if (rel !== p.rel)
+                delete state.files[p.rel];
+            await writeText(dir, rel, text);
+            state.files[rel] = { id, hash: hashText(text) };
+        }
+        else {
+            const server = await client.call("get_menu", { store, menu: id });
+            const rel = menuPathOf(server.handle);
+            const text = serializeMenu(server);
+            if (rel !== p.rel)
+                delete state.files[p.rel];
+            await writeText(dir, rel, text);
+            state.files[rel] = { id, hash: hashText(text) };
+        }
+        await writeContentState(dir, state);
+        if (!flags.json)
+            s.out(`Pushed ${p.rel}`);
+    }
+    if (flags.json)
+        s.out(JSON.stringify(results, null, 2));
+    return 0;
+}
+const titleOf = (t) => t["en"] || t["ar"] || Object.values(t)[0] || "";
+const SYNC_HELP = (kind) => [
+    kind === "page"
+        ? "Files: pages/<handle>.html, policies/<handle>.html, blogs/<blog>/<handle>.html — settings as JSON in <!--cerkel … -->, then the body per language after <!--lang:ar-->, <!--lang:en-->…"
+        : "Files: menus/<handle>.json — { \"title\": …, \"items\": [ { \"title\": {\"ar\": …}, \"url\": \"/collections/all\", \"children\": [ … ] } ] }",
+    "The file name is the handle. --dir <path> picks the folder (default: here).",
+];
+export const CONTENT_COMMANDS = {
+    "page pull": {
+        usage: "cerkel page pull [--store <slug>] [--dir <path>] [--force] [--json]",
+        summary: "Download the store's pages, policies and blog articles as files",
+        help: [...SYNC_HELP("page"), "Refuses to overwrite files you changed since the last pull or push unless --force.", READ_HELP],
+        options: SYNC_OPTIONS,
+        run: (s, v) => pull(s, v, "page"),
+    },
+    "page push": {
+        usage: "cerkel page push [files…] [--dir <path>] [--force] [--yes] [--dry-run] [--json]",
+        summary: "Send changed page files to the store (shows the changes and asks first)",
+        help: [
+            "Sends only files changed since the last pull/push; a new file creates the page. A file deleted locally is NOT deleted on the store (use cerkel page delete).",
+            "A page someone changed in the admin since your pull is refused as a conflict unless --force.",
+            WRITE_HELP,
+        ],
+        options: SYNC_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => push(s, v, "page", pos),
+    },
+    "page list": {
+        usage: "cerkel page list [--kind page|policy|article] [--search <text>] [--store <slug>] [--json]",
+        summary: "List the store's pages, policies and blog articles",
+        help: [READ_HELP],
+        options: { ...READ_OPTIONS, kind: { type: "string" }, search: { type: "string" } },
+        run: (s, v) => {
+            const kind = str(v, "kind");
+            if (kind && !["page", "policy", "article"].includes(kind))
+                throw new CliError("--kind is page, policy or article.");
+            return runRead(s, flagsOf(v), "search_pages", { limit: 200, ...(kind ? { kind } : {}), ...(str(v, "search") ? { q: str(v, "search") } : {}) }, (d) => [
+                ...table([["PATH", "TITLE", "VISIBLE", "SOURCE"], ...d.pages.map((p) => [p.path, titleOf(p.title), p.published ? "yes" : "no", p.source])]),
+                ...(d.total > d.pages.length ? [`… ${d.total - d.pages.length} more (use --search)`] : []),
+            ]);
+        },
+    },
+    "page delete": {
+        usage: "cerkel page delete <path|id> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Delete a page, policy or article (its URL then answers 404 unless redirected)",
+        help: ["Name it by its path: /pages/about, /policies/refund-policy, /blogs/news/launch.", WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel page delete <path|id>");
+            return runWrite(s, flagsOf(v), "delete_page", { page: pos[0] });
+        },
+    },
+    "menu pull": {
+        usage: "cerkel menu pull [--store <slug>] [--dir <path>] [--force] [--json]",
+        summary: "Download the store's navigation menus as files",
+        help: [...SYNC_HELP("menu"), "Refuses to overwrite files you changed since the last pull or push unless --force.", READ_HELP],
+        options: SYNC_OPTIONS,
+        run: (s, v) => pull(s, v, "menu"),
+    },
+    "menu push": {
+        usage: "cerkel menu push [files…] [--dir <path>] [--force] [--yes] [--dry-run] [--json]",
+        summary: "Send changed menu files to the store (shows the changes and asks first)",
+        help: ["Sends only files changed since the last pull/push; a new file creates the menu. Each file replaces that menu's whole item tree.", WRITE_HELP],
+        options: SYNC_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => push(s, v, "menu", pos),
+    },
+    "menu list": {
+        usage: "cerkel menu list [--store <slug>] [--json]",
+        summary: "List the store's navigation menus",
+        help: [READ_HELP],
+        options: READ_OPTIONS,
+        run: (s, v) => runRead(s, flagsOf(v), "search_menus", {}, (d) => table([["HANDLE", "TITLE", "ITEMS"], ...d.menus.map((m) => [m.handle, m.title, String(m.itemCount)])])),
+    },
+    "menu delete": {
+        usage: "cerkel menu delete <handle> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Delete a navigation menu",
+        help: [WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            if (pos.length !== 1)
+                throw new CliError("Usage: cerkel menu delete <handle>");
+            return runWrite(s, flagsOf(v), "delete_menu", { menu: pos[0] });
+        },
+    },
+};

package/dist/commands/customer.js

@@ -0,0 +1,126 @@
+import { bool, str } from "../command.js";
+import { READ_HELP, READ_OPTIONS, WRITE_HELP, WRITE_OPTIONS, flagsOf, runRead, runWrite, show } from "../commerce.js";
+import { CliError } from "../errors.js";
+import { table } from "../format.js";
+import { listFlag, need } from "./order-args.js";
+const pct = (r) => (r === null ? "—" : `${Math.round(r * 100)}%`);
+export const CUSTOMER_COMMANDS = {
+    "customer list": {
+        usage: "cerkel customer list [--q <text>] [--flag blocked|watch|vip]… [--tag <t>]… [--refusers] [--sort lastAt|orders|ordered|collected|refused|name] [--limit <n>] [--page <n>] [--store <slug>] [--json]",
+        summary: "Search the store's customers",
+        help: ["Everyone who placed a real order in this store. Phones are masked unless your login may see customer details.", READ_HELP],
+        options: { ...READ_OPTIONS, q: { type: "string" }, flag: { type: "string", multiple: true }, tag: { type: "string", multiple: true }, refusers: { type: "boolean" }, sort: { type: "string" }, limit: { type: "string" }, page: { type: "string" } },
+        run: (s, v) => runRead(s, flagsOf(v), "search_customers", {
+            ...(str(v, "q") ? { q: str(v, "q") } : {}), ...(listFlag(v, "flag") ? { flag: listFlag(v, "flag") } : {}), ...(listFlag(v, "tag") ? { tag: listFlag(v, "tag") } : {}),
+            ...(bool(v, "refusers") ? { refusers: true } : {}), ...(str(v, "sort") ? { sort: str(v, "sort") } : {}),
+            ...(str(v, "limit") ? { limit: Number(str(v, "limit")) } : {}), ...(str(v, "page") ? { page: Number(str(v, "page")) } : {}),
+        }, (d) => [
+            ...table([["Name", "Phone", "Latest order", "Orders", "Ordered", "Refused", "Flags", "Tags"], ...d.customers.map((c) => [c.name ?? "—", c.phone ?? "—", c.latestOrder ?? "—", String(c.orders), show(c.ordered), String(c.refused), c.flags.join(", "), c.tags.join(", ")])]),
+            `${d.customers.length} of ${d.total}.`,
+        ]),
+    },
+    "customer get": {
+        usage: "cerkel customer get <phone|order> [--store <slug>] [--json]",
+        summary: "Show a customer: orders in this store, refusal rate, risk, flags and notes",
+        help: [READ_HELP],
+        options: READ_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 1, "cerkel customer get <phone|order>");
+            return runRead(s, flagsOf(v), "get_customer", { customer: pos[0] }, (d) => [
+                ...table([
+                    ["Name", d.name ?? "—"], ["Phone", `${d.phone ?? "—"}${d.phoneAlt ? ` / ${d.phoneAlt}` : ""}`], ["Email", d.email ?? "—"],
+                    ["Refusal rate", `${pct(d.refusal.rate)} (${d.refusal.refused} refused, ${d.refusal.delivered} delivered)`],
+                    ["Risk", d.risk ? `${d.risk.band} (${d.risk.score})` : "—"],
+                    ["Flags", d.flags.map((f) => f.flag + (f.note ? ` (${f.note})` : "")).join(", ") || "—"],
+                    ["Tags", d.tags.join(", ") || "—"], ["Note", d.note ?? "—"], ["WhatsApp offers", d.whatsappOffers.subscribed ? "on" : "off"],
+                ]),
+                "",
+                ...table([["Order", "Placed", "Status", "Total"], ...d.orders.map((o) => [o.number, o.placedAt.slice(0, 10), o.status, o.total.formatted])]),
+            ]);
+        },
+    },
+    "customer update": {
+        usage: "cerkel customer update <phone|order> [--name <name>] [--email <email>] [--phone-alt <phone>] [--note <text>] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Edit a customer's name, email, second number or note",
+        help: ["An empty --email / --phone-alt removes it. The main phone cannot change. Orders keep the details they were placed with.", WRITE_HELP],
+        options: { ...WRITE_OPTIONS, name: { type: "string" }, email: { type: "string" }, "phone-alt": { type: "string" }, note: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 1, "cerkel customer update <phone|order> --name … | --email … | --phone-alt … | --note …");
+            const args = {
+                ...(str(v, "name") !== undefined ? { name: str(v, "name") } : {}), ...(str(v, "email") !== undefined ? { email: str(v, "email") } : {}),
+                ...(str(v, "phone-alt") !== undefined ? { phone_alt: str(v, "phone-alt") } : {}), ...(str(v, "note") !== undefined ? { note: str(v, "note") } : {}),
+            };
+            if (!Object.keys(args).length)
+                throw new CliError("Pass at least one of --name, --email, --phone-alt or --note.");
+            return runWrite(s, flagsOf(v), "update_customer_profile", { customer: pos[0], ...args });
+        },
+    },
+    "customer tag": {
+        usage: "cerkel customer tag <phone|order> [--add <t>]… [--remove <t>]… [--set <t,t>] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Add, remove or replace a customer's tags",
+        help: [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 customer tag <phone|order> --add <tag> | --remove <tag> | --set <tags>");
+            const set = str(v, "set");
+            return runWrite(s, flagsOf(v), "set_customer_tags", {
+                customer: 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") } : {}),
+            });
+        },
+    },
+    "customer flag": {
+        usage: "cerkel customer flag <phone|order> <blocked|watch|vip> [--off] [--note <why>] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Flag a customer (blocked refuses them cash on delivery) or lift a flag with --off",
+        help: ["Flags apply in every store of the organisation; the customer's risk is recomputed right after.", WRITE_HELP],
+        options: { ...WRITE_OPTIONS, off: { type: "boolean" }, note: { type: "string" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 2, "cerkel customer flag <phone|order> <blocked|watch|vip> [--off]");
+            return runWrite(s, flagsOf(v), "set_customer_flag", { customer: pos[0], flag: pos[1], on: !bool(v, "off"), ...(str(v, "note") ? { note: str(v, "note") } : {}) });
+        },
+    },
+    "review list": {
+        usage: "cerkel review list [--status pending|approved|rejected|hidden]… [--rating <1-5>]… [--q <text>] [--limit <n>] [--store <slug>] [--json]",
+        summary: "List the store's customer reviews",
+        help: [READ_HELP],
+        options: { ...READ_OPTIONS, status: { type: "string", multiple: true }, rating: { type: "string", multiple: true }, q: { type: "string" }, limit: { type: "string" } },
+        run: (s, v) => runRead(s, flagsOf(v), "list_reviews", {
+            ...(listFlag(v, "status") ? { status: listFlag(v, "status") } : {}),
+            ...(listFlag(v, "rating") ? { rating: listFlag(v, "rating").map(Number) } : {}),
+            ...(str(v, "q") ? { q: str(v, "q") } : {}), ...(str(v, "limit") ? { limit: Number(str(v, "limit")) } : {}),
+        }, (d) => [
+            ...table([["Id", "Status", "Rating", "Reviewer", "Order", "Review"], ...d.reviews.map((r) => [r.id, r.status, `${r.rating}★`, r.reviewer.name ?? "—", r.order ?? "—", (r.title ?? r.body ?? "").slice(0, 60)])]),
+            Object.entries(d.counts).map(([k, n]) => `${k}: ${n}`).join(" · "),
+        ]),
+    },
+    "review moderate": {
+        usage: "cerkel review moderate <id> <approved|rejected|hidden|pending> [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Approve, reject or hide a review",
+        help: ["Approved reviews show on the storefront.", WRITE_HELP],
+        options: WRITE_OPTIONS,
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 2, "cerkel review moderate <id> <approved|rejected|hidden|pending>");
+            return runWrite(s, flagsOf(v), "moderate_review", { review: pos[0], status: pos[1] });
+        },
+    },
+    "review reply": {
+        usage: "cerkel review reply <id> <text…> [--remove] [--store <slug>] [--yes] [--dry-run] [--json]",
+        summary: "Write (or with --remove, take down) the store's public reply to a review",
+        help: [WRITE_HELP],
+        options: { ...WRITE_OPTIONS, remove: { type: "boolean" } },
+        positionals: true,
+        run: (s, v, pos) => {
+            need(pos, 1, "cerkel review reply <id> <text…>");
+            const text = pos.slice(1).join(" ").trim();
+            if (!text && !bool(v, "remove"))
+                throw new CliError("Write the reply after the id, or pass --remove to take it down.");
+            return runWrite(s, flagsOf(v), "reply_review", { review: pos[0], reply: bool(v, "remove") ? "" : text });
+        },
+    },
+};

package/dist/commands/dev.js

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