@mesh-tech/mesh-cli 0.1.0 → 0.12.0

package/dist/src/docs/discover.js

@@ -0,0 +1,233 @@
+/**
+ * Doc-root discovery.
+ *
+ * The one rule of the portal: **a directory publishes its markdown if, and
+ * only if, it contains a `docs.json`.** This module finds those directories,
+ * validates their declarations, and walks them for publishable pages —
+ * skipping any path with a reserved segment (at any depth) and any `README.md`
+ * (a README is the directory's GitHub face, not portal content; a root that
+ * wants one published names it in `include[]`, the escape hatch).
+ *
+ * Discovery is purely about *which files* publish. Reading their content —
+ * titles, front-matter, links — is assembly's job (`assemble.ts`).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { docsJsonSchema, hasReservedSegment, slugify } from "./schema.js";
+/**
+ * Directories the walk never descends into while LOOKING FOR roots. This list
+ * is about walk performance and sanity (`.git`, build output), and is
+ * deliberately separate from the reserved list, which is about publish
+ * safety. `node_modules` is on both: it is huge, and it must never publish.
+ */
+const ROOT_WALK_SKIP = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    ".turbo",
+    ".next",
+    ".deploy",
+    ".generated",
+    "coverage",
+    ".portal",
+    ".vercel",
+    ".wrangler",
+]);
+/**
+ * The route a page gets inside its section: the path relative to the root,
+ * each segment slugified, the `.md` dropped, and a trailing `index` collapsed
+ * so a directory's index page serves at the directory's route.
+ */
+export function routePathFor(relPath) {
+    const withoutExt = relPath.replace(/\.md$/i, "");
+    const parts = withoutExt.split("/").map(slugify);
+    // A trailing `index` segment collapses: the file serves at its directory's
+    // route (a root-level index.md is the section's own landing page).
+    if (parts[parts.length - 1] === "index")
+        parts.pop();
+    return parts.join("/");
+}
+/** Recursively collect `*.md` files under `dir`, skipping reserved segments. */
+function walkMarkdown(absDir, relDir, errors, rootDir) {
+    const out = [];
+    let entries;
+    try {
+        entries = readdirSync(absDir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+        if (hasReservedSegment(entry.name)) {
+            // Reserved names are silently skipped in the walk — exclusion here is
+            // the normal case, not an error. The gate separately asserts that
+            // nothing reserved ever reaches the OUTPUT (fail-closed).
+            continue;
+        }
+        const abs = path.join(absDir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name.startsWith("."))
+                continue;
+            out.push(...walkMarkdown(abs, rel, errors, rootDir));
+        }
+        else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            // A README is the directory's GitHub face — it does not publish via the
+            // walk. The include[] escape hatch is how a README becomes a page.
+            if (entry.name.toLowerCase() === "readme.md")
+                continue;
+            out.push(rel);
+        }
+        else if (entry.isFile() &&
+            entry.name === "docs.json" &&
+            relDir !== "" // the root's own docs.json is the declaration, not content
+        ) {
+            errors.push(`nested doc root: ${rootDir}/.../${rel} — a docs.json inside another doc root is ambiguous; give it its own sibling root or remove it`);
+        }
+    }
+    return out;
+}
+/**
+ * Find every doc root under `repoRoot`, validate it, and collect its pages.
+ *
+ * The walk looks for `docs.json` files anywhere in the repo (excluding the
+ * ROOT_WALK_SKIP directories), so a package opts in by adding one file and
+ * nothing else. Roots are sorted by (order, title); pages within a root are
+ * sorted by route path so assembly is deterministic.
+ */
+export function discoverDocRoots(repoRoot) {
+    const errors = [];
+    const roots = [];
+    const findRoots = (absDir, relDir, insideReserved) => {
+        let entries;
+        try {
+            entries = readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        const hasDocsJson = entries.some((e) => e.isFile() && e.name === "docs.json");
+        if (hasDocsJson) {
+            const rel = relDir || ".";
+            if (insideReserved || (relDir && hasReservedSegment(relDir))) {
+                // Fail-closed: a root under a reserved directory is the "mistake one"
+                // half of the leak scenario. Refusing it here means even a deliberate
+                // docs.json in docs/plans/ publishes nothing.
+                errors.push(`doc root ${rel}/ is under a reserved segment — it publishes nothing. Move the content out of the reserved directory instead.`);
+            }
+            else {
+                const root = loadRoot(absDir, rel, errors);
+                // An invalid declaration publishes NOTHING — assembling pages under a
+                // guessed title/slug could put content at routes nobody reviewed.
+                if (root)
+                    roots.push(root);
+            }
+            // Never look for further roots inside a claimed root — a nested
+            // docs.json is reported by the page walk instead (ambiguous ownership).
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (ROOT_WALK_SKIP.has(entry.name))
+                continue;
+            // Dot-directories are tooling, not content — ALL of them, so a
+            // .pi/docs.json is skipped here exactly like a .claude one. The page
+            // walk does the same, so a root found there could never publish anyway.
+            if (entry.name.startsWith("."))
+                continue;
+            const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+            findRoots(path.join(absDir, entry.name), rel, insideReserved || hasReservedSegment(entry.name));
+        }
+    };
+    findRoots(repoRoot, "", false);
+    const pages = [];
+    for (const root of roots) {
+        const absRoot = path.join(repoRoot, root.dir);
+        const relFiles = walkMarkdown(absRoot, "", errors, root.dir);
+        for (const relPath of relFiles.sort()) {
+            pages.push({
+                source: root.dir === "." ? relPath : `${root.dir}/${relPath}`,
+                root,
+                routePath: routePathFor(relPath),
+                included: false,
+            });
+        }
+        for (const includePath of root.config.include) {
+            const normalized = includePath
+                .replace(/\\/g, "/")
+                .replace(/^\.\//, "")
+                .replace(/\/+$/, "");
+            if (hasReservedSegment(normalized)) {
+                errors.push(`${root.dir}/docs.json includes ${normalized}, which is under a reserved segment — include[] cannot pull internal material into the site`);
+                continue;
+            }
+            if (!normalized.toLowerCase().endsWith(".md")) {
+                errors.push(`${root.dir}/docs.json includes ${normalized}, which is not a markdown file`);
+                continue;
+            }
+            if (!existsSync(path.join(repoRoot, normalized))) {
+                errors.push(`${root.dir}/docs.json includes ${normalized}, which does not exist`);
+                continue;
+            }
+            if (pages.some((p) => p.source === normalized))
+                continue; // walked already
+            const stem = path.posix.basename(normalized).replace(/\.md$/i, "");
+            pages.push({
+                source: normalized,
+                root,
+                // An included README is the section's index page — "a package README
+                // is its natural overview page". Anything else routes by its stem.
+                routePath: stem.toLowerCase() === "readme" ? "" : slugify(stem),
+                included: true,
+            });
+        }
+    }
+    // Route collisions are authoring mistakes two files cannot both survive —
+    // catch them at discovery so the failure names both sources.
+    const seenRoutes = new Map();
+    for (const page of pages) {
+        const route = [page.root.slug, page.routePath].filter(Boolean).join("/");
+        const existing = seenRoutes.get(route);
+        if (existing) {
+            errors.push(`route collision: ${page.source} and ${existing} both map to /${route || "(site root)"}`);
+        }
+        seenRoutes.set(route, page.source);
+    }
+    roots.sort((a, b) => a.config.order - b.config.order ||
+        a.config.title.localeCompare(b.config.title));
+    return { roots, pages, errors };
+}
+/** Parse and validate one root's docs.json. Returns null (and records why) when invalid — an invalid declaration publishes nothing. */
+function loadRoot(absDir, relDir, errors) {
+    const configPath = path.join(absDir, "docs.json");
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    catch (error) {
+        errors.push(`${relDir}/docs.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+    const parsed = docsJsonSchema.safeParse(raw);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            errors.push(`${relDir}/docs.json: ${issue.path.join(".") || "(root)"}: ${issue.message}`);
+        }
+        return null;
+    }
+    const config = parsed.data;
+    const slug = config.slug ?? slugify(config.title);
+    return { dir: relDir, config, slug };
+}
+/** What exists at `candidate`, or null. Link resolution needs the file/dir split for blob-vs-tree URLs. */
+export function pathKind(candidate) {
+    try {
+        const stat = statSync(candidate);
+        return stat.isDirectory() ? "dir" : "file";
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=discover.js.map

package/dist/src/docs/discover.js.map

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

package/dist/src/docs/portal.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `mesh docs portal` — assemble the developer portal from the repo's
+ * docs.json-discovered markdown and hand it to the renderer (Zudoku) to build
+ * or serve.
+ *
+ * Modes:
+ *
+ *   mesh docs portal                 assemble → `zudoku build` → apps/docs/dist
+ *   mesh docs portal --serve         assemble → `zudoku dev` (local preview)
+ *   mesh docs portal --assemble-only assemble and stop (content/, config,
+ *                                    manifests) — what CI runs before `build`
+ *   mesh docs portal --check         the CI gate: assemble to a scratch dir and
+ *                                    fail on any of the four assertions below
+ *
+ * The four --check assertions, any of which exits non-zero:
+ *   1. a docs.json fails schema validation (or any other discovery error)
+ *   2. an assembled output path contains a reserved segment (fail-closed —
+ *      internal material must never be publishable)
+ *   3. an internal link resolves to nothing
+ *   4. the committed CLI reference is stale (the command tree drifted)
+ *
+ * Assembly always writes `publish-manifest.json` — every source path that
+ * made it into the site — which CI uploads as an artifact; on PRs
+ * `--diff-base <ref>` also prints the added/removed published paths into the
+ * GitHub job summary.
+ */
+import type { AssembleResult } from "./assemble.js";
+/** The Zudoku app package directory, relative to the repo root. */
+export declare const DOCS_APP_DIR = "apps/docs";
+export interface PortalRunResult {
+    assembled: AssembleResult;
+    errors: string[];
+}
+/**
+ * Run discovery + assembly. Shared by every mode; the scratch-dir variant is
+ * what --check uses so the gate never depends on (or dirties) apps/docs.
+ */
+export declare function runAssemble(args: {
+    repoRoot: string;
+    outDir: string;
+    configOut?: string;
+    writeFiles?: boolean;
+}): PortalRunResult;
+/** Print the assembly report: counts, external-link note, broken-link list. */
+export declare function reportAssembly(result: PortalRunResult): void;
+/**
+ * The --check gate. Returns the failure list (empty = pass). Also writes the
+ * job-summary publish-set diff when --diff-base names a ref and
+ * GITHUB_STEP_SUMMARY is writable.
+ */
+export declare function checkPortal(args: {
+    repoRoot: string;
+    diffBase?: string | undefined;
+    printManifest?: boolean;
+    /** Stable path to write publish-manifest.json to (CI uploads it as an artifact). */
+    manifestOut?: string | undefined;
+    checkCliReference: () => Promise<string | null>;
+}): Promise<string[]>;
+export interface PortalCommandOptions {
+    out?: string | undefined;
+    assembleOnly?: boolean;
+    serve?: boolean;
+    port?: string;
+    check?: boolean;
+    printManifest?: boolean;
+    diffBase?: string | undefined;
+    manifestOut?: string | undefined;
+}
+/**
+ * The command body. Kept free of commander types so the test suite can drive
+ * it directly; `commands/docs.ts` is a thin flag adapter.
+ */
+export declare function runPortalCommand(opts: PortalCommandOptions, deps: {
+    repoRoot: string;
+    checkCliReference: () => Promise<string | null>;
+}): Promise<void>;
+/** Re-exported so commands/docs.ts can wire the CLI-reference staleness check. */
+export declare function cliReferenceStaleness(repoRoot: string): Promise<string | null>;
+//# sourceMappingURL=portal.d.ts.map

package/dist/src/docs/portal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal.d.ts","sourceRoot":"","sources":["../../../src/docs/portal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAyBH,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,eAAe,CAAC;AAGrE,mEAAmE;AACnE,eAAO,MAAM,YAAY,cAAc,CAAC;AAWxC,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,cAAc,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,eAAe,CAsDlB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAqB5D;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACjD,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA4CpB;AAqDD,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,oBAAoB,EAC1B,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACjD,GACA,OAAO,CAAC,IAAI,CAAC,CAmEf;AAED,kFAAkF;AAClF,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxB"}

package/dist/src/docs/portal.js

@@ -0,0 +1,242 @@
+/**
+ * `mesh docs portal` — assemble the developer portal from the repo's
+ * docs.json-discovered markdown and hand it to the renderer (Zudoku) to build
+ * or serve.
+ *
+ * Modes:
+ *
+ *   mesh docs portal                 assemble → `zudoku build` → apps/docs/dist
+ *   mesh docs portal --serve         assemble → `zudoku dev` (local preview)
+ *   mesh docs portal --assemble-only assemble and stop (content/, config,
+ *                                    manifests) — what CI runs before `build`
+ *   mesh docs portal --check         the CI gate: assemble to a scratch dir and
+ *                                    fail on any of the four assertions below
+ *
+ * The four --check assertions, any of which exits non-zero:
+ *   1. a docs.json fails schema validation (or any other discovery error)
+ *   2. an assembled output path contains a reserved segment (fail-closed —
+ *      internal material must never be publishable)
+ *   3. an internal link resolves to nothing
+ *   4. the committed CLI reference is stale (the command tree drifted)
+ *
+ * Assembly always writes `publish-manifest.json` — every source path that
+ * made it into the site — which CI uploads as an artifact; on PRs
+ * `--diff-base <ref>` also prints the added/removed published paths into the
+ * GitHub job summary.
+ */
+import { spawn } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { logError, logInfo, logSuccess, logWarn } from "../utils/log.js";
+import { assemblePortal, currentBaseline, currentCommit, diffPublishSets, publishSetAtRef, renderPublishSetSummary, renderVersionJson, renderZudokuConfig, } from "./assemble.js";
+import { discoverDocRoots } from "./discover.js";
+/** The Zudoku app package directory, relative to the repo root. */
+export const DOCS_APP_DIR = "apps/docs";
+const CONTENT_DIR = "content";
+const GENERATED_CONFIG = "zudoku.config.ts";
+const PUBLISH_MANIFEST = "publish-manifest.json";
+const VERSION_JSON_DIR = "public";
+const VERSION_JSON = "version.json";
+const SITE_TITLE = "Mesh Developer Portal";
+const SITE_DESCRIPTION = "Build and run financial-services apps on Mesh Platform with the mesh developer CLI.";
+/**
+ * Run discovery + assembly. Shared by every mode; the scratch-dir variant is
+ * what --check uses so the gate never depends on (or dirties) apps/docs.
+ */
+export function runAssemble(args) {
+    const discovery = discoverDocRoots(args.repoRoot);
+    const assembled = assemblePortal({
+        repoRoot: args.repoRoot,
+        discovery,
+        outDir: args.outDir,
+        meshBaseline: currentBaseline(args.repoRoot),
+        commit: currentCommit(args.repoRoot),
+    });
+    const errors = [...discovery.errors];
+    if (args.writeFiles !== false) {
+        // The manifest lands BESIDE the content dir for a real assemble
+        // (apps/docs/publish-manifest.json — gitignored derived state) and INSIDE
+        // the scratch dir for a --check run, so concurrent checks never share a
+        // file and nothing is written loose to the tmpdir root.
+        const manifestPath = args.outDir.includes(tmpdir())
+            ? path.join(args.outDir, PUBLISH_MANIFEST)
+            : path.join(args.outDir, "..", PUBLISH_MANIFEST);
+        writeFileSync(manifestPath, `${JSON.stringify(assembled.publishManifest, null, 2)}\n`);
+        if (args.configOut) {
+            writeFileSync(args.configOut, renderZudokuConfig({
+                navigation: assembled.navigation,
+                title: SITE_TITLE,
+                description: SITE_DESCRIPTION,
+                baseline: currentBaseline(args.repoRoot),
+                commit: currentCommit(args.repoRoot),
+            }));
+            const versionDir = path.join(path.dirname(args.configOut), VERSION_JSON_DIR);
+            mkdirSync(versionDir, { recursive: true });
+            writeFileSync(path.join(versionDir, VERSION_JSON), renderVersionJson({
+                baseline: currentBaseline(args.repoRoot),
+                commit: currentCommit(args.repoRoot),
+                builtAt: new Date().toISOString(),
+            }));
+        }
+    }
+    return { assembled, errors };
+}
+/** Print the assembly report: counts, external-link note, broken-link list. */
+export function reportAssembly(result) {
+    const { assembled } = result;
+    logSuccess(`Assembled ${assembled.pages.length} pages from ${new Set(assembled.pages.map((p) => p.sectionTitle)).size} sections → ${assembled.outDir}`);
+    if (assembled.externalLinks.length > 0) {
+        const unique = new Set(assembled.externalLinks.map((issue) => `${issue.page} → ${issue.href}`));
+        logInfo(`${unique.size} link${unique.size === 1 ? "" : "s"} point at repo files outside the portal and were rewritten to blob links`);
+    }
+    if (assembled.brokenLinks.length > 0) {
+        logWarn(`${assembled.brokenLinks.length} link(s) resolve to nothing:`);
+        for (const issue of assembled.brokenLinks) {
+            logWarn(`  ${issue.page}: ${issue.href}`);
+        }
+    }
+}
+/**
+ * The --check gate. Returns the failure list (empty = pass). Also writes the
+ * job-summary publish-set diff when --diff-base names a ref and
+ * GITHUB_STEP_SUMMARY is writable.
+ */
+export async function checkPortal(args) {
+    const scratch = mkdtempSync(path.join(tmpdir(), "mesh-docs-check-"));
+    const result = runAssemble({ repoRoot: args.repoRoot, outDir: scratch });
+    const failures = [...result.errors];
+    for (const violation of result.assembled.reservedViolations) {
+        failures.push(`assembled output path contains a reserved segment: ${violation}`);
+    }
+    for (const issue of result.assembled.brokenLinks) {
+        failures.push(`broken link on ${issue.page}: ${issue.href}`);
+    }
+    const cliReferenceError = await args.checkCliReference();
+    if (cliReferenceError)
+        failures.push(cliReferenceError);
+    reportAssembly(result);
+    if (args.printManifest) {
+        process.stdout.write(`${JSON.stringify(result.assembled.publishManifest, null, 2)}\n`);
+    }
+    if (args.manifestOut) {
+        mkdirSync(path.dirname(args.manifestOut), { recursive: true });
+        writeFileSync(args.manifestOut, `${JSON.stringify(result.assembled.publishManifest, null, 2)}\n`);
+    }
+    if (args.diffBase) {
+        writePublishSetSummary(args.repoRoot, args.diffBase, result.assembled.publishManifest);
+    }
+    return failures;
+}
+/** Diff the publish set against a git ref; print + append to the GH job summary. */
+function writePublishSetSummary(repoRoot, diffBase, manifest) {
+    let diff = null;
+    try {
+        const base = publishSetAtRef(repoRoot, diffBase);
+        diff = diffPublishSets(base, manifest.sources);
+    }
+    catch (error) {
+        logWarn(`could not compute the publish-set diff against ${diffBase}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const summary = renderPublishSetSummary(manifest, diff);
+    process.stdout.write(`\n${summary}`);
+    const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+    if (summaryPath) {
+        try {
+            appendFileSync(summaryPath, summary);
+        }
+        catch {
+            logWarn(`GITHUB_STEP_SUMMARY is set but not writable (${summaryPath})`);
+        }
+    }
+}
+/** Spawn the renderer. Returns its exit code. */
+function runZudoku(args) {
+    const cliArgs = args.mode === "dev"
+        ? ["dev", "--port", String(args.port ?? 3000)]
+        : ["build"];
+    logInfo(`Running \`zudoku ${cliArgs.join(" ")}\` in ${args.appDir}`);
+    return new Promise((resolve, reject) => {
+        const child = spawn("pnpm", ["exec", "zudoku", ...cliArgs], {
+            cwd: args.appDir,
+            stdio: "inherit",
+            env: process.env,
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+}
+/**
+ * The command body. Kept free of commander types so the test suite can drive
+ * it directly; `commands/docs.ts` is a thin flag adapter.
+ */
+export async function runPortalCommand(opts, deps) {
+    const { repoRoot } = deps;
+    if (opts.check) {
+        const failures = await checkPortal({
+            repoRoot,
+            diffBase: opts.diffBase,
+            printManifest: opts.printManifest ?? false,
+            manifestOut: opts.manifestOut,
+            checkCliReference: deps.checkCliReference,
+        });
+        if (failures.length > 0) {
+            for (const failure of failures)
+                logError(failure);
+            throw new Error(`docs portal check failed with ${failures.length} problem(s)`);
+        }
+        logSuccess("Docs portal check passed");
+        return;
+    }
+    const appDir = path.join(repoRoot, DOCS_APP_DIR);
+    const outDir = opts.out
+        ? path.resolve(repoRoot, opts.out)
+        : path.join(appDir, CONTENT_DIR);
+    const result = runAssemble({
+        repoRoot,
+        outDir,
+        configOut: path.join(appDir, GENERATED_CONFIG),
+    });
+    reportAssembly(result);
+    if (result.errors.length > 0) {
+        for (const error of result.errors)
+            logError(error);
+        throw new Error(`docs portal assembly failed with ${result.errors.length} problem(s)`);
+    }
+    if (opts.assembleOnly || opts.out) {
+        logInfo(`Assembled content at ${path.relative(repoRoot, outDir)} — build with: pnpm --filter @mesh-tech/docs build`);
+        return;
+    }
+    const mode = opts.serve ? "dev" : "build";
+    let port;
+    if (opts.serve && opts.port) {
+        port = Number.parseInt(opts.port, 10);
+        if (!Number.isInteger(port) || port < 0 || port > 65535) {
+            throw new Error(`Invalid --port: ${opts.port}`);
+        }
+    }
+    const code = await runZudoku({
+        appDir,
+        mode,
+        ...(port !== undefined ? { port } : {}),
+    });
+    if (code !== 0)
+        throw new Error(`zudoku ${mode} exited with code ${code}`);
+    if (mode === "build") {
+        logSuccess(`Portal built → ${path.join(path.relative(repoRoot, appDir), "dist")}`);
+    }
+}
+/** Re-exported so commands/docs.ts can wire the CLI-reference staleness check. */
+export async function cliReferenceStaleness(repoRoot) {
+    const [{ createProgram }, { extractCliReference, renderCliReferenceMarkdown },] = await Promise.all([
+        import("../program.js"),
+        import("./cli-reference.js"),
+    ]);
+    const outPath = path.join(repoRoot, "docs/portal/generated/cli-reference.md");
+    const markdown = renderCliReferenceMarkdown(extractCliReference(createProgram()));
+    const existing = existsSync(outPath) ? readFileSync(outPath, "utf-8") : null;
+    if (existing === markdown)
+        return null;
+    return `${existing === null ? "CLI reference is missing" : "CLI reference is stale"}: docs/portal/generated/cli-reference.md — the commander tree changed; regenerate and commit with \`pnpm exec mesh docs cli-reference\``;
+}
+//# sourceMappingURL=portal.js.map

package/dist/src/docs/portal.js.map

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

package/dist/src/docs/registry-docs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The docs-as-registry-artifact client.
+ *
+ * The release job publishes the built portal as `@mesh-tech/docs` in the
+ * fixed lockstep group, so the docs version IS the @mesh-tech/* baseline
+ * version it describes. The audience is exactly "people who can install the
+ * packages": the CodeArtifact registry is Zitadel-role-gated (see
+ * `mesh registry login`), so no public hosting is required for the docs to
+ * reach precisely the authorized set.
+ *
+ * This module reads the user's existing `~/.npmrc` CodeArtifact token (the
+ * one `mesh registry login` writes), lists published docs versions, and
+ * fetches + caches a version's tarball. It never talks to AWS directly.
+ */
+export declare const DOCS_PACKAGE = "@mesh-tech/docs";
+export interface DocsRegistryAuth {
+    endpoint: string;
+    token: string;
+}
+/** The CodeArtifact token + endpoint from `mesh registry login`'s ~/.npmrc line. */
+export declare function readDocsRegistryAuth(npmrcPath?: string): DocsRegistryAuth | null;
+/** x.y.z numeric compare (release versions carry no prerelease suffixes). */
+export declare function compareVersions(a: string, b: string): number;
+export interface DocsVersionList {
+    versions: string[];
+    latest: string | undefined;
+}
+/**
+ * Every published docs version, oldest → newest, plus the registry's
+ * `latest` dist-tag. Throws with the login remediation when the registry
+ * rejects the token — an expired token is the common case (12h TTL).
+ */
+export declare function listDocsVersions(auth: DocsRegistryAuth, fetchImpl?: typeof fetch): Promise<DocsVersionList>;
+/** Where fetched docs versions live: `~/.cache/mesh/docs/<version>/`. */
+export declare function docsCacheRoot(): string;
+/**
+ * Fetch and extract a docs version into the cache; returns the directory
+ * containing the site's `dist/`. Cache hit = the directory already has a
+ * `dist/index.html`. Partial downloads extract to a temp sibling and rename,
+ * so an interrupted fetch never leaves a half-written "good" cache entry.
+ */
+export declare function fetchDocsArtifact(auth: DocsRegistryAuth, version: string, cacheRoot?: string, fetchImpl?: typeof fetch): Promise<string>;
+//# sourceMappingURL=registry-docs.d.ts.map

package/dist/src/docs/registry-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-docs.d.ts","sourceRoot":"","sources":["../../../src/docs/registry-docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,eAAO,MAAM,YAAY,oBAAoB,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAAC,SAAS,GAAE,MAAwB,GAAG,gBAAgB,GAAG,IAAI,CAGjG;AAoBD,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAY5D;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,gBAAgB,EACtB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,eAAe,CAAC,CA2B1B;AAED,yEAAyE;AACzE,wBAAgB,aAAa,IAAI,MAAM,CAGtC;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAwB,EACnC,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,MAAM,CAAC,CAyDjB"}