@cerkel/cli 0.0.0-stage → 1.0.1

package/dist/content-files.js

@@ -0,0 +1,246 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { CliError } from "./errors.js";
+import { stateDirOf } from "./state.js";
+export const CONTENT_FILE = "content.json";
+/** `<dir>/.cerkel/content.json`, or `.raizn/` for a folder pulled before 1.0 (state.ts stateDirOf). */
+export const contentStatePath = (dir) => path.join(dir, stateDirOf(dir, CONTENT_FILE), CONTENT_FILE);
+export const hashText = (s) => createHash("sha256").update(s.replace(/\r\n/g, "\n"), "utf8").digest("hex");
+/** Languages in a stable order: Arabic first (the default), then the rest alphabetically. */
+const langOrder = (keys) => [...keys].sort((a, b) => (a === "ar" ? -1 : b === "ar" ? 1 : a.localeCompare(b)));
+export const pagePathOf = (p) => p.kind === "article" ? `blogs/${p.blog ?? "news"}/${p.handle}.html` : p.kind === "policy" ? `policies/${p.handle}.html` : `pages/${p.handle}.html`;
+export const menuPathOf = (handle) => `menus/${handle}.json`;
+/** A relative POSIX path → what it holds, or null when it is not a content file. */
+export function addressOf(rel) {
+    const seg = rel.split("/");
+    const strip = (f, ext) => (f.endsWith(ext) && f.length > ext.length ? f.slice(0, -ext.length) : null);
+    if (seg.length === 2 && seg[0] === "pages") {
+        const h = strip(seg[1], ".html");
+        return h ? { type: "page", page: { kind: "page", blog: null, handle: h } } : null;
+    }
+    if (seg.length === 2 && seg[0] === "policies") {
+        const h = strip(seg[1], ".html");
+        return h ? { type: "page", page: { kind: "policy", blog: null, handle: h } } : null;
+    }
+    if (seg.length === 3 && seg[0] === "blogs") {
+        const h = strip(seg[2], ".html");
+        return h ? { type: "page", page: { kind: "article", blog: seg[1], handle: h } } : null;
+    }
+    if (seg.length === 2 && seg[0] === "menus") {
+        const h = strip(seg[1], ".json");
+        return h ? { type: "menu", handle: h } : null;
+    }
+    return null;
+}
+export function pageFileOf(p) {
+    return {
+        title: p.title, bodyHtml: p.bodyHtml, summary: p.summary, blogTitle: p.blogTitle, seoTitle: p.seoTitle, seoDescription: p.seoDescription,
+        imageUrl: p.imageUrl, author: p.author, tags: p.tags, templateSuffix: p.templateSuffix, published: p.published, publishedAt: p.publishedAt,
+    };
+}
+/** The file text for a page. Its settings (everything but the body) are pretty JSON; bodies follow per language. */
+export function serializePage(p) {
+    const { bodyHtml, ...settings } = p;
+    const head = `<!--cerkel\n${JSON.stringify(settings, null, 2)}\n-->\n`;
+    const bodies = langOrder(Object.keys(bodyHtml)).map((l) => `<!--lang:${l}-->\n${bodyHtml[l].replace(/\n+$/, "")}\n`).join("");
+    return head + bodies;
+}
+const LANG_MARKER = /^<!--lang:([a-z]{2,3}(?:-[A-Za-z0-9]{2,8})?)-->$/gm;
+const isLocalized = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
+/** Parse a page file. Throws CliError naming the file and what is wrong. */
+export function parsePage(text, file) {
+    const src = text.replace(/\r\n/g, "\n").replace(/^\uFEFF/, "");
+    // `<!--raizn` is what `raizn` wrote before 1.0: such a file still pushes as it is.
+    const open = ["<!--cerkel\n", "<!--raizn\n"].find((m) => src.startsWith(m));
+    if (!open)
+        throw new CliError(`${file}: a page file starts with its settings in <!--cerkel … --> (pull a page to see the layout).`);
+    const end = src.indexOf("\n-->", open.length - 1);
+    if (end < 0)
+        throw new CliError(`${file}: the <!--cerkel settings block is not closed with -->.`);
+    let settings;
+    try {
+        settings = JSON.parse(src.slice(open.length, end));
+    }
+    catch (e) {
+        throw new CliError(`${file}: the settings block is not valid JSON (${e instanceof Error ? e.message : String(e)}).`);
+    }
+    if (typeof settings !== "object" || settings === null || Array.isArray(settings))
+        throw new CliError(`${file}: the settings block must be a JSON object.`);
+    const rest = src.slice(end + 4).replace(/^\n/, "");
+    const bodyHtml = {};
+    const marks = [...rest.matchAll(LANG_MARKER)];
+    if (!marks.length && rest.trim())
+        throw new CliError(`${file}: put the body after a language marker, e.g. <!--lang:ar--> on its own line.`);
+    if (marks.length && rest.slice(0, marks[0].index).trim())
+        throw new CliError(`${file}: text before the first <!--lang:xx--> marker belongs to no language.`);
+    marks.forEach((m, i) => {
+        const start = m.index + m[0].length;
+        const stop = i + 1 < marks.length ? marks[i + 1].index : rest.length;
+        const body = rest.slice(start, stop).replace(/^\n/, "").replace(/\n+$/, "");
+        if (bodyHtml[m[1]] !== undefined)
+            throw new CliError(`${file}: the language "${m[1]}" appears twice.`);
+        if (body.trim())
+            bodyHtml[m[1]] = body;
+    });
+    const loc = (k, required) => {
+        const v = settings[k];
+        if (v === null || v === undefined) {
+            if (required)
+                throw new CliError(`${file}: "${k}" is required (text per language, e.g. {"ar": "…", "en": "…"}).`);
+            return null;
+        }
+        if (!isLocalized(v))
+            throw new CliError(`${file}: "${k}" must be text per language, e.g. {"ar": "…", "en": "…"}.`);
+        return v;
+    };
+    const str = (k) => {
+        const v = settings[k];
+        if (v === null || v === undefined || v === "")
+            return null;
+        if (typeof v !== "string")
+            throw new CliError(`${file}: "${k}" must be text or null.`);
+        return v;
+    };
+    const known = new Set(["title", "summary", "blogTitle", "seoTitle", "seoDescription", "imageUrl", "author", "tags", "templateSuffix", "published", "publishedAt"]);
+    const unknown = Object.keys(settings).filter((k) => !known.has(k));
+    if (unknown.length)
+        throw new CliError(`${file}: unknown setting(s) ${unknown.map((k) => `"${k}"`).join(", ")}. The handle comes from the file name.`);
+    const tags = settings["tags"] ?? [];
+    if (!Array.isArray(tags) || tags.some((t) => typeof t !== "string"))
+        throw new CliError(`${file}: "tags" must be a list of text.`);
+    const published = settings["published"] ?? true;
+    if (typeof published !== "boolean")
+        throw new CliError(`${file}: "published" must be true or false.`);
+    return {
+        title: loc("title", true), bodyHtml, summary: loc("summary", false), blogTitle: loc("blogTitle", false), seoTitle: loc("seoTitle", false),
+        seoDescription: loc("seoDescription", false), imageUrl: str("imageUrl"), author: str("author"), tags: tags, templateSuffix: str("templateSuffix"),
+        published, publishedAt: str("publishedAt"),
+    };
+}
+export const serializeMenu = (m) => `${JSON.stringify({ title: m.title, items: m.items }, null, 2)}\n`;
+export function parseMenu(text, file) {
+    let v;
+    try {
+        v = JSON.parse(text.replace(/^\uFEFF/, ""));
+    }
+    catch (e) {
+        throw new CliError(`${file}: not valid JSON (${e instanceof Error ? e.message : String(e)}).`);
+    }
+    const o = v;
+    if (typeof o !== "object" || o === null || Array.isArray(o) || typeof o["title"] !== "string" || !Array.isArray(o["items"])) {
+        throw new CliError(`${file}: a menu file is { "title": "…", "items": [ … ] }.`);
+    }
+    const unknown = Object.keys(o).filter((k) => k !== "title" && k !== "items");
+    if (unknown.length)
+        throw new CliError(`${file}: unknown key(s) ${unknown.map((k) => `"${k}"`).join(", ")}. The handle comes from the file name.`);
+    return { title: o["title"], items: o["items"] };
+}
+/**
+ * update_page arguments that make the server's page equal the file: per-language fields send every
+ * local language and "" for a language the server has but the file dropped (update_page merges).
+ */
+export function pageUpdateArgs(id, addr, file, server) {
+    const withRemovals = (local, remote) => {
+        const out = { ...local };
+        for (const k of Object.keys(remote ?? {}))
+            if (!(k in local))
+                out[k] = "";
+        return out;
+    };
+    const nullable = (local, remote) => (local === null ? null : withRemovals(local, remote));
+    return {
+        page: id,
+        ...(addr.handle !== server.handle ? { handle: addr.handle } : {}),
+        ...(addr.kind === "article" && addr.blog !== server.blog ? { newBlog: addr.blog } : {}),
+        title: withRemovals(file.title, server.title),
+        bodyHtml: withRemovals(file.bodyHtml, server.bodyHtml),
+        summary: nullable(file.summary, server.summary),
+        blogTitle: nullable(file.blogTitle, server.blogTitle),
+        seoTitle: nullable(file.seoTitle, server.seoTitle),
+        seoDescription: nullable(file.seoDescription, server.seoDescription),
+        imageUrl: file.imageUrl, author: file.author, tags: file.tags, templateSuffix: file.templateSuffix,
+        published: file.published, publishedAt: file.publishedAt,
+    };
+}
+/** create_page arguments for a new file. */
+export function pageCreateArgs(addr, file) {
+    const out = { kind: addr.kind, handle: addr.handle, title: file.title, bodyHtml: file.bodyHtml, tags: file.tags, published: file.published };
+    if (addr.kind === "article")
+        out["blog"] = addr.blog;
+    for (const k of ["summary", "blogTitle", "seoTitle", "seoDescription", "imageUrl", "author", "templateSuffix", "publishedAt"])
+        if (file[k] !== null)
+            out[k] = file[k];
+    return out;
+}
+// --- the folder ----------------------------------------------------------------------
+export async function readContentState(dir) {
+    let raw;
+    try {
+        raw = await fs.readFile(contentStatePath(dir), "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw e;
+    }
+    const s = JSON.parse(raw);
+    if (s.version !== 1 || typeof s.store !== "string" || typeof s.files !== "object" || s.files === null) {
+        throw new CliError(`${contentStatePath(dir)} is not a content state file this version of cerkel understands. Pull again with --force.`);
+    }
+    return s;
+}
+export async function writeContentState(dir, state) {
+    const d = path.join(dir, stateDirOf(dir, CONTENT_FILE));
+    await fs.mkdir(d, { recursive: true });
+    await fs.writeFile(path.join(d, ".gitignore"), "*\n");
+    const sorted = {};
+    for (const k of Object.keys(state.files).sort())
+        sorted[k] = state.files[k];
+    const file = path.join(d, CONTENT_FILE);
+    await fs.writeFile(`${file}.tmp`, JSON.stringify({ ...state, files: sorted }, null, 2) + "\n");
+    await fs.rename(`${file}.tmp`, file);
+}
+/** Every content file under `dir` of the given types, as POSIX relative paths. */
+export async function listContentFiles(dir, types) {
+    const out = [];
+    const walk = async (rel, depth) => {
+        let entries;
+        try {
+            entries = await fs.readdir(path.join(dir, rel), { withFileTypes: true });
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return;
+            throw e;
+        }
+        for (const e of entries) {
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory() && depth < 2)
+                await walk(r, depth + 1);
+            else if (e.isFile()) {
+                const a = addressOf(r);
+                if (a && types.includes(a.type))
+                    out.push(r);
+            }
+        }
+    };
+    for (const top of ["pages", "policies", "blogs", "menus"])
+        await walk(top, 1);
+    return out.sort();
+}
+export async function readText(dir, rel) {
+    try {
+        return await fs.readFile(path.join(dir, ...rel.split("/")), "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw e;
+    }
+}
+export async function writeText(dir, rel, text) {
+    const full = path.join(dir, ...rel.split("/"));
+    await fs.mkdir(path.dirname(full), { recursive: true });
+    await fs.writeFile(full, text);
+}

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,201 @@
+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.
+ *
+ * Until 1.0 the CLI was `raizn`: its logins sit under the keychain service "raizn-cli" and in
+ * ~/.config/raizn/credentials. Each is read once, moved to the cerkel place, and removed there.
+ */
+export const KEYCHAIN_SERVICE = "cerkel-cli";
+export const LEGACY_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, app = "cerkel") {
+    if (platform === "win32") {
+        const base = env["APPDATA"] || path.join(os.homedir(), "AppData", "Roaming");
+        return path.join(base, app, "credentials");
+    }
+    return path.join(os.homedir(), ".config", app, "credentials");
+}
+/** Where `raizn` (before 1.0) kept the file: read once and moved (FileCredentialStore). */
+export const legacyCredentialsFilePath = (env = process.env, platform = process.platform) => credentialsFilePath(env, platform, "raizn");
+async function readJsonFile(file) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch (e) {
+        return e.code === "ENOENT" ? null : {};
+    }
+}
+export class FileCredentialStore {
+    file;
+    legacyFile;
+    migrated = false;
+    /** `legacyFile`: the old cerkel file. While the cerkel file does not exist yet, its logins move over once. */
+    constructor(file, legacyFile = null) {
+        this.file = file;
+        this.legacyFile = legacyFile;
+    }
+    async readAll() {
+        const current = await readJsonFile(this.file);
+        if (current !== null || !this.legacyFile || this.migrated)
+            return current ?? {};
+        this.migrated = true;
+        const old = await readJsonFile(this.legacyFile);
+        if (!old || Object.keys(old).length === 0)
+            return {};
+        await this.writeAll(old);
+        await fs.rm(this.legacyFile, { force: true });
+        return old;
+    }
+    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, service = KEYCHAIN_SERVICE) {
+        this.keyring ??= loadKeyring();
+        return this.keyring.then((k) => {
+            if (!k)
+                return null;
+            try {
+                return new k.Entry(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 */
+            }
+            const moved = await this.moveLegacy(origin, e);
+            if (moved)
+                return moved;
+        }
+        return this.file.get(origin);
+    }
+    /** A login `raizn` (before 1.0) saved under "raizn-cli": copied to "cerkel-cli" once, then removed there. */
+    async moveLegacy(origin, target) {
+        const old = await this.entry(origin, LEGACY_KEYCHAIN_SERVICE);
+        if (!old)
+            return null;
+        try {
+            const v = old.getPassword();
+            if (!v)
+                return null;
+            target.setPassword(v);
+            try {
+                old.deletePassword();
+            }
+            catch { /* the copy is in place; a stale old entry is only read once more */ }
+            return v;
+        }
+        catch {
+            return null;
+        }
+    }
+    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;
+        // Logging out also removes a login `raizn` saved that was never moved.
+        for (const service of [KEYCHAIN_SERVICE, LEGACY_KEYCHAIN_SERVICE]) {
+            const e = await this.entry(origin, service);
+            if (!e)
+                continue;
+            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,146 @@
+/**
+ * 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";
+}
+/** How much of `oldText` would disappear if it were replaced by `newText`, line by line. */
+export function diffStats(oldText, newText) {
+    const ops = myers(splitLines(oldText), splitLines(newText));
+    const stats = { removed: 0, added: 0, places: 0 };
+    let runRemoves = false;
+    for (const o of [...ops, { kind: " ", line: "" }]) {
+        if (o.kind === " ") {
+            if (runRemoves)
+                stats.places++;
+            runRemoves = false;
+        }
+        else if (o.kind === "-") {
+            stats.removed++;
+            runRemoves = true;
+        }
+        else
+            stats.added++;
+    }
+    return stats;
+}

package/dist/env.js

@@ -0,0 +1,24 @@
+/**
+ * The CLI's environment variables. CERKEL_TOKEN and CERKEL_API_URL are the names since 1.0; the old
+ * RAIZN_TOKEN and RAIZN_API_URL (the CLI was `raizn` until then) still work, and a CERKEL_* one wins
+ * when both are set.
+ */
+export const TOKEN_VARS = ["CERKEL_TOKEN", "RAIZN_TOKEN"];
+export const API_URL_VARS = ["CERKEL_API_URL", "RAIZN_API_URL"];
+function first(env, names) {
+    for (const name of names) {
+        const value = env[name]?.trim();
+        if (value)
+            return { name, value };
+    }
+    return null;
+}
+/** The token a pipeline injected, and the name it came under (for messages). */
+export const envToken = (env) => first(env, TOKEN_VARS);
+/** The API URL the environment asks for, or null. */
+export const envApiUrl = (env) => first(env, API_URL_VARS)?.value ?? null;
+/** Every token the environment holds under either name, raw and trimmed, so the redactor hides them all. */
+export const envTokenSecrets = (env) => TOKEN_VARS.flatMap((name) => {
+    const v = env[name];
+    return v ? [v, v.trim()] : [];
+});