@mesh-tech/mesh-cli 0.20.2 → 0.20.4

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

@@ -1,53 +1,23 @@
-/**
- * Assembly: turn the discovered doc roots into a plain content tree plus a
- * navigation manifest, ready for a docs renderer (Zudoku today) to build.
- *
- * The seam of the whole design is here: assembly's output is a directory of
- * markdown files, a generated `zudoku.config.ts`, and a publish manifest.
- * Nothing downstream knows about Mesh; nothing upstream knows about Zudoku.
- *
- * What assembly does, per page:
- *   - derives the title (front-matter `title:` → first `#` heading → filename)
- *     and writes it into the assembled front-matter, so nav labels and page
- *     titles can never drift apart
- *   - rewrites links: a relative link between two published files is correct
- *     *on disk* but meaningless at a route, so published targets become
- *     routes, unpublished-but-real files become repo blob links (reported as
- *     `external`), and links that resolve to nothing are reported `broken`
- *   - footers the page with the exact repo file it came from, so a reader who
- *     spots a mistake knows where to fix it
- *
- * It also emits the publish manifest — every source path that made it into
- * the site — which the CI gate uploads and diffs so growing the public
- * surface is a thing a reviewer sees.
- */
 import type { DiscoveredPage, Discovery } from "./discover.js";
 export type LinkIssueKind = "broken" | "external";
 export interface LinkIssue {
     kind: LinkIssueKind;
-    /** Route of the page whose markdown contains the link. */
     page: string;
-    /** The href exactly as written in the source markdown. */
     href: string;
 }
 export interface AssembledPage {
-    /** Repo-relative source path. */
     source: string;
-    /** Absolute site route, e.g. "/building-apps/primitives/service" or "/". */
     route: string;
-    /** Route without the leading slash — also the assembled file's stem path. */
     filePath: string;
     title: string;
     sectionTitle: string;
     sectionOrder: number;
     sectionSlug: string;
-    /** Position within its directory: front-matter `order:` → undefined (filename sort). */
     order?: number;
 }
 export interface PublishManifest {
     version: 1;
     count: number;
-    /** Every repo-relative source path that made it into the site, sorted. */
     sources: string[];
 }
 export interface AssembleResult {
@@ -57,7 +27,6 @@ export interface AssembleResult {
     brokenLinks: LinkIssue[];
     externalLinks: LinkIssue[];
     publishManifest: PublishManifest;
-    /** Fail-closed assertion data: assembled output paths containing a reserved segment. */
     reservedViolations: string[];
 }
 interface FrontMatter {
@@ -65,48 +34,13 @@ interface FrontMatter {
     body: string;
     hasFrontMatter: boolean;
 }
-/**
- * Split a markdown document into front-matter and body. Only a `---` fence on
- * the very first line counts — a horizontal rule later in the prose is not
- * front-matter. A YAML parse failure is not fatal: the document is treated as
- * having no front-matter (the heading/filename title fallbacks still apply),
- * because one bad page must not take the whole site down at assemble time.
- */
 export declare function splitFrontMatter(markdown: string): FrontMatter;
-/**
- * The title derivation order, fixed by the design: front-matter `title:` →
- * first `#` heading → filename. `sidebar_label` wins for the nav when present
- * (Zudoku honours it), but the document still gets its real title.
- */
 export declare function deriveTitle(frontMatter: Record<string, unknown>, body: string, source: string): string;
 export interface LinkResolution {
     href: string;
     issue?: LinkIssue;
 }
-/**
- * Remove HTML comments (`<!-- … -->`, single- or multi-line) from a page body.
- * They are invisible in any rendered output by definition — the source file
- * keeps them — and multi-line comments currently crash Zudoku's MDX plugin
- * (`chunks[startIndex].slice is not a function`), which turns one authored
- * comment into a failed site build. Fenced code blocks are left alone: a doc
- * *teaching* HTML comments shows them as code, and that code must survive.
- */
 export declare function stripHtmlComments(body: string): string;
-/**
- * Resolve one link, exactly the #3503 semantics with routes instead of slugs:
- *
- *   - anchors, absolute URLs, mailto: → untouched
- *   - an `ignoreLinkPrefixes` match → untouched (declared deliberately
- *     unresolvable — the app-kit README's `node_modules/…` guidance exists in
- *     a tenant's install, never in this repo)
- *   - a file the portal publishes → that page's route
- *   - a directory whose index/README the portal publishes → that route
- *   - a real repo file the portal does not publish → a repo blob link
- *     (reported `external`)
- *   - nothing → reported `broken`
- *   - a site-rooted path (`/guides/x`) → validated against the route set, so a
- *     typo'd route fails the gate instead of shipping as a 404
- */
 export declare function resolveLink(args: {
     href: string;
     pageRoute: string;
@@ -114,11 +48,9 @@ export declare function resolveLink(args: {
     sourceIndex: Map<string, AssembledPage>;
     routes: Set<string>;
     ignoreLinkPrefixes: string[];
-    /** Exists-on-disk probe (file OR directory); returns "file" | "dir" | null. */
     pathKind: (repoRelPath: string) => "file" | "dir" | null;
     repoUrl: string;
 }): LinkResolution;
-/** Rewrite every link in a page body, collecting issues. */
 export declare function rewriteLinks(args: {
     body: string;
     page: AssembledPage;
@@ -134,45 +66,16 @@ export declare function rewriteLinks(args: {
 export interface AssembleOptions {
     repoRoot: string;
     discovery: Discovery;
-    /** Directory the assembled markdown tree is written to. */
     outDir: string;
     repoUrl?: string;
     ignoreLinkPrefixes?: string[];
-    /**
-     * Version string stamped into the footer + version.json — the fixed
-     * lockstep group's version post-`changeset version`. Undefined outside a
-     * release build.
-     */
     meshBaseline?: string;
-    /** Short commit the build is from. */
     commit?: string;
 }
-/** A page's full route: section slug + route path. "/" for the site home. */
 export declare function pageRoute(page: DiscoveredPage): string;
-/** The assembled file path (no leading slash, with extension). */
 export declare function pageFilePath(route: string): string;
-/**
- * Assemble the discovered pages into `outDir`. Pure function of the repo tree
- * — the same inputs always produce the same tree, manifest, and navigation.
- */
 export declare function assemblePortal(options: AssembleOptions): AssembleResult;
-/**
- * Build the Zudoku navigation array from the assembled pages.
- *
- * Shape: one root category ("Documentation", clicking it lands on the home
- * page) whose items are one non-collapsible category per doc root — the
- * sidebar's section headers — each holding the section's tree: pages as doc
- * items, directories as nested categories. A directory with an index page
- * becomes a clickable category (its link); the section's own index page
- * becomes the section category's link. Order is front-matter `order:` first,
- * then filename — never declared anywhere but the files themselves.
- */
 export declare function buildNavigation(pages: AssembledPage[]): unknown[];
-/**
- * Render the generated `zudoku.config.ts`. It is regenerated on every
- * assemble and gitignored — the navigation manifest is derived state, and
- * committed derived state is how the old manifest rotted.
- */
 export declare function renderZudokuConfig(args: {
     navigation: unknown[];
     title: string;
@@ -180,38 +83,18 @@ export declare function renderZudokuConfig(args: {
     baseline?: string | undefined;
     commit?: string | undefined;
 }): string;
-/** version.json — the version-parity contract the parity monitor asserts. */
 export declare function renderVersionJson(args: {
     baseline?: string | undefined;
     commit: string;
     builtAt: string;
 }): string;
-/** Best-effort short commit of the repo being assembled. */
 export declare function currentCommit(repoRoot: string): string;
-/** The fixed lockstep group's version, read from app-kit's package.json. */
 export declare function currentBaseline(repoRoot: string): string | undefined;
 export interface PublishSetDiff {
     added: string[];
     removed: string[];
 }
-/**
- * Compute the publish set of another git ref WITHOUT checking it out — the
- * docs.json files and tree listing are read via `git show`/`git ls-tree`, and
- * the same discovery rules (reserved segments, README exclusion, include[])
- * are applied to that listing. Lets a PR diff its publish set against its
- * merge base in a CI job that has no second worktree and no installed deps
- * for the base.
- *
- * APPROXIMATION, base side only: this reimplementation skips schema
- * validation (an invalid docs.json publishes nothing in real discovery but
- * is walked here), nested-root rejection, and route-collision detection, so
- * it can OVER-report the base's publish set (a spurious "removed" row in the
- * summary) — never under-report the head's. The head side is always real
- * discovery; the gate's assertions never read this function.
- */
 export declare function publishSetAtRef(repoRoot: string, ref: string): string[];
 export declare function diffPublishSets(base: string[], head: string[]): PublishSetDiff;
-/** Render the publish-set diff as a GitHub job-summary markdown block. */
 export declare function renderPublishSetSummary(manifest: PublishManifest, diff: PublishSetDiff | null): string;
 export {};
-//# sourceMappingURL=assemble.d.ts.map

package/dist/src/docs/assemble.js

@@ -1,26 +1,3 @@
-/**
- * Assembly: turn the discovered doc roots into a plain content tree plus a
- * navigation manifest, ready for a docs renderer (Zudoku today) to build.
- *
- * The seam of the whole design is here: assembly's output is a directory of
- * markdown files, a generated `zudoku.config.ts`, and a publish manifest.
- * Nothing downstream knows about Mesh; nothing upstream knows about Zudoku.
- *
- * What assembly does, per page:
- *   - derives the title (front-matter `title:` → first `#` heading → filename)
- *     and writes it into the assembled front-matter, so nav labels and page
- *     titles can never drift apart
- *   - rewrites links: a relative link between two published files is correct
- *     *on disk* but meaningless at a route, so published targets become
- *     routes, unpublished-but-real files become repo blob links (reported as
- *     `external`), and links that resolve to nothing are reported `broken`
- *   - footers the page with the exact repo file it came from, so a reader who
- *     spots a mistake knows where to fix it
- *
- * It also emits the publish manifest — every source path that made it into
- * the site — which the CI gate uploads and diffs so growing the public
- * surface is a thing a reviewer sees.
- */
 import { execFileSync } from "node:child_process";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -29,13 +6,6 @@ import { pathKind } from "./discover.js";
 import { hasReservedSegment } from "./schema.js";
 const DEFAULT_REPO_URL = "https://github.com/mesh-tech/mesh-platform";
 const DEFAULT_IGNORE_LINK_PREFIXES = ["node_modules/"];
-/**
- * Split a markdown document into front-matter and body. Only a `---` fence on
- * the very first line counts — a horizontal rule later in the prose is not
- * front-matter. A YAML parse failure is not fatal: the document is treated as
- * having no front-matter (the heading/filename title fallbacks still apply),
- * because one bad page must not take the whole site down at assemble time.
- */
 export function splitFrontMatter(markdown) {
     const normalized = markdown.replace(/^\uFEFF/, "");
     if (!normalized.startsWith("---\n") && !normalized.startsWith("---\r\n")) {
@@ -58,27 +28,20 @@ export function splitFrontMatter(markdown) {
         }
     }
     catch {
-        // fall through to the no-front-matter shape
     }
     return { data: {}, body, hasFrontMatter: true };
 }
-/** Serialize front-matter data + body back into a markdown document. */
 function joinFrontMatter(data, body) {
     const lines = Object.entries(data).map(([key, value]) => {
         if (typeof value === "number" || typeof value === "boolean")
             return `${key}: ${value}`;
         const text = String(value);
-        // Quote only when YAML would misread the bare form.
         return /^[\w .,'’()/-]+$/.test(text)
             ? `${key}: ${text}`
             : `${key}: ${JSON.stringify(text)}`;
     });
     return `---\n${lines.join("\n")}\n---\n\n${body.replace(/^\s*\n/, "")}`;
 }
-// ---------------------------------------------------------------------------
-// Title derivation
-// ---------------------------------------------------------------------------
-/** First `#` heading text, or undefined. Headings inside code fences don't count. */
 function firstHeading(body) {
     let inFence = false;
     for (const line of body.split("\n")) {
@@ -94,16 +57,10 @@ function firstHeading(body) {
     }
     return undefined;
 }
-/** Titleize a filename stem for the filename-fallback case: `hub-dev-local` → "Hub dev local". */
 function titleizeStem(stem) {
     const words = stem.replace(/[-_]+/g, " ").trim();
     return words.charAt(0).toUpperCase() + words.slice(1);
 }
-/**
- * The title derivation order, fixed by the design: front-matter `title:` →
- * first `#` heading → filename. `sidebar_label` wins for the nav when present
- * (Zudoku honours it), but the document still gets its real title.
- */
 export function deriveTitle(frontMatter, body, source) {
     const fmTitle = frontMatter.title;
     if (typeof fmTitle === "string" && fmTitle.trim())
@@ -135,8 +92,6 @@ function scanLinks(markdown) {
             offset += line.length + 1;
             continue;
         }
-        // Reference definitions: [id]: href — the href runs to end of line
-        // (optionally followed by a title). Rewrite in place.
         const refDef = /^ {0,3}\[[^\]]+\]:\s*(\S+)/.exec(line);
         if (refDef) {
             const href = refDef[1];
@@ -145,7 +100,6 @@ function scanLinks(markdown) {
             offset += line.length + 1;
             continue;
         }
-        // Inline links/images, skipping inline code spans.
         let i = 0;
         while (i < line.length) {
             const ch = line[i];
@@ -174,11 +128,6 @@ function scanLinks(markdown) {
     }
     return hits;
 }
-/**
- * At `line[i] === "["`, try to read `[...](href …)` or `[...][id]`. Only the
- * `(...)` form carries an inline href we can rewrite; reference uses are
- * covered by rewriting their definitions.
- */
 function scanBracketLink(line, open, lineOffset, hits) {
     const closeBracket = line.indexOf("]", open);
     if (closeBracket === -1)
@@ -203,7 +152,6 @@ function scanBracketLink(line, open, lineOffset, hits) {
     if (closeParen === -1)
         return line.length;
     const inner = line.slice(j, closeParen).trim();
-    // href may be followed by a "title" — split on the first space.
     const space = inner.search(/\s/);
     const href = space === -1 ? inner : inner.slice(0, space);
     if (href) {
@@ -212,14 +160,6 @@ function scanBracketLink(line, open, lineOffset, hits) {
     }
     return closeParen + 1;
 }
-/**
- * Remove HTML comments (`<!-- … -->`, single- or multi-line) from a page body.
- * They are invisible in any rendered output by definition — the source file
- * keeps them — and multi-line comments currently crash Zudoku's MDX plugin
- * (`chunks[startIndex].slice is not a function`), which turns one authored
- * comment into a failed site build. Fenced code blocks are left alone: a doc
- * *teaching* HTML comments shows them as code, and that code must survive.
- */
 export function stripHtmlComments(body) {
     const lines = body.split("\n");
     const out = [];
@@ -259,8 +199,6 @@ export function stripHtmlComments(body) {
             inComment = true;
             rest = rest.slice(start + 4);
         }
-        // A line that held only a comment collapses to nothing; a line with prose
-        // around a comment keeps its prose.
         if (rebuilt.trim() !== "" || !inComment)
             out.push(rebuilt.replace(/\s+$/, ""));
     }
@@ -281,21 +219,6 @@ function splitHash(href) {
         ? [href, ""]
         : [href.slice(0, index), href.slice(index + 1)];
 }
-/**
- * Resolve one link, exactly the #3503 semantics with routes instead of slugs:
- *
- *   - anchors, absolute URLs, mailto: → untouched
- *   - an `ignoreLinkPrefixes` match → untouched (declared deliberately
- *     unresolvable — the app-kit README's `node_modules/…` guidance exists in
- *     a tenant's install, never in this repo)
- *   - a file the portal publishes → that page's route
- *   - a directory whose index/README the portal publishes → that route
- *   - a real repo file the portal does not publish → a repo blob link
- *     (reported `external`)
- *   - nothing → reported `broken`
- *   - a site-rooted path (`/guides/x`) → validated against the route set, so a
- *     typo'd route fails the gate instead of shipping as a 404
- */
 export function resolveLink(args) {
     const { href, pageRoute, sourceDir, sourceIndex, routes, repoUrl } = args;
     if (href.startsWith("#") || isAbsoluteHref(href))
@@ -306,7 +229,6 @@ export function resolveLink(args) {
     const hash = rawHash ? `#${rawHash}` : "";
     if (rawTarget === "")
         return { href };
-    // Site-rooted route reference.
     if (rawTarget.startsWith("/")) {
         const route = rawTarget.replace(/\/$/, "") || "/";
         return routes.has(route)
@@ -317,7 +239,6 @@ export function resolveLink(args) {
     const page = sourceIndex.get(repoPath);
     if (page)
         return { href: `${page.route}${hash}` };
-    // A link to a directory conventionally means its index page.
     for (const candidate of [`${repoPath}/index.md`]) {
         const indexPage = sourceIndex.get(normalizeRepoPath(candidate));
         if (indexPage)
@@ -333,7 +254,6 @@ export function resolveLink(args) {
     }
     return { href, issue: { kind: "broken", page: pageRoute, href } };
 }
-/** Rewrite every link in a page body, collecting issues. */
 export function rewriteLinks(args) {
     const issues = [];
     const hits = scanLinks(args.body);
@@ -361,25 +281,17 @@ export function rewriteLinks(args) {
     out += args.body.slice(cursor);
     return { body: out, issues };
 }
-/** A page's full route: section slug + route path. "/" for the site home. */
 export function pageRoute(page) {
     const joined = [page.root.slug, page.routePath].filter(Boolean).join("/");
     return `/${joined}`.replace(/\/$/, "") || "/";
 }
-/** The assembled file path (no leading slash, with extension). */
 export function pageFilePath(route) {
     return route === "/" ? "index.md" : `${route.slice(1)}.md`;
 }
-/**
- * Assemble the discovered pages into `outDir`. Pure function of the repo tree
- * — the same inputs always produce the same tree, manifest, and navigation.
- */
 export function assemblePortal(options) {
     const { repoRoot, discovery, outDir } = options;
     const repoUrl = options.repoUrl ?? DEFAULT_REPO_URL;
     const ignoreLinkPrefixes = options.ignoreLinkPrefixes ?? DEFAULT_IGNORE_LINK_PREFIXES;
-    // Build the page model first: routes must all exist before any link can be
-    // rewritten against them.
     const pages = discovery.pages.map((page) => {
         const route = pageRoute(page);
         return {
@@ -418,9 +330,6 @@ export function assemblePortal(options) {
         for (const issue of rewritten.issues) {
             (issue.kind === "broken" ? brokenLinks : externalLinks).push(issue);
         }
-        // Front-matter: keep the author's, guarantee `title`. `showLastModified`
-        // is off — the assembled tree is rebuilt every run, so git-mtime-derived
-        // dates would say "today" on every page.
         const outData = { ...frontMatter.data, title };
         const blobBase = repoUrl.replace(/\/$/, "").replace(/\/(blob|tree)$/, "");
         const sourceNote = `\n\n---\n\n<sub>Source: [\`${page.source}\`](${blobBase}/blob/main/${page.source}) — edit that file, not this page.</sub>\n`;
@@ -429,9 +338,6 @@ export function assemblePortal(options) {
         writeFileSync(outFile, joinFrontMatter(outData, rewritten.body.trimEnd() + sourceNote));
     }
     const navigation = buildNavigation(pages);
-    // Fail-closed: no assembled output path may contain a reserved segment. The
-    // walk already skips reserved directories, so a violation here means the
-    // exclusion itself broke — exactly what the gate exists to catch.
     const reservedViolations = pages
         .map((p) => p.filePath)
         .filter((filePath) => hasReservedSegment(filePath));
@@ -453,17 +359,6 @@ export function assemblePortal(options) {
 function titleizeDir(name) {
     return titleizeStem(name);
 }
-/**
- * Build the Zudoku navigation array from the assembled pages.
- *
- * Shape: one root category ("Documentation", clicking it lands on the home
- * page) whose items are one non-collapsible category per doc root — the
- * sidebar's section headers — each holding the section's tree: pages as doc
- * items, directories as nested categories. A directory with an index page
- * becomes a clickable category (its link); the section's own index page
- * becomes the section category's link. Order is front-matter `order:` first,
- * then filename — never declared anywhere but the files themselves.
- */
 export function buildNavigation(pages) {
     const sections = new Map();
     for (const page of pages) {
@@ -482,13 +377,6 @@ export function buildNavigation(pages) {
     const sortPages = (list) => [...list].sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) -
         (b.order ?? Number.MAX_SAFE_INTEGER) ||
         a.filePath.localeCompare(b.filePath));
-    // A nav doc reference (item or category link — same shape in both places).
-    // A `path` is a CUSTOM path in Zudoku: when it equals the file-derived
-    // route, the build moves the file's entry onto itself and deletes it
-    // (resolveCustomNavigationPaths compares `path === file` without the
-    // leading slash). The assembler already names files so the file route IS
-    // the desired route — so `path` is only emitted for the one genuinely
-    // custom mapping: the home page (file "index" → "/").
     const docRef = (page) => {
         const file = page.filePath.replace(/\.md$/, "");
         return page.route === `/${file}`
@@ -500,7 +388,6 @@ export function buildNavigation(pages) {
         const indexPage = section.pages.find((p) => p.route === `/${section.slug}` ||
             (section.slug === "" && p.route === "/"));
         const rest = section.pages.filter((p) => p !== indexPage);
-        // Group remaining pages by their section-relative directory.
         const rootPages = [];
         const dirs = new Map();
         for (const page of rest) {
@@ -560,14 +447,6 @@ export function buildNavigation(pages) {
         },
     ];
 }
-// ---------------------------------------------------------------------------
-// Generated config + manifests
-// ---------------------------------------------------------------------------
-/**
- * Render the generated `zudoku.config.ts`. It is regenerated on every
- * assemble and gitignored — the navigation manifest is derived state, and
- * committed derived state is how the old manifest rotted.
- */
 export function renderZudokuConfig(args) {
     const versionLine = args.baseline
         ? `Documents @mesh-tech/* ${args.baseline} · built from ${args.commit ?? "unknown"}`
@@ -594,7 +473,6 @@ export function renderZudokuConfig(args) {
             },
         },
         redirects: [],
-        // Search is Zudoku's built-in Pagefind index — no config needed.
     };
     const json = JSON.stringify(config, null, 2).replace(`"THEME_IMPORT"`, "portalTheme");
     return `/**
@@ -613,7 +491,6 @@ const config: ZudokuConfig = ${json};
 export default config;
 `;
 }
-/** version.json — the version-parity contract the parity monitor asserts. */
 export function renderVersionJson(args) {
     return `${JSON.stringify({
         meshBaseline: args.baseline ?? null,
@@ -621,7 +498,6 @@ export function renderVersionJson(args) {
         builtAt: args.builtAt,
     }, null, 2)}\n`;
 }
-/** Best-effort short commit of the repo being assembled. */
 export function currentCommit(repoRoot) {
     try {
         return execFileSync("git", ["rev-parse", "--short", "HEAD"], {
@@ -633,7 +509,6 @@ export function currentCommit(repoRoot) {
         return "unknown";
     }
 }
-/** The fixed lockstep group's version, read from app-kit's package.json. */
 export function currentBaseline(repoRoot) {
     try {
         const pkg = JSON.parse(readFileSync(path.join(repoRoot, "libs/app-kit/package.json"), "utf-8"));
@@ -643,21 +518,6 @@ export function currentBaseline(repoRoot) {
         return undefined;
     }
 }
-/**
- * Compute the publish set of another git ref WITHOUT checking it out — the
- * docs.json files and tree listing are read via `git show`/`git ls-tree`, and
- * the same discovery rules (reserved segments, README exclusion, include[])
- * are applied to that listing. Lets a PR diff its publish set against its
- * merge base in a CI job that has no second worktree and no installed deps
- * for the base.
- *
- * APPROXIMATION, base side only: this reimplementation skips schema
- * validation (an invalid docs.json publishes nothing in real discovery but
- * is walked here), nested-root rejection, and route-collision detection, so
- * it can OVER-report the base's publish set (a spurious "removed" row in the
- * summary) — never under-report the head's. The head side is always real
- * discovery; the gate's assertions never read this function.
- */
 export function publishSetAtRef(repoRoot, ref) {
     const git = (gitArgs) => execFileSync("git", gitArgs, {
         cwd: repoRoot,
@@ -711,7 +571,6 @@ export function diffPublishSets(base, head) {
         removed: base.filter((source) => !headSet.has(source)),
     };
 }
-/** Render the publish-set diff as a GitHub job-summary markdown block. */
 export function renderPublishSetSummary(manifest, diff) {
     const lines = [
         `## Docs portal publish set`,
@@ -736,4 +595,3 @@ export function renderPublishSetSummary(manifest, diff) {
     lines.push(``, `</details>`);
     return `${lines.join("\n")}\n`;
 }
-//# sourceMappingURL=assemble.js.map

package/dist/src/docs/cli-reference.d.ts

@@ -1,38 +1,19 @@
-/**
- * Generate the `mesh` CLI reference from the commander tree.
- *
- * This is the load-bearing half of "self-documenting": the reference is not a
- * hand-maintained table that drifts from the code, it is a projection of the
- * same `Command` objects the CLI parses. Add a flag and the docs grow it; the
- * `--check` mode in `mesh docs` fails CI when the two diverge.
- *
- * Pure by construction — `extractCliReference` and `renderCliReferenceMarkdown`
- * do no I/O, so they are directly unit-testable.
- */
 import type { Command } from "commander";
 export interface CliOptionRef {
-    /** Option flags exactly as declared, e.g. `-p, --port <n>`. */
     flags: string;
     description: string;
-    /** Rendered default, if the option declares one. */
     defaultValue?: string;
     required: boolean;
-    /** Enumerated allowed values, when the option declares `.choices()`. */
     choices?: string[];
 }
 export interface CliCommandRef {
-    /** Full invocation path, e.g. `mesh hub dev`. */
     path: string;
-    /** Leaf name only, e.g. `dev`. */
     name: string;
     aliases: string[];
     description: string;
-    /** Positional argument usage, e.g. `<context> [names...]`. */
     args: string;
     options: CliOptionRef[];
-    /** Slug used for the anchor/id of this command's section. */
     slug: string;
-    /** Nesting depth below the root program (top-level commands are 1). */
     depth: number;
     subcommands: CliCommandRef[];
 }
@@ -42,52 +23,13 @@ export interface CliReference {
     options: CliOptionRef[];
     commands: CliCommandRef[];
 }
-/** Machine-specific paths that must never reach a committed artifact. */
 export interface MachinePaths {
     homeDir: string;
     tmpDir: string;
 }
-/**
- * Collapse machine-specific absolute paths to the symbols a reader recognizes.
- *
- * Some option defaults are computed at registration time from the environment —
- * `mesh install-shim --dir` defaults to `path.join(os.homedir(), ".local/bin")`.
- * Rendered literally, the generated reference embeds whoever ran the generator
- * (`/Users/dmb/.local/bin` vs `/home/runner/.local/bin`), which makes the
- * artifact machine-dependent and the `--check` gate pass only on one laptop —
- * exactly how this was caught, by CI failing a locally-green gate.
- *
- * Substituting `~` fixes determinism and is also what the reader wants to see.
- * Longest prefix first, since tmpdir can live under home on macOS.
- */
 export declare function normalizeMachinePaths(value: string, paths: MachinePaths): string;
-/**
- * Render a default value the way a reader would type it, not the way
- * `JSON.stringify` would: bare for strings so `docs/docs.config.json` doesn't
- * arrive wrapped in quotes, JSON for everything structured.
- *
- * `paths` is injectable so the normalization above is testable without
- * depending on the machine running the test.
- */
 export declare function formatDefault(value: unknown, paths?: MachinePaths): string | undefined;
-/** Slugify a command path into a stable anchor: `mesh hub dev` → `mesh-hub-dev`. */
 export declare function slugifyCommandPath(path: string): string;
-/**
- * Project a commander program into a serializable reference tree.
- *
- * The root program's `--version` option is excluded: its value is the CLI
- * version, which would make the generated output differ on every release and
- * turn the `--check` gate into noise.
- */
 export declare function extractCliReference(program: Command): CliReference;
-/** Depth-first walk over every command in the tree, parents before children. */
 export declare function flattenCommands(reference: CliReference): CliCommandRef[];
-/**
- * Render the reference as markdown.
- *
- * The output carries a generated-file banner naming the command that rebuilds
- * it, because the failure mode for generated docs is someone hand-editing the
- * artifact and losing the change on the next build.
- */
 export declare function renderCliReferenceMarkdown(reference: CliReference): string;
-//# sourceMappingURL=cli-reference.d.ts.map