@wirecat/cli-base 0.0.0-stage → 0.21.0

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":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAE5D,yFAAyF;AACzF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAU,CAAA;AAEvH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,QAA2B,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,SAAS,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,CAAA;AAEjH,MAAM,eAAe,GAAG,sEAAsE,CAAA;AAU9F;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,IAAY,EACZ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAA2D,EACxG,EAAE;IACF,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAA;IACzB,IAAI,OAA2B,CAAA;IAC/B,IAAI,WAAW,GAAG,IAAI,GAAG,EAAU,CAAA;IACnC,IAAI,KAAK,GAAG,IAAI,CAAA;IAEhB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACvC,MAAM,KAAK,GAAG,gBAAgB,KAAK,GAAG,CAAC,EAAE,CAAA;QACzC,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YACvB,WAAW,GAAG,IAAI,GAAG,EAAE,CAAA;YACvB,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;gBAC3B,IAAI,OAAO;oBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,UAAU,0BAA0B,OAAO,mBAAmB,CAAC,CAAA;qBACnG,IAAI,CAAC,KAAK;oBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,UAAU,2BAA2B,CAAC,CAAA;YACrF,CAAC;iBAAM,CAAC;gBACN,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACxC,IAAI,CAAC,KAAK;oBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,IAAI,sCAAsC,CAAC,CAAA;qBAC9E,CAAC;oBACJ,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,KAAK,CAAA;oBACrC,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;wBAChF,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,IAAI,oBAAoB,CAAC,CAAA;oBACvD,IAAI,OAAO,IAAI,KAAK,IAAI,OAAO,KAAK,OAAO;wBACzC,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,wBAAwB,OAAO,uBAAuB,OAAO,EAAE,CAAC,CAAA;gBAC1F,CAAC;YACH,CAAC;YACD,KAAK,GAAG,KAAK,CAAA;YACb,OAAM;QACR,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YAC7B,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,OAAO,oBAAoB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YAC9G,IAAI,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,OAAO,eAAe,OAAO,GAAG,CAAC,CAAA;YAC3F,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAC1B,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,iBAAiB,KAAK,6BAA6B,CAAC,CAAA;IACtH,CAAC,CAAC,CAAA;IAEF,IAAI,OAAO,IAAI,KAAK;QAAE,QAAQ,CAAC,IAAI,CAAC,gCAAgC,OAAO,EAAE,CAAC,CAAA;IAC9E,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED,0GAA0G;AAC1G,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAe,EAAE,EAAE,CACtC,OAAO;KACJ,OAAO,CAAC,0BAA0B,EAAE,IAAI,CAAC;KACzC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;KACvB,WAAW,EAAE;KACb,OAAO,CAAC,0BAA0B,EAAE,EAAE,CAAC;KACvC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;AAEvB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,EAAE,CAC1C,IAAI;KACD,OAAO,CAAC,wCAAwC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;KAC1F,OAAO,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAA;AAE7D,gGAAgG;AAChG,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,EAAE;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC5B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAA;IACjC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;IACxC,WAAW,CAAC,IAAI,CAAC;SACd,KAAK,CAAC,IAAI,CAAC;SACX,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;QACzB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAM;QACpC,MAAM,OAAO,GAAG,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QACpE,IAAI,OAAO,KAAK,SAAS;YAAE,OAAM;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,CAAA;QAC1B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAClC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAA;QAC1B,OAAO,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAA;IACpD,CAAC,CAAC,CAAA;IACJ,KAAK,MAAM,CAAC,EAAE,IAAI,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC3F,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED,sFAAsF;AACtF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAiB,EAAE,IAAI,GAAwB,IAAI,GAAG,EAAE,EAAY,EAAE,CAClG,UAAU,CAAC,SAAS,CAAC;IACnB,CAAC,CAAC,WAAW,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QAChE,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,CAAA;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QACxC,4FAA4F;QAC5F,sFAAsF;QACtF,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAA;QACvD,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,EAAE,WAAW,EAAE;YAAE,OAAO,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACjF,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IACpE,CAAC,CAAC;IACJ,CAAC,CAAC,EAAE,CAAA;AAaR,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,IAAY,EACZ,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,GAAG,GAAG,EAAE,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB,EAAE,QAAQ,GAAG,GAAG,EAAE,CAAC,KAAK,EAAa,EAC3G,EAAE;IACF,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAA;IACzB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAA;IAC5C,MAAM,OAAO,GAAG,CAAC,IAAY,EAAE,EAAE;QAC/B,IAAI,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC3B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA;YAC7C,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACxB,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC,CAAA;IAED,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;QAC3B,WAAW,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;aACpC,KAAK,CAAC,IAAI,CAAC;aACX,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YACvB,MAAM,KAAK,GAAG,GAAG,IAAI,IAAI,KAAK,GAAG,CAAC,EAAE,CAAA;YACpC,KAAK,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,2CAA2C,CAAC,EAAE,CAAC;gBACpF,IAAI,CAAC,MAAM,IAAI,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC;oBAAE,SAAQ;gBAC5D,MAAM,CAAC,IAAI,GAAG,EAAE,EAAE,MAAM,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;gBACjE,MAAM,WAAW,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAA;gBACrE,IAAI,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;oBAAE,SAAQ;gBACzC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;oBAC7B,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,IAAI,iBAAiB,CAAC,CAAA;oBACzD,SAAQ;gBACV,CAAC;gBACD,IACE,MAAM;oBACN,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC;oBAC3B,QAAQ,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE;oBAC9B,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;oBAEjC,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,IAAI,IAAI,MAAM,oBAAoB,CAAC,CAAA;YAC1E,CAAC;YAED,IAAI,CAAC,IAAI;gBAAE,OAAM;YACjB,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,oCAAoC,CAAC,CAAA;YACtF,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,kCAAkC,CAAC,CAAA;YAClF,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,iBAAiB,KAAK,iBAAiB,CAAC,CAAA;QAC1G,CAAC,CAAC,CAAA;IACN,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA"}

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":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C,gFAAgF;AAChF,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,OAAO;IACP,cAAc;IACd,OAAO;IACP,UAAU;IACV,eAAe;IACf,iBAAiB;IACjB,UAAU;CACF,CAAA;AAEV,gGAAgG;AAChG,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;AAUzG;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,IAAY,EACZ,EAAE,IAAI,GAAG,MAAM,EAAE,QAAQ,GAAG,cAAc,EAAE,QAAQ,GAAG,CAAC,WAAW,CAAC,EAAE,GAAmB,EAAE,EAC3F,EAAE;IACF,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;IAC1C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,CAAC,GAAG,IAAI,2DAA2D,CAAC,CAAA;IAEtG,IAAI,IAA6B,CAAA;IACjC,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAA4B,CAAA;IAC9E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,GAAG,IAAI,0BAA2B,KAAe,CAAC,OAAO,EAAE,CAAC,CAAA;IACtE,CAAC;IAED,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QACjC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,gBAAgB,GAAG,yBAAyB,CAAC,CAAA;IAC7F,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IACrH,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,oCAAoC,CAAC,CAAA;IAE1F,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IAC/F,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,gBAAgB,IAAI,mBAAmB,CAAC,CAAA;QACjF,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACd,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAQ;QACrC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,gBAAgB,IAAI,UAAU,IAAI,IAAI,IAAI,KAAK,CAAC,CAAA;IACpH,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,QAAQ;QACzB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,gBAAgB,IAAI,8BAA8B,CAAC,CAAA;IAE/F,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,WAAW,CAAC,CAAA;IAChG,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QAC9B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YACjB,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,mEAAmE,CAAC,CAAA;QACnG,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAA;QACrD,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC;aAC7B,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAA;QAC5C,IAAI,MAAM,KAAK,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,KAAK,MAAM,oDAAoD,CAAC,CAAA;QAC/G,MAAM,KAAK,GAAG,IAAI;aACf,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC;aACrC,KAAK,CAAC,IAAI,CAAC;aACX,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;QACrC,IAAI,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,oCAAoC,CAAC,CAAA;IAClH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA"}

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/result-fields.d.ts

@@ -0,0 +1,4 @@
+export declare const fieldsOf: (value: string) => string[];
+/** Projects item data while retaining the list envelope and operation identifiers. */
+export declare const projectFields: (value: unknown, fields: readonly string[]) => unknown;
+//# sourceMappingURL=result-fields.d.ts.map

package/dist/result-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-fields.d.ts","sourceRoot":"","sources":["../src/result-fields.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,QAAQ,UAAW,MAAM,KAAG,MAAM,EAI9C,CAAA;AA6BD,sFAAsF;AACtF,eAAO,MAAM,aAAa,UAAW,OAAO,UAAU,SAAS,MAAM,EAAE,KAAG,OAMzE,CAAA"}

package/dist/result-fields.js

@@ -0,0 +1,56 @@
+import { CliError } from "./errors.js";
+const forbidden = new Set(["__proto__", "prototype", "constructor"]);
+const validate = (paths) => {
+    if (paths.length === 0 ||
+        paths.length > 128 ||
+        paths.some((path) => path.length > 256 ||
+            !/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$/.test(path) ||
+            path.split(".").some((part) => forbidden.has(part))))
+        throw new CliError("validation_error", "--fields takes comma-separated field paths, for example id,locator,text");
+};
+export const fieldsOf = (value) => {
+    const paths = value.split(",").map((one) => one.trim());
+    validate(paths);
+    return [...new Set(paths)];
+};
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const select = (value, paths, item = false) => {
+    if (!object(value))
+        return value;
+    const fields = item ? paths.map((path) => (path.startsWith("items.") ? path.slice(6) : path)) : paths;
+    const result = {};
+    for (const path of fields.filter((one) => !fields.some((parent) => parent !== one && one.startsWith(`${parent}.`)))) {
+        const parts = path.split(".");
+        let found = value;
+        for (const part of parts) {
+            if (!object(found) || !Object.hasOwn(found, part)) {
+                found = undefined;
+                break;
+            }
+            found = found[part];
+        }
+        if (found === undefined)
+            continue;
+        let target = result;
+        for (const part of parts.slice(0, -1)) {
+            if (!object(target[part]))
+                target[part] = {};
+            target = target[part];
+        }
+        target[parts.at(-1)] = found;
+    }
+    for (const name of ["operationId", "sendId"])
+        if (Object.hasOwn(value, name))
+            result[name] = value[name];
+    return result;
+};
+/** Projects item data while retaining the list envelope and operation identifiers. */
+export const projectFields = (value, fields) => {
+    validate(fields);
+    if (Array.isArray(value))
+        return value.map((item) => select(item, fields, true));
+    if (object(value) && Array.isArray(value.items))
+        return { ...value, items: value.items.map((item) => select(item, fields, true)) };
+    return select(value, fields, object(value) && !Object.hasOwn(value, "items"));
+};
+//# sourceMappingURL=result-fields.js.map

package/dist/result-fields.js.map

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

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"}

package/dist/sanitize.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Text that came from Braze or from a customer's input file, made safe to display.
+ *
+ * A campaign name, a catalog title and a user attribute are all edited somewhere we do not
+ * control and handed back to us as data. A terminal executes what it is given: `\x1b[2K\x1b[1G`
+ * clears the line and returns the cursor, so a campaign name can overwrite output this tool
+ * already printed. Braze's own error messages reach a terminal the same way (`SEC-2`).
+ *
+ * CLI machine output preserves original strings as a contract with scripts. JSON escapes C0
+ * characters but leaves C1 and other invisible Unicode raw; display and agent text need this guard.
+ */
+/**
+ * Control characters become visible rather than disappearing. A reader has to know the value
+ * contained something strange; an audit that silently drops bytes is worse than one that shows
+ * them.
+ *
+ * `\t` and `\n` survive, because a table and a multi-line field are built out of them.
+ */
+export declare const visibleControls: (text: string) => string;
+/**
+ * For a value that must stay on one line: a name, a title, a file name, a URL. A newline in a
+ * sender's name would otherwise print as a line of its own, indistinguishable from real output.
+ */
+export declare const singleLine: (text: string) => string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAwBH;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,SAAU,MAAM,KAAG,MAQ9C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,SAAU,MAAM,KAAG,MAA6D,CAAA"}

package/dist/sanitize.js

@@ -0,0 +1,52 @@
+/**
+ * Text that came from Braze or from a customer's input file, made safe to display.
+ *
+ * A campaign name, a catalog title and a user attribute are all edited somewhere we do not
+ * control and handed back to us as data. A terminal executes what it is given: `\x1b[2K\x1b[1G`
+ * clears the line and returns the cursor, so a campaign name can overwrite output this tool
+ * already printed. Braze's own error messages reach a terminal the same way (`SEC-2`).
+ *
+ * CLI machine output preserves original strings as a contract with scripts. JSON escapes C0
+ * characters but leaves C1 and other invisible Unicode raw; display and agent text need this guard.
+ */
+/**
+ * C0 minus tab and newline, DEL, and C1 — which xterm honours as escapes in its 8-bit form. Then
+ * the direction overrides and isolates, which reorder what follows them (`invoice\u202efdp.exe`
+ * reads as a PDF), and the invisible zero-width space and direction marks.
+ *
+ * U+200C and U+200D stay: Persian and Indic text need the non-joiner, and every multi-person emoji
+ * is built with the joiner.
+ */
+const CONTROL = 
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the whole point
+/[\u0000-\u0008\u000B-\u001F\u007F-\u009F\u200B\u200E\u200F\u202A-\u202E\u2066-\u2069\uFEFF\u{E0000}-\u{E007F}]/gu;
+const SUBDIVISION_FLAG = /\u{1F3F4}[\u{E0061}-\u{E007A}]{2}[\u{E0030}-\u{E0039}\u{E0061}-\u{E007A}]{1,3}\u{E007F}/gu;
+const LINE_BREAKS = /[\t\n\u2028\u2029]/g;
+const escaped = (c) => {
+    const code = c.codePointAt(0) ?? 0;
+    if (code > 0xffff)
+        return `\\u{${code.toString(16)}}`;
+    return code > 0xff ? `\\u${code.toString(16).padStart(4, "0")}` : `\\x${code.toString(16).padStart(2, "0")}`;
+};
+/**
+ * Control characters become visible rather than disappearing. A reader has to know the value
+ * contained something strange; an audit that silently drops bytes is worse than one that shows
+ * them.
+ *
+ * `\t` and `\n` survive, because a table and a multi-line field are built out of them.
+ */
+export const visibleControls = (text) => {
+    let at = 0;
+    let result = "";
+    for (const flag of text.matchAll(SUBDIVISION_FLAG)) {
+        result += text.slice(at, flag.index).replace(CONTROL, escaped) + flag[0];
+        at = flag.index + flag[0].length;
+    }
+    return result + text.slice(at).replace(CONTROL, escaped);
+};
+/**
+ * For a value that must stay on one line: a name, a title, a file name, a URL. A newline in a
+ * sender's name would otherwise print as a line of its own, indistinguishable from real output.
+ */
+export const singleLine = (text) => visibleControls(text).replace(LINE_BREAKS, escaped);
+//# sourceMappingURL=sanitize.js.map