@wirecat/cli-core 0.0.0 → 0.18.0

package/dist/release/index.d.ts

@@ -0,0 +1,38 @@
+export { type ChangelogRules, changelogProblems, type DocsRules, docsProblems, idPattern, JOURNAL_IDS, markdownFiles, slug, } from "./markdown.js";
+export { REQUIRED_PAGES, type StructureRules, structureProblems } from "./structure.js";
+export type Check = {
+    name: string;
+    run: () => string[];
+};
+/**
+ * Runs every check even after one fails, so one pass shows the whole list, and returns how many
+ * failed. The caller exits: a library that calls `process.exit` cannot be tested.
+ */
+export declare const releaseCheck: (checks: readonly Check[], { version, log }: {
+    version: string;
+    log: (line: string) => void;
+}) => number;
+export declare const run: (root: string, command: string, args: readonly string[]) => {
+    ok: boolean;
+    output: string;
+};
+/** A check that passes when the command exits 0, and otherwise shows the last 15 lines it printed. */
+export declare const command: (root: string, name: string, ...args: string[]) => () => string[];
+export declare const packageVersion: (root: string) => string;
+export declare const notOnNpm: (root: string, packageName: string, version: string) => () => string[];
+/**
+ * `allowed` holds exact paths, and directories ending in `/`; `said` is how the problem names them.
+ */
+export declare const packProblems: (paths: readonly string[], allowed: readonly string[], said: string) => string[];
+export declare const packContents: (root: string, allowed: readonly string[], said: string) => () => string[];
+/**
+ * The whole of a `version:check` / `version:sync` script: what to print, and the exit code — 2 when
+ * either file cannot be read, 1 on drift. A CLI keeps its version in `package.json` and in a source
+ * file read at run time — `--version` must not load `package.json`, which is not there once the
+ * command is bundled — and the day they disagree is a release day.
+ */
+export declare const versionScript: (root: string, argv: readonly string[], file?: string) => {
+    code: 0 | 1 | 2;
+    message: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/release/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/release/index.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,cAAc,EACnB,iBAAiB,EACjB,KAAK,SAAS,EACd,YAAY,EACZ,SAAS,EACT,WAAW,EACX,aAAa,EACb,IAAI,GACL,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAEvF,MAAM,MAAM,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,MAAM,EAAE,CAAA;CAAE,CAAA;AAEzD;;;GAGG;AACH,eAAO,MAAM,YAAY,WACf,SAAS,KAAK,EAAE,oBACN;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,WAWnE,CAAA;AAED,eAAO,MAAM,GAAG,SAAU,MAAM,WAAW,MAAM,QAAQ,SAAS,MAAM,EAAE;;;CAIzE,CAAA;AAED,sGAAsG;AACtG,eAAO,MAAM,OAAO,SACX,MAAM,QAAQ,MAAM,WAAW,MAAM,EAAE,WAC1C,MAAM,EAGT,CAAA;AAEH,eAAO,MAAM,cAAc,SAAU,MAAM,WACoD,CAAA;AAE/F,eAAO,MAAM,QAAQ,SAAU,MAAM,eAAe,MAAM,WAAW,MAAM,WAAS,MAAM,EAGlF,CAAA;AAER;;GAEG;AACH,eAAO,MAAM,YAAY,UAAW,SAAS,MAAM,EAAE,WAAW,SAAS,MAAM,EAAE,QAAQ,MAAM,aAG1B,CAAA;AAErE,eAAO,MAAM,YAAY,SAAU,MAAM,WAAW,SAAS,MAAM,EAAE,QAAQ,MAAM,WAAS,MAAM,EASjG,CAAA;AAcD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,QACN,SAAS,MAAM,EAAE,oBAEtB;IAAE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAiBpC,CAAA"}

package/dist/release/index.js

@@ -0,0 +1,91 @@
+/**
+ * Everything about a release that a program can decide. Each check returns the problems it found,
+ * one line each, saying what and where; an empty list is a pass. The judgement half — changelog
+ * wording, docs against the diff, live checks — is each CLI's release skill.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export { changelogProblems, docsProblems, idPattern, JOURNAL_IDS, markdownFiles, slug, } from "./markdown.js";
+export { REQUIRED_PAGES, structureProblems } from "./structure.js";
+/**
+ * Runs every check even after one fails, so one pass shows the whole list, and returns how many
+ * failed. The caller exits: a library that calls `process.exit` cannot be tested.
+ */
+export const releaseCheck = (checks, { version, log }) => {
+    let failed = 0;
+    for (const { name, run } of checks) {
+        const problems = run();
+        log(`${problems.length === 0 ? "ok  " : "FAIL"}  ${name}`);
+        for (const problem of problems)
+            log(problem.replace(/^/gm, "      "));
+        if (problems.length > 0)
+            failed++;
+    }
+    log(failed === 0 ? `\n${version}: every check passed` : `\n${version}: ${failed} check(s) failed`);
+    return failed;
+};
+export const run = (root, command, args) => {
+    const done = spawnSync(command, args, { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    const output = `${done.stdout ?? ""}${done.stderr ?? ""}${done.error ? String(done.error) : ""}`;
+    return { ok: done.status === 0, output };
+};
+/** A check that passes when the command exits 0, and otherwise shows the last 15 lines it printed. */
+export const command = (root, name, ...args) => () => {
+    const { ok, output } = run(root, name, args);
+    return ok ? [] : [output.trim().split("\n").slice(-15).join("\n") || `exit ${name} ${args.join(" ")}`];
+};
+export const packageVersion = (root) => JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+export const notOnNpm = (root, packageName, version) => () => run(root, "npm", ["view", `${packageName}@${version}`, "version", "--prefer-online"]).ok
+    ? [`${version} is already on npm — raise the version`]
+    : [];
+/**
+ * `allowed` holds exact paths, and directories ending in `/`; `said` is how the problem names them.
+ */
+export const packProblems = (paths, allowed, said) => paths
+    .filter((path) => !allowed.some((entry) => (entry.endsWith("/") ? path.startsWith(entry) : path === entry)))
+    .map((path) => `npm pack: ${path} would ship — only ${said} may`);
+export const packContents = (root, allowed, said) => () => {
+    const { ok, output } = run(root, "npm", ["pack", "--dry-run", "--json", "--ignore-scripts"]);
+    if (!ok)
+        return [output.trim()];
+    const [packed] = JSON.parse(output.slice(output.indexOf("[")));
+    return packProblems((packed?.files ?? []).map(({ path }) => path), allowed, said);
+};
+const VERSION = /export const VERSION = "([^"]*)"/;
+const versionsOf = (root, file) => {
+    const declared = packageVersion(root);
+    if (typeof declared !== "string" || !/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(declared))
+        return `package.json has no usable "version" (got ${JSON.stringify(declared)})`;
+    const source = readFileSync(join(root, file), "utf8");
+    const current = VERSION.exec(source)?.[1];
+    if (!current)
+        return `${file} does not export a VERSION string`;
+    return { declared, current, source };
+};
+/**
+ * The whole of a `version:check` / `version:sync` script: what to print, and the exit code — 2 when
+ * either file cannot be read, 1 on drift. A CLI keeps its version in `package.json` and in a source
+ * file read at run time — `--version` must not load `package.json`, which is not there once the
+ * command is bundled — and the day they disagree is a release day.
+ */
+export const versionScript = (root, argv, file = "src/version.ts") => {
+    const found = versionsOf(root, file);
+    if (typeof found === "string")
+        return { code: 2, message: found };
+    const { declared, current, source } = found;
+    if (argv.includes("--sync")) {
+        if (current === declared)
+            return { code: 0, message: `version ${declared} — already in step` };
+        writeFileSync(join(root, file), source.replace(`"${current}"`, `"${declared}"`));
+        return { code: 0, message: `${file}: ${current} → ${declared}` };
+    }
+    if (current !== declared)
+        return {
+            code: 1,
+            message: `version drift: package.json says ${declared}, ${file} says ${current}.\n` +
+                "Run `pnpm version:sync` — package.json is the one that is edited.",
+        };
+    return { code: 0, message: `version ${declared} — package.json and ${file} agree` };
+};
+//# sourceMappingURL=index.js.map

package/dist/release/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/release/index.ts"],"names":[],"mappings":"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"}

package/dist/release/markdown.d.ts

@@ -0,0 +1,36 @@
+/** The prefixes of the owner's journal ids; a project adds its own (`CLI`, `MAX`, …). */
+export declare const JOURNAL_IDS: readonly ["NEED", "FIND", "BUG", "SEC", "PERF", "UX", "IDEA", "RISK", "DEBT", "ASK", "TASK"];
+export declare const idPattern: (prefixes: readonly string[]) => RegExp;
+export type ChangelogRules = {
+    /** The only `###` headings a section may have. */
+    headings: readonly string[];
+    /** The top section's title until it is dated, `Unreleased` or `Не выпущено`. */
+    unreleased: string;
+    ids: readonly string[];
+};
+/**
+ * `release`: the top section must be `version`, and nothing may be left unreleased — a release
+ * workflow builds its notes by matching `## <version> `, so a heading slightly off publishes empty
+ * notes without an error.
+ */
+export declare const changelogProblems: (text: string, { version, release, headings, unreleased, ids }: ChangelogRules & {
+    version?: string;
+    release: boolean;
+}) => string[];
+/** GitHub's heading anchor: lower case, only letters, digits, `-`, `_` and spaces kept, spaces to `-`. */
+export declare const slug: (heading: string) => string;
+export declare const withoutCode: (text: string) => string;
+/** Every `.md` under `directory`, not descending into a directory named in `skip`. */
+export declare const markdownFiles: (directory: string, skip?: ReadonlySet<string>) => string[];
+export type DocsRules = {
+    /** Absolute paths; a missing one is passed over. */
+    files: readonly string[];
+    ids: readonly string[];
+    /** A page a user reads, by its path relative to `root`: no correction mark, struck-out text or id. */
+    userPage?: (name: string) => boolean;
+    correction?: RegExp;
+    /** A link not to follow — a private or sibling checkout that CI does not have. */
+    skipLink?: (target: string, destination: string) => boolean;
+};
+export declare const docsProblems: (root: string, { files, ids, userPage, correction, skipLink }: DocsRules) => string[];
+//# sourceMappingURL=markdown.d.ts.map

package/dist/release/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/release/markdown.ts"],"names":[],"mappings":"AAGA,yFAAyF;AACzF,eAAO,MAAM,WAAW,YAAI,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAU,CAAA;AAEvH,eAAO,MAAM,SAAS,aAAc,SAAS,MAAM,EAAE,WAA4D,CAAA;AAIjH,MAAM,MAAM,cAAc,GAAG;IAC3B,kDAAkD;IAClD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAA;IAClB,GAAG,EAAE,SAAS,MAAM,EAAE,CAAA;CACvB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,SACtB,MAAM,mDACqC,cAAc,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,aAyCzG,CAAA;AAED,0GAA0G;AAC1G,eAAO,MAAM,IAAI,YAAa,MAAM,WAMb,CAAA;AAEvB,eAAO,MAAM,WAAW,SAAU,MAAM,WAGqB,CAAA;AAsB7D,sFAAsF;AACtF,eAAO,MAAM,aAAa,cAAe,MAAM,SAAQ,WAAW,CAAC,MAAM,CAAC,KAAe,MAAM,EAWvF,CAAA;AAER,MAAM,MAAM,SAAS,GAAG;IACtB,oDAAoD;IACpD,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,GAAG,EAAE,SAAS,MAAM,EAAE,CAAA;IACtB,sGAAsG;IACtG,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;IACpC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAA;CAC5D,CAAA;AAED,eAAO,MAAM,YAAY,SACjB,MAAM,kDACsF,SAAS,aA8C5G,CAAA"}

package/dist/release/markdown.js

@@ -0,0 +1,153 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+/** The prefixes of the owner's journal ids; a project adds its own (`CLI`, `MAX`, …). */
+export const JOURNAL_IDS = ["NEED", "FIND", "BUG", "SEC", "PERF", "UX", "IDEA", "RISK", "DEBT", "ASK", "TASK"];
+export const idPattern = (prefixes) => new RegExp(`\\b(?:${prefixes.join("|")})-\\d+\\b`, "g");
+const VERSION_HEADING = /^## (\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?) — (\d{2})\.(\d{2})\.(\d{4})$/;
+/**
+ * `release`: the top section must be `version`, and nothing may be left unreleased — a release
+ * workflow builds its notes by matching `## <version> `, so a heading slightly off publishes empty
+ * notes without an error.
+ */
+export const changelogProblems = (text, { version, release, headings, unreleased, ids }) => {
+    const problems = [];
+    const id = idPattern(ids);
+    let section;
+    let subheadings = new Set();
+    let first = true;
+    text.split("\n").forEach((line, index) => {
+        const where = `CHANGELOG.md:${index + 1}`;
+        if (line.startsWith("## ")) {
+            section = line.slice(3);
+            subheadings = new Set();
+            if (section === unreleased) {
+                if (release)
+                    problems.push(`${where}: "${unreleased}" is left — date it as ${version} before releasing`);
+                else if (!first)
+                    problems.push(`${where}: "${unreleased}" must be the top section`);
+            }
+            else {
+                const found = VERSION_HEADING.exec(line);
+                if (!found)
+                    problems.push(`${where}: "${line}" is not "## <version> — DD.MM.YYYY"`);
+                else {
+                    const [, heading, day, month] = found;
+                    if (Number(day) < 1 || Number(day) > 31 || Number(month) < 1 || Number(month) > 12)
+                        problems.push(`${where}: "${line}" has no such date`);
+                    if (release && first && heading !== version)
+                        problems.push(`${where}: the top section is ${heading}, package.json says ${version}`);
+                }
+            }
+            first = false;
+            return;
+        }
+        if (line.startsWith("### ")) {
+            const heading = line.slice(4);
+            if (!headings.includes(heading))
+                problems.push(`${where}: "${heading}" is not one of: ${headings.join(", ")}`);
+            if (subheadings.has(heading))
+                problems.push(`${where}: "${heading}" twice in "${section}"`);
+            subheadings.add(heading);
+        }
+        for (const found of line.match(id) ?? [])
+            problems.push(`${where}: internal id ${found} — say what changed instead`);
+    });
+    if (release && first)
+        problems.push(`CHANGELOG.md: no section for ${version}`);
+    return problems;
+};
+/** GitHub's heading anchor: lower case, only letters, digits, `-`, `_` and spaces kept, spaces to `-`. */
+export const slug = (heading) => heading
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/<[^>]+>/g, "")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{M}\p{N}\-_ ]/gu, "")
+    .replace(/ /g, "-");
+export const withoutCode = (text) => text
+    .replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, (block) => block.replace(/[^\n]/g, " "))
+    .replace(/`[^`\n]*`/g, (span) => " ".repeat(span.length));
+// Headings are read from the raw text, so code inside a heading still counts toward its anchor.
+const anchorsOf = (text) => {
+    const raw = text.split("\n");
+    const anchors = new Set();
+    const counts = new Map();
+    withoutCode(text)
+        .split("\n")
+        .forEach((masked, index) => {
+        if (!/^#{1,6} /.test(masked))
+            return;
+        const heading = /^#{1,6} (.+?)\s*#*\s*$/.exec(raw[index] ?? "")?.[1];
+        if (heading === undefined)
+            return;
+        const base = slug(heading);
+        const seen = counts.get(base) ?? 0;
+        counts.set(base, seen + 1);
+        anchors.add(seen === 0 ? base : `${base}-${seen}`);
+    });
+    for (const [, name = ""] of text.matchAll(/<a\s+(?:name|id)="([^"]+)"/g))
+        anchors.add(name);
+    return anchors;
+};
+/** Every `.md` under `directory`, not descending into a directory named in `skip`. */
+export const markdownFiles = (directory, skip = new Set()) => existsSync(directory)
+    ? readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        if (skip.has(entry.name))
+            return [];
+        const path = join(directory, entry.name);
+        // stat, not the entry's own type: Claude Code's sandbox mounts character devices over names
+        // like .claude/loop.md, and the directory listing still reports what lies underneath.
+        const stats = statSync(path, { throwIfNoEntry: false });
+        if (entry.isDirectory() && stats?.isDirectory())
+            return markdownFiles(path, skip);
+        return stats?.isFile() && entry.name.endsWith(".md") ? [path] : [];
+    })
+    : [];
+export const docsProblems = (root, { files, ids, userPage = () => false, correction = /correction \d{4}/i, skipLink = () => false }) => {
+    const id = idPattern(ids);
+    const cache = new Map();
+    const anchors = (path) => {
+        let found = cache.get(path);
+        if (!found) {
+            found = anchorsOf(readFileSync(path, "utf8"));
+            cache.set(path, found);
+        }
+        return found;
+    };
+    const problems = [];
+    for (const path of files.filter((file) => existsSync(file))) {
+        const name = relative(root, path);
+        const user = userPage(name);
+        withoutCode(readFileSync(path, "utf8"))
+            .split("\n")
+            .forEach((line, index) => {
+            const where = `${name}:${index + 1}`;
+            for (const [, target] of line.matchAll(/!?\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
+                if (!target || /^[a-z][a-z0-9+.-]*:/i.test(target))
+                    continue;
+                const [file = "", anchor] = decodeURIComponent(target).split("#");
+                const destination = file === "" ? path : resolve(dirname(path), file);
+                if (skipLink(file, destination))
+                    continue;
+                if (!existsSync(destination)) {
+                    problems.push(`${where}: link to ${file} — no such file`);
+                    continue;
+                }
+                if (anchor &&
+                    destination.endsWith(".md") &&
+                    statSync(destination).isFile() &&
+                    !anchors(destination).has(anchor))
+                    problems.push(`${where}: link to ${file}#${anchor} — no such heading`);
+            }
+            if (!user)
+                return;
+            if (correction.test(line))
+                problems.push(`${where}: a correction mark on a user page`);
+            if (line.includes("~~"))
+                problems.push(`${where}: struck-out text on a user page`);
+            for (const found of line.match(id) ?? [])
+                problems.push(`${where}: internal id ${found} on a user page`);
+        });
+    }
+    return problems;
+};
+//# sourceMappingURL=markdown.js.map

package/dist/release/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/release/markdown.ts"],"names":[],"mappings":"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"}

package/dist/release/structure.d.ts

@@ -0,0 +1,16 @@
+/** The pages every tool has — the shared page set in cli-docs' STRUCTURE.md. */
+export declare const REQUIRED_PAGES: readonly ["index", "installation", "usage", "commands", "configuration", "troubleshooting", "security"];
+export type StructureRules = {
+    /** The docs folder, relative to `root`. */
+    docs?: string;
+    required?: readonly string[];
+    /** Pages in `meta.json` that are not files in the folder: `changelog` comes from the root. */
+    external?: readonly string[];
+};
+/**
+ * The docs folder against its `meta.json`: every listed page exists, every page is listed once,
+ * the required ones are there, and each page has exactly one `# heading`, its title. `README.md`
+ * is the contributors' index and stays out of the sidebar.
+ */
+export declare const structureProblems: (root: string, { docs, required, external }?: StructureRules) => string[];
+//# sourceMappingURL=structure.d.ts.map

package/dist/release/structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../../src/release/structure.ts"],"names":[],"mappings":"AAIA,gFAAgF;AAChF,eAAO,MAAM,cAAc,YACzB,OAAO,EACP,cAAc,EACd,OAAO,EACP,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,UAAU,CACF,CAAA;AAKV,MAAM,MAAM,cAAc,GAAG;IAC3B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,SACtB,MAAM,iCAC4D,cAAc,aA+CvF,CAAA"}

package/dist/release/structure.js

@@ -0,0 +1,74 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { withoutCode } from "./markdown.js";
+/** The pages every tool has — the shared page set in cli-docs' STRUCTURE.md. */
+export const REQUIRED_PAGES = [
+    "index",
+    "installation",
+    "usage",
+    "commands",
+    "configuration",
+    "troubleshooting",
+    "security",
+];
+// Fumadocs' own keys (fumadocs.dev/docs/page-conventions); the portal reads meta.json as it is.
+const META_KEYS = new Set(["title", "icon", "pages", "defaultOpen", "collapsible", "pagesIndex", "root"]);
+/**
+ * The docs folder against its `meta.json`: every listed page exists, every page is listed once,
+ * the required ones are there, and each page has exactly one `# heading`, its title. `README.md`
+ * is the contributors' index and stays out of the sidebar.
+ */
+export const structureProblems = (root, { docs = "docs", required = REQUIRED_PAGES, external = ["changelog"] } = {}) => {
+    const folder = join(root, docs);
+    const metaPath = join(folder, "meta.json");
+    if (!existsSync(metaPath))
+        return [`${docs}/meta.json: missing — it lists the pages in sidebar order`];
+    let meta;
+    try {
+        meta = JSON.parse(readFileSync(metaPath, "utf8"));
+    }
+    catch (error) {
+        return [`${docs}/meta.json: not JSON — ${error.message}`];
+    }
+    const problems = [];
+    for (const key of Object.keys(meta))
+        if (!META_KEYS.has(key))
+            problems.push(`${docs}/meta.json: "${key}" is not a Fumadocs key`);
+    const listed = Array.isArray(meta.pages) ? meta.pages.filter((page) => typeof page === "string") : [];
+    if (!Array.isArray(meta.pages))
+        problems.push(`${docs}/meta.json: "pages" must be a list`);
+    const pages = listed.filter((page) => !/^---.*---$/.test(page) && !/^\[.*\]\(.*\)$/.test(page));
+    const seen = new Set();
+    for (const page of pages) {
+        if (seen.has(page))
+            problems.push(`${docs}/meta.json: "${page}" is listed twice`);
+        seen.add(page);
+        if (external.includes(page))
+            continue;
+        if (!existsSync(join(folder, `${page}.md`)))
+            problems.push(`${docs}/meta.json: "${page}" — no ${docs}/${page}.md`);
+    }
+    for (const page of required)
+        if (!seen.has(page))
+            problems.push(`${docs}/meta.json: "${page}" is required and not listed`);
+    const files = readdirSync(folder).filter((name) => name.endsWith(".md") && name !== "README.md");
+    for (const file of files) {
+        const page = file.slice(0, -3);
+        if (!seen.has(page))
+            problems.push(`${docs}/${file}: not in meta.json — listed nowhere, so the portal never shows it`);
+        const text = readFileSync(join(folder, file), "utf8");
+        const titles = withoutCode(text)
+            .split("\n")
+            .filter((line) => /^# /.test(line)).length;
+        if (titles !== 1)
+            problems.push(`${docs}/${file}: ${titles} "# " headings — a page has exactly one, its title`);
+        const first = text
+            .replace(/^(\s*<!--[\s\S]*?-->)*/, "")
+            .split("\n")
+            .find((line) => line.trim() !== "");
+        if (titles === 1 && !first?.startsWith("# "))
+            problems.push(`${docs}/${file}: the "# " heading must come first`);
+    }
+    return problems;
+};
+//# sourceMappingURL=structure.js.map

package/dist/release/structure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.js","sourceRoot":"","sources":["../../src/release/structure.ts"],"names":[],"mappings":"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"}

package/dist/renderer.d.ts

@@ -0,0 +1,34 @@
+import { type Streams } from "./streams.js";
+/**
+ * What a renderer can be asked for. `auto` is not here on purpose: choosing between a person and a
+ * pipe is the caller's job and happens once, so a renderer can never be handed a mode it has to
+ * resolve.
+ */
+export declare const RENDER_FORMATS: readonly ["pretty", "json", "jsonl"];
+export type RenderFormat = (typeof RENDER_FORMATS)[number];
+export interface Renderer {
+    /** The one thing a caller asked for. In a machine mode this is the whole of stdout. */
+    result(value: unknown): void;
+    /** Each item on its own line. Only meaningful in `jsonl`; elsewhere it renders the whole list. */
+    stream(items: Iterable<unknown>): void;
+    note(message: string): void;
+    success(message: string): void;
+    warn(message: string): void;
+    failure(message: string): void;
+}
+export interface RendererOptions {
+    format: RenderFormat;
+    color: boolean;
+    streams?: Streams;
+    /** Drops `note`, `success` and `warn`. A failure is still said, and the result is untouched. */
+    quiet?: boolean;
+}
+/**
+ * **Every diagnostic goes to stderr, in every mode — pretty included.**
+ *
+ * The brief only requires that of the machine modes, but making it unconditional means §44 holds
+ * by construction instead of by a mode check somebody can forget. It also means piping human
+ * output still gives you the content and not the commentary.
+ */
+export declare const createRenderer: ({ format, color, streams, quiet, }: RendererOptions) => Renderer;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3D;;;;GAIG;AACH,eAAO,MAAM,cAAc,YAAI,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAU,CAAA;AAClE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAE1D,MAAM,WAAW,QAAQ;IACvB,uFAAuF;IACvF,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;IAC5B,kGAAkG;IAClG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IACtC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gGAAgG;IAChG,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,uCAKxB,eAAe,KAAG,QAyCpB,CAAA"}

package/dist/renderer.js

@@ -0,0 +1,55 @@
+import { renderPretty } from "./pretty.js";
+import { visibleControls } from "./sanitize.js";
+import { processStreams } from "./streams.js";
+/**
+ * What a renderer can be asked for. `auto` is not here on purpose: choosing between a person and a
+ * pipe is the caller's job and happens once, so a renderer can never be handed a mode it has to
+ * resolve.
+ */
+export const RENDER_FORMATS = ["pretty", "json", "jsonl"];
+/**
+ * **Every diagnostic goes to stderr, in every mode — pretty included.**
+ *
+ * The brief only requires that of the machine modes, but making it unconditional means §44 holds
+ * by construction instead of by a mode check somebody can forget. It also means piping human
+ * output still gives you the content and not the commentary.
+ */
+export const createRenderer = ({ format, color, streams = processStreams, quiet = false, }) => {
+    // Sanitised in every mode, not just `pretty`: a diagnostic goes to stderr, and stderr is read
+    // by a person whatever stdout was asked to be. The message is often the other side's own words.
+    const mark = (symbol, message) => format === "pretty" ? `${symbol} ${visibleControls(message)}` : visibleControls(message);
+    const say = (symbol) => (message) => {
+        if (!quiet)
+            streams.diagnostic(mark(symbol, message));
+    };
+    const diagnostics = {
+        note: say("·"),
+        success: say("✓"),
+        warn: say("!"),
+        failure: (message) => streams.diagnostic(mark("✗", message)),
+    };
+    if (format === "jsonl") {
+        return {
+            ...diagnostics,
+            result: (value) => streams.data(JSON.stringify(value)),
+            stream: (items) => {
+                for (const item of items)
+                    streams.data(JSON.stringify(item));
+            },
+        };
+    }
+    if (format === "pretty") {
+        return {
+            ...diagnostics,
+            result: (value) => streams.data(renderPretty(value, { color })),
+            stream: (items) => streams.data(renderPretty([...items], { color })),
+        };
+    }
+    // json — exactly one deterministic value, and nothing else, ever.
+    return {
+        ...diagnostics,
+        result: (value) => streams.data(JSON.stringify(value)),
+        stream: (items) => streams.data(JSON.stringify([...items])),
+    };
+};
+//# sourceMappingURL=renderer.js.map

package/dist/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAgB,MAAM,cAAc,CAAA;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAU,CAAA;AAsBlE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,EAC7B,MAAM,EACN,KAAK,EACL,OAAO,GAAG,cAAc,EACxB,KAAK,GAAG,KAAK,GACG,EAAY,EAAE;IAC9B,8FAA8F;IAC9F,gGAAgG;IAChG,MAAM,IAAI,GAAG,CAAC,MAAc,EAAE,OAAe,EAAE,EAAE,CAC/C,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAA;IAE1F,MAAM,GAAG,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,CAAC,OAAe,EAAE,EAAE;QAClD,IAAI,CAAC,KAAK;YAAE,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACvD,CAAC,CAAA;IAED,MAAM,WAAW,GAAG;QAClB,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC;QACd,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC;QACjB,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC;QACd,OAAO,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;KACrE,CAAA;IAED,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACvB,OAAO;YACL,GAAG,WAAW;YACd,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACtD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;gBAChB,KAAK,MAAM,IAAI,IAAI,KAAK;oBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;YAC9D,CAAC;SACF,CAAA;IACH,CAAC;IAED,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,OAAO;YACL,GAAG,WAAW;YACd,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/D,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,GAAG,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;SACrE,CAAA;IACH,CAAC;IAED,kEAAkE;IAClE,OAAO;QACL,GAAG,WAAW;QACd,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACtD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;KAC5D,CAAA;AACH,CAAC,CAAA"}

package/dist/retry.d.ts

@@ -0,0 +1,27 @@
+import type { ErrorCode } from "./errors.js";
+export interface RetryConfig {
+    /** Attempts after the first. One means two attempts in total. */
+    retries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    /** Beyond this we stop waiting and hand back a structured error instead of blocking. */
+    maxRetryAfterMs: number;
+}
+export declare const DEFAULT_RETRY: RetryConfig;
+/**
+ * Full jitter: the wait is uniform over `[0, min(cap, base · 2^n))`. Picking the exponential value
+ * itself synchronizes every client that failed at the same moment, which is the stampede the
+ * backoff exists to avoid.
+ *
+ * `attempt` is the attempt that just failed, counting from 1.
+ */
+export declare const backoffMs: (attempt: number, config: RetryConfig, random: () => number) => number;
+/**
+ * The three outcomes where nothing came back, and so there is nothing to classify.
+ *
+ * **This says the attempt failed without an answer — never that the operation is safe to repeat.**
+ * A request that died after leaving may well have been carried out, which is why a write gets
+ * `outcome_unknown` rather than a retry.
+ */
+export declare const isTransportFailure: (code: ErrorCode) => boolean;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,wFAAwF;IACxF,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,eAAO,MAAM,aAAa,EAAE,WAK3B,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,YAAa,MAAM,UAAU,WAAW,UAAU,MAAM,MAAM,KAAG,MAGtF,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,SAAU,SAAS,KAAG,OACmB,CAAA"}

package/dist/retry.js

@@ -0,0 +1,26 @@
+export const DEFAULT_RETRY = {
+    retries: 1,
+    baseDelayMs: 250,
+    maxDelayMs: 10_000,
+    maxRetryAfterMs: 30_000,
+};
+/**
+ * Full jitter: the wait is uniform over `[0, min(cap, base · 2^n))`. Picking the exponential value
+ * itself synchronizes every client that failed at the same moment, which is the stampede the
+ * backoff exists to avoid.
+ *
+ * `attempt` is the attempt that just failed, counting from 1.
+ */
+export const backoffMs = (attempt, config, random) => {
+    const ceiling = Math.min(config.maxDelayMs, config.baseDelayMs * 2 ** (attempt - 1));
+    return Math.round(random() * ceiling);
+};
+/**
+ * The three outcomes where nothing came back, and so there is nothing to classify.
+ *
+ * **This says the attempt failed without an answer — never that the operation is safe to repeat.**
+ * A request that died after leaving may well have been carried out, which is why a write gets
+ * `outcome_unknown` rather than a retry.
+ */
+export const isTransportFailure = (code) => code === "timeout" || code === "network_error" || code === "cancelled";
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,aAAa,GAAgB;IACxC,OAAO,EAAE,CAAC;IACV,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,MAAM;IAClB,eAAe,EAAE,MAAM;CACxB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAe,EAAE,MAAmB,EAAE,MAAoB,EAAU,EAAE;IAC9F,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,WAAW,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAA;IACpF,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,CAAA;AACvC,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,IAAe,EAAW,EAAE,CAC7D,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,eAAe,IAAI,IAAI,KAAK,WAAW,CAAA"}