@raizn/cli 0.1.0

package/dist/commands/theme.js

@@ -0,0 +1,297 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { apiOrigin } from "../api-url.js";
+import { createDraft, getPreviewUrl, getThemeFiles, listThemes, submitForApproval, validateThemeFiles, } from "../api.js";
+import { chunkFiles } from "../chunk.js";
+import { CliError } from "../errors.js";
+import { formatIssue, plural, table } from "../format.js";
+import { bytesOf, hashBytes, isLayoutPath, textOf, toDiskPath, toLayoutPath } from "../layout.js";
+import { findRoot, listLocalFiles, localChanges, readLocal, readState, writeState } from "../state.js";
+import { conflictAdvice, pushChanges } from "../sync.js";
+const byNewest = (a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? "");
+// --- list --------------------------------------------------------------------
+export async function themeList(s, opts) {
+    const co = await s.checkout();
+    const store = opts.store ?? co?.state.store;
+    if (!store)
+        throw new CliError("Which store? Pass --store <slug> (see `raizn stores`).");
+    const themes = await listThemes(await s.client(co?.state), store);
+    const rank = (t) => (t.role === "live" ? 0 : t.role === "draft" ? 1 : 2);
+    const rows = [...themes].sort((a, b) => rank(a) - rank(b) || byNewest(a, b));
+    if (rows.length === 0) {
+        s.err(`${store} has no themes.`);
+        return 0;
+    }
+    for (const line of table([["ID", "NAME", "ROLE", "UPDATED"], ...rows.map((t) => [t.id, t.name, t.role, t.updatedAt ?? "—"])]))
+        s.out(line);
+    return 0;
+}
+export async function themePull(s, opts) {
+    const root = opts.dir ? path.resolve(s.ctx.cwd, opts.dir) : ((await findRoot(s.ctx.cwd)) ?? s.ctx.cwd);
+    const existing = await readState(root);
+    if (opts.live) {
+        if (!opts.dir) {
+            throw new CliError("--live needs --dir <folder>. The live theme is only ever pulled as a read-only reference, into a folder of its own.");
+        }
+        const enclosing = await findRoot(root);
+        const enclosingState = enclosing ? await readState(enclosing) : null;
+        if (enclosingState && !enclosingState.readOnly) {
+            throw new CliError(`${enclosing} is an editable draft checkout. Pull the live theme into a different folder, e.g. --dir ../live-reference.`);
+        }
+        if (opts.theme)
+            throw new CliError("--live and --theme cannot be combined: --live always means the store's live theme.");
+    }
+    else if (existing?.readOnly) {
+        throw new CliError(`${root} holds a read-only copy of the live theme. Pull a draft into a different folder (--dir <folder>).`);
+    }
+    const store = opts.store ?? existing?.store;
+    if (!store)
+        throw new CliError("Which store? Pass --store <slug> (see `raizn stores`).");
+    // A different store is a fresh checkout: the folder's recorded API still applies unless it was the same store.
+    const client = await s.client(existing && existing.store === store ? existing : null);
+    let files;
+    if (opts.live) {
+        files = await getThemeFiles(client, store);
+    }
+    else {
+        const themeId = await chooseDraft(s, client, store, opts, existing);
+        files = await getThemeFiles(client, store, themeId);
+        if (files.theme.role === "live") {
+            // The server decides what a theme is; if it says live, we will not open it for editing.
+            throw new CliError(`Theme ${themeId} is the LIVE theme. It is never pulled for editing; use --live --dir <folder> for a read-only copy.`);
+        }
+    }
+    // Refuse before touching anything if local work would be overwritten.
+    const incoming = new Map();
+    const skipped = [];
+    for (const f of files.files) {
+        if (!isLayoutPath(f.path)) {
+            skipped.push(f.path);
+            continue;
+        }
+        incoming.set(f.path, { content: f.content, tag: f.tag, hash: hashBytes(bytesOf(f.content)) });
+    }
+    const { changes } = await localChanges(root, existing);
+    const atRisk = changes.filter((c) => incoming.get(c.path)?.hash !== c.hash);
+    if (atRisk.length > 0 && !opts.force) {
+        const list = atRisk.slice(0, 20).map((c) => `  ${c.kind === "new" ? "new     " : "modified"}  ${c.path}`);
+        throw new CliError([
+            `${root} has ${plural(atRisk.length, "local change")} that pulling would overwrite or leave behind:`,
+            ...list,
+            ...(atRisk.length > 20 ? [`  … and ${atRisk.length - 20} more`] : []),
+            "Push them first (`raizn theme push`), or re-run with --force to replace them with the server's copy.",
+        ].join("\n"));
+    }
+    let written = 0;
+    let same = 0;
+    const nextFiles = {};
+    for (const [p, f] of incoming) {
+        const disk = toDiskPath(root, p);
+        const current = await readLocal(root, p);
+        if (current && hashBytes(current) === f.hash)
+            same++;
+        else {
+            await fs.mkdir(path.dirname(disk), { recursive: true });
+            await fs.writeFile(disk, bytesOf(f.content));
+            written++;
+        }
+        nextFiles[p] = { tag: f.tag, hash: f.hash };
+    }
+    // Files the server no longer has: remove only what we can prove is ours and untouched.
+    let removed = 0;
+    const kept = [];
+    const known = existing?.files ?? {};
+    const candidates = new Set([...Object.keys(known), ...changes.map((c) => c.path)]);
+    for (const p of candidates) {
+        if (incoming.has(p))
+            continue;
+        const bytes = await readLocal(root, p);
+        if (!bytes)
+            continue;
+        if (known[p] && known[p].hash === hashBytes(bytes)) {
+            await fs.rm(toDiskPath(root, p), { force: true });
+            removed++;
+        }
+        else
+            kept.push(p);
+    }
+    const readOnly = opts.live;
+    await writeState(root, {
+        version: 1,
+        api: client.url.href,
+        store,
+        themeId: files.theme.id,
+        themeName: files.theme.name,
+        role: files.theme.role,
+        readOnly,
+        pulledAt: s.ctx.now().toISOString(),
+        files: nextFiles,
+    });
+    s.out(`Pulled "${files.theme.name}" (${files.theme.role}, ${files.theme.id}) from ${store} into ${root}`);
+    s.out(`  ${plural(incoming.size, "file")}: ${written} written, ${same} already up to date${removed ? `, ${removed} removed` : ""}`);
+    for (const p of skipped)
+        s.err(`  skipped ${p}: not a theme file path this CLI knows how to store`);
+    for (const p of kept)
+        s.err(`  kept ${p}: the server no longer has it, but your copy has changes`);
+    const pending = (files.sections ?? []).filter((x) => x.unpublishedChanges);
+    if (pending.length > 0) {
+        s.out(`  Custom sections with unpublished changes (store-wide): ${pending.map((x) => `${x.type} v${x.version}${x.publishedVersion ? ` (live v${x.publishedVersion})` : " (never published)"}`).join(", ")}`);
+    }
+    if (readOnly) {
+        s.out("This is a READ-ONLY copy of the live theme, for reference. push, dev and submit refuse to run here.");
+    }
+    else {
+        s.out("Next: `raizn theme dev` to edit with a live preview, then `raizn theme submit -m \"…\"`.");
+    }
+    return 0;
+}
+async function chooseDraft(s, client, store, opts, existing) {
+    const themes = await listThemes(client, store);
+    const live = themes.find((t) => t.role === "live");
+    if (opts.theme) {
+        const t = themes.find((x) => x.id === opts.theme);
+        if (!t)
+            throw new CliError(`No theme ${opts.theme} on ${store}. See \`raizn theme list --store ${store}\`.`);
+        if (t.role === "live") {
+            throw new CliError(`Theme ${t.id} ("${t.name}") is the LIVE theme. It is never pulled for editing. Pull a draft (or omit --theme to create one), or use --live --dir <folder> for a read-only copy.`);
+        }
+        if (t.role !== "draft")
+            throw new CliError(`Theme ${t.id} is ${t.role}; only drafts can be pulled for editing.`);
+        return t.id;
+    }
+    // Re-running pull in a checkout refreshes the draft it already tracks.
+    if (existing && existing.store === store && themes.some((t) => t.id === existing.themeId && t.role === "draft"))
+        return existing.themeId;
+    const drafts = themes.filter((t) => t.role === "draft").sort(byNewest);
+    if (drafts[0]) {
+        if (drafts.length > 1)
+            s.err(`Using the newest draft "${drafts[0].name}" (${drafts[0].id}); pass --theme <id> for another.`);
+        return drafts[0].id;
+    }
+    const from = live ? ` from the live theme "${live.name}"` : "";
+    if (!opts.yes) {
+        if (!s.ctx.io.isTTY) {
+            throw new CliError(`${store} has no draft theme. Re-run with --yes to create one${from}.`);
+        }
+        const answer = (await s.ctx.io.prompt(`${store} has no draft theme. Create a draft${from}? [y/N] `)).trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes")
+            throw new CliError("No draft created; nothing pulled.");
+    }
+    const name = live ? `${live.name} (draft)` : "Draft";
+    const made = await createDraft(client, store, name, live?.id);
+    s.err(`Created draft "${made.name}" (${made.themeId}).`);
+    return made.themeId;
+}
+// --- check -------------------------------------------------------------------
+export async function themeCheck(s, opts) {
+    const co = await s.checkout();
+    let root;
+    let store;
+    let themeId;
+    let paths;
+    if (co) {
+        root = co.root;
+        store = opts.store ?? co.state.store;
+        themeId = store === co.state.store ? co.state.themeId : undefined;
+        paths = opts.all ? await listLocalFiles(root) : (await localChanges(root, co.state)).changes.map((c) => c.path);
+    }
+    else {
+        // CI: a plain git checkout of theme files, no state — validate everything against the store.
+        if (!opts.store)
+            throw new CliError("This folder is not a theme checkout. Pass --store <slug> to validate every theme file in it.");
+        root = s.ctx.cwd;
+        store = opts.store;
+        paths = await listLocalFiles(root);
+    }
+    if (paths.length === 0) {
+        s.out(co && !opts.all ? "Nothing to check: no changed files. Use --all to check every file." : "No theme files found in this folder.");
+        return 0;
+    }
+    const files = [];
+    for (const p of paths) {
+        const bytes = await readLocal(root, p);
+        if (bytes)
+            files.push({ path: p, content: textOf(bytes) });
+    }
+    const client = await s.client(co?.state);
+    let errors = 0;
+    let warnings = 0;
+    for (const chunk of chunkFiles(files)) {
+        const r = await validateThemeFiles(client, store, themeId, chunk);
+        for (const res of r.results ?? []) {
+            for (const issue of res.errors ?? []) {
+                s.out(formatIssue(res.path, issue));
+                if (issue.severity === "error")
+                    errors++;
+                else
+                    warnings++;
+            }
+        }
+    }
+    s.err(`Checked ${plural(files.length, "file")}: ${plural(errors, "error")}, ${plural(warnings, "warning")}.`);
+    return errors > 0 ? 1 : 0;
+}
+// --- push --------------------------------------------------------------------
+export async function themePush(s, opts) {
+    const { root, state } = await s.requireCheckout({ editable: true });
+    let only;
+    if (opts.files.length > 0) {
+        only = [];
+        for (const f of opts.files) {
+            const p = toLayoutPath(root, path.resolve(s.ctx.cwd, f));
+            if (!p || !isLayoutPath(p))
+                throw new CliError(`${f} is not a theme file in this checkout (${root}).`);
+            only.push(p);
+        }
+    }
+    const { changes, deleted } = await localChanges(root, state, only);
+    for (const p of deleted) {
+        s.err(`  ${p} was deleted locally; push never deletes on the server${p.startsWith("sections/") ? " (use `raizn section delete`)" : ""}.`);
+    }
+    if (changes.length === 0) {
+        s.out("Nothing to push.");
+        return 0;
+    }
+    s.err(`Pushing ${plural(changes.length, "file")} to "${state.themeName}" on ${state.store}${opts.force ? " (--force: overwriting server changes)" : ""}…`);
+    const client = await s.client(state);
+    const r = await pushChanges(s, client, root, state, changes, { force: opts.force });
+    conflictAdvice(s, r.conflicts);
+    const failed = r.conflicts.length + r.invalid.length + r.refused.length;
+    s.err(`${r.saved} saved, ${r.unchanged} unchanged, ${failed} failed.`);
+    return failed > 0 ? 1 : 0;
+}
+// --- preview -----------------------------------------------------------------
+export async function themePreview(s, opts) {
+    const { state } = await s.requireCheckout({ editable: false });
+    const r = await getPreviewUrl(await s.client(state), state.store, state.themeId);
+    s.out(r.url);
+    if (r.expiresAt)
+        s.err(`Signed link; expires ${r.expiresAt}.`);
+    if (opts.open)
+        await s.ctx.openUrl(r.url);
+    return 0;
+}
+// --- submit ------------------------------------------------------------------
+export async function themeSubmit(s, opts) {
+    const title = opts.title?.trim();
+    if (!title)
+        throw new CliError('A title is required: raizn theme submit -m "What this change does".');
+    const { root, state } = await s.requireCheckout({ editable: true });
+    const { changes } = await localChanges(root, state);
+    if (changes.length > 0) {
+        throw new CliError([
+            `You have ${plural(changes.length, "unpushed change")}; the approval would not include them:`,
+            ...changes.slice(0, 20).map((c) => `  ${c.path}`),
+            "Run `raizn theme push` first, then submit.",
+        ].join("\n"));
+    }
+    const client = await s.client(state);
+    const r = await submitForApproval(client, state.store, state.themeId, title, opts.description);
+    s.out(`Submitted "${state.themeName}" for approval: request ${r.requestId}`);
+    s.out(`Review it: ${apiOrigin(client.url)}/themes/requests/${encodeURIComponent(r.requestId)}`);
+    if (r.sections && r.sections.length > 0) {
+        s.out(`These custom sections will go live with this request when it is published: ${r.sections.map((x) => `${x.type} v${x.version}`).join(", ")}.`);
+    }
+    s.out("Nothing is live yet. Someone with publish rights approves and publishes it in the Raizn admin.");
+    return 0;
+}

package/dist/context.js

@@ -0,0 +1,5 @@
+/** Timers that read the globals at call time, so vitest's fake timers apply to them. */
+export const globalTimers = {
+    setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
+    clearTimeout: (h) => globalThis.clearTimeout(h),
+};

package/dist/credentials.js

@@ -0,0 +1,153 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Where a token lives between runs. The OS keychain first (encrypted at rest, unlocked with the
+ * login session); a 0600 file when there is no keychain — a headless Linux box, a container, a
+ * platform `@napi-rs/keyring` has no binary for. Both are keyed by API origin so a staging login
+ * never shadows production.
+ */
+export const KEYCHAIN_SERVICE = "raizn-cli";
+/**
+ * Loaded lazily and inside try/catch: the native addon is an optional convenience, and a missing
+ * binary must degrade to the file store instead of crashing every command.
+ */
+async function loadKeyring() {
+    try {
+        const mod = (await import("@napi-rs/keyring"));
+        return typeof mod.Entry === "function" ? mod : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function credentialsFilePath(env = process.env, platform = process.platform) {
+    if (platform === "win32") {
+        const base = env["APPDATA"] || path.join(os.homedir(), "AppData", "Roaming");
+        return path.join(base, "raizn", "credentials");
+    }
+    return path.join(os.homedir(), ".config", "raizn", "credentials");
+}
+export class FileCredentialStore {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    async readAll() {
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.file, "utf8"));
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    async writeAll(all) {
+        await fs.mkdir(path.dirname(this.file), { recursive: true, mode: 0o700 });
+        const tmp = `${this.file}.${process.pid}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(all, null, 2) + "\n", { mode: 0o600 });
+        // `mode` only applies when the file is created; chmod covers a pre-existing temp name and
+        // filesystems that ignore the create mode. No-op on Windows, where %APPDATA% is per-user.
+        await fs.chmod(tmp, 0o600).catch(() => { });
+        await fs.rename(tmp, this.file);
+    }
+    async get(origin) {
+        const v = (await this.readAll())[origin];
+        return typeof v === "string" && v ? v : null;
+    }
+    async set(origin, token) {
+        const all = await this.readAll();
+        all[origin] = token;
+        await this.writeAll(all);
+        return "file";
+    }
+    async delete(origin) {
+        const all = await this.readAll();
+        if (!(origin in all))
+            return false;
+        delete all[origin];
+        if (Object.keys(all).length === 0) {
+            await fs.rm(this.file, { force: true });
+        }
+        else {
+            await this.writeAll(all);
+        }
+        return true;
+    }
+}
+export class SystemCredentialStore {
+    file;
+    keyring = null;
+    constructor(file) {
+        this.file = file;
+    }
+    entry(origin) {
+        this.keyring ??= loadKeyring();
+        return this.keyring.then((k) => {
+            if (!k)
+                return null;
+            try {
+                return new k.Entry(KEYCHAIN_SERVICE, origin);
+            }
+            catch {
+                return null;
+            }
+        });
+    }
+    async get(origin) {
+        const e = await this.entry(origin);
+        if (e) {
+            try {
+                const v = e.getPassword();
+                if (v)
+                    return v;
+            }
+            catch {
+                /* locked or unavailable keychain: fall through to the file */
+            }
+        }
+        return this.file.get(origin);
+    }
+    async set(origin, token) {
+        const e = await this.entry(origin);
+        if (e) {
+            try {
+                e.setPassword(token);
+                // A stale copy in the file would outlive a later `logout` that only reached the keychain.
+                await this.file.delete(origin);
+                return "keychain";
+            }
+            catch {
+                /* no usable keychain (e.g. no Secret Service on a headless Linux box) */
+            }
+        }
+        return this.file.set(origin, token);
+    }
+    async delete(origin) {
+        let removed = false;
+        const e = await this.entry(origin);
+        if (e) {
+            try {
+                removed = e.deletePassword() || removed;
+            }
+            catch {
+                /* nothing to delete, or keychain unavailable */
+            }
+        }
+        return (await this.file.delete(origin)) || removed;
+    }
+}
+/** In-memory store for tests and for callers that must never touch the machine's keychain. */
+export class MemoryCredentialStore {
+    map = new Map();
+    async get(origin) {
+        return this.map.get(origin) ?? null;
+    }
+    async set(origin, token) {
+        this.map.set(origin, token);
+        return "file";
+    }
+    async delete(origin) {
+        return this.map.delete(origin);
+    }
+}

package/dist/diff.js

@@ -0,0 +1,126 @@
+/**
+ * A unified diff for conflicts: what the server holds now vs what you have locally. Myers'
+ * O(ND) algorithm rather than an LCS table, because a 5,000-line template against itself with a
+ * handful of edits should take microseconds, not a 100 MB matrix.
+ */
+/** Beyond this many edits the files are simply different; a full replace reads just as well. */
+const MAX_EDITS = 2000;
+function myers(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const max = n + m;
+    const offset = max + 1;
+    const v = new Int32Array(2 * max + 3);
+    // trace[d] = the frontier before round d, trimmed to the diagonals round d can read.
+    const trace = [];
+    const at = (d, k) => trace[d][k + d + 1];
+    let found = false;
+    for (let d = 0; d <= max && !found; d++) {
+        if (d > MAX_EDITS)
+            return [...a.map((line) => ({ kind: "-", line })), ...b.map((line) => ({ kind: "+", line }))];
+        trace.push(v.slice(offset - d - 1, offset + d + 2));
+        for (let k = -d; k <= d; k += 2) {
+            let x;
+            if (k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1]))
+                x = v[offset + k + 1];
+            else
+                x = v[offset + k - 1] + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v[offset + k] = x;
+            if (x >= n && y >= m) {
+                found = true;
+                break;
+            }
+        }
+    }
+    // Walk the trace backwards to recover the edit script.
+    const ops = [];
+    let x = n;
+    let y = m;
+    for (let d = trace.length - 1; d >= 0; d--) {
+        const k = x - y;
+        let prevK;
+        if (k === -d || (k !== d && at(d, k - 1) < at(d, k + 1)))
+            prevK = k + 1;
+        else
+            prevK = k - 1;
+        const prevX = d === 0 ? 0 : at(d, prevK);
+        const prevY = d === 0 ? 0 : prevX - prevK;
+        while (x > prevX && y > prevY) {
+            ops.push({ kind: " ", line: a[x - 1] });
+            x--;
+            y--;
+        }
+        if (d === 0)
+            break;
+        if (x === prevX)
+            ops.push({ kind: "+", line: b[y - 1] });
+        else
+            ops.push({ kind: "-", line: a[x - 1] });
+        x = prevX;
+        y = prevY;
+    }
+    return ops.reverse();
+}
+const splitLines = (s) => {
+    const lines = s.replace(/\r\n/g, "\n").split("\n");
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+};
+export function unifiedDiff(oldText, newText, oldLabel, newLabel, context = 3) {
+    const a = splitLines(oldText);
+    const b = splitLines(newText);
+    const ops = myers(a, b);
+    if (ops.every((o) => o.kind === " "))
+        return "";
+    const out = [`--- ${oldLabel}`, `+++ ${newLabel}`];
+    // Positions (1-based) in a and b at each op, to label hunks.
+    let ai = 1;
+    let bi = 1;
+    const pos = ops.map((o) => {
+        const p = { a: ai, b: bi };
+        if (o.kind !== "+")
+            ai++;
+        if (o.kind !== "-")
+            bi++;
+        return p;
+    });
+    let i = 0;
+    while (i < ops.length) {
+        if (ops[i].kind === " ") {
+            i++;
+            continue;
+        }
+        const start = Math.max(0, i - context);
+        let end = i;
+        // Extend the hunk while the next change is within 2×context unchanged lines.
+        for (;;) {
+            while (end < ops.length && ops[end].kind !== " ")
+                end++;
+            let gap = end;
+            while (gap < ops.length && ops[gap].kind === " ")
+                gap++;
+            if (gap < ops.length && gap - end <= context * 2)
+                end = gap;
+            else {
+                end = Math.min(ops.length, end + context);
+                break;
+            }
+        }
+        const hunk = ops.slice(start, end);
+        const aStart = pos[start].a;
+        const bStart = pos[start].b;
+        const aLen = hunk.filter((o) => o.kind !== "+").length;
+        const bLen = hunk.filter((o) => o.kind !== "-").length;
+        out.push(`@@ -${aLen === 0 ? aStart - 1 : aStart},${aLen} +${bLen === 0 ? bStart - 1 : bStart},${bLen} @@`);
+        for (const o of hunk)
+            out.push(`${o.kind}${o.line}`);
+        i = end;
+    }
+    return out.join("\n") + "\n";
+}

package/dist/errors.js

@@ -0,0 +1,54 @@
+/**
+ * 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. */
+export class AuthError extends CliError {
+    name = "AuthError";
+}
+/** 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}`;