@cerkel/cli 0.0.0-stage → 1.0.1

package/dist/commands/theme-tools.js

@@ -0,0 +1,432 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { apiOrigin } from "../api-url.js";
+import { createDraft, getThemeFiles, listThemes, nameOf, putThemeFiles } from "../api.js";
+import { chunkFiles } from "../chunk.js";
+import { CliError } from "../errors.js";
+import { plural, table } from "../format.js";
+import { bytesOf, hashBytes, isLayoutPath, textOf, toDiskPath } from "../layout.js";
+import { findRoot, listLocalFiles, localChanges, readLocal, readState, writeState } from "../state.js";
+import { createZip } from "../zip.js";
+async function target(s, opts) {
+    const co = await s.checkout();
+    const store = opts.store ?? co?.state.store ?? (await s.defaultStore());
+    const client = await s.client(co?.state, store);
+    const fromFolder = co && co.state.store === store ? co.state.themeId : undefined;
+    return { client, store, themeId: opts.theme ?? fromFolder, checkout: co };
+}
+/** A theme write needs a named theme: `--theme`, or this folder's. Never the live theme by default. */
+function needTheme(t, verb) {
+    if (t.themeId)
+        return t.themeId;
+    throw new CliError(`Which theme ${verb}? Pass --theme <id> (\`cerkel theme list\` shows them), or run this in a theme folder.`);
+}
+const json = (s, data) => s.out(JSON.stringify(data, null, 2));
+const kb = (bytes) => (bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`);
+const getInfo = (t) => t.client.call("get_theme_info", { store: t.store, ...(t.themeId ? { themeId: t.themeId } : {}) });
+export async function themeInfo(s, opts) {
+    const t = await target(s, opts);
+    const d = await getInfo(t);
+    if (opts.json) {
+        json(s, { ...d, editorUrl: `${apiOrigin(t.client.url)}${d.editorPath}`, codeUrl: `${apiOrigin(t.client.url)}${d.codePath}` });
+        return 0;
+    }
+    const files = Object.entries(d.files).sort(([a], [b]) => a.localeCompare(b)).map(([k, n]) => `${k} ${n}`).join(", ");
+    for (const line of table([
+        ["Name", d.name],
+        ["ID", d.id],
+        ["Role", d.role === "live" ? "live (what customers see)" : "draft"],
+        ["Store", t.store],
+        ["Preset", d.preset],
+        ["Updated", d.updatedAt],
+        ["Created by", d.createdBy ?? "—"],
+        ["Published", d.publishedAt ? `${d.publishedAt}${d.publishedBy ? ` by ${d.publishedBy}` : ""}` : "—"],
+        ["Templates", d.templates.join(", ") || "—"],
+        ["Files", files ? `${files} (${kb(d.bytes)})` : "—"],
+        ["In review", d.review ? `${d.review.status}: "${d.review.title}" (${apiOrigin(t.client.url)}/themes/requests/${d.review.requestId})` : "—"],
+        ["Editor", `${apiOrigin(t.client.url)}${d.editorPath}`],
+        ["Code", `${apiOrigin(t.client.url)}${d.codePath}`],
+        ["Preview host", d.previewHost ?? "— (no Cerkel-served domain yet)"],
+    ]))
+        s.out(line);
+    return 0;
+}
+export async function themeOpen(s, opts) {
+    const t = await target(s, opts);
+    const d = await getInfo(t);
+    const url = `${apiOrigin(t.client.url)}${opts.code ? d.codePath : d.editorPath}`;
+    s.out(url);
+    if (d.role === "live")
+        s.err("This is the live theme: the editor opens it read-only. Edit a draft (`cerkel theme pull` makes one).");
+    if (!opts.print)
+        await s.ctx.openUrl(url);
+    return 0;
+}
+// --- rename / delete -------------------------------------------------------------------------------
+export async function themeRename(s, name, opts) {
+    const clean = name?.trim();
+    if (!clean)
+        throw new CliError('What name? e.g. `cerkel theme rename "Ramadan 2027"`.');
+    const t = await target(s, opts);
+    const themeId = needTheme(t, "to rename");
+    const r = await t.client.call("rename_theme", { store: t.store, themeId, name: clean });
+    // This folder tracks that theme: keep its recorded name in step.
+    if (t.checkout && t.checkout.state.themeId === r.id && t.checkout.state.themeName !== r.name) {
+        await writeState(t.checkout.root, { ...t.checkout.state, themeName: r.name });
+    }
+    if (opts.json)
+        json(s, r);
+    else
+        s.out(r.before === r.name ? `"${r.name}" already has that name.` : `Renamed "${r.before}" → "${r.name}" (${r.role}, ${r.id}).`);
+    return 0;
+}
+export async function themeDeleteTheme(s, opts) {
+    if (!opts.theme)
+        throw new CliError("Which draft? Pass --theme <id> (`cerkel theme list` shows them). To delete files from this folder's draft, name them: `cerkel theme delete snippets/old.liquid`.");
+    const t = await target(s, opts);
+    const d = await getInfo(t);
+    if (d.role === "live")
+        throw new CliError(`"${d.name}" is the LIVE theme — what customers see. It can never be deleted. Only drafts can.`);
+    if (!opts.yes) {
+        if (!s.ctx.io.isTTY)
+            throw new CliError(`Deleting "${d.name}" cannot be undone, and there is no terminal to confirm in. Re-run with --yes.`);
+        s.err(`This deletes the draft "${d.name}" (${d.id}) on ${t.store}: its templates, settings and files (their history stays). Every shared preview link to it stops working. It cannot be undone.`);
+        const typed = (await s.ctx.io.prompt(`Type the theme's name to delete it: `)).trim();
+        if (typed !== d.name.trim())
+            throw new CliError("The name did not match; nothing was deleted.");
+    }
+    const r = await t.client.call("delete_theme", { store: t.store, themeId: d.id });
+    if (opts.json)
+        json(s, r);
+    else
+        s.out(`Deleted the draft "${r.name}" (${r.id}).`);
+    if (t.checkout && t.checkout.state.themeId === r.id) {
+        s.err(`${t.checkout.root} was a checkout of that draft. Run \`cerkel theme pull\` there to work on another draft (your local files are kept).`);
+    }
+    return 0;
+}
+// --- share -----------------------------------------------------------------------------------------
+export async function themeShare(s, opts) {
+    const days = opts.days === undefined ? undefined : Number(opts.days);
+    if (days !== undefined && (!Number.isInteger(days) || days < 1 || days > 14))
+        throw new CliError("--days is a whole number from 1 to 14.");
+    const t = await target(s, opts);
+    const themeId = needTheme(t, "to share");
+    if (t.checkout && t.checkout.state.themeId === themeId) {
+        const pending = (await localChanges(t.checkout.root, t.checkout.state)).changes.length;
+        if (pending > 0)
+            s.err(`Note: ${plural(pending, "local change")} not pushed yet; the link shows the draft as it is on the server (\`cerkel theme push\` first).`);
+    }
+    const r = await t.client.call("share_theme", {
+        store: t.store, themeId, ...(days !== undefined ? { days } : {}), ...(opts.path ? { path: opts.path } : {}),
+    });
+    if (opts.json) {
+        json(s, r);
+        return 0;
+    }
+    s.out(r.url);
+    s.err(`Preview of "${r.theme.name}" — anyone with this link sees the draft until ${r.expiresAt} (${plural(r.days, "day")}). Deleting the draft revokes it.`);
+    return 0;
+}
+/** `product.title` → `{{ product.title }}`; anything that is already Liquid markup is sent as typed. */
+export const asLiquid = (input) => (/\{\{|\{%/.test(input) ? input : `{{ ${input} }}`);
+const CONSOLE_HELP = [
+    "Type Liquid and press Enter: `product.title`, `{{ collections | size }}`, `{% for p in all_products %}{{ p.title }} {% endfor %}`.",
+    "A bare expression is wrapped in {{ }}. Commands: .path /products/<handle> (the page whose data you see), .locale en, .help, .exit (or Ctrl-D).",
+];
+export async function themeConsole(s, opts) {
+    const t = await target(s, opts);
+    let pagePath = opts.path ?? "/";
+    let locale = opts.locale;
+    const evaluate = async (liquid) => t.client.call("evaluate_liquid", {
+        store: t.store, liquid, path: pagePath, ...(t.themeId ? { themeId: t.themeId } : {}), ...(locale ? { locale } : {}),
+    });
+    const show = (r) => {
+        if (opts.json) {
+            json(s, r);
+            return r.liquidError === null;
+        }
+        if (r.liquidError) {
+            s.err(`Liquid error: ${r.liquidError}`);
+            return false;
+        }
+        s.out(r.output === "" ? "(empty)" : r.output);
+        return true;
+    };
+    // One shot: `-e/--eval`, or Liquid piped in on stdin.
+    if (opts.eval !== undefined || !s.ctx.io.isTTY) {
+        const liquid = opts.eval ?? (await s.ctx.io.readStdin());
+        if (!liquid.trim())
+            throw new CliError('Nothing to evaluate. Pass -e "{{ product.title }}", pipe Liquid in, or run it in a terminal for the interactive console.');
+        return show(await evaluate(opts.eval !== undefined ? asLiquid(liquid) : liquid)) ? 0 : 1;
+    }
+    // The REPL.
+    const first = await evaluate("");
+    s.err(`Liquid console — "${first.theme.name}" (${first.theme.role}) on ${t.store}, page ${first.page.path} (${first.page.template}${first.page.found ? "" : ", not found"}), language ${first.locale}.`);
+    for (const line of CONSOLE_HELP)
+        s.err(line);
+    try {
+        for (;;) {
+            const input = await s.ctx.io.readLine(`${pagePath}> `);
+            if (input === null)
+                break;
+            const line = input.trim();
+            if (!line)
+                continue;
+            if (line === ".exit" || line === "exit" || line === ".quit")
+                break;
+            if (line === ".help") {
+                for (const l of CONSOLE_HELP)
+                    s.err(l);
+                continue;
+            }
+            if (line.startsWith(".path")) {
+                const next = line.slice(5).trim() || "/";
+                const was = pagePath;
+                pagePath = next;
+                const check = await evaluate("").catch((e) => {
+                    s.err(e instanceof Error ? e.message : String(e));
+                    return null;
+                });
+                if (check)
+                    s.err(`Page ${check.page.path} (${check.page.template}${check.page.found ? "" : ", not found — that page's objects are empty"}).`);
+                else
+                    pagePath = was;
+                continue;
+            }
+            if (line.startsWith(".locale")) {
+                const next = line.slice(7).trim();
+                if (!next) {
+                    s.err("Which language? e.g. .locale en");
+                    continue;
+                }
+                const was = locale;
+                locale = next;
+                const check = await evaluate("").catch((e) => {
+                    s.err(e instanceof Error ? e.message : String(e));
+                    return null;
+                });
+                if (check)
+                    s.err(`Language ${check.locale}.`);
+                else
+                    locale = was;
+                continue;
+            }
+            try {
+                show(await evaluate(asLiquid(line)));
+            }
+            catch (e) {
+                // A refusal (a typo'd path, a dropped connection) never ends the session.
+                s.err(e instanceof Error ? e.message : String(e));
+            }
+        }
+    }
+    finally {
+        s.ctx.io.closeLines();
+    }
+    return 0;
+}
+const SOURCE = { file: "theme file", compiled: "built-in", legacy: "custom section", none: "nothing" };
+export async function themeProfile(s, opts) {
+    const runs = opts.runs === undefined ? undefined : Number(opts.runs);
+    if (runs !== undefined && (!Number.isInteger(runs) || runs < 1 || runs > 5))
+        throw new CliError("--runs is a whole number from 1 to 5.");
+    const t = await target(s, opts);
+    const p = await t.client.call("profile_theme", {
+        store: t.store, ...(t.themeId ? { themeId: t.themeId } : {}), ...(opts.path ? { path: opts.path } : {}), ...(opts.locale ? { locale: opts.locale } : {}), ...(runs ? { runs } : {}),
+    });
+    if (opts.json) {
+        json(s, p);
+        return 0;
+    }
+    const median = [...p.pageMs].sort((a, b) => a - b)[Math.floor(p.pageMs.length / 2)] ?? 0;
+    s.out(`"${p.theme.name}" (${p.theme.role}) — ${p.path} in ${p.locale}, HTTP ${p.status}, ${plural(p.pageMs.length, "run")}${p.pageMs.length > 1 ? " (medians)" : ""}`);
+    const slowest = Math.max(...p.sections.map((x) => x.ms), 0);
+    for (const line of table([
+        ["#", "SECTION", "TYPE", "WHERE", "RENDERED BY", "MS"],
+        ...p.sections.map((x, n) => [
+            String(n + 1), x.id, x.type, x.template ?? "—",
+            `${SOURCE[x.source] ?? x.source}${x.client ? " (browser)" : ""}`,
+            `${x.ms.toFixed(1)}${x.ms === slowest && slowest > 0 ? "  ← slowest" : ""}${x.error ? "  ERROR" : ""}`,
+        ]),
+    ]))
+        s.out(line);
+    s.out(`Sections ${p.sectionsMs.toFixed(1)} ms · whole page ${median.toFixed(1)} ms (request to last byte, from the Cerkel server).`);
+    for (const x of p.sections.filter((y) => y.error))
+        s.err(`${x.id} (${x.type}): ${x.error}`);
+    if (p.sections.some((x) => x.client))
+        s.err("(browser) = a built-in section drawn in the shopper's browser: its server time is only its setup.");
+    return p.sections.some((x) => x.error) ? 1 : 0;
+}
+// --- package ---------------------------------------------------------------------------------------
+const slug = (v) => v.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+export async function themePackage(s, opts) {
+    const root = (await findRoot(s.ctx.cwd)) ?? s.ctx.cwd;
+    const state = await readState(root);
+    const paths = await listLocalFiles(root);
+    if (paths.length === 0)
+        throw new CliError(`No theme files in ${root}. Run this in a theme folder (\`cerkel theme pull\` or \`cerkel theme init\`).`);
+    const base = (state ? slug(`${state.store}-${state.themeName}`) : slug(path.basename(root))) || "theme";
+    const out = path.resolve(s.ctx.cwd, opts.output ?? `${base}.zip`);
+    if (!out.toLowerCase().endsWith(".zip"))
+        throw new CliError("--output must end in .zip.");
+    try {
+        await fs.access(out);
+        if (!opts.force)
+            throw new CliError(`${out} already exists. Pass --force to replace it, or --output <file>.zip.`);
+    }
+    catch (e) {
+        if (e instanceof CliError)
+            throw e;
+    }
+    const entries = [];
+    let bytes = 0;
+    for (const p of paths) {
+        const b = await readLocal(root, p);
+        if (!b)
+            continue;
+        entries.push({ name: p, data: b });
+        bytes += b.length;
+    }
+    const zip = createZip(entries, s.ctx.now());
+    await fs.mkdir(path.dirname(out), { recursive: true });
+    await fs.writeFile(out, zip);
+    if (opts.json) {
+        json(s, { file: out, files: entries.map((e) => e.name), bytes: zip.length });
+        return 0;
+    }
+    s.out(out);
+    s.err(`Packaged ${plural(entries.length, "theme file")} (${kb(bytes)}, ${kb(zip.length)} zipped) from ${root}${state ? ` — "${state.themeName}" as it is in this folder, including changes not pushed yet` : ""}.`);
+    return 0;
+}
+export async function themeInit(s, dir, opts) {
+    const co = await s.checkout();
+    const client = await s.client(co?.state, opts.store ?? co?.state.store ?? null);
+    const { starters } = await client.call("list_theme_starters", {});
+    if (opts.list) {
+        if (opts.json)
+            json(s, starters.map((x) => ({ key: x.key, name: x.name, description: x.description, files: x.files.map((f) => f.path) })));
+        else
+            for (const line of table([["STARTER", "NAME", "WHAT IT IS"], ...starters.map((x) => [x.key, nameOf(x.name), nameOf(x.description)])]))
+                s.out(line);
+        return 0;
+    }
+    const starter = opts.starter ? starters.find((x) => x.key === opts.starter) : starters[0];
+    if (!starter)
+        throw new CliError(`No starter "${opts.starter}". \`cerkel theme init --list\` shows them.`);
+    const target = path.resolve(s.ctx.cwd, dir ?? "cerkel-theme");
+    const enclosing = await findRoot(target);
+    if (enclosing)
+        throw new CliError(`${target} is inside the theme folder ${enclosing}. Start a new theme in a folder of its own.`);
+    let existing = [];
+    try {
+        existing = (await fs.readdir(target)).filter((n) => !n.startsWith("."));
+    }
+    catch { /* a new folder */ }
+    if (existing.length > 0)
+        throw new CliError(`${target} is not empty. Choose a new folder: \`cerkel theme init <folder>\`.`);
+    for (const f of starter.files) {
+        if (!isLayoutPath(f.path))
+            throw new CliError(`The server sent a starter file this CLI cannot store (${f.path}). Update the CLI.`);
+        const disk = toDiskPath(target, f.path);
+        await fs.mkdir(path.dirname(disk), { recursive: true });
+        await fs.writeFile(disk, bytesOf(f.content));
+    }
+    await fs.writeFile(path.join(target, "README.md"), starter.readme);
+    if (opts.json) {
+        json(s, { folder: target, starter: starter.key, files: starter.files.map((f) => f.path) });
+        return 0;
+    }
+    s.out(`Created ${target} from the "${nameOf(starter.name)}" starter: ${plural(starter.files.length, "theme file")} and a README.`);
+    s.out("Next:");
+    s.out(`  cd ${path.relative(s.ctx.cwd, target) || "."}`);
+    s.out(`  cerkel theme push --new [--store <slug>]   # a new draft (copied from the live theme) with these files`);
+    s.out("  cerkel theme dev                           # edit with a live preview on the store's own domain");
+    s.out('  cerkel theme submit -m "New design"        # send it for approval');
+    return 0;
+}
+// --- push --new ------------------------------------------------------------------------------------
+/**
+ * `cerkel theme push --new`: this folder (an init folder, or any folder of theme files that is not a
+ * checkout) → a NEW draft copied from the live theme, with these files on top. The folder then
+ * becomes that draft's checkout: the draft's other files (the live theme's templates, settings,
+ * texts) are written next to yours, so `dev`, `push` and `submit` work as after a pull.
+ */
+export async function themePushNew(s, opts) {
+    const enclosing = await findRoot(s.ctx.cwd);
+    if (enclosing) {
+        throw new CliError(`${enclosing} is already the checkout of a draft. \`cerkel theme push\` sends its changes; --new is for a folder of theme files with no draft yet (e.g. after \`cerkel theme init\`).`);
+    }
+    const root = s.ctx.cwd;
+    const paths = await listLocalFiles(root);
+    if (paths.length === 0)
+        throw new CliError(`No theme files in ${root} to push. \`cerkel theme init\` creates a starter theme.`);
+    const store = opts.store ?? (await s.defaultStore());
+    const client = await s.client(null, store);
+    const live = (await listThemes(client, store)).find((t) => t.role === "live");
+    const name = opts.name?.trim() || `${path.basename(root)} (draft)`;
+    const made = await createDraft(client, store, name, live?.id);
+    s.err(`Created the draft "${made.name}" (${made.themeId}) on ${store}${live ? `, copied from the live theme "${live.name}"` : ""}.`);
+    // The new draft already holds the live theme's copy of files like templates/index.json: claim
+    // exactly that version (its tag), so the push replaces it instead of reporting a conflict.
+    const server = await getThemeFiles(client, store, made.themeId);
+    const serverTag = new Map(server.files.map((f) => [f.path, f.tag]));
+    const local = new Map();
+    for (const p of paths) {
+        const b = await readLocal(root, p);
+        if (b)
+            local.set(p, b);
+    }
+    const payload = [...local].map(([p, b]) => ({ path: p, content: textOf(b), baseTag: serverTag.get(p) ?? null }));
+    const results = new Map();
+    let saved = 0;
+    let failed = 0;
+    for (const chunk of chunkFiles(payload)) {
+        const r = await putThemeFiles(client, store, made.themeId, chunk, false);
+        for (const res of r.results ?? []) {
+            results.set(res.path, res);
+            if (res.status === "saved" || res.status === "unchanged") {
+                if (res.status === "saved")
+                    saved++;
+                s.out(`  ${res.status.padEnd(9)}  ${res.path}`);
+            }
+            else {
+                failed++;
+                s.out(`  ${res.status.padEnd(9)}  ${res.path}${res.message ? ` — ${res.message}` : ""}`);
+                for (const issue of res.errors ?? [])
+                    s.out(`    ${res.path}:${issue.line ?? 1}:${issue.column ?? 1}  ${issue.severity}  ${issue.message}`);
+            }
+        }
+    }
+    // The folder becomes the draft's checkout.
+    const after = await getThemeFiles(client, store, made.themeId);
+    const files = {};
+    let added = 0;
+    for (const f of after.files) {
+        if (!isLayoutPath(f.path))
+            continue;
+        const mine = local.get(f.path);
+        const pushed = results.get(f.path);
+        if (mine && (pushed?.status === "saved" || pushed?.status === "unchanged")) {
+            files[f.path] = { tag: f.tag, hash: hashBytes(mine) };
+        }
+        else if (mine) {
+            // Refused: keep the local file as an unpushed change against the server's version.
+            files[f.path] = { tag: f.tag, hash: hashBytes(bytesOf(f.content)) };
+        }
+        else {
+            const disk = toDiskPath(root, f.path);
+            await fs.mkdir(path.dirname(disk), { recursive: true });
+            await fs.writeFile(disk, bytesOf(f.content));
+            files[f.path] = { tag: f.tag, hash: hashBytes(bytesOf(f.content)) };
+            added++;
+        }
+    }
+    await writeState(root, {
+        version: 1, api: client.url.href, store, themeId: made.themeId, themeName: made.name, role: "draft", readOnly: false,
+        pulledAt: s.ctx.now().toISOString(), files,
+    });
+    s.err(`${saved} saved, ${failed} failed. ${plural(added, "file")} of the draft written next to yours; this folder is now the checkout of "${made.name}".`);
+    s.err(failed > 0 ? "Fix the files above and run `cerkel theme push`." : "Next: `cerkel theme dev`, then `cerkel theme submit -m \"…\"`.");
+    return failed > 0 ? 1 : 0;
+}