@mandujs/core 0.24.0 → 0.25.1

package/src/content/prebuild.ts

@@ -0,0 +1,400 @@
+/**
+ * Content Prebuild Runner (Issue #196).
+ *
+ * # Purpose
+ *
+ * `mandu dev` manages routes, the bundler, and HMR — but it does NOT
+ * auto-generate files under `content/` that derived scripts produce
+ * (e.g. `scripts/prebuild-docs.ts` writes `content/docs-data.ts`,
+ * `scripts/prebuild-seo.ts` writes `content/sitemap.xml`, …). Without
+ * this module every project has to wire the chain by hand:
+ *
+ *     bun scripts/prebuild-docs.ts && bun scripts/prebuild-seo.ts && mandu dev
+ *
+ * — which is error-prone and fragile on Windows where `&&` chains misbehave
+ * in some shells. Issue #196 asks us to move this into the CLI so `mandu dev`
+ * alone is enough.
+ *
+ * # Contract
+ *
+ *   1. **Discovery**: walk `<rootDir>/scripts/` for any file matching
+ *      `prebuild*.{ts,tsx,js,mjs}`. Sort lexicographically so
+ *      `prebuild-1-xxx` always runs before `prebuild-2-yyy` when the user
+ *      needs ordering control via filename prefix.
+ *
+ *   2. **Execution**: run each script in a fresh `bun` subprocess with
+ *      `stdio: "inherit"` so prebuild logs flow through unchanged. Scripts
+ *      run **sequentially** (the first one's exit must settle before the
+ *      next starts) — parallel execution is tempting but most docs-style
+ *      prebuilds write to the same output dir and race conditions would
+ *      silently corrupt output files.
+ *
+ *   3. **Failure mode**: a non-zero exit from any script aborts the chain
+ *      and surfaces `PrebuildError` to the caller. `mandu dev` decides
+ *      whether to abort (prod) or log + continue (dev) based on caller
+ *      flags — this module does not make that policy decision.
+ *
+ *   4. **Timeout**: per-script 2-minute wall-clock cap, matching the
+ *      policy established by `packages/mcp/src/util/runCommand.ts` (#136).
+ *      Override via `options.timeoutMs` for unusual long-running seeds.
+ *
+ *   5. **No side-effects on empty discovery**: if no scripts are found,
+ *      `runPrebuildScripts` returns `{ ran: 0 }` silently. This is the
+ *      default for projects without a `content/` workflow, so importing
+ *      this module into `dev.ts` must stay invisible to them.
+ *
+ * # Non-goals
+ *
+ *   - NOT a general task-runner. Scripts are pure one-shot generators —
+ *     no daemon / watch / IPC semantics.
+ *   - NOT content-layer integration. This module does not know about
+ *     `defineContentConfig` or the `ContentLayer` class; it purely
+ *     orchestrates `scripts/prebuild-*.ts`.
+ *   - NOT a Bun-only primitive: we use `Bun.spawn` for the subprocess
+ *     because it is cheaper than `node:child_process` and matches the
+ *     rest of the codebase (see MEMORY "child_process.spawn → Bun.spawn
+ *     교체"), but the module exports do not expose any Bun types on the
+ *     public surface.
+ */
+
+import path from "node:path";
+import fs from "node:fs";
+
+// ---------------------------------------------------------------------------
+// Discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Filename shapes we treat as prebuild scripts. Sorted by lexicographic
+ * order after discovery so that `prebuild-01-foo.ts` reliably runs before
+ * `prebuild-02-bar.ts` — the user's ordering knob.
+ *
+ * We include `.mjs` because some projects ship pre-compiled prebuild
+ * scripts in ESM format for CI speed.
+ */
+const PREBUILD_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".mjs"]);
+const PREBUILD_FILENAME_RE = /^prebuild[-_.a-zA-Z0-9]*\.(ts|tsx|js|mjs)$/;
+
+/**
+ * Discover prebuild scripts under `<rootDir>/<scriptsDir>`.
+ *
+ * Returns absolute paths (forward-slash on Windows) sorted lexicographically.
+ * Does NOT touch the filesystem beyond a single `readdir` — symlinks are
+ * treated like regular files (followed by Node's default policy).
+ *
+ * Exported as a named function so the dev-autoprebuild test can exercise
+ * discovery independently of execution.
+ */
+export function discoverPrebuildScripts(
+  rootDir: string,
+  scriptsDir = "scripts",
+): string[] {
+  const scriptsPath = path.resolve(rootDir, scriptsDir);
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(scriptsPath);
+  } catch {
+    // No scripts/ directory — not an error, just an empty discovery.
+    return [];
+  }
+
+  const matched: string[] = [];
+  for (const name of entries) {
+    if (!PREBUILD_FILENAME_RE.test(name)) continue;
+    const ext = path.extname(name);
+    if (!PREBUILD_EXTENSIONS.has(ext)) continue;
+    // Full absolute path — forward-slash on Windows so the log output is
+    // consistent with the rest of the dev logging (see `maskSlotPath` in
+    // `packages/cli/src/commands/dev.ts` for the same normalization
+    // pattern).
+    const abs = path.join(scriptsPath, name).replace(/\\/g, "/");
+    matched.push(abs);
+  }
+  matched.sort((a, b) => a.localeCompare(b));
+  return matched;
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+/**
+ * Error thrown when a prebuild script exits non-zero or times out. The
+ * `scriptPath` + `exitCode` fields are stable so callers can decide
+ * recovery policy without string-matching the message.
+ */
+export class PrebuildError extends Error {
+  readonly scriptPath: string;
+  readonly exitCode: number | null;
+  readonly durationMs: number;
+
+  constructor(
+    message: string,
+    options: {
+      scriptPath: string;
+      exitCode: number | null;
+      durationMs: number;
+      cause?: unknown;
+    },
+  ) {
+    super(message);
+    this.name = "PrebuildError";
+    this.scriptPath = options.scriptPath;
+    this.exitCode = options.exitCode;
+    this.durationMs = options.durationMs;
+    if (options.cause !== undefined) {
+      (this as Error & { cause?: unknown }).cause = options.cause;
+    }
+  }
+}
+
+export interface PrebuildRunnerOptions {
+  /** Project root. Absolute path — we resolve scripts relative to this. */
+  rootDir: string;
+  /**
+   * Relative scripts dir (default: `"scripts"`). Override for projects
+   * that put generators in a non-standard location.
+   */
+  scriptsDir?: string;
+  /**
+   * Per-script wall-clock timeout in milliseconds. Default: 2 minutes,
+   * matching the MCP `runCommand()` convention (#136).
+   */
+  timeoutMs?: number;
+  /**
+   * Called once per discovered script, before the subprocess starts.
+   * Useful for CLI progress logs. Not awaited.
+   */
+  onStart?: (scriptPath: string, index: number, total: number) => void;
+  /**
+   * Called once per script after the subprocess exits (success OR failure).
+   * Always runs before the Promise resolves/rejects.
+   */
+  onFinish?: (result: {
+    scriptPath: string;
+    exitCode: number | null;
+    durationMs: number;
+  }) => void;
+  /**
+   * Injected spawn hook — overridable in tests so we do not have to
+   * actually fork `bun`. Default uses `Bun.spawn` with `stdio: "inherit"`.
+   *
+   * Contract: returns a `{ exited }` with an `exited` Promise that
+   * resolves to the exit code (null on signal / timeout kill). The hook
+   * is responsible for the actual kill on timeout.
+   */
+  spawn?: SpawnHook;
+}
+
+export interface PrebuildResult {
+  ran: number;
+  scripts: Array<{
+    scriptPath: string;
+    exitCode: number | null;
+    durationMs: number;
+  }>;
+}
+
+/**
+ * Spawn shim — kept as an interface so tests can inject a pure-in-memory
+ * replacement without monkey-patching `globalThis.Bun`.
+ */
+export type SpawnHook = (args: {
+  scriptPath: string;
+  cwd: string;
+  timeoutMs: number;
+}) => Promise<{ exitCode: number | null; durationMs: number }>;
+
+/**
+ * Default spawn hook: fork `bun <scriptPath>` with `stdio: "inherit"` so
+ * the user sees prebuild logs on the terminal in real time.
+ *
+ * The `timeoutMs` guard kills the subprocess via SIGTERM (Unix) /
+ * `proc.kill()` (which sends SIGKILL on Windows — Bun's cross-platform
+ * `kill` API). We intentionally do not chain SIGTERM → SIGKILL because
+ * prebuild scripts are short-lived generators: a hung one is a bug the
+ * user should see as a timeout error, not a half-killed zombie.
+ *
+ * `env` is inherited but we strip the inherited `MANDU_PERF` flag so the
+ * prebuild's own perf log output doesn't muddle the dev boot perf trace
+ * — otherwise the user's "dev boot in Nms" numbers include every
+ * prebuild step, which is misleading.
+ */
+export const defaultSpawn: SpawnHook = async ({
+  scriptPath,
+  cwd,
+  timeoutMs,
+}) => {
+  const start = performance.now();
+
+  // Scrub MANDU_PERF so prebuild logs don't leak into `mandu dev` perf
+  // traces. Everything else is inherited.
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k === "MANDU_PERF") continue;
+    if (typeof v === "string") env[k] = v;
+  }
+
+  // Feature-detect Bun.spawn so this module can be imported in Node test
+  // contexts without crashing on module load. Tests that need Bun-less
+  // execution use the `spawn` injection hook anyway.
+  type BunLike = {
+    spawn: (opts: {
+      cmd: string[];
+      cwd?: string;
+      stdio?: readonly [unknown, unknown, unknown];
+      env?: Record<string, string>;
+    }) => {
+      exited: Promise<number>;
+      kill: (signal?: number | string) => void;
+    };
+  };
+  const bun = (globalThis as { Bun?: BunLike }).Bun;
+  if (!bun) {
+    throw new Error(
+      "[Mandu prebuild] Bun.spawn is not available in this environment. " +
+        "Inject a custom `spawn` hook via PrebuildRunnerOptions to run outside Bun.",
+    );
+  }
+
+  const proc = bun.spawn({
+    cmd: ["bun", scriptPath],
+    cwd,
+    stdio: ["inherit", "inherit", "inherit"],
+    env,
+  });
+
+  // Timeout guard. Bun.spawn's `exited` Promise never rejects; it resolves
+  // with the exit code (or null on signal). So we race against a setTimeout
+  // and kill the subprocess if the timer wins.
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    try {
+      proc.kill();
+    } catch {
+      // Ignore — child may already be gone.
+    }
+  }, timeoutMs);
+
+  try {
+    const exitCode = await proc.exited;
+    const durationMs = performance.now() - start;
+    if (timedOut) {
+      throw new PrebuildError(
+        `Prebuild script '${scriptPath}' exceeded timeout (${timeoutMs}ms) and was killed.`,
+        { scriptPath, exitCode: null, durationMs },
+      );
+    }
+    return { exitCode, durationMs };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * Run every `scripts/prebuild-*.ts` in sequence. Resolves with a summary
+ * of which scripts ran and how long each took. Rejects with
+ * `PrebuildError` on the first failure (subsequent scripts are NOT run,
+ * matching the `&&` chain semantics the user relied on before).
+ *
+ * @example
+ * ```ts
+ * await runPrebuildScripts({ rootDir: process.cwd() });
+ * ```
+ */
+export async function runPrebuildScripts(
+  options: PrebuildRunnerOptions,
+): Promise<PrebuildResult> {
+  const {
+    rootDir,
+    scriptsDir = "scripts",
+    timeoutMs = 2 * 60 * 1000,
+    onStart,
+    onFinish,
+    spawn = defaultSpawn,
+  } = options;
+
+  const scripts = discoverPrebuildScripts(rootDir, scriptsDir);
+  if (scripts.length === 0) {
+    return { ran: 0, scripts: [] };
+  }
+
+  const results: PrebuildResult["scripts"] = [];
+  for (let i = 0; i < scripts.length; i++) {
+    const scriptPath = scripts[i];
+    onStart?.(scriptPath, i, scripts.length);
+
+    let exitCode: number | null;
+    let durationMs: number;
+    try {
+      const res = await spawn({ scriptPath, cwd: rootDir, timeoutMs });
+      exitCode = res.exitCode;
+      durationMs = res.durationMs;
+    } catch (err) {
+      if (err instanceof PrebuildError) {
+        onFinish?.({
+          scriptPath: err.scriptPath,
+          exitCode: err.exitCode,
+          durationMs: err.durationMs,
+        });
+        results.push({
+          scriptPath: err.scriptPath,
+          exitCode: err.exitCode,
+          durationMs: err.durationMs,
+        });
+        // Re-throw to abort the chain on failure.
+        throw err;
+      }
+      // Non-PrebuildError rejection — wrap so callers only see one error shape.
+      throw new PrebuildError(
+        `Prebuild script '${scriptPath}' failed: ${err instanceof Error ? err.message : String(err)}`,
+        {
+          scriptPath,
+          exitCode: null,
+          durationMs: 0,
+          cause: err,
+        },
+      );
+    }
+
+    onFinish?.({ scriptPath, exitCode, durationMs });
+    results.push({ scriptPath, exitCode, durationMs });
+
+    if (exitCode !== 0) {
+      throw new PrebuildError(
+        `Prebuild script '${scriptPath}' exited with code ${exitCode}. ` +
+          `Subsequent prebuild scripts were not run.`,
+        { scriptPath, exitCode, durationMs },
+      );
+    }
+  }
+
+  return { ran: results.length, scripts: results };
+}
+
+/**
+ * Determine whether a project appears to use the content/prebuild workflow.
+ * Used by `mandu dev` to decide whether to enable auto-prebuild by default:
+ * projects without `content/` AND without `scripts/prebuild-*.ts` pay no
+ * cost and see no behaviour change.
+ *
+ * Policy: auto-prebuild activates when EITHER
+ *   (a) `<rootDir>/content/` exists (the convention for Astro-style
+ *       content collections), OR
+ *   (b) at least one `scripts/prebuild-*.ts` is discovered.
+ *
+ * Returns `false` in every other case so `mandu dev` stays a pure
+ * pass-through for simple apps.
+ */
+export function shouldAutoPrebuild(rootDir: string, scriptsDir = "scripts"): boolean {
+  const contentDir = path.resolve(rootDir, "content");
+  try {
+    const stat = fs.statSync(contentDir);
+    if (stat.isDirectory()) return true;
+  } catch {
+    // No content/ — fall through to scripts check.
+  }
+  const scripts = discoverPrebuildScripts(rootDir, scriptsDir);
+  return scripts.length > 0;
+}

package/src/content/schema.ts

@@ -0,0 +1,20 @@
+/**
+ * Schema Re-exports (Issue #199)
+ *
+ * Thin re-export shim so content authors can `import { z } from
+ * '@mandujs/core/content'` without pulling `zod` directly into their
+ * `content.config.ts`. This keeps the import path consistent with
+ * how users import `defineCollection`, and it gives us one chokepoint
+ * if we ever need to swap the validation backend or wrap Zod with
+ * Mandu-specific helpers.
+ *
+ * NOTE: we intentionally do NOT add a "fat" z here (no custom helpers,
+ * no `.mandu()` extensions) — keeping it identical to upstream Zod
+ * means `content.config.ts` files stay portable if a project moves
+ * between frameworks.
+ */
+
+import { z } from "zod";
+
+export { z };
+export type { ZodSchema, ZodError, ZodType, ZodTypeAny, infer as Infer } from "zod";

package/src/content/sidebar.ts

@@ -0,0 +1,212 @@
+/**
+ * Sidebar Generator (Issue #199)
+ *
+ * Takes a loaded `Collection` and produces a nested `{ title, href,
+ * children }` tree suitable for rendering a docs sidebar. The goal is
+ * to make the common case (slash-delimited slugs → hierarchical nav)
+ * work with zero config, while leaving escape hatches for projects
+ * with bespoke ordering.
+ *
+ * # Ordering rules
+ *
+ *   1. `order` field from frontmatter (ascending, missing = +Infinity)
+ *   2. Fallback: slug alphabetical
+ *   3. Category-level ordering: a `_category` meta file with an
+ *      `order` field controls sibling order at the parent level —
+ *      deliberately NOT implemented at the MVP; callers that need it
+ *      today can pass a custom `sortNodes` comparator.
+ *
+ * # Draft entries
+ *
+ * When `collection.all()` yields entries with `data.draft === true`,
+ * they are **filtered out by default**. Callers can disable this by
+ * passing `includeDrafts: true` (useful during preview builds).
+ */
+
+import type { Collection, CollectionEntry } from "./collection";
+export type { Collection };
+
+/** A node in the sidebar tree. */
+export interface SidebarNode {
+  title: string;
+  href: string;
+  /** Present only on branch nodes (grouped categories). */
+  children?: SidebarNode[];
+  /** Draft/external flags — populated by the generator, caller-facing. */
+  draft?: boolean;
+}
+
+/** Options controlling sidebar shape and filtering. */
+export interface GenerateSidebarOptions<T> {
+  /**
+   * Href prefix prepended to every node. Defaults to `/` so a slug
+   * of `intro` becomes `/intro`. Projects mounting docs under
+   * `/docs/` should pass `basePath: '/docs'`.
+   */
+  basePath?: string;
+  /**
+   * Extract the title shown in the sidebar. Defaults to
+   * `entry.data.title ?? entry.slug`. Implementations that store
+   * the sidebar label in a different field (e.g. `nav_title`) can
+   * override here.
+   */
+  getTitle?: (entry: CollectionEntry<T>) => string;
+  /**
+   * When true, include entries with `data.draft === true`. Defaults
+   * to false so production builds never leak unpublished pages into
+   * the nav.
+   */
+  includeDrafts?: boolean;
+  /**
+   * Custom comparator applied to siblings at every level. When
+   * omitted, the default (order-then-slug) comparator is used —
+   * consistent with `Collection.all()`'s default sort so the
+   * sidebar order matches the `.all()` order.
+   */
+  sortNodes?: (a: SidebarNode, b: SidebarNode, depth: number) => number;
+  /**
+   * When a directory has no own "index" entry, synthesize a branch
+   * node from the directory name. Default: true. Disable when a
+   * project prefers flat nav with all leaves at root.
+   */
+  synthesizeGroups?: boolean;
+}
+
+interface InternalNode {
+  title: string;
+  href: string;
+  order: number;
+  draft: boolean;
+  slugSegments: string[];
+  children: Map<string, InternalNode>;
+  /** Source entry if this node corresponds to a real file. */
+  entry?: CollectionEntry<unknown>;
+}
+
+/**
+ * Build a sidebar tree from a collection. Awaits `collection.all()`
+ * internally so callers don't need to load beforehand.
+ */
+export async function generateSidebar<T>(
+  collection: Collection<T>,
+  options: GenerateSidebarOptions<T> = {}
+): Promise<SidebarNode[]> {
+  const {
+    basePath = "/",
+    getTitle,
+    includeDrafts = false,
+    sortNodes,
+    synthesizeGroups = true,
+  } = options;
+  const entries = await collection.all();
+  const visible = includeDrafts
+    ? entries
+    : entries.filter((e) => !(e.data as { draft?: unknown })?.draft);
+
+  const root = new Map<string, InternalNode>();
+  for (const entry of visible) {
+    insertEntry(root, entry, getTitle, basePath, synthesizeGroups);
+  }
+
+  const tree = toSidebarNodes(root, basePath, synthesizeGroups);
+  sortTree(tree, 0, sortNodes);
+  return tree;
+}
+
+function insertEntry<T>(
+  root: Map<string, InternalNode>,
+  entry: CollectionEntry<T>,
+  getTitle: ((entry: CollectionEntry<T>) => string) | undefined,
+  basePath: string,
+  synthesizeGroups: boolean
+): void {
+  const segments = entry.slug === "" ? [""] : entry.slug.split("/");
+  let cursor = root;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    const isLeaf = i === segments.length - 1;
+    let node = cursor.get(seg);
+    if (!node) {
+      node = {
+        title: seg || "index",
+        href: joinHref(basePath, segments.slice(0, i + 1).join("/")),
+        order: Number.POSITIVE_INFINITY,
+        draft: false,
+        slugSegments: segments.slice(0, i + 1),
+        children: new Map(),
+      };
+      cursor.set(seg, node);
+    }
+    if (isLeaf) {
+      // Attach entry data to this node — overrides synthesized title.
+      node.entry = entry as CollectionEntry<unknown>;
+      node.title = getTitle
+        ? getTitle(entry)
+        : typeof (entry.data as { title?: unknown })?.title === "string"
+          ? String((entry.data as { title: string }).title)
+          : entry.slug || "index";
+      const rawOrder = (entry.data as { order?: unknown })?.order;
+      if (typeof rawOrder === "number") node.order = rawOrder;
+      node.draft = Boolean((entry.data as { draft?: unknown })?.draft);
+      node.href = joinHref(basePath, entry.slug);
+    } else if (!synthesizeGroups) {
+      // When groups are disabled, promote deeply-nested leaves to
+      // flat root entries. We still traverse for consistent sorting.
+      cursor = node.children;
+      continue;
+    }
+    cursor = node.children;
+  }
+}
+
+function toSidebarNodes(
+  map: Map<string, InternalNode>,
+  _basePath: string,
+  _synthesizeGroups: boolean
+): SidebarNode[] {
+  const out: SidebarNode[] = [];
+  for (const node of map.values()) {
+    const children =
+      node.children.size > 0
+        ? toSidebarNodes(node.children, _basePath, _synthesizeGroups)
+        : undefined;
+    const sidebarNode: SidebarNode = {
+      title: node.title,
+      href: node.href,
+    };
+    if (node.draft) sidebarNode.draft = true;
+    if (children) sidebarNode.children = children;
+    out.push(sidebarNode);
+  }
+  return out;
+}
+
+function sortTree(
+  nodes: SidebarNode[],
+  depth: number,
+  custom: ((a: SidebarNode, b: SidebarNode, depth: number) => number) | undefined
+): void {
+  // Fallback comparator: order field via per-node metadata is lost in
+  // the conversion to SidebarNode (intentionally — the public surface
+  // is title/href), so sort by title with a numeric-aware collator so
+  // "10-foo" sorts after "2-foo" for authors prefixing filenames.
+  const fallback = (a: SidebarNode, b: SidebarNode): number =>
+    a.title.localeCompare(b.title, undefined, { numeric: true });
+  nodes.sort((a, b) => {
+    if (custom) {
+      const c = custom(a, b, depth);
+      if (c !== 0) return c;
+    }
+    return fallback(a, b);
+  });
+  for (const node of nodes) {
+    if (node.children) sortTree(node.children, depth + 1, custom);
+  }
+}
+
+function joinHref(base: string, slug: string): string {
+  const normalizedBase = base.endsWith("/") ? base.slice(0, -1) : base;
+  if (!slug) return normalizedBase || "/";
+  const normalizedSlug = slug.startsWith("/") ? slug.slice(1) : slug;
+  return `${normalizedBase}/${normalizedSlug}`.replace(/\/+/g, "/");
+}