@cerkel/cli 0.0.0-stage → 1.0.0

package/dist/state.js

@@ -0,0 +1,153 @@
+import { existsSync, promises as fs } from "node:fs";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { LAYOUT_DIRS, hashBytes, isLayoutPath, legacySectionPartOf, toDiskPath } from "./layout.js";
+/**
+ * `.cerkel/state.json` — what this folder was pulled from and the server tag + local hash of every
+ * file at that moment. It never holds the token: a checkout gets committed, zipped and shared.
+ */
+export const STATE_DIR = ".cerkel";
+/** Where `raizn` (before 1.0) kept a folder's state. A folder pulled then keeps using it; nothing is moved. */
+export const LEGACY_STATE_DIR = ".raizn";
+export const STATE_FILE = "state.json";
+/**
+ * The state folder of `root` for `file`: `.cerkel`, unless the folder was pulled by `raizn` (before 1.0)
+ * and so holds `.raizn/<file>`, or a `.raizn` folder and no `.cerkel` one (so its state stays together).
+ */
+export function stateDirOf(root, file = STATE_FILE) {
+    if (existsSync(path.join(root, STATE_DIR, file)))
+        return STATE_DIR;
+    if (existsSync(path.join(root, LEGACY_STATE_DIR, file)))
+        return LEGACY_STATE_DIR;
+    if (existsSync(path.join(root, LEGACY_STATE_DIR)) && !existsSync(path.join(root, STATE_DIR)))
+        return LEGACY_STATE_DIR;
+    return STATE_DIR;
+}
+export const statePath = (root) => path.join(root, stateDirOf(root), STATE_FILE);
+export async function readState(root) {
+    let raw;
+    try {
+        raw = await fs.readFile(statePath(root), "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw e;
+    }
+    let s;
+    try {
+        s = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError(`${statePath(root)} is not valid JSON. Pull again with \`cerkel theme pull --force\`.`);
+    }
+    const o = s;
+    if (o.version !== 1 || typeof o.store !== "string" || typeof o.themeId !== "string" || typeof o.files !== "object" || o.files === null) {
+        throw new CliError(`${statePath(root)} is not a state file this version of cerkel understands. Pull again with \`cerkel theme pull --force\`.`);
+    }
+    return { ...o, readOnly: o.readOnly === true };
+}
+/** Written to a temp file and renamed, so a Ctrl-C mid-write never leaves half a state file. */
+export async function writeState(root, state) {
+    const dir = path.join(root, stateDirOf(root));
+    await fs.mkdir(dir, { recursive: true });
+    // `*` keeps the whole folder — state, tags, anything added later — out of the theme's git repo.
+    await fs.writeFile(path.join(dir, ".gitignore"), "*\n");
+    const file = statePath(root);
+    const tmp = `${file}.${process.pid}.tmp`;
+    const sorted = {};
+    for (const k of Object.keys(state.files).sort())
+        sorted[k] = state.files[k];
+    await fs.writeFile(tmp, JSON.stringify({ ...state, files: sorted }, null, 2) + "\n");
+    await fs.rename(tmp, file);
+}
+/** Walk up from `start` to the nearest folder holding `.cerkel/state.json` (or `.raizn/`), like git finds `.git`. */
+export async function findRoot(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        try {
+            await fs.access(statePath(dir));
+            return dir;
+        }
+        catch {
+            /* keep walking */
+        }
+        const up = path.dirname(dir);
+        if (up === dir)
+            return null;
+        dir = up;
+    }
+}
+/** Every layout file under `root`, as POSIX layout paths. Anything else in the folder is ignored. */
+export async function listLocalFiles(root) {
+    const out = [];
+    for (const top of LAYOUT_DIRS) {
+        let entries;
+        try {
+            entries = await fs.readdir(path.join(root, top), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (!e.isFile())
+                continue;
+            const p = `${top}/${e.name}`;
+            if (isLayoutPath(p))
+                out.push(p);
+        }
+    }
+    return out.sort();
+}
+export async function readLocal(root, layoutPath) {
+    try {
+        return await fs.readFile(toDiskPath(root, layoutPath));
+    }
+    catch (e) {
+        if (e.code === "ENOENT" || e.code === "EISDIR")
+            return null;
+        throw e;
+    }
+}
+/**
+ * `sections/<type>.schema.json` / `.css` files of a checkout pulled before sections became ONE file
+ * (migration 0079). The server refuses them; they are listed so push can say what to do instead.
+ */
+export async function listLegacySectionParts(root) {
+    let entries;
+    try {
+        entries = await fs.readdir(path.join(root, "sections"), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((e) => e.isFile() && legacySectionPartOf(`sections/${e.name}`)).map((e) => `sections/${e.name}`).sort();
+}
+/**
+ * Files whose bytes differ from what the state recorded, plus layout files the state never saw.
+ * `deleted` = files the state tracks that are gone from disk (legacy section parts never count).
+ */
+export async function localChanges(root, state, only) {
+    const files = state?.files ?? {};
+    const onDisk = only ? [...only] : await listLocalFiles(root);
+    const changes = [];
+    for (const p of onDisk) {
+        const bytes = await readLocal(root, p);
+        if (!bytes)
+            continue;
+        const hash = hashBytes(bytes);
+        const known = files[p];
+        if (!known)
+            changes.push({ path: p, kind: "new", bytes, hash });
+        else if (known.hash !== hash)
+            changes.push({ path: p, kind: "modified", bytes, hash });
+    }
+    const deleted = [];
+    if (!only) {
+        const present = new Set(onDisk);
+        for (const p of Object.keys(files))
+            if (!present.has(p) && isLayoutPath(p))
+                deleted.push(p);
+    }
+    return { changes, deleted: deleted.sort() };
+}

package/dist/sync.js

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { deleteThemeFiles, putThemeFiles } from "./api.js";
+import { chunkFiles } from "./chunk.js";
+import { unifiedDiff } from "./diff.js";
+import { formatIssue } from "./format.js";
+import { writeState } from "./state.js";
+import { isDeletablePath, isGeneratedPath, textOf } from "./layout.js";
+/** Contract: tag = first 16 hex of SHA-256 over the UTF-8 content. Only a fallback; the server's tag wins. */
+const tagOf = (content) => createHash("sha256").update(content, "utf8").digest("hex").slice(0, 16);
+/**
+ * Send `changes` with the tag each was based on, then record what the server accepted. State is
+ * written after every chunk, so a 429 or a dropped connection halfway through never forgets the
+ * files that did land, and never marks as pushed a file that did not.
+ */
+export async function pushChanges(s, client, root, state, changes, opts) {
+    const outcome = { saved: 0, unchanged: 0, conflicts: [], serverCopies: new Map(), invalid: [], refused: [] };
+    const byPath = new Map(changes.map((c) => [c.path, c]));
+    // `baseTags` lets a confirmed `push --force` claim the exact server version the person was shown.
+    const baseOf = (p) => (opts.baseTags?.has(p) ? opts.baseTags.get(p) : (state.files[p]?.tag ?? null));
+    const payload = changes.map((c) => ({ path: c.path, content: textOf(c.bytes), baseTag: baseOf(c.path) }));
+    for (const chunk of chunkFiles(payload)) {
+        const r = await putThemeFiles(client, state.store, state.themeId, chunk, opts.force);
+        for (const res of r.results ?? []) {
+            const local = byPath.get(res.path);
+            if (!local)
+                continue;
+            const sent = chunk.find((f) => f.path === res.path);
+            report(s, res, sent?.content ?? "", opts.compact === true);
+            if (res.status === "saved" || res.status === "unchanged") {
+                // Keep OUR bytes' hash with the server's tag: the server may store a normalised form,
+                // but what is on disk is what we sent, so that is what "unmodified" must mean.
+                state.files[res.path] = { tag: res.tag ?? tagOf(sent?.content ?? ""), hash: local.hash };
+                if (res.status === "saved")
+                    outcome.saved++;
+                else
+                    outcome.unchanged++;
+            }
+            else if (res.status === "conflict") {
+                outcome.conflicts.push(res.path);
+                outcome.serverCopies.set(res.path, res.current);
+            }
+            else if (res.status === "invalid")
+                outcome.invalid.push(res.path);
+            else
+                outcome.refused.push(res.path);
+        }
+        await writeState(root, state);
+    }
+    return outcome;
+}
+function report(s, res, localContent, compact) {
+    const pad = (status) => `  ${status.padEnd(9)}  ${res.path}`;
+    switch (res.status) {
+        case "saved":
+            s.out(pad("saved"));
+            return;
+        case "unchanged":
+            if (!compact)
+                s.out(pad("unchanged"));
+            return;
+        case "conflict": {
+            s.out(`${pad("conflict")} — changed on the server since you last pulled or pushed it`);
+            if (res.current) {
+                const diff = unifiedDiff(res.current.content, localContent, `server/${res.path}`, `local/${res.path}`);
+                for (const line of diff.trimEnd().split("\n"))
+                    s.out(line);
+            }
+            return;
+        }
+        case "invalid":
+            s.out(pad("invalid"));
+            for (const issue of res.errors ?? [])
+                s.out(`    ${formatIssue(res.path, issue, !compact)}`);
+            return;
+        default:
+            s.out(`${pad(res.status)}${res.message ? ` — ${res.message}` : ""}`);
+            for (const issue of res.errors ?? [])
+                s.out(`    ${formatIssue(res.path, issue, !compact)}`);
+    }
+}
+export function conflictAdvice(s, conflicts) {
+    if (conflicts.length === 0)
+        return;
+    s.err(`${conflicts.length} file(s) changed on the server since you last synced them (someone else, or the admin editor, saved a newer version). ` +
+        "Merge the server's changes into your file and push again, run `cerkel theme pull --force` to take the server's version, or `cerkel theme push --force` to overwrite it.");
+}
+/**
+ * Files deleted locally that the state still tracks → deleted from the draft, each only if the
+ * server still holds the copy we last synced (`baseTag`): a newer server copy is a conflict, never a
+ * silent loss. A section still placed by a template is refused by the server with the templates named.
+ */
+export async function pushDeletes(s, client, root, state, paths, opts = {}) {
+    const out = { deleted: 0, kept: [], failed: [] };
+    const targets = paths.filter((p) => isDeletablePath(p) && !isGeneratedPath(p));
+    out.kept = paths.filter((p) => !targets.includes(p));
+    for (const p of out.kept)
+        s.err(`  ${p} was deleted locally but cannot be deleted from the draft (it always exists); \`cerkel theme pull\` brings it back.`);
+    if (targets.length === 0)
+        return out;
+    const r = await deleteThemeFiles(client, state.store, state.themeId, targets.map((p) => ({ path: p, baseTag: state.files[p]?.tag ?? null })));
+    for (const res of r.results ?? []) {
+        if (res.status === "deleted" || res.status === "unchanged") {
+            delete state.files[res.path];
+            if (res.status === "deleted")
+                out.deleted++;
+            if (res.status === "deleted" || !opts.compact)
+                s.out(`  ${"deleted".padEnd(9)}  ${res.path}`);
+        }
+        else {
+            out.failed.push(res.path);
+            const why = res.status === "in_use"
+                ? `still placed by ${(res.usedIn ?? []).join(", ") || "a template"} — remove it from there first`
+                : res.status === "conflict"
+                    ? "changed on the server since you last synced it — pull first"
+                    : (res.message ?? "refused");
+            s.out(`  ${res.status.padEnd(9)}  ${res.path} — ${why}`);
+        }
+    }
+    await writeState(root, state);
+    return out;
+}

package/dist/zip.js

@@ -0,0 +1,88 @@
+import { deflateRawSync } from "node:zlib";
+// ---------------------------------------------------------------------------
+// A minimal ZIP writer for `cerkel theme package` — no dependency (the CLI ships with one, the
+// keychain). PKZIP 2.0: one local header + data per file, then the central directory. Each file is
+// DEFLATE-compressed unless that would make it larger (then stored), names are UTF-8 (flag bit 11,
+// so Arabic file names would survive — theme paths are ASCII today), timestamps are the given date
+// in DOS format. Readable by every unzip, macOS Archive Utility, Windows Explorer and Shopify-style
+// tooling. Files and archives here are tiny (a theme is well under 4 GB), so no ZIP64.
+// ---------------------------------------------------------------------------
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+export function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** A Date as the DOS time and date fields (local time, 2-second resolution, 1980 or later). */
+function dosTime(d) {
+    const year = Math.max(1980, d.getFullYear());
+    return {
+        time: (d.getHours() << 11) | (d.getMinutes() << 5) | Math.floor(d.getSeconds() / 2),
+        date: ((year - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+    };
+}
+export function createZip(entries, modified) {
+    const { time, date } = dosTime(modified);
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const e of entries) {
+        const name = Buffer.from(e.name, "utf8");
+        const raw = Buffer.from(e.data);
+        const deflated = deflateRawSync(raw, { level: 9 });
+        const store = deflated.length >= raw.length;
+        const body = store ? raw : deflated;
+        const crc = crc32(raw);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4); // version needed: 2.0
+        local.writeUInt16LE(0x0800, 6); // UTF-8 names
+        local.writeUInt16LE(store ? 0 : 8, 8);
+        local.writeUInt16LE(time, 10);
+        local.writeUInt16LE(date, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(body.length, 18);
+        local.writeUInt32LE(raw.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28);
+        locals.push(local, name, body);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE((3 << 8) | 20, 4); // made by: Unix, 2.0 — so the mode below is read
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(0x0800, 8);
+        central.writeUInt16LE(store ? 0 : 8, 10);
+        central.writeUInt16LE(time, 12);
+        central.writeUInt16LE(date, 14);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(body.length, 20);
+        central.writeUInt32LE(raw.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt16LE(0, 30); // extra
+        central.writeUInt16LE(0, 32); // comment
+        central.writeUInt16LE(0, 34); // disk
+        central.writeUInt16LE(0, 36); // internal attributes
+        central.writeUInt32LE((0o100644 << 16) >>> 0, 38); // -rw-r--r--
+        central.writeUInt32LE(offset, 42);
+        centrals.push(central, name);
+        offset += local.length + name.length + body.length;
+    }
+    const dir = Buffer.concat(centrals);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(dir.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...locals, dir, end]);
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@cerkel/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Run a Cerkel store from the terminal: its theme as local files (preview, send for approval) and its catalogue, prices, stock and collections.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Raizn-Global/raizn-commerce.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "cerkel": "dist/bin.js",
+    "raizn": "dist/raizn-alias.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.3",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.8"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }