@forumulate/cli 0.8.0 → 0.10.0

package/dist/validate.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALIDATE_HELP = exports.SCHEMA_VERSION = void 0;
+exports.collectDocuments = collectDocuments;
+exports.runValidateCommand = runValidateCommand;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const yaml_1 = require("yaml");
+const http_1 = require("./api/http");
+const api_base_1 = require("./api-base");
+const credentials_1 = require("./credentials");
+const exit_codes_1 = require("./exit-codes");
+const reserved_1 = require("./publish/reserved");
+const frontmatter_1 = require("./publish/frontmatter");
+/**
+ * `forumulate validate <dir>` (FMU-D11): check a folder's configuration
+ * against the published schemas before publishing it.
+ *
+ * Reads the manifest (`forumulate.yaml`), the front matter of every Markdown
+ * file, and any JSON/YAML file whose `$schema` names one of our schemas
+ * (`https://forumulate.com/schemas/<date>/<name>.json`) — a theme kept in
+ * git, a site config — and sends them to `POST /schemas/<date>/validate`.
+ * The server holds the zod schemas the API validates writes with, so this
+ * answers exactly what the publish would, did-you-mean included, without the
+ * CLI carrying a second copy of every schema. No token needed.
+ */
+exports.SCHEMA_VERSION = '2026-12-01';
+const SCHEMA_NAMES = ['site-config', 'space-theme', 'forumulate-yaml', 'front-matter', 'forum-category'];
+const SCHEMA_URL = /\/schemas\/(\d{4}-\d{2}-\d{2})\/([a-z-]+)\.json$/;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache']);
+const MAX_FILES = 5000;
+const BATCH = 400;
+exports.VALIDATE_HELP = `forumulate validate — check a folder's configuration against the published schemas
+
+Usage:
+  forumulate validate [dir] [--json]
+
+Checks forumulate.yaml, every Markdown file's front matter, and any JSON or YAML
+file whose "$schema" names https://forumulate.com/schemas/${exports.SCHEMA_VERSION}/<name>.json
+(site-config, space-theme, forumulate-yaml, front-matter, forum-category).
+Each problem is printed with its file, key path and did-you-mean. Unknown
+front matter keys are warnings (they are ignored on publish); everything else
+is an error.
+
+${exit_codes_1.EXIT_CODES_HELP}
+  (validate: 0 when every document is valid, 2 when one is not)`;
+function walk(dir, out = []) {
+    for (const name of (0, node_fs_1.readdirSync)(dir).sort()) {
+        if (out.length >= MAX_FILES)
+            break;
+        if (SKIP_DIRS.has(name) || name.startsWith('.'))
+            continue;
+        const p = (0, node_path_1.join)(dir, name);
+        if ((0, node_fs_1.statSync)(p).isDirectory())
+            walk(p, out);
+        else
+            out.push(p);
+    }
+    return out;
+}
+/** The documents a folder holds, each with the schema it is checked against. */
+function collectDocuments(root, files, problems) {
+    const docs = [];
+    for (const path of files.list(root)) {
+        const rel = (0, node_path_1.relative)(root, path) || path;
+        const base = rel.split(/[\\/]/).pop() ?? rel;
+        const ext = (0, node_path_1.extname)(base).toLowerCase();
+        try {
+            if (reserved_1.MANIFEST_NAMES.includes(base) && !rel.includes('/') && !rel.includes('\\')) {
+                const text = files.read(path);
+                docs.push({ schema: 'forumulate-yaml', document: ext === '.json' ? JSON.parse(text) : (0, yaml_1.parse)(text), source: rel });
+            }
+            else if (ext === '.md' || ext === '.mdx') {
+                const { data, raw } = (0, frontmatter_1.splitFront)(files.read(path));
+                if (raw !== null)
+                    docs.push({ schema: 'front-matter', document: data, source: rel });
+            }
+            else if (ext === '.json' || ext === '.yaml' || ext === '.yml') {
+                const text = files.read(path);
+                if (!text.includes('/schemas/'))
+                    continue;
+                const doc = (ext === '.json' ? JSON.parse(text) : (0, yaml_1.parse)(text));
+                const m = typeof doc?.$schema === 'string' ? SCHEMA_URL.exec(doc.$schema) : null;
+                if (!m || !SCHEMA_NAMES.includes(m[2]))
+                    continue;
+                if (m[1] !== exports.SCHEMA_VERSION)
+                    problems.push(`${rel}: names schemas of ${m[1]}; this CLI checks ${exports.SCHEMA_VERSION}.`);
+                const { $schema: _s, ...rest } = doc;
+                docs.push({ schema: m[2], document: rest, source: rel });
+            }
+        }
+        catch (e) {
+            problems.push(`${rel}: ${e.message}`);
+        }
+    }
+    return docs;
+}
+async function runValidateCommand(argv, deps) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        deps.out(exports.VALIDATE_HELP);
+        return exit_codes_1.EXIT.OK;
+    }
+    const json = argv.includes('--json');
+    const positionals = argv.filter((a) => !a.startsWith('--'));
+    if (positionals.length > 1) {
+        deps.err('Usage: forumulate validate [dir] [--json]');
+        return exit_codes_1.EXIT.USAGE;
+    }
+    const root = (0, node_path_1.resolve)(positionals[0] ?? '.');
+    const files = deps.files ?? {
+        list: (d) => walk(d),
+        read: (p) => (0, node_fs_1.readFileSync)(p, 'utf8'),
+    };
+    const problems = [];
+    let docs;
+    try {
+        docs = collectDocuments(root, files, problems);
+    }
+    catch (e) {
+        deps.err(`Cannot read ${root}: ${e.message}`);
+        return exit_codes_1.EXIT.USAGE;
+    }
+    const env = deps.env ?? process.env;
+    const baseUrl = (0, api_base_1.apiBaseFromEnv)(env);
+    const http = deps.http ??
+        new http_1.Http({
+            baseUrl,
+            token: (0, credentials_1.resolveToken)(baseUrl, env, deps.flagToken),
+            userAgent: deps.userAgent ?? '@forumulate/cli',
+        });
+    const results = [];
+    try {
+        for (let i = 0; i < docs.length; i += BATCH) {
+            const res = await http.send({
+                method: 'POST',
+                path: `/schemas/${exports.SCHEMA_VERSION}/validate`,
+                body: { documents: docs.slice(i, i + BATCH) },
+            });
+            results.push(...(res.data.results ?? []));
+        }
+    }
+    catch (e) {
+        deps.err(`Validation failed: ${e.message}`);
+        return (0, exit_codes_1.exitCodeForError)(e);
+    }
+    const invalid = results.filter((r) => !r.valid).length + problems.length;
+    if (json) {
+        deps.out(JSON.stringify({ root, checked: results.length, invalid, problems, results }, null, 2));
+    }
+    else {
+        for (const p of problems)
+            deps.out(`ERROR    ${p}`);
+        for (const r of results)
+            for (const i of r.issues) {
+                const where = `${r.source ?? r.schema}${i.path ? ` ${i.path}` : ''}`;
+                deps.out(`${i.severity === 'error' ? 'ERROR  ' : 'WARNING'}  ${where}: ${i.message}`);
+                if (i.hint)
+                    deps.out(`         ${i.hint}`);
+            }
+        deps.out(`${results.length} document(s) checked, ${invalid} invalid` +
+            (docs.length === 0 ? ' (no forumulate.yaml, front matter or $schema file found)' : '') +
+            '.');
+    }
+    return invalid > 0 ? exit_codes_1.EXIT.USAGE : exit_codes_1.EXIT.OK;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Kept in step with package.json by `cli-version.test.ts` — they had drifted to
+ * 0.1.0 and 0.2.1, so `--version` reported a release that was never published.
+ * Its own module so `api list` can name the CLI that bundled its operation
+ * list without importing `run.ts` (which imports it).
+ */
+export declare const VERSION = "0.10.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,OAAO,WAAW,CAAC"}

package/dist/version.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+/**
+ * Kept in step with package.json by `cli-version.test.ts` — they had drifted to
+ * 0.1.0 and 0.2.1, so `--version` reported a release that was never published.
+ * Its own module so `api list` can name the CLI that bundled its operation
+ * list without importing `run.ts` (which imports it).
+ */
+exports.VERSION = '0.10.0';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACU,QAAA,OAAO,GAAG,QAAQ,CAAC"}

package/dist/whoami.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `forumulate whoami` and `forumulate auth status` (FMU-D06).
+ *
+ * `whoami` printed a name and an email. The Referalli integrator had a PAT in
+ * `FORUMULATE_TOKEN`, an older one in `credentials.json` and a third in CI,
+ * plus `FORUMULATE_BASE` exported from a tutorial — a variable nothing reads —
+ * and spent an afternoon on a 401 that any of the four could have caused. This
+ * prints the token's source, which PAT it is (id, name, last four characters),
+ * when it expires, everything it is narrowed to, and the API it was sent to;
+ * and it names every `FORUMULATE_*` variable in the environment that nothing
+ * reads, with the one it was probably meant to be.
+ */
+/** Every variable the CLI, the SDK and the MCP server read. */
+export declare const KNOWN_ENV: readonly ["FORUMULATE_TOKEN", "FORUMULATE_URL", "FORUMULATE_API_URL", "FORUMULATE_ORG", "FORUMULATE_SPACE", "FORUMULATE_LIBRARY", "FORUMULATE_API_VERSION", "FORUMULATE_CONFIG_DIR", "FORUMULATE_MCP", "FORUMULATE_MCP_URL"];
+/** `FORUMULATE_*` names nothing reads, each with its likely meaning (or none). */
+export declare function unknownEnv(env: NodeJS.ProcessEnv): {
+    name: string;
+    didYouMean?: string;
+}[];
+/** The warning lines for unknown variables — printed by every command, on stderr. */
+export declare function envWarnings(env: NodeJS.ProcessEnv): string[];
+export interface WhoamiDeps {
+    out: (l: string) => void;
+    err: (l: string) => void;
+    env: NodeJS.ProcessEnv;
+    baseUrl?: string;
+    /** `--token`, when given. */
+    flagToken?: string;
+    /** GET /auth/me with the resolved token (injected for tests). */
+    me: () => Promise<{
+        user: {
+            id: string;
+            name: string;
+            email: string;
+        };
+        token?: Record<string, unknown>;
+    }>;
+}
+export declare const WHOAMI_HELP = "forumulate whoami \u2014 who the CLI is acting as, and with which token\n\nUsage:\n  forumulate whoami [--json] [--token <pat>]\n  forumulate auth status [--json]          the same report, for scripts\n\nPrints:\n  user          name, email and id\n  token source  --token flag | FORUMULATE_TOKEN | credentials.json (with its path)\n  token         the PAT's id, name, last four characters, created, expires\n  narrowed to   scopes, spaces, capabilities, constraints\n  api           the API base the token was sent to (FORUMULATE_API_URL, FORUMULATE_URL\n                or the default)\n  warnings      every FORUMULATE_* variable nothing reads, with the one it was\n                probably meant to be (FORUMULATE_BASE \u2192 FORUMULATE_URL)\n\nPrecedence: --token beats FORUMULATE_TOKEN beats the token `forumulate login` stored\nfor this API. Guide: https://forumulate.com/guides/api-tokens-and-scopes\n\nExit status:\n  0  ok          1  failed (verification mismatch, doctor FAIL)\n  2  usage       3  auth (no token, 401, token not allowed)\n  4  not found   5  conflict (409/412, edited in the studio since your last publish)\n  124 --wait timed out (the job keeps running; with --wait, a failed job is 1)";
+export declare function runWhoami(json: boolean, deps: WhoamiDeps): Promise<number>;
+//# sourceMappingURL=whoami.d.ts.map

package/dist/whoami.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whoami.d.ts","sourceRoot":"","sources":["../src/whoami.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,SAAS,8NAWZ,CAAC;AAkCX,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,CAY1F;AAED,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,EAAE,CAK5D;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,EAAE,EAAE,MAAM,OAAO,CAAC;QAChB,IAAI,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QAClD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACjC,CAAC,CAAC;CACJ;AAED,eAAO,MAAM,WAAW,osCAmBL,CAAC;AAEpB,wBAAsB,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAqEhF"}

package/dist/whoami.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WHOAMI_HELP = exports.KNOWN_ENV = void 0;
+exports.unknownEnv = unknownEnv;
+exports.envWarnings = envWarnings;
+exports.runWhoami = runWhoami;
+const api_base_1 = require("./api-base");
+const credentials_1 = require("./credentials");
+const exit_codes_1 = require("./exit-codes");
+/**
+ * `forumulate whoami` and `forumulate auth status` (FMU-D06).
+ *
+ * `whoami` printed a name and an email. The Referalli integrator had a PAT in
+ * `FORUMULATE_TOKEN`, an older one in `credentials.json` and a third in CI,
+ * plus `FORUMULATE_BASE` exported from a tutorial — a variable nothing reads —
+ * and spent an afternoon on a 401 that any of the four could have caused. This
+ * prints the token's source, which PAT it is (id, name, last four characters),
+ * when it expires, everything it is narrowed to, and the API it was sent to;
+ * and it names every `FORUMULATE_*` variable in the environment that nothing
+ * reads, with the one it was probably meant to be.
+ */
+/** Every variable the CLI, the SDK and the MCP server read. */
+exports.KNOWN_ENV = [
+    'FORUMULATE_TOKEN',
+    'FORUMULATE_URL',
+    'FORUMULATE_API_URL',
+    'FORUMULATE_ORG',
+    'FORUMULATE_SPACE',
+    'FORUMULATE_LIBRARY',
+    'FORUMULATE_API_VERSION',
+    'FORUMULATE_CONFIG_DIR',
+    'FORUMULATE_MCP',
+    'FORUMULATE_MCP_URL',
+];
+/** Spellings people reach for, mapped to the variable they meant. */
+const ALIASES = {
+    FORUMULATE_BASE: 'FORUMULATE_URL',
+    FORUMULATE_BASE_URL: 'FORUMULATE_URL',
+    FORUMULATE_HOST: 'FORUMULATE_URL',
+    FORUMULATE_SITE: 'FORUMULATE_URL',
+    FORUMULATE_ENDPOINT: 'FORUMULATE_API_URL',
+    FORUMULATE_API: 'FORUMULATE_API_URL',
+    FORUMULATE_API_BASE: 'FORUMULATE_API_URL',
+    FORUMULATE_PAT: 'FORUMULATE_TOKEN',
+    FORUMULATE_API_KEY: 'FORUMULATE_TOKEN',
+    FORUMULATE_KEY: 'FORUMULATE_TOKEN',
+    FORUMULATE_ACCESS_TOKEN: 'FORUMULATE_TOKEN',
+    FORUMULATE_ORGANIZATION: 'FORUMULATE_ORG',
+    FORUMULATE_ORG_ID: 'FORUMULATE_ORG',
+    FORUMULATE_SPACE_ID: 'FORUMULATE_SPACE',
+    FORUMULATE_VERSION: 'FORUMULATE_API_VERSION',
+};
+function distance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= a.length; i++)
+        for (let j = 1; j <= b.length; j++)
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    return d[a.length][b.length];
+}
+/** `FORUMULATE_*` names nothing reads, each with its likely meaning (or none). */
+function unknownEnv(env) {
+    const known = new Set(exports.KNOWN_ENV);
+    return Object.keys(env)
+        .filter((k) => k.startsWith('FORUMULATE_') && !known.has(k))
+        .sort()
+        .map((name) => {
+        if (ALIASES[name])
+            return { name, didYouMean: ALIASES[name] };
+        const best = [...known]
+            .map((k) => ({ k, d: distance(name, k) }))
+            .sort((x, y) => x.d - y.d)[0];
+        return best && best.d <= 4 ? { name, didYouMean: best.k } : { name };
+    });
+}
+/** The warning lines for unknown variables — printed by every command, on stderr. */
+function envWarnings(env) {
+    return unknownEnv(env).map((u) => `warning: ${u.name} is not read by forumulate${u.didYouMean ? `; did you mean ${u.didYouMean}?` : '.'}`);
+}
+exports.WHOAMI_HELP = `forumulate whoami — who the CLI is acting as, and with which token
+
+Usage:
+  forumulate whoami [--json] [--token <pat>]
+  forumulate auth status [--json]          the same report, for scripts
+
+Prints:
+  user          name, email and id
+  token source  --token flag | FORUMULATE_TOKEN | credentials.json (with its path)
+  token         the PAT's id, name, last four characters, created, expires
+  narrowed to   scopes, spaces, capabilities, constraints
+  api           the API base the token was sent to (FORUMULATE_API_URL, FORUMULATE_URL
+                or the default)
+  warnings      every FORUMULATE_* variable nothing reads, with the one it was
+                probably meant to be (FORUMULATE_BASE → FORUMULATE_URL)
+
+Precedence: --token beats FORUMULATE_TOKEN beats the token \`forumulate login\` stored
+for this API. Guide: https://forumulate.com/guides/api-tokens-and-scopes
+
+${exit_codes_1.EXIT_CODES_HELP}`;
+async function runWhoami(json, deps) {
+    const apiBase = deps.baseUrl ?? (0, api_base_1.apiBaseFromEnv)(deps.env);
+    const where = (0, credentials_1.resolveTokenSource)(apiBase, deps.env, deps.flagToken);
+    const warnings = unknownEnv(deps.env);
+    const report = {
+        apiBase,
+        tokenSource: where.source,
+        ...(where.path ? { credentialsPath: where.path } : {}),
+        warnings,
+    };
+    let code = exit_codes_1.EXIT.OK;
+    if (where.source === 'none') {
+        report.error = { message: 'No token: run `forumulate login`, set FORUMULATE_TOKEN, or pass --token.' };
+        code = exit_codes_1.EXIT.AUTH;
+    }
+    else {
+        try {
+            const me = await deps.me();
+            report.user = me.user;
+            if (me.token)
+                report.token = me.token;
+        }
+        catch (e) {
+            const err = e;
+            report.error = { status: err.status, code: err.code, message: err.message ?? String(e) };
+            code = (0, exit_codes_1.exitCodeForError)(e);
+        }
+    }
+    if (json) {
+        deps.out(JSON.stringify(report, null, 2));
+        return code;
+    }
+    const t = report.token ?? {};
+    const label = {
+        flag: '--token flag',
+        env: 'FORUMULATE_TOKEN (environment)',
+        credentials: `credentials.json (${where.path ?? ''})`,
+        none: 'none',
+    };
+    if (report.user)
+        deps.out(`${report.user.name} <${report.user.email}> (${report.user.id})`);
+    deps.out(`token source  ${label[where.source]}`);
+    if (report.token) {
+        deps.out(`token         ${t.name ?? '(unnamed)'}  id ${t.id ?? '—'}  …${t.last4 ?? '????'}`);
+        deps.out(`created       ${t.createdAt ?? '—'}`);
+        deps.out(`expires       ${t.expiresAt ?? 'never'}`);
+        deps.out(`scopes        ${t.scopes?.join(', ') || '—'}`);
+        deps.out(`spaces        ${t.spaceIds?.join(', ') ?? 'all'}`);
+        deps.out(`capabilities  ${t.capabilities?.join(', ') ?? 'not narrowed'}`);
+        deps.out(`constraints   ${t.constraints ? JSON.stringify(t.constraints) : 'none'}`);
+    }
+    else if (report.user)
+        deps.out('token         a session, not a personal access token');
+    deps.out(`api           ${apiBase}`);
+    for (const w of warnings)
+        deps.err(`warning: ${w.name} is not read by forumulate${w.didYouMean ? `; did you mean ${w.didYouMean}?` : '.'}`);
+    if (report.error)
+        deps.err(`Error${report.error.status ? ` ${report.error.status}` : ''}${report.error.code ? ` (${report.error.code})` : ''}: ${report.error.message}`);
+    return code;
+}
+//# sourceMappingURL=whoami.js.map

package/dist/whoami.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forumulate/cli",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Command-line interface for Forumulate — manage orgs, spaces, docs, and search from your terminal.",
   "license": "MIT",
   "homepage": "https://forumulate.com/guides",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "yaml": "^2.6.1",
-    "@forumulate/sdk": "0.7.0"
+    "@forumulate/sdk": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^22.9.0",

package/dist/publish-dir.d.ts

@@ -1,54 +0,0 @@
-/** One markdown file, as the publisher sees it. */
-export interface LocalDoc {
-    /** Path as given on the command line, for the plan a person reads. */
-    path: string;
-    /** The slug this file publishes at. */
-    slug: string;
-    title: string;
-    markdown: string;
-}
-/** What a directory publish would do, before it does any of it. */
-export interface PublishPlan {
-    create: LocalDoc[];
-    update: (LocalDoc & {
-        itemId: string;
-    })[];
-    /** Published pieces with no file — never touched, only reported. */
-    orphans: {
-        slug: string;
-        title: string;
-    }[];
-}
-/**
- * A file's own front matter, in the small form every static-site generator
- * writes: `key: value` lines, no nesting, no arrays. Anything richer belongs in
- * the page itself, and guessing at YAML we do not support would publish a
- * document whose first paragraph is a parse error.
- */
-export declare function parseFrontMatter(text: string): {
-    data: Record<string, string>;
-    body: string;
-};
-/** `01-getting-started.md` → `getting-started`; `a/b/c.md` → `a-b-c`. */
-export declare function slugFor(file: string, root: string, front: Record<string, string>): string;
-/** The first `# heading`, else the front matter's title, else the slug. */
-export declare function titleFor(body: string, front: Record<string, string>, slug: string): string;
-/** Every `.md`/`.mdx` under a directory, depth-first, in a stable order. */
-export declare function readDocs(root: string): LocalDoc[];
-/**
- * What publishing this directory would change, decided against what the space
- * already holds.
- *
- * A file whose slug the space already has is an UPDATE; one it does not is a
- * CREATE; a published piece with no file is an orphan — reported and left
- * alone, because a directory is a source of truth for what it contains and not
- * a statement about what should be deleted.
- */
-export declare function planPublish(docs: LocalDoc[], existing: {
-    id: string;
-    slug?: string;
-    title: string;
-}[]): PublishPlan;
-/** The plan as a person reads it — the whole point of `--dry-run`. */
-export declare function describePlan(plan: PublishPlan, root: string): string[];
-//# sourceMappingURL=publish-dir.d.ts.map

package/dist/publish-dir.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"publish-dir.d.ts","sourceRoot":"","sources":["../src/publish-dir.ts"],"names":[],"mappings":"AAGA,mDAAmD;AACnD,MAAM,WAAW,QAAQ;IACvB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,MAAM,EAAE,CAAC,QAAQ,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAC;IAC1C,oEAAoE;IACpE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5C;AAID;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAe7F;AAED,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAUzF;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1F;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CAmBjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,QAAQ,EAAE,EAChB,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,GACvD,WAAW,CAcb;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAUtE"}

package/dist/publish-dir.js

@@ -1,119 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseFrontMatter = parseFrontMatter;
-exports.slugFor = slugFor;
-exports.titleFor = titleFor;
-exports.readDocs = readDocs;
-exports.planPublish = planPublish;
-exports.describePlan = describePlan;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
-const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
-/**
- * A file's own front matter, in the small form every static-site generator
- * writes: `key: value` lines, no nesting, no arrays. Anything richer belongs in
- * the page itself, and guessing at YAML we do not support would publish a
- * document whose first paragraph is a parse error.
- */
-function parseFrontMatter(text) {
-    const m = FRONT_MATTER.exec(text);
-    if (!m)
-        return { data: {}, body: text };
-    const data = {};
-    for (const line of (m[1] ?? '').split(/\r?\n/)) {
-        const at = line.indexOf(':');
-        if (at <= 0)
-            continue;
-        const key = line.slice(0, at).trim();
-        const value = line
-            .slice(at + 1)
-            .trim()
-            .replace(/^["']|["']$/g, '');
-        if (key)
-            data[key] = value;
-    }
-    return { data, body: text.slice(m[0].length) };
-}
-/** `01-getting-started.md` → `getting-started`; `a/b/c.md` → `a-b-c`. */
-function slugFor(file, root, front) {
-    if (front.slug)
-        return front.slug.trim();
-    const rel = (0, node_path_1.relative)(root, file).replace(/\.mdx?$/i, '');
-    return rel
-        .split(node_path_1.sep)
-        .map((part) => part.replace(/^\d+[-_]/, ''))
-        .join('-')
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
-/** The first `# heading`, else the front matter's title, else the slug. */
-function titleFor(body, front, slug) {
-    if (front.title)
-        return front.title.trim();
-    const heading = /^#\s+(.+)$/m.exec(body);
-    return heading?.[1]?.trim() || slug;
-}
-/** Every `.md`/`.mdx` under a directory, depth-first, in a stable order. */
-function readDocs(root) {
-    const out = [];
-    const walk = (dir) => {
-        for (const entry of (0, node_fs_1.readdirSync)(dir).sort()) {
-            if (entry.startsWith('.'))
-                continue;
-            const path = (0, node_path_1.join)(dir, entry);
-            if ((0, node_fs_1.statSync)(path).isDirectory()) {
-                walk(path);
-                continue;
-            }
-            if (!/\.mdx?$/i.test(entry))
-                continue;
-            const raw = (0, node_fs_1.readFileSync)(path, 'utf8');
-            const { data, body } = parseFrontMatter(raw);
-            const slug = slugFor(path, root, data);
-            out.push({ path, slug, title: titleFor(body, data, slug), markdown: body.trim() });
-        }
-    };
-    walk(root);
-    return out;
-}
-/**
- * What publishing this directory would change, decided against what the space
- * already holds.
- *
- * A file whose slug the space already has is an UPDATE; one it does not is a
- * CREATE; a published piece with no file is an orphan — reported and left
- * alone, because a directory is a source of truth for what it contains and not
- * a statement about what should be deleted.
- */
-function planPublish(docs, existing) {
-    const bySlug = new Map(existing.filter((e) => e.slug).map((e) => [e.slug, e]));
-    const create = [];
-    const update = [];
-    for (const doc of docs) {
-        const match = bySlug.get(doc.slug);
-        if (match)
-            update.push({ ...doc, itemId: match.id });
-        else
-            create.push(doc);
-    }
-    const named = new Set(docs.map((d) => d.slug));
-    const orphans = existing
-        .filter((e) => e.slug && !named.has(e.slug))
-        .map((e) => ({ slug: e.slug, title: e.title }));
-    return { create, update, orphans };
-}
-/** The plan as a person reads it — the whole point of `--dry-run`. */
-function describePlan(plan, root) {
-    const lines = [];
-    for (const d of plan.create)
-        lines.push(`  create  ${d.slug}   ← ${(0, node_path_1.relative)(root, d.path) || d.path}`);
-    for (const d of plan.update)
-        lines.push(`  update  ${d.slug}   ← ${(0, node_path_1.relative)(root, d.path) || d.path}`);
-    for (const o of plan.orphans)
-        lines.push(`  (left)  ${o.slug}   — published here, no file in this directory`);
-    if (lines.length === 0)
-        lines.push('  nothing to do — no .md files found');
-    return lines;
-}
-//# sourceMappingURL=publish-dir.js.map

package/dist/publish-dir.js.map

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