@cerkel/cli 0.0.0-stage → 1.0.1

package/dist/errors.js

@@ -0,0 +1,73 @@
+/**
+ * Every failure the CLI reports is one of these. Commands throw them; `main` turns them into one
+ * redacted line and an exit code. Nothing else prints an error.
+ */
+export class CliError extends Error {
+    exitCode;
+    name = "CliError";
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+/**
+ * 401 from the server. Never retried: a revoked token does not come back by asking again.
+ * `reason` is the server's machine word for it (`data.reason`: `revoked`, `cli_store_required`, …)
+ * when it sent one.
+ */
+export class AuthError extends CliError {
+    reason;
+    name = "AuthError";
+    constructor(message, reason = null) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/**
+ * This login (or RAIZN_TOKEN) cannot be used for the store the command is for: it is not tied to a
+ * store any more, or it is tied to another one. The message is one line that already says what to
+ * run, so it is printed exactly as it is. Like every AuthError it is never retried.
+ */
+export class StoreLoginError extends AuthError {
+    name = "StoreLoginError";
+}
+/** The server's two words for "this token is not bound to exactly one store". */
+export const isNotOneStore = (reason) => reason === "cli_store_required" || reason === "store_required";
+/** 429 from the server. `retryAfterSeconds` is what the server asked for, not a guess. */
+export class RateLimitError extends CliError {
+    retryAfterSeconds;
+    name = "RateLimitError";
+    constructor(message, retryAfterSeconds) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+/**
+ * The server looked at the request and said no (`permission_denied`, `not_a_draft`, …). The code
+ * and message are the server's, shown verbatim: the CLI's own checks are a convenience, the
+ * server's answer is the truth.
+ */
+export class ToolRefusal extends CliError {
+    tool;
+    code;
+    serverMessage;
+    details;
+    name = "ToolRefusal";
+    constructor(tool, code, serverMessage, details) {
+        super(`The server refused ${tool}: ${code}: ${serverMessage}`);
+        this.tool = tool;
+        this.code = code;
+        this.serverMessage = serverMessage;
+        this.details = details;
+    }
+}
+/** Transport failures: network down, 413, 5xx, a body that is not JSON-RPC. */
+export class ServerError extends CliError {
+    status;
+    name = "ServerError";
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export const retryAt = (seconds, now) => new Date(now.getTime() + seconds * 1000).toLocaleTimeString("en-GB", { hour12: false });

package/dist/format.js

@@ -0,0 +1,13 @@
+/** Left-aligned columns, two spaces apart. Plain text so it pipes into grep/awk cleanly. */
+export function table(rows) {
+    const widths = [];
+    for (const r of rows)
+        r.forEach((c, i) => (widths[i] = Math.max(widths[i] ?? 0, [...c].length)));
+    return rows.map((r) => r.map((c, i) => (i === r.length - 1 ? c : c + " ".repeat((widths[i] ?? 0) - [...c].length))).join("  ").trimEnd());
+}
+/** `path:line:col  severity  message` — the shape editors and CI annotators already parse. */
+export function formatIssue(path, issue, withSeverity = true) {
+    const loc = issue.line ? `${path}:${issue.line}:${issue.column ?? 1}` : path;
+    return withSeverity ? `${loc}  ${issue.severity}  ${issue.message}` : `${loc} ${issue.message}`;
+}
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;

package/dist/layout.js

@@ -0,0 +1,122 @@
+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.
+ */
+/** A section type — the server's rule (`@raizn/core/theme/files` `SECTION_TYPE_RE`), 2–80 characters. */
+export const SECTION_TYPE_RE = /^[a-z0-9][a-z0-9_-]{1,79}$/;
+/** A block or snippet name: may start with `_` (Horizon's private blocks, `blocks/_card.liquid`). */
+export const PART_NAME_RE = /^_?[a-z0-9][a-z0-9_-]{0,79}$/;
+/** A stored asset: lower-case `.css` or `.svg` (images and fonts live in the store's media library). */
+const ASSET_RE = /^assets\/[a-z0-9][a-z0-9._-]{0,99}\.(css|svg)$/;
+const TEMPLATE_RE = /^templates\/[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)?\.json$/;
+const LAYOUT_RE = /^layout\/(header|footer)\.json$/;
+const SECTION_RE = /^sections\/([a-z0-9][a-z0-9_-]{1,79})\.liquid$/;
+const PART_RE = /^(blocks|snippets)\/_?[a-z0-9][a-z0-9_-]{0,79}\.liquid$/;
+/** The theme's built-in texts, one file per storefront language (contract § File layout, "Theme content"). */
+const LOCALES_RE = /^locales\/(ar|en|ckb)\.json$/;
+const FIXED = new Set(["config/settings.json", "assets/custom.css"]);
+/**
+ * Before migration 0079 a section was three files: `.liquid`, `.schema.json` and `.css`. They are
+ * not theme files any more (the server refuses them), but an old checkout still has them on disk;
+ * they are recognised ONLY so pull can clean them up and push can say what to do with them.
+ */
+const LEGACY_PART_RE = /^sections\/([a-z0-9][a-z0-9_-]{1,79})\.(schema\.json|css)$/;
+/** Top-level folders the layout uses (Shopify's), in its order; the walker never descends anywhere else. */
+export const LAYOUT_DIRS = ["layout", "templates", "sections", "blocks", "snippets", "assets", "config", "locales"];
+/**
+ * A theme file path, mirroring the server's grammar (docs/liquid-themes.md §1): lower case, one
+ * folder deep, no traversal. Anything the server would refuse is not a layout path here either.
+ */
+export function isLayoutPath(p) {
+    if (typeof p !== "string" || p.length > 200)
+        return false;
+    return FIXED.has(p) || TEMPLATE_RE.test(p) || LAYOUT_RE.test(p) || SECTION_RE.test(p) || PART_RE.test(p) || ASSET_RE.test(p) || LOCALES_RE.test(p);
+}
+/** `sections/<type>.schema.json` / `.css` from a pre-0079 checkout → the section type; null otherwise. */
+export function legacySectionPartOf(p) {
+    return LEGACY_PART_RE.exec(p)?.[1] ?? null;
+}
+/**
+ * `assets/*.generated.css` is written by the platform (the theme's compiled stylesheet): pulled for
+ * reference, never pushed or deleted from here.
+ */
+export const isGeneratedPath = (p) => /^assets\/[a-z0-9][a-z0-9._-]*\.generated\.css$/.test(p);
+/**
+ * Files the server can delete from a draft: sections, blocks, snippets and stored assets. Templates,
+ * the layout groups, `config/settings.json`, `assets/custom.css` and locales always exist.
+ */
+export const isDeletablePath = (p) => !FIXED.has(p) && !isGeneratedPath(p) && (SECTION_RE.test(p) || PART_RE.test(p) || ASSET_RE.test(p));
+/** `sections/promo.liquid` → `promo`; null for anything that is not a section file. */
+export function sectionTypeOf(p) {
+    return SECTION_RE.exec(p)?.[1] ?? null;
+}
+/** A section is ONE file: its Liquid, then `{% stylesheet %}`, then `{% schema %}`. */
+export const sectionPath = (type) => `sections/${type}.liquid`;
+/**
+ * Server-side write order: stored files (sections, blocks, snippets, assets) → settings/CSS/texts →
+ * templates; chunking follows it so a template never arrives in an earlier request than the new
+ * section it places.
+ */
+export function writeRank(p) {
+    if (FIXED.has(p))
+        return 1;
+    if (p.startsWith("sections/") || p.startsWith("blocks/") || p.startsWith("snippets/") || p.startsWith("assets/"))
+        return 0;
+    if (p.startsWith("config/") || p.startsWith("locales/"))
+        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
+ * (plus the legacy section parts, which have the same safe shape).
+ */
+export function toDiskPath(root, layoutPath) {
+    if (!isLayoutPath(layoutPath) && !legacySectionPartOf(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);
+}
+/**
+ * One leading UTF-8 BOM (EF BB BF) is dropped before hashing and sending. Windows PowerShell 5.1
+ * (`Set-Content -Encoding utf8`) adds one; it carries no meaning, the server's JSON parser refuses
+ * it, and a file that differs only by it is not a change. Only the first one goes: a second
+ * U+FEFF is content. Pulls still write exactly what the server sent.
+ */
+export function stripBom(buf) {
+    return buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf ? buf.subarray(3) : buf;
+}
+export const hashBytes = (buf) => createHash("sha256").update(normaliseEol(stripBom(buf))).digest("hex");
+/**
+ * Bytes → the string we send: one leading BOM dropped, CRLF → LF, everything else exactly as
+ * saved (`Buffer#toString` does not eat a further U+FEFF the way TextDecoder would).
+ */
+export const textOf = (buf) => normaliseEol(stripBom(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/logins.js

@@ -0,0 +1,49 @@
+/** A store slug as the server names stores: lowercase letters, digits and hyphens. */
+export const STORE_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+export const isStoreSlug = (s) => STORE_SLUG_RE.test(s);
+const VERSION = 2;
+export const emptyBook = () => ({ logins: {}, legacy: null });
+export function parseBook(raw) {
+    if (!raw || !raw.trim())
+        return emptyBook();
+    const text = raw.trim();
+    if (text.startsWith("{")) {
+        try {
+            const o = JSON.parse(text);
+            if (o && o.v === VERSION && o.logins && typeof o.logins === "object" && !Array.isArray(o.logins)) {
+                const logins = {};
+                for (const [slug, token] of Object.entries(o.logins)) {
+                    if (isStoreSlug(slug) && typeof token === "string" && token)
+                        logins[slug] = token;
+                }
+                return { logins, legacy: typeof o.legacy === "string" && o.legacy ? o.legacy : null };
+            }
+        }
+        catch {
+            /* not a book: fall through and treat it as a bare token */
+        }
+    }
+    return { logins: {}, legacy: text };
+}
+/** null = nothing left to keep (the caller deletes the entry). Logins are written in slug order. */
+export function serialiseBook(book) {
+    const slugs = Object.keys(book.logins).filter((s) => book.logins[s]).sort();
+    if (slugs.length === 0 && !book.legacy)
+        return null;
+    const logins = Object.fromEntries(slugs.map((s) => [s, book.logins[s]]));
+    return JSON.stringify({ v: VERSION, logins, ...(book.legacy ? { legacy: book.legacy } : {}) });
+}
+export const bookTokens = (book) => [...Object.values(book.logins), ...(book.legacy ? [book.legacy] : [])];
+export const bookStores = (book) => Object.keys(book.logins).sort();
+export async function readBook(creds, origin) {
+    return parseBook(await creds.get(origin));
+}
+/** Saves the book for this origin; an empty book removes the entry altogether. */
+export async function writeBook(creds, origin, book) {
+    const value = serialiseBook(book);
+    if (value === null) {
+        await creds.delete(origin);
+        return "removed";
+    }
+    return creds.set(origin, value);
+}

package/dist/raizn-alias.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// `raizn` is the CLI's old name (@raizn/cli). This alias keeps old scripts working for a while: one
+// line on stderr (so --json output and pipes are untouched), then exactly what `cerkel` would do.
+process.stderr.write("raizn is now cerkel: run `cerkel …` instead (this alias goes away in a later release).\n");
+await import("./bin.js");
+export {};

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,266 @@
+import { DEFAULT_API_URL, apiOrigin, parseApiUrl } from "./api-url.js";
+import { listStores, oneStoreOf } from "./api.js";
+import { McpClient } from "./client.js";
+import { AuthError, CliError, StoreLoginError, ToolRefusal, isNotOneStore } from "./errors.js";
+import { bookStores, bookTokens, readBook, writeBook } from "./logins.js";
+import { envApiUrl, envToken, envTokenSecrets } from "./env.js";
+import { makeRedactor } from "./redact.js";
+import { findRoot, readState } from "./state.js";
+/** "This login is not tied to a store any more": naming the folder's / requested store, or none. */
+export function notTiedLine(source, store, envVar = "CERKEL_TOKEN") {
+    return source === "env"
+        ? `${envVar} is not tied to one store. Create a token for one store in the Cerkel admin at Settings → MCP.`
+        : `This login is not tied to a store any more — run \`cerkel login --store ${store ?? "<slug>"}\`.`;
+}
+/** "This login is for X — run cerkel login --store Y": X is the login's own store, Y the one asked for. */
+export function mismatchLine(source, own, asked, envVar = "CERKEL_TOKEN") {
+    if (source === "env") {
+        return own ? `${envVar} is for ${own}, not ${asked}. Use a token for ${asked}.` : `${envVar} cannot reach ${asked}. Use a token for ${asked}.`;
+    }
+    return own ? `This login is for ${own} — run \`cerkel login --store ${asked}\`.` : `This login cannot reach ${asked} — run \`cerkel login --store ${asked}\`.`;
+}
+/**
+ * A client whose refusals speak about logins and stores in the CLI's words: a login the server no
+ * longer accepts because it is not tied to one store, a store this login is not for. Everything else
+ * is the server's own message, untouched.
+ */
+class StoreClient extends McpClient {
+    login;
+    constructor(opts, login) {
+        super(opts);
+        this.login = login;
+    }
+    async call(tool, args) {
+        try {
+            return await super.call(tool, args);
+        }
+        catch (e) {
+            throw await this.explain(e, args);
+        }
+    }
+    async explain(e, args) {
+        const asked = typeof args["store"] === "string" ? args["store"] : this.login.store;
+        if (e instanceof AuthError && !(e instanceof StoreLoginError)) {
+            if (isNotOneStore(e.reason))
+                return new StoreLoginError(notTiedLine(this.login.source, asked, this.login.envVar), e.reason);
+            if (this.login.source === "stored")
+                return new AuthError(`${e.message} Run \`cerkel login --store ${asked ?? "<slug>"}\` to sign in again.`, e.reason);
+            return e;
+        }
+        // The server's refusal is the same for every store but this login's, real or not; say which
+        // store THIS login is for (asking the server with the same token), and nothing about any other.
+        if (e instanceof ToolRefusal && e.code === "store_not_allowed" && asked) {
+            return new StoreLoginError(mismatchLine(this.login.source, await this.ownStore(), asked, this.login.envVar));
+        }
+        return e;
+    }
+    async ownStore() {
+        try {
+            return oneStoreOf(await super.call("list_stores", {}))?.slug ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+export class Session {
+    ctx;
+    apiFlag;
+    secrets = [];
+    redact;
+    clients = new Map();
+    books = new Map();
+    apiUrl = null;
+    constructor(ctx, apiFlag) {
+        this.ctx = ctx;
+        this.apiFlag = apiFlag;
+        this.redact = makeRedactor(() => this.secrets);
+        this.secrets.push(...envTokenSecrets(ctx.env));
+    }
+    /** 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 CERKEL_API_URL (or the old 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.`);
+        }
+        this.apiUrl = flag ?? recorded ?? parseApiUrl(envApiUrl(this.ctx.env) ?? DEFAULT_API_URL);
+        return this.apiUrl;
+    }
+    /** This origin's logins, read once per command. Every token in it is redacted from all output. */
+    book(url) {
+        const origin = apiOrigin(url);
+        let b = this.books.get(origin);
+        if (!b) {
+            b = readBook(this.ctx.credentials, origin).then((book) => {
+                for (const t of bookTokens(book))
+                    this.addSecret(t);
+                return book;
+            });
+            this.books.set(origin, b);
+        }
+        return b;
+    }
+    async saveBook(url, book) {
+        const origin = apiOrigin(url);
+        for (const t of bookTokens(book))
+            this.addSecret(t);
+        const where = await writeBook(this.ctx.credentials, origin, book);
+        this.books.set(origin, Promise.resolve(book));
+        return where;
+    }
+    /**
+     * The login for `store` (a --store flag, or the theme folder's store) — or, with no store to go
+     * on, the only login there is. CERKEL_TOKEN (CI; or the old RAIZN_TOKEN) always wins, so a pipeline never picks up
+     * someone's laptop token. Never names a store the caller did not name: with several logins and no
+     * store it asks for --store.
+     */
+    async login(url, store) {
+        const env = envToken(this.ctx.env);
+        if (env)
+            return { token: env.value, source: "env", store, envVar: env.name };
+        let book = await this.book(url);
+        // A 0.1.x token is only consulted when the per-store logins cannot answer, and what is wrong
+        // with it only surfaces when nothing else can be used.
+        let problem = null;
+        if (book.legacy && !(store && book.logins[store]))
+            ({ book, problem } = await this.adoptLegacy(url, book, store));
+        if (store) {
+            const token = book.logins[store];
+            if (token)
+                return { token, source: "stored", store };
+            throw problem ?? new CliError(`Not logged in to ${store}. Run \`cerkel login --store ${store}\`.`);
+        }
+        const stores = bookStores(book);
+        if (stores.length === 1)
+            return { token: book.logins[stores[0]], source: "stored", store: stores[0] };
+        if (stores.length === 0)
+            throw problem ?? new CliError(`Not logged in to ${apiOrigin(url)}. Run \`cerkel login --store <slug>\` (or set CERKEL_TOKEN in CI).`);
+        throw new CliError("You are logged in to more than one store. Pass --store <slug>, or run this inside a theme folder (`cerkel logins` lists your logins).");
+    }
+    /**
+     * A token saved by raizn 0.1.x is not filed under a store. Ask the server which store it is for:
+     * one that answers with exactly one store is filed under it, so no command asks again; one the
+     * server no longer accepts — a 0.1.x login reached every store, which is refused for good — is
+     * dropped, and `problem` says to log in to one store. A network failure throws and keeps it for
+     * next time.
+     */
+    async adoptLegacy(url, book, store) {
+        const legacy = book.legacy;
+        const next = { logins: { ...book.logins }, legacy: null };
+        let who;
+        try {
+            who = await listStores(this.clientWith(url, legacy));
+        }
+        catch (e) {
+            if (!(e instanceof AuthError))
+                throw e;
+            await this.saveBook(url, next);
+            return {
+                book: next,
+                problem: isNotOneStore(e.reason)
+                    ? new StoreLoginError(notTiedLine("stored", store), e.reason)
+                    : new AuthError(`Your saved login no longer works: ${e.message} Run \`cerkel login --store ${store ?? "<slug>"}\`.`, e.reason),
+            };
+        }
+        const own = oneStoreOf(who);
+        // A token for several stores (an old Settings → MCP token in its grace) is not something cerkel uses.
+        const adopted = own ? { logins: { [own.slug]: legacy, ...next.logins }, legacy: null } : next;
+        await this.saveBook(url, adopted);
+        return { book: adopted, problem: own ? null : new StoreLoginError(notTiedLine("stored", store)) };
+    }
+    /**
+     * `adoptLegacy` for `cerkel login`, `logout` and `logins`, which must not fail because of an old
+     * login: files it under its store when it can, drops it when the server refuses it and says so,
+     * and leaves it alone when the server cannot be reached.
+     */
+    async tidyLegacy(url) {
+        const book = await this.book(url);
+        if (!book.legacy)
+            return;
+        try {
+            const { problem } = await this.adoptLegacy(url, book, null);
+            if (problem)
+                this.err("Removed an older saved login that is not tied to one store (cerkel now keeps one login per store).");
+        }
+        catch {
+            /* offline: keep it for next time */
+        }
+    }
+    clientWith(url, token) {
+        this.addSecret(token);
+        return new McpClient({ url, token, fetch: this.ctx.fetch, userAgent: `cerkel-cli/${this.ctx.version}` });
+    }
+    /**
+     * The client for one store: `store`, or the folder's (`state.store`), or — with neither — the
+     * only login. Its refusals are translated into the CLI's lines about logins and stores.
+     */
+    client(state, store) {
+        const forStore = store ?? state?.store ?? null;
+        const key = forStore ?? "";
+        let c = this.clients.get(key);
+        if (!c) {
+            c = (async () => {
+                const url = this.api(state);
+                const login = await this.login(url, forStore);
+                this.addSecret(login.token);
+                return new StoreClient({ url, token: login.token, fetch: this.ctx.fetch, userAgent: `cerkel-cli/${this.ctx.version}` }, login);
+            })();
+            this.clients.set(key, c);
+        }
+        return c;
+    }
+    /**
+     * The store a command means when it names none and runs outside a theme folder: the store of the
+     * one login there is (RAIZN_TOKEN: the store the server says it is for).
+     */
+    async defaultStore() {
+        const login = await this.login(this.api(), null);
+        if (login.store)
+            return login.store;
+        const own = oneStoreOf(await listStores(await this.client(null, null)));
+        if (!own)
+            throw new CliError("Which store? Pass --store <slug>.");
+        return own.slug;
+    }
+    /** 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 `cerkel 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 \`cerkel theme pull --store ${co.state.store}\` in another folder to edit a draft.`);
+        }
+        // A convenience, not the control: the server refuses every write to a non-draft (`not_a_draft`).
+        // This only saves a round trip when state.json says the folder holds something else.
+        if (opts.editable && co.state.role !== "draft") {
+            const what = co.state.role === "live" ? "the LIVE theme" : `a theme whose role is "${String(co.state.role)}", not a draft`;
+            throw new CliError(`${co.root} holds ${what} (${co.state.themeId}). Nothing can be written from here. Pull a draft with \`cerkel theme pull --store ${co.state.store}\` in another folder.`);
+        }
+        return co;
+    }
+}