@raizn/cli 0.1.0

package/dist/layout.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+/**
+ * The Shopify-style layout (contract § File layout). Layout paths are always POSIX
+ * (`templates/index.json`); they become OS paths only at the moment we touch the disk.
+ */
+export const SECTION_TYPE_RE = /^[a-z0-9][a-z0-9_-]{1,79}$/;
+const TEMPLATE_RE = /^templates\/[A-Za-z0-9][A-Za-z0-9_-]*(?:\.[A-Za-z0-9][A-Za-z0-9_-]*)?\.json$/;
+const LAYOUT_RE = /^layout\/[a-z0-9][a-z0-9_-]*\.json$/;
+const SECTION_RE = /^sections\/([a-z0-9][a-z0-9_-]{1,79})\.(liquid|schema\.json|css)$/;
+const FIXED = new Set(["config/settings.json", "assets/custom.css"]);
+/** Top-level folders the layout uses; the walker never descends anywhere else. */
+export const LAYOUT_DIRS = ["templates", "layout", "config", "assets", "sections"];
+export function isLayoutPath(p) {
+    return FIXED.has(p) || TEMPLATE_RE.test(p) || LAYOUT_RE.test(p) || SECTION_RE.test(p);
+}
+/** `sections/promo.schema.json` → `promo`; null for anything that is not a section file. */
+export function sectionTypeOf(p) {
+    return SECTION_RE.exec(p)?.[1] ?? null;
+}
+export const sectionPaths = (type) => ({
+    liquid: `sections/${type}.liquid`,
+    schema: `sections/${type}.schema.json`,
+    css: `sections/${type}.css`,
+});
+/**
+ * Server-side write order is sections → settings/CSS → templates; chunking follows it so a
+ * template never arrives in an earlier request than the new section it places.
+ */
+export function writeRank(p) {
+    if (p.startsWith("sections/"))
+        return 0;
+    if (p.startsWith("config/") || p.startsWith("assets/"))
+        return 1;
+    return 2;
+}
+/**
+ * Layout path → absolute OS path under `root`. Paths come from the server too, so this is also
+ * the guard against `../` or an absolute path escaping the checkout: only exact layout shapes pass.
+ */
+export function toDiskPath(root, layoutPath) {
+    if (!isLayoutPath(layoutPath))
+        throw new Error(`Not a theme file path: ${layoutPath}`);
+    return path.join(root, ...layoutPath.split("/"));
+}
+/** Absolute or cwd-relative OS path → layout path, or null when it is outside the checkout. */
+export function toLayoutPath(root, diskPath) {
+    const rel = path.relative(root, path.resolve(diskPath));
+    if (!rel || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+        return null;
+    return rel.split(path.sep).join(path.posix.sep);
+}
+// --- content ---------------------------------------------------------------
+/**
+ * A git checkout with `core.autocrlf` rewrites LF to CRLF on disk. Hashing and sending the
+ * LF form means such a checkout neither looks modified nor pushes carriage returns.
+ */
+export function normaliseEol(buf) {
+    if (!buf.includes(0x0d))
+        return buf;
+    const out = Buffer.allocUnsafe(buf.length);
+    let j = 0;
+    for (let i = 0; i < buf.length; i++) {
+        const b = buf[i];
+        if (b === 0x0d && buf[i + 1] === 0x0a)
+            continue;
+        out[j++] = b;
+    }
+    return out.subarray(0, j);
+}
+export const hashBytes = (buf) => createHash("sha256").update(normaliseEol(buf)).digest("hex");
+/**
+ * Bytes → the string we send. `Buffer#toString` keeps a BOM as U+FEFF rather than eating it
+ * (TextDecoder would drop it), so what the person saved is exactly what the server receives.
+ */
+export const textOf = (buf) => normaliseEol(buf).toString("utf8");
+/** The server's content → the exact bytes we write. No BOM added, no newline appended. */
+export const bytesOf = (content) => Buffer.from(content, "utf8");

package/dist/redact.js

@@ -0,0 +1,27 @@
+/**
+ * Everything the CLI prints goes through a redactor. The token is the one secret this tool holds,
+ * and the places it could leak are exactly the ones nobody reviews: an error echoed from a proxy,
+ * a stack trace pasted into a chat, CI logs kept for months.
+ */
+export const REDACTED = "***";
+// A full MCP token is `rzn_` + 43 base64url characters. The 8-character prefix the server shows
+// (e.g. `rzn_ab12`) is too short to match, so it stays readable — it names a token, it does not
+// grant anything.
+const TOKEN_SHAPE = /rzn_[A-Za-z0-9_-]{16,}/g;
+// Anything shaped like an Authorization header value, whichever scheme casing a proxy echoes back.
+const BEARER_SHAPE = /\b(Bearer)\s+[^\s"',;]+/gi;
+const AUTH_HEADER_SHAPE = /\b(authorization)(["']?\s*[:=]\s*["']?)(?:[A-Za-z]+\s+)?[^\s"',;]+/gi;
+export function makeRedactor(secrets) {
+    return (text) => {
+        let out = text;
+        for (const s of secrets()) {
+            // Very short strings would shred ordinary words; a real token is never this short.
+            if (s && s.length >= 8)
+                out = out.split(s).join(REDACTED);
+        }
+        return out
+            .replace(TOKEN_SHAPE, REDACTED)
+            .replace(AUTH_HEADER_SHAPE, `$1$2${REDACTED}`)
+            .replace(BEARER_SHAPE, `$1 ${REDACTED}`);
+    };
+}

package/dist/session.js

@@ -0,0 +1,93 @@
+import { DEFAULT_API_URL, apiOrigin, parseApiUrl } from "./api-url.js";
+import { McpClient } from "./client.js";
+import { CliError } from "./errors.js";
+import { makeRedactor } from "./redact.js";
+import { findRoot, readState } from "./state.js";
+/**
+ * Per-invocation plumbing shared by every command: which API, which token, redacted output,
+ * and the checkout (if any) the command runs in.
+ */
+export class Session {
+    ctx;
+    apiFlag;
+    secrets = [];
+    redact;
+    clientPromise = null;
+    apiUrl = null;
+    constructor(ctx, apiFlag) {
+        this.ctx = ctx;
+        this.apiFlag = apiFlag;
+        this.redact = makeRedactor(() => this.secrets);
+        const envToken = ctx.env["RAIZN_TOKEN"];
+        if (envToken)
+            this.secrets.push(envToken.trim());
+    }
+    /** Every printed line goes through the redactor — not only errors — so no path can leak it. */
+    out(line = "") {
+        this.ctx.io.out(this.redact(line));
+    }
+    err(line = "") {
+        this.ctx.io.err(this.redact(line));
+    }
+    addSecret(s) {
+        if (s)
+            this.secrets.push(s);
+    }
+    /**
+     * `--api`, then the checkout's recorded API, then RAIZN_API_URL, then the default. The
+     * checkout outranks the environment because its theme id only means something on the server
+     * it was pulled from; an explicit flag that disagrees with it is refused rather than obeyed.
+     */
+    api(state) {
+        if (this.apiUrl)
+            return this.apiUrl;
+        const flag = this.apiFlag ? parseApiUrl(this.apiFlag) : null;
+        const recorded = state?.api ? parseApiUrl(state.api) : null;
+        if (flag && recorded && flag.href !== recorded.href) {
+            throw new CliError(`This folder was pulled from ${recorded.href}, not ${flag.href}. Drop --api, or pull into a different folder.`);
+        }
+        const env = this.ctx.env["RAIZN_API_URL"];
+        this.apiUrl = flag ?? recorded ?? parseApiUrl(env && env.trim() ? env : DEFAULT_API_URL);
+        return this.apiUrl;
+    }
+    /** RAIZN_TOKEN (CI) wins over a stored login, so a pipeline never picks up someone's laptop token. */
+    async token(url) {
+        const env = this.ctx.env["RAIZN_TOKEN"]?.trim();
+        if (env)
+            return { token: env, source: "env" };
+        const stored = await this.ctx.credentials.get(apiOrigin(url));
+        if (!stored)
+            throw new CliError(`Not logged in to ${apiOrigin(url)}. Run \`raizn login\` (or set RAIZN_TOKEN in CI).`);
+        this.addSecret(stored);
+        return { token: stored, source: "stored" };
+    }
+    clientWith(url, token) {
+        this.addSecret(token);
+        return new McpClient({ url, token, fetch: this.ctx.fetch, userAgent: `raizn-cli/${this.ctx.version}` });
+    }
+    client(state) {
+        this.clientPromise ??= (async () => {
+            const url = this.api(state);
+            const { token } = await this.token(url);
+            return this.clientWith(url, token);
+        })();
+        return this.clientPromise;
+    }
+    /** The checkout this command runs in, found by walking up from the working directory. */
+    async checkout() {
+        const root = await findRoot(this.ctx.cwd);
+        if (!root)
+            return null;
+        const state = await readState(root);
+        return state ? { root, state } : null;
+    }
+    async requireCheckout(opts) {
+        const co = await this.checkout();
+        if (!co)
+            throw new CliError("This folder is not a theme checkout. Run `raizn theme pull --store <slug>` first.");
+        if (opts.editable && co.state.readOnly) {
+            throw new CliError(`${co.root} is a read-only copy of the LIVE theme. Nothing can be written from here. Run \`raizn theme pull --store ${co.state.store}\` in another folder to edit a draft.`);
+        }
+        return co;
+    }
+}

package/dist/state.js

@@ -0,0 +1,121 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { LAYOUT_DIRS, hashBytes, isLayoutPath, toDiskPath } from "./layout.js";
+/**
+ * `.raizn/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 = ".raizn";
+export const STATE_FILE = "state.json";
+export const statePath = (root) => path.join(root, STATE_DIR, 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 \`raizn 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 raizn understands. Pull again with \`raizn 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, STATE_DIR);
+    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 `.raizn/state.json`, 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;
+    }
+}
+/** Files whose bytes differ from what the state recorded, plus layout files the state never saw. */
+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))
+                deleted.push(p);
+    }
+    return { changes, deleted: deleted.sort() };
+}

package/dist/sync.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { 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 { 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: [], invalid: [], refused: [] };
+    const byPath = new Map(changes.map((c) => [c.path, c]));
+    const payload = changes.map((c) => ({ path: c.path, content: textOf(c.bytes), baseTag: state.files[c.path]?.tag ?? null }));
+    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);
+            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 `raizn theme pull --force` to take the server's version, or `raizn theme push --force` to overwrite it.");
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@raizn/cli",
+  "version": "0.1.0",
+  "description": "Edit a Raizn Commerce store's theme as local files, preview it on the real store domain and send it for approval.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Raizn-Global/raizn-commerce.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "raizn": "dist/bin.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"
+  }
+}