@mesh-tech/mesh-cli 0.36.0 → 0.38.0

package/dist/bin/mesh.chunk-HPYZWPRM.js

@@ -0,0 +1,1146 @@
+import {
+  logError,
+  logInfo,
+  logSuccess,
+  logWarn
+} from "./mesh.chunk-WFFDF346.js";
+
+// packages/mesh-cli/src/docs/discover.ts
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+// packages/mesh-cli/src/docs/schema.ts
+import { z } from "zod";
+var RESERVED_SEGMENTS = [
+  "plans",
+  "designs",
+  "proposals",
+  "incidents",
+  "handoffs",
+  "reviews",
+  "runbooks",
+  "hran",
+  "superpowers",
+  "templates",
+  "archive",
+  "internal",
+  "drafts",
+  "node_modules",
+  "__tests__",
+  ".claude",
+  ".pi"
+];
+var docsJsonSchema = z.object({
+  /** Section label in the nav, e.g. "Building apps". */
+  title: z.string().min(1),
+  /**
+   * Section position in the nav. Ties break alphabetically by title, so two
+   * sections can never fight over a slot nondeterministically.
+   */
+  order: z.number().int().default(50),
+  /**
+   * Route prefix for the section. Defaults to the slugified title. The
+   * empty string is legal and means "this section lives at the site root" —
+   * exactly one root should do that (the front door, `docs/portal`).
+   */
+  slug: z.string().regex(
+    /^$|^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+    'slug must be lower-kebab-case or ""'
+  ).optional(),
+  /**
+   * Escape hatch: explicit repo-relative paths to publish that live outside
+   * any natural doc root (a package README, a repo-root policy file). Expected
+   * to hold a handful of entries across the whole repo — adding one is a
+   * deliberate, reviewable act. Paths under a reserved segment are refused.
+   */
+  include: z.array(z.string().min(1)).default([])
+}).strict();
+function isReservedSegment(segment) {
+  const lowered = segment.toLowerCase();
+  return RESERVED_SEGMENTS.some((reserved) => reserved === lowered);
+}
+function hasReservedSegment(relPath) {
+  return relPath.split("/").some(isReservedSegment);
+}
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "index";
+}
+
+// packages/mesh-cli/src/docs/discover.ts
+var ROOT_WALK_SKIP = /* @__PURE__ */ new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  ".turbo",
+  ".next",
+  ".deploy",
+  ".generated",
+  "coverage",
+  ".portal",
+  ".vercel",
+  ".wrangler"
+]);
+function routePathFor(relPath) {
+  const withoutExt = relPath.replace(/\.md$/i, "");
+  const parts = withoutExt.split("/").map(slugify);
+  if (parts[parts.length - 1] === "index") parts.pop();
+  return parts.join("/");
+}
+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)) {
+      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")) {
+      if (entry.name.toLowerCase() === "readme.md") continue;
+      out.push(rel);
+    } else if (entry.isFile() && entry.name === "docs.json" && relDir !== "") {
+      errors.push(
+        `nested doc root: ${rootDir}/.../${rel} \u2014 a docs.json inside another doc root is ambiguous; give it its own sibling root or remove it`
+      );
+    }
+  }
+  return out;
+}
+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)) {
+        errors.push(
+          `doc root ${rel}/ is under a reserved segment \u2014 it publishes nothing. Move the content out of the reserved directory instead.`
+        );
+      } else {
+        const root = loadRoot(absDir, rel, errors);
+        if (root) roots.push(root);
+      }
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (ROOT_WALK_SKIP.has(entry.name)) continue;
+      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 \u2014 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;
+      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
+      });
+    }
+  }
+  const seenRoutes = /* @__PURE__ */ 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 };
+}
+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 };
+}
+function pathKind(candidate) {
+  try {
+    const stat = statSync(candidate);
+    return stat.isDirectory() ? "dir" : "file";
+  } catch {
+    return null;
+  }
+}
+
+// packages/mesh-cli/src/docs/portal.ts
+import { spawn } from "node:child_process";
+import {
+  appendFileSync,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  mkdtempSync,
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path3 from "node:path";
+
+// packages/mesh-cli/src/docs/assemble.ts
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync as readFileSync2, rmSync, writeFileSync } from "node:fs";
+import path2 from "node:path";
+import { parse as parseYaml } from "yaml";
+var DEFAULT_REPO_URL = "https://github.com/mesh-tech/mesh-platform";
+var DEFAULT_IGNORE_LINK_PREFIXES = ["node_modules/"];
+function splitFrontMatter(markdown) {
+  const normalized = markdown.replace(/^\uFEFF/, "");
+  if (!normalized.startsWith("---\n") && !normalized.startsWith("---\r\n")) {
+    return { data: {}, body: markdown, hasFrontMatter: false };
+  }
+  const end = normalized.indexOf("\n---", 4);
+  if (end === -1) return { data: {}, body: markdown, hasFrontMatter: false };
+  const rawBlock = normalized.slice(4, end);
+  const bodyStart = normalized.indexOf("\n", end + 1);
+  const body = (bodyStart === -1 ? "" : normalized.slice(bodyStart + 1)).replace(/^\r?\n/, "");
+  try {
+    const data = parseYaml(rawBlock);
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      return {
+        data,
+        body,
+        hasFrontMatter: true
+      };
+    }
+  } catch {
+  }
+  return { data: {}, body, hasFrontMatter: true };
+}
+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);
+    return /^[\w .,'’()/-]+$/.test(text) ? `${key}: ${text}` : `${key}: ${JSON.stringify(text)}`;
+  });
+  return `---
+${lines.join("\n")}
+---
+
+${body.replace(/^\s*\n/, "")}`;
+}
+function firstHeading(body) {
+  let inFence = false;
+  for (const line of body.split("\n")) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const match = /^#\s+(.+?)\s*#*\s*$/.exec(line);
+    if (match) return match[1].trim();
+  }
+  return void 0;
+}
+function titleizeStem(stem) {
+  const words = stem.replace(/[-_]+/g, " ").trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function deriveTitle(frontMatter, body, source) {
+  const fmTitle = frontMatter.title;
+  if (typeof fmTitle === "string" && fmTitle.trim()) return fmTitle.trim();
+  const heading = firstHeading(body);
+  if (heading) return heading;
+  const stem = path2.posix.basename(source).replace(/\.md$/i, "");
+  return titleizeStem(stem);
+}
+function scanLinks(markdown) {
+  const hits = [];
+  const lines = markdown.split("\n");
+  let offset = 0;
+  let inFence = null;
+  for (const line of lines) {
+    const fenceMatch = /^(\s{0,3})(`{3,}|~{3,})/.exec(line);
+    if (fenceMatch) {
+      if (!inFence) {
+        inFence = { marker: fenceMatch[2][0] };
+      } else if (fenceMatch[2].startsWith(inFence.marker)) {
+        inFence = null;
+      }
+      offset += line.length + 1;
+      continue;
+    }
+    if (inFence) {
+      offset += line.length + 1;
+      continue;
+    }
+    const refDef = /^ {0,3}\[[^\]]+\]:\s*(\S+)/.exec(line);
+    if (refDef) {
+      const href = refDef[1];
+      const start = offset + line.indexOf(href);
+      hits.push({ start, end: start + href.length, href });
+      offset += line.length + 1;
+      continue;
+    }
+    let i = 0;
+    while (i < line.length) {
+      const ch = line[i];
+      if (ch === "`") {
+        const run = /^`+/.exec(line.slice(i))[0];
+        const close = line.indexOf(run, i + run.length);
+        i = close === -1 ? line.length : close + run.length;
+        continue;
+      }
+      if (ch === "<") {
+        const close = line.indexOf(">", i);
+        i = close === -1 ? line.length : close + 1;
+        continue;
+      }
+      if (ch === "!" && line[i + 1] === "[") {
+        i = scanBracketLink(line, i + 1, offset, hits);
+        continue;
+      }
+      if (ch === "[") {
+        i = scanBracketLink(line, i, offset, hits);
+        continue;
+      }
+      i++;
+    }
+    offset += line.length + 1;
+  }
+  return hits;
+}
+function scanBracketLink(line, open, lineOffset, hits) {
+  const closeBracket = line.indexOf("]", open);
+  if (closeBracket === -1) return line.length;
+  if (line[closeBracket + 1] !== "(") return closeBracket + 1;
+  let j = closeBracket + 2;
+  while (j < line.length && /\s/.test(line[j])) j++;
+  if (line[j] === "<") {
+    const end = line.indexOf(">", j);
+    if (end === -1) return line.length;
+    hits.push({
+      start: lineOffset + j + 1,
+      end: lineOffset + end,
+      href: line.slice(j + 1, end)
+    });
+    return end + 1;
+  }
+  const closeParen = line.indexOf(")", j);
+  if (closeParen === -1) return line.length;
+  const inner = line.slice(j, closeParen).trim();
+  const space = inner.search(/\s/);
+  const href = space === -1 ? inner : inner.slice(0, space);
+  if (href) {
+    const start = lineOffset + line.indexOf(href, j);
+    hits.push({ start, end: start + href.length, href });
+  }
+  return closeParen + 1;
+}
+function stripHtmlComments(body) {
+  const lines = body.split("\n");
+  const out = [];
+  let inFence = false;
+  let inComment = false;
+  for (const line of lines) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      if (!inComment) inFence = !inFence;
+      if (!inComment) out.push(line);
+      continue;
+    }
+    if (inFence) {
+      out.push(line);
+      continue;
+    }
+    let rest = line;
+    let rebuilt = "";
+    while (rest.length > 0) {
+      if (inComment) {
+        const end = rest.indexOf("-->");
+        if (end === -1) {
+          rest = "";
+          break;
+        }
+        inComment = false;
+        rest = rest.slice(end + 3);
+        continue;
+      }
+      const start = rest.indexOf("<!--");
+      if (start === -1) {
+        rebuilt += rest;
+        break;
+      }
+      rebuilt += rest.slice(0, start);
+      inComment = true;
+      rest = rest.slice(start + 4);
+    }
+    if (rebuilt.trim() !== "" || !inComment)
+      out.push(rebuilt.replace(/\s+$/, ""));
+  }
+  return out.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+function isAbsoluteHref(href) {
+  return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(href);
+}
+function normalizeRepoPath(value) {
+  return path2.posix.normalize(value.replace(/\\/g, "/")).replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function splitHash(href) {
+  const index = href.indexOf("#");
+  return index === -1 ? [href, ""] : [href.slice(0, index), href.slice(index + 1)];
+}
+function resolveLink(args) {
+  const { href, pageRoute: pageRoute2, sourceDir, sourceIndex, routes, repoUrl } = args;
+  if (href.startsWith("#") || isAbsoluteHref(href)) return { href };
+  if (args.ignoreLinkPrefixes.some((prefix) => href.startsWith(prefix)))
+    return { href };
+  const [rawTarget, rawHash] = splitHash(href);
+  const hash = rawHash ? `#${rawHash}` : "";
+  if (rawTarget === "") return { href };
+  if (rawTarget.startsWith("/")) {
+    const route = rawTarget.replace(/\/$/, "") || "/";
+    return routes.has(route) ? { href: `${route}${hash}` } : { href, issue: { kind: "broken", page: pageRoute2, href } };
+  }
+  const repoPath = normalizeRepoPath(path2.posix.join(sourceDir, rawTarget));
+  const page = sourceIndex.get(repoPath);
+  if (page) return { href: `${page.route}${hash}` };
+  for (const candidate of [`${repoPath}/index.md`]) {
+    const indexPage = sourceIndex.get(normalizeRepoPath(candidate));
+    if (indexPage) return { href: `${indexPage.route}${hash}` };
+  }
+  const kind = args.pathKind(repoPath);
+  if (kind !== null) {
+    const base = repoUrl.replace(/\/$/, "").replace(/\/(blob|tree)$/, "");
+    return {
+      href: `${base}/${kind === "dir" ? "tree" : "blob"}/main/${repoPath}${hash}`,
+      issue: { kind: "external", page: pageRoute2, href }
+    };
+  }
+  return { href, issue: { kind: "broken", page: pageRoute2, href } };
+}
+function rewriteLinks(args) {
+  const issues = [];
+  const hits = scanLinks(args.body);
+  if (hits.length === 0) return { body: args.body, issues };
+  const sourceDir = path2.posix.dirname(args.page.source);
+  let out = "";
+  let cursor = 0;
+  for (const hit of hits) {
+    const resolution = resolveLink({
+      href: hit.href,
+      pageRoute: args.page.route,
+      sourceDir,
+      sourceIndex: args.sourceIndex,
+      routes: args.routes,
+      ignoreLinkPrefixes: args.ignoreLinkPrefixes,
+      pathKind: args.pathKind,
+      repoUrl: args.repoUrl
+    });
+    out += args.body.slice(cursor, hit.start) + resolution.href;
+    cursor = hit.end;
+    if (resolution.issue) issues.push(resolution.issue);
+  }
+  out += args.body.slice(cursor);
+  return { body: out, issues };
+}
+function pageRoute(page) {
+  const joined = [page.root.slug, page.routePath].filter(Boolean).join("/");
+  return `/${joined}`.replace(/\/$/, "") || "/";
+}
+function pageFilePath(route) {
+  return route === "/" ? "index.md" : `${route.slice(1)}.md`;
+}
+function assemblePortal(options) {
+  const { repoRoot, discovery, outDir } = options;
+  const repoUrl = options.repoUrl ?? DEFAULT_REPO_URL;
+  const ignoreLinkPrefixes = options.ignoreLinkPrefixes ?? DEFAULT_IGNORE_LINK_PREFIXES;
+  const pages = discovery.pages.map((page) => {
+    const route = pageRoute(page);
+    return {
+      source: page.source,
+      route,
+      filePath: pageFilePath(route),
+      title: "",
+      sectionTitle: page.root.config.title,
+      sectionOrder: page.root.config.order,
+      sectionSlug: page.root.slug
+    };
+  });
+  const sourceIndex = new Map(
+    pages.map((p) => [normalizeRepoPath(p.source), p])
+  );
+  const routes = new Set(pages.map((p) => p.route));
+  const brokenLinks = [];
+  const externalLinks = [];
+  rmSync(outDir, { recursive: true, force: true });
+  mkdirSync(outDir, { recursive: true });
+  for (const page of pages) {
+    const raw = readFileSync2(path2.join(repoRoot, page.source), "utf-8");
+    const frontMatter = splitFrontMatter(raw);
+    const title = deriveTitle(frontMatter.data, frontMatter.body, page.source);
+    page.title = title;
+    const order = frontMatter.data.order;
+    if (typeof order === "number" && Number.isFinite(order)) page.order = order;
+    const rewritten = rewriteLinks({
+      body: stripHtmlComments(frontMatter.body),
+      page,
+      sourceIndex,
+      routes,
+      ignoreLinkPrefixes,
+      pathKind: (rel) => pathKind(path2.join(repoRoot, rel)),
+      repoUrl
+    });
+    for (const issue of rewritten.issues) {
+      (issue.kind === "broken" ? brokenLinks : externalLinks).push(issue);
+    }
+    const outData = { ...frontMatter.data, title };
+    const blobBase = repoUrl.replace(/\/$/, "").replace(/\/(blob|tree)$/, "");
+    const sourceNote = `
+
+---
+
+<sub>Source: [\`${page.source}\`](${blobBase}/blob/main/${page.source}) \u2014 edit that file, not this page.</sub>
+`;
+    const outFile = path2.join(outDir, page.filePath);
+    mkdirSync(path2.dirname(outFile), { recursive: true });
+    writeFileSync(
+      outFile,
+      joinFrontMatter(outData, rewritten.body.trimEnd() + sourceNote)
+    );
+  }
+  const navigation = buildNavigation(pages);
+  const reservedViolations = pages.map((p) => p.filePath).filter((filePath) => hasReservedSegment(filePath));
+  const publishManifest = {
+    version: 1,
+    count: pages.length,
+    sources: pages.map((p) => p.source).sort()
+  };
+  return {
+    outDir,
+    pages,
+    navigation,
+    brokenLinks,
+    externalLinks,
+    publishManifest,
+    reservedViolations
+  };
+}
+function titleizeDir(name) {
+  return titleizeStem(name);
+}
+function buildNavigation(pages) {
+  const sections = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    const key = page.sectionSlug;
+    if (!sections.has(key)) {
+      sections.set(key, {
+        title: page.sectionTitle,
+        order: page.sectionOrder,
+        slug: page.sectionSlug,
+        pages: []
+      });
+    }
+    sections.get(key).pages.push(page);
+  }
+  const sortedSections = [...sections.values()].sort(
+    (a, b) => a.order - b.order || a.title.localeCompare(b.title)
+  );
+  const sortPages = (list) => [...list].sort(
+    (a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER) || a.filePath.localeCompare(b.filePath)
+  );
+  const docRef = (page) => {
+    const file = page.filePath.replace(/\.md$/, "");
+    return page.route === `/${file}` ? file : { type: "doc", file, path: page.route };
+  };
+  const items = [];
+  for (const section of sortedSections) {
+    const indexPage = section.pages.find(
+      (p) => p.route === `/${section.slug}` || section.slug === "" && p.route === "/"
+    );
+    const rest = section.pages.filter((p) => p !== indexPage);
+    const rootPages = [];
+    const dirs = /* @__PURE__ */ new Map();
+    for (const page of rest) {
+      const rel = page.route.replace(/^\//, "");
+      const sectionPrefix = section.slug ? `${section.slug}/` : "";
+      const relParts = (sectionPrefix && rel.startsWith(sectionPrefix) ? rel.slice(sectionPrefix.length) : rel).split("/").filter(Boolean);
+      if (relParts.length <= 1) {
+        rootPages.push(page);
+        continue;
+      }
+      const dirKey = relParts.slice(0, -1).join("/");
+      if (!dirs.has(dirKey)) {
+        dirs.set(dirKey, {
+          label: titleizeDir(relParts[relParts.length - 2]),
+          routePath: relParts.slice(0, -1).join("/"),
+          pages: [],
+          dirs: /* @__PURE__ */ new Map()
+        });
+      }
+      dirs.get(dirKey).pages.push(page);
+    }
+    const byRoute = new Map(section.pages.map((p) => [p.route, p]));
+    const childItems = sortPages(rootPages).map(docRef);
+    for (const dir of [...dirs.values()].sort(
+      (a, b) => a.routePath.localeCompare(b.routePath)
+    )) {
+      const dirRoute = `/${[section.slug, dir.routePath].filter(Boolean).join("/")}`.replace(
+        /\/$/,
+        ""
+      ) || "/";
+      const dirIndex = byRoute.get(dirRoute);
+      const grandchildren = sortPages(
+        dir.pages.filter((p) => p !== dirIndex)
+      ).map(docRef);
+      if (grandchildren.length === 0 && dirIndex) {
+        childItems.push(docRef(dirIndex));
+        continue;
+      }
+      childItems.push({
+        type: "category",
+        label: dir.label,
+        ...dirIndex ? { link: docRef(dirIndex) } : {},
+        items: grandchildren
+      });
+    }
+    items.push({
+      type: "category",
+      label: section.title,
+      collapsible: false,
+      ...indexPage ? { link: docRef(indexPage) } : {},
+      items: childItems
+    });
+  }
+  return [
+    {
+      type: "category",
+      label: "Documentation",
+      link: { type: "doc", file: "index", path: "/" },
+      items
+    }
+  ];
+}
+function renderZudokuConfig(args) {
+  const versionLine = args.baseline ? `Documents @mesh-tech/* ${args.baseline} \xB7 built from ${args.commit ?? "unknown"}` : `Local build \xB7 ${args.commit ?? "unknown"}`;
+  const config = {
+    metadata: {
+      title: args.title,
+      description: args.description
+    },
+    site: {
+      title: args.title,
+      logoUrl: "/",
+      footer: {
+        copyright: `${versionLine} \xB7 /version.json`
+      }
+    },
+    theme: "THEME_IMPORT",
+    navigation: args.navigation,
+    docs: {
+      files: ["/content/**/*.{md,mdx}"],
+      defaultOptions: {
+        toc: true,
+        showLastModified: false
+      }
+    },
+    redirects: []
+    // Search is Zudoku's built-in Pagefind index — no config needed.
+  };
+  const json = JSON.stringify(config, null, 2).replace(
+    `"THEME_IMPORT"`,
+    "portalTheme"
+  );
+  return `/**
+ * GENERATED by \`mesh docs portal\` \u2014 do not edit.
+ *
+ * The navigation array is derived from the repo's docs.json roots and the
+ * markdown tree beneath them. To change what the site publishes, change the
+ * tree; to change section labels or order, change the root's docs.json.
+ * Regenerate: pnpm exec mesh docs portal --assemble-only
+ */
+import type { ZudokuConfig } from "zudoku";
+import { portalTheme } from "./theme.js";
+
+const config: ZudokuConfig = ${json};
+
+export default config;
+`;
+}
+function renderVersionJson(args) {
+  return `${JSON.stringify(
+    {
+      meshBaseline: args.baseline ?? null,
+      commit: args.commit,
+      builtAt: args.builtAt
+    },
+    null,
+    2
+  )}
+`;
+}
+function currentCommit(repoRoot) {
+  try {
+    return execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+      cwd: repoRoot,
+      encoding: "utf-8"
+    }).trim();
+  } catch {
+    return "unknown";
+  }
+}
+function currentBaseline(repoRoot) {
+  try {
+    const pkg = JSON.parse(
+      readFileSync2(path2.join(repoRoot, "packages/app-kit/package.json"), "utf-8")
+    );
+    return pkg.version;
+  } catch {
+    return void 0;
+  }
+}
+function publishSetAtRef(repoRoot, ref) {
+  const git = (gitArgs) => execFileSync("git", gitArgs, {
+    cwd: repoRoot,
+    encoding: "utf-8",
+    maxBuffer: 64 * 1024 * 1024
+  });
+  const allFiles = git(["ls-tree", "-r", "--name-only", ref]).split("\n").filter(Boolean);
+  const docsJsonPaths = allFiles.filter(
+    (file) => file === "docs.json" || file.endsWith("/docs.json")
+  );
+  const published = /* @__PURE__ */ new Set();
+  for (const docsJsonPath of docsJsonPaths) {
+    const rootDir = docsJsonPath === "docs.json" ? "" : docsJsonPath.slice(0, -"/docs.json".length);
+    if (rootDir && hasReservedSegment(rootDir)) continue;
+    let config;
+    try {
+      config = JSON.parse(git(["show", `${ref}:${docsJsonPath}`]));
+    } catch {
+      continue;
+    }
+    const prefix = rootDir ? `${rootDir}/` : "";
+    for (const file of allFiles) {
+      if (!file.startsWith(prefix) || !file.toLowerCase().endsWith(".md"))
+        continue;
+      const rel = file.slice(prefix.length);
+      if (hasReservedSegment(rel)) continue;
+      if (path2.posix.basename(file).toLowerCase() === "readme.md") continue;
+      published.add(file);
+    }
+    for (const include of config.include ?? []) {
+      const normalized = include.replace(/\\/g, "/").replace(/^\.\//, "");
+      if (hasReservedSegment(normalized)) continue;
+      if (allFiles.includes(normalized)) published.add(normalized);
+    }
+  }
+  return [...published].sort();
+}
+function diffPublishSets(base, head) {
+  const baseSet = new Set(base);
+  const headSet = new Set(head);
+  return {
+    added: head.filter((source) => !baseSet.has(source)),
+    removed: base.filter((source) => !headSet.has(source))
+  };
+}
+function renderPublishSetSummary(manifest, diff) {
+  const lines = [
+    `## Docs portal publish set`,
+    ``,
+    `**${manifest.count} pages publish** from this tree.`,
+    ``
+  ];
+  if (diff && (diff.added.length > 0 || diff.removed.length > 0)) {
+    lines.push(`### Changes vs the merge base`, ``);
+    for (const source of diff.added) lines.push(`- \u2795 \`${source}\``);
+    for (const source of diff.removed) lines.push(`- \u2796 \`${source}\``);
+    lines.push(
+      ``,
+      `Growing the public surface is a deliberate act \u2014 a reviewer should see this list.`
+    );
+  } else if (diff) {
+    lines.push(`No change vs the merge base.`);
+  }
+  lines.push(``, `<details><summary>Full publish set</summary>`, ``);
+  for (const source of manifest.sources) lines.push(`- \`${source}\``);
+  lines.push(``, `</details>`);
+  return `${lines.join("\n")}
+`;
+}
+
+// packages/mesh-cli/src/docs/portal.ts
+var DOCS_APP_DIR = "apps/docs";
+var CONTENT_DIR = "content";
+var GENERATED_CONFIG = "zudoku.config.ts";
+var PUBLISH_MANIFEST = "publish-manifest.json";
+var VERSION_JSON_DIR = "public";
+var VERSION_JSON = "version.json";
+var SITE_TITLE = "Mesh Developer Portal";
+var SITE_DESCRIPTION = "Build and run financial-services apps on Mesh Platform with the mesh developer CLI.";
+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) {
+    const manifestPath = args.outDir.includes(tmpdir()) ? path3.join(args.outDir, PUBLISH_MANIFEST) : path3.join(args.outDir, "..", PUBLISH_MANIFEST);
+    writeFileSync2(
+      manifestPath,
+      `${JSON.stringify(assembled.publishManifest, null, 2)}
+`
+    );
+    if (args.configOut) {
+      writeFileSync2(
+        args.configOut,
+        renderZudokuConfig({
+          navigation: assembled.navigation,
+          title: SITE_TITLE,
+          description: SITE_DESCRIPTION,
+          baseline: currentBaseline(args.repoRoot),
+          commit: currentCommit(args.repoRoot)
+        })
+      );
+      const versionDir = path3.join(
+        path3.dirname(args.configOut),
+        VERSION_JSON_DIR
+      );
+      mkdirSync2(versionDir, { recursive: true });
+      writeFileSync2(
+        path3.join(versionDir, VERSION_JSON),
+        renderVersionJson({
+          baseline: currentBaseline(args.repoRoot),
+          commit: currentCommit(args.repoRoot),
+          builtAt: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      );
+    }
+  }
+  return { assembled, errors };
+}
+function reportAssembly(result) {
+  const { assembled } = result;
+  logSuccess(
+    `Assembled ${assembled.pages.length} pages from ${new Set(assembled.pages.map((p) => p.sectionTitle)).size} sections \u2192 ${assembled.outDir}`
+  );
+  if (assembled.externalLinks.length > 0) {
+    const unique = new Set(
+      assembled.externalLinks.map((issue) => `${issue.page} \u2192 ${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}`);
+    }
+  }
+}
+async function checkPortal(args) {
+  const scratch = mkdtempSync(path3.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)}
+`
+    );
+  }
+  if (args.manifestOut) {
+    mkdirSync2(path3.dirname(args.manifestOut), { recursive: true });
+    writeFileSync2(
+      args.manifestOut,
+      `${JSON.stringify(result.assembled.publishManifest, null, 2)}
+`
+    );
+  }
+  if (args.diffBase) {
+    writePublishSetSummary(
+      args.repoRoot,
+      args.diffBase,
+      result.assembled.publishManifest
+    );
+  }
+  return failures;
+}
+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(`
+${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})`);
+    }
+  }
+}
+function runZudoku(args) {
+  const cliArgs = args.mode === "dev" ? ["dev", "--port", String(args.port ?? 3e3)] : ["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));
+  });
+}
+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 = path3.join(repoRoot, DOCS_APP_DIR);
+  const outDir = opts.out ? path3.resolve(repoRoot, opts.out) : path3.join(appDir, CONTENT_DIR);
+  const result = runAssemble({
+    repoRoot,
+    outDir,
+    configOut: path3.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 ${path3.relative(repoRoot, outDir)} \u2014 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 !== void 0 ? { port } : {}
+  });
+  if (code !== 0) throw new Error(`zudoku ${mode} exited with code ${code}`);
+  if (mode === "build") {
+    logSuccess(
+      `Portal built \u2192 ${path3.join(path3.relative(repoRoot, appDir), "dist")}`
+    );
+  }
+}
+async function cliReferenceStaleness(repoRoot) {
+  const [
+    { createProgram },
+    { extractCliReference, renderCliReferenceMarkdown }
+  ] = await Promise.all([
+    import("./mesh.program-BIDQBSSI.js"),
+    import("./mesh.cli-reference-H3TOPIET.js")
+  ]);
+  const outPath = path3.join(repoRoot, "docs/portal/generated/cli-reference.md");
+  const markdown = renderCliReferenceMarkdown(
+    extractCliReference(createProgram())
+  );
+  const existing = existsSync2(outPath) ? readFileSync3(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 \u2014 the commander tree changed; regenerate and commit with \`pnpm exec mesh docs cli-reference\``;
+}
+
+// packages/mesh-cli/src/utils/build-info.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import * as fs from "fs";
+import * as path4 from "path";
+import { fileURLToPath } from "url";
+function detectRuntimeMode(modulePath) {
+  return modulePath.split(/[\\/]/).includes("dist") ? "dist" : "source";
+}
+function formatVersionLine(info) {
+  if (info.mode === "source") {
+    const at = [info.commit, info.builtAt].filter(Boolean).join(" ");
+    return `${info.version} (source${at ? ` @ ${at}` : ""})`;
+  }
+  const built = info.builtAt ? ` ${info.builtAt.slice(0, 10)}` : "";
+  const commit = info.commit ? `, commit ${info.commit}` : "";
+  const detail = built || commit ? `${built}${commit}` : " \u2014 build metadata unavailable";
+  return `${info.version} (published build${detail})`;
+}
+function findCliPackageRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 8; i++) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path4.join(dir, "package.json"), "utf-8"));
+      if (pkg.name === "@mesh-tech/mesh-cli") return dir;
+    } catch {
+    }
+    const parent = path4.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function resolveCliRuntime(opts) {
+  const vcs = opts?.vcs ?? true;
+  const here = path4.dirname(fileURLToPath(import.meta.url));
+  const mode = detectRuntimeMode(here);
+  const root = findCliPackageRoot(here);
+  let version = "0.0.0";
+  if (root) {
+    try {
+      version = JSON.parse(fs.readFileSync(path4.join(root, "package.json"), "utf-8")).version ?? version;
+    } catch {
+    }
+  }
+  const info = { version, mode };
+  if (!root) return info;
+  if (mode === "dist") {
+    try {
+      const meta = JSON.parse(
+        fs.readFileSync(path4.join(root, "dist", "build-info.json"), "utf-8")
+      );
+      info.commit = meta.commit;
+      info.builtAt = meta.builtAt;
+    } catch {
+    }
+    return info;
+  }
+  if (!vcs) return info;
+  try {
+    const git = (args) => execFileSync2("git", args, {
+      cwd: root,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }).trim();
+    info.commit = git(["rev-parse", "--short", "HEAD"]);
+    info.builtAt = git(["log", "-1", "--format=%cs"]);
+  } catch {
+  }
+  return info;
+}
+
+export {
+  discoverDocRoots,
+  DOCS_APP_DIR,
+  runAssemble,
+  reportAssembly,
+  runPortalCommand,
+  cliReferenceStaleness,
+  formatVersionLine,
+  resolveCliRuntime
+};