@mandujs/core 0.53.2 → 0.54.0

package/src/content/prebuild.ts

@@ -1,636 +1,636 @@
-/**
- * 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.
- *
- *      **Error surface (Issue #203)**: when a script exits non-zero we
- *      tail its stdout/stderr (last 10 lines of each) into the error
- *      message so the user can see WHY it failed without scrolling back
- *      through the terminal. When a spawn rejection is a real `Error`
- *      (e.g. `ENOENT`) we propagate its `message` and attach `cause` so
- *      `err.cause?.stack` is recoverable — fixing the "non-Error thrown"
- *      ghost stack traces reporters saw pre-#203.
- *
- *   4. **Timeout (Issue #203 — configurable)**: per-script wall-clock cap.
- *      Default is 2 minutes (matching `packages/mcp/src/util/runCommand.ts`
- *      #136). Override precedence, highest first:
- *
- *        a. `options.timeoutMs` (explicit caller arg)
- *        b. `MANDU_PREBUILD_TIMEOUT_MS` environment variable
- *        c. `ManduConfig.dev.prebuildTimeoutMs` (threaded through by the
- *           CLI in `packages/cli/src/commands/dev.ts`)
- *        d. Default: 120_000 ms
- *
- *      When the timer fires we throw `PrebuildTimeoutError` with the
- *      script path + limit so `error.message` alone carries enough info
- *      to let the user pick their override path without re-reading docs.
- *
- *   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)$/;
-
-/**
- * Default per-script timeout. Matches the MCP `runCommand()` convention
- * (#136). Exported so `@mandujs/core` consumers (validators, tests) can
- * reference the same constant instead of re-hardcoding `2 * 60 * 1000`.
- */
-export const DEFAULT_PREBUILD_TIMEOUT_MS = 2 * 60 * 1000;
-
-/**
- * Env var name for the runtime override. Checked inside
- * `resolvePrebuildTimeout` when the caller does not pass an explicit
- * `timeoutMs`. Invalid values (non-numeric, <= 0) are ignored with a
- * single stderr warning so a typo does not silently break the default.
- */
-export const PREBUILD_TIMEOUT_ENV = "MANDU_PREBUILD_TIMEOUT_MS";
-
-/**
- * Resolve the timeout to apply for a single prebuild script, with
- * precedence (highest first):
- *
- *   1. `explicit` argument — if the CLI or a test passes an explicit
- *      `timeoutMs`, we honour it verbatim (no env lookup). This keeps
- *      the injected-spawn unit tests deterministic.
- *   2. `MANDU_PREBUILD_TIMEOUT_MS` environment variable (runtime knob
- *      for ops — set once in CI / docker env without re-deploying code).
- *   3. `DEFAULT_PREBUILD_TIMEOUT_MS`.
- *
- * Separated from `runPrebuildScripts` so the CLI can log the resolved
- * value without re-implementing the lookup.
- */
-export function resolvePrebuildTimeout(explicit?: number): number {
-  if (typeof explicit === "number" && explicit > 0) {
-    return explicit;
-  }
-  const envRaw = process.env[PREBUILD_TIMEOUT_ENV];
-  if (typeof envRaw === "string" && envRaw.length > 0) {
-    const parsed = Number(envRaw);
-    if (Number.isFinite(parsed) && parsed > 0) {
-      return parsed;
-    }
-    // Warn once per process — a typoed env var silently falling back to
-    // the default is the kind of issue #203 was reported to fix.
-    console.warn(
-      `[Mandu prebuild] ignoring invalid ${PREBUILD_TIMEOUT_ENV}='${envRaw}' (expected positive number of milliseconds). Falling back to default ${DEFAULT_PREBUILD_TIMEOUT_MS}ms.`,
-    );
-  }
-  return DEFAULT_PREBUILD_TIMEOUT_MS;
-}
-
-/**
- * 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 when we could not
- * complete the spawn (e.g. `bun` binary missing, ENOENT on the script
- * path). The `scriptPath` + `exitCode` fields are stable so callers can
- * decide recovery policy without string-matching the message.
- *
- * Issue #203: when wrapping an inner `Error`, we preserve the inner
- * `.message` (shown in the message) AND set `this.cause = err` so
- * runtimes that render `err.cause` get the full stack. Previously we
- * sometimes lost the inner error entirely, producing a useless
- * `"non-Error thrown"` surface.
- */
-export class PrebuildError extends Error {
-  readonly scriptPath: string;
-  readonly exitCode: number | null;
-  readonly durationMs: number;
-  /** Last ~10 lines of stdout captured from the child process, if any. */
-  readonly stdoutTail?: string;
-  /** Last ~10 lines of stderr captured from the child process, if any. */
-  readonly stderrTail?: string;
-
-  constructor(
-    message: string,
-    options: {
-      scriptPath: string;
-      exitCode: number | null;
-      durationMs: number;
-      cause?: unknown;
-      stdoutTail?: string;
-      stderrTail?: string;
-    },
-  ) {
-    super(message);
-    this.name = "PrebuildError";
-    this.scriptPath = options.scriptPath;
-    this.exitCode = options.exitCode;
-    this.durationMs = options.durationMs;
-    if (options.stdoutTail !== undefined) this.stdoutTail = options.stdoutTail;
-    if (options.stderrTail !== undefined) this.stderrTail = options.stderrTail;
-    if (options.cause !== undefined) {
-      (this as Error & { cause?: unknown }).cause = options.cause;
-    }
-  }
-}
-
-/**
- * Error thrown specifically when the per-script wall-clock timer elapses
- * before the subprocess exits. Separate class (a subclass of
- * `PrebuildError`) so callers can pattern-match:
- *
- *     if (err instanceof PrebuildTimeoutError) { showTimeoutHint(); }
- *     else if (err instanceof PrebuildError)   { showGenericHint(); }
- *
- * Without the subclass they would have to grep the `.message` string,
- * which is the exact anti-pattern Issue #203 flagged.
- *
- * The message always ends with an actionable hint naming the three
- * override paths (config field, env var, CLI flag) so the user can pick
- * one without reading the docs.
- */
-export class PrebuildTimeoutError extends PrebuildError {
-  readonly timeoutMs: number;
-
-  constructor(options: {
-    scriptPath: string;
-    timeoutMs: number;
-    durationMs: number;
-    stdoutTail?: string;
-    stderrTail?: string;
-  }) {
-    const { scriptPath, timeoutMs, durationMs } = options;
-    super(
-      `PrebuildTimeoutError: ${scriptPath} exceeded ${timeoutMs}ms (set dev.prebuildTimeoutMs in mandu.config.ts or ${PREBUILD_TIMEOUT_ENV} env var to override).`,
-      {
-        scriptPath,
-        exitCode: null,
-        durationMs,
-        stdoutTail: options.stdoutTail,
-        stderrTail: options.stderrTail,
-      },
-    );
-    this.name = "PrebuildTimeoutError";
-    this.timeoutMs = timeoutMs;
-  }
-}
-
-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. Precedence matches
-   * `resolvePrebuildTimeout`: explicit arg > `MANDU_PREBUILD_TIMEOUT_MS`
-   * > `DEFAULT_PREBUILD_TIMEOUT_MS` (120_000).
-   *
-   * The CLI threads `ManduConfig.dev.prebuildTimeoutMs` into this field
-   * so end-users typically configure the timeout declaratively without
-   * passing an arg to this API.
-   */
-  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 `{ exitCode, durationMs }`. May also return
-   * `stdoutTail` / `stderrTail` strings (the default spawn does not —
-   * it uses `stdio: "inherit"` so there is no captured output to tail).
-   * 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`.
- *
- * The hook is expected to self-enforce `timeoutMs` by killing the child
- * when the timer fires, then throwing `PrebuildTimeoutError`. The
- * default spawn follows this pattern. Custom hooks that skip the kill
- * are responsible for any consequent zombie.
- */
-export type SpawnHook = (args: {
-  scriptPath: string;
-  cwd: string;
-  timeoutMs: number;
-}) => Promise<{
-  exitCode: number | null;
-  durationMs: number;
-  stdoutTail?: string;
-  stderrTail?: string;
-}>;
-
-/**
- * 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.
- *
- * Note: `stdio: "inherit"` means we cannot capture stdout/stderr to tail
- * into the error message. The captured-tail feature is exercised by
- * injected spawn hooks in the test suite and by any future
- * capture-mode hook callers may want to wire (e.g. CI log bundling).
- */
-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 PrebuildTimeoutError({
-        scriptPath,
-        timeoutMs,
-        durationMs,
-      });
-    }
-    return { exitCode, durationMs };
-  } finally {
-    clearTimeout(timer);
-  }
-};
-
-/**
- * Coerce an unknown rejection into a stable Error shape.
- *
- * Issue #203 root cause: the original wrap path did
- *
- *     throw new Error("non-Error thrown: " + String(e));
- *
- * when `e` was, say, a plain string — which destroyed stack info and
- * yielded the "non-Error thrown" message the reporter saw. This helper
- * preserves whatever signal we can extract:
- *
- *   - `Error` instance → use `err.message`, attach as `cause`.
- *   - Non-Error (string / number / object)  → use `String(e)` as
- *     message prefix AND attach the raw value as `cause` so debug
- *     tooling can introspect it.
- *
- * Never produces the string "non-Error thrown" — that phrase was the
- * explicit regression beacon.
- */
-function describeInner(err: unknown): { message: string; cause: unknown } {
-  if (err instanceof Error) {
-    // `.message` may still be empty (hand-thrown `new Error()`); fall
-    // back to the class name so the user sees something.
-    const message = err.message.length > 0 ? err.message : err.name;
-    return { message, cause: err };
-  }
-  // Primitives / plain objects: coerce to string. We intentionally do NOT
-  // use the phrase "non-Error thrown" (the Issue #203 regression beacon).
-  let message: string;
-  try {
-    message = typeof err === "string" ? err : JSON.stringify(err);
-  } catch {
-    message = String(err);
-  }
-  if (!message || message === "{}") message = String(err);
-  return { message: message || "unknown spawn rejection", cause: err };
-}
-
-/**
- * Run every `scripts/prebuild-*.ts` in sequence. Resolves with a summary
- * of which scripts ran and how long each took. Rejects with
- * `PrebuildError` (or `PrebuildTimeoutError` specifically) 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",
-    onStart,
-    onFinish,
-    spawn = defaultSpawn,
-  } = options;
-
-  // Resolve timeout with env-var awareness so both the CLI and direct
-  // programmatic callers pick up `MANDU_PREBUILD_TIMEOUT_MS` without
-  // plumbing.
-  const timeoutMs = resolvePrebuildTimeout(options.timeoutMs);
-
-  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;
-    let stdoutTail: string | undefined;
-    let stderrTail: string | undefined;
-    try {
-      const res = await spawn({ scriptPath, cwd: rootDir, timeoutMs });
-      exitCode = res.exitCode;
-      durationMs = res.durationMs;
-      stdoutTail = res.stdoutTail;
-      stderrTail = res.stderrTail;
-    } catch (err) {
-      // Already a PrebuildError (typically PrebuildTimeoutError from the
-      // default spawn): propagate as-is after notifying onFinish so the
-      // caller's UI ticks the row off.
-      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,
-        });
-        throw err;
-      }
-      // Non-PrebuildError rejection — wrap in a way that preserves the
-      // inner error's message + stack (Issue #203: previously this path
-      // produced a "non-Error thrown" surface with no useful info).
-      const { message, cause } = describeInner(err);
-      throw new PrebuildError(
-        `Prebuild script '${scriptPath}' failed: ${message}`,
-        {
-          scriptPath,
-          exitCode: null,
-          durationMs: 0,
-          cause,
-        },
-      );
-    }
-
-    onFinish?.({ scriptPath, exitCode, durationMs });
-    results.push({ scriptPath, exitCode, durationMs });
-
-    if (exitCode !== 0) {
-      // Include captured output tails in the error so logs are actionable
-      // even after the dev server aborts and wipes the scrollback.
-      const tailHint = formatTailHint({ stdoutTail, stderrTail });
-      throw new PrebuildError(
-        `Prebuild script '${scriptPath}' exited with code ${exitCode}. ` +
-          `Subsequent prebuild scripts were not run.` +
-          (tailHint ? `\n${tailHint}` : ""),
-        { scriptPath, exitCode, durationMs, stdoutTail, stderrTail },
-      );
-    }
-  }
-
-  return { ran: results.length, scripts: results };
-}
-
-/**
- * Format the captured stdout/stderr tails into a human-readable multi-line
- * hint suffix for `PrebuildError.message`. Returns an empty string when
- * neither tail is present (the default spawn path) so we do not bloat the
- * message with "[stdout tail]\n(empty)" noise in the common case.
- */
-function formatTailHint(args: {
-  stdoutTail?: string;
-  stderrTail?: string;
-}): string {
-  const lines: string[] = [];
-  if (args.stderrTail && args.stderrTail.length > 0) {
-    lines.push("--- stderr (last 10 lines) ---");
-    lines.push(tailLines(args.stderrTail, 10));
-  }
-  if (args.stdoutTail && args.stdoutTail.length > 0) {
-    lines.push("--- stdout (last 10 lines) ---");
-    lines.push(tailLines(args.stdoutTail, 10));
-  }
-  return lines.join("\n");
-}
-
-/**
- * Keep only the last N lines of a string. Exported indirectly through
- * `PrebuildError.message` formatting so test assertions can recompute
- * the expected tail without importing this helper.
- */
-function tailLines(text: string, n: number): string {
-  const normalized = text.replace(/\r\n/g, "\n");
-  const lines = normalized.split("\n");
-  // Strip one trailing empty line (shell output convention) so we count
-  // real lines only.
-  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
-  return lines.slice(-n).join("\n");
-}
-
-/**
- * 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;
-}
+/**
+ * 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.
+ *
+ *      **Error surface (Issue #203)**: when a script exits non-zero we
+ *      tail its stdout/stderr (last 10 lines of each) into the error
+ *      message so the user can see WHY it failed without scrolling back
+ *      through the terminal. When a spawn rejection is a real `Error`
+ *      (e.g. `ENOENT`) we propagate its `message` and attach `cause` so
+ *      `err.cause?.stack` is recoverable — fixing the "non-Error thrown"
+ *      ghost stack traces reporters saw pre-#203.
+ *
+ *   4. **Timeout (Issue #203 — configurable)**: per-script wall-clock cap.
+ *      Default is 2 minutes (matching `packages/mcp/src/util/runCommand.ts`
+ *      #136). Override precedence, highest first:
+ *
+ *        a. `options.timeoutMs` (explicit caller arg)
+ *        b. `MANDU_PREBUILD_TIMEOUT_MS` environment variable
+ *        c. `ManduConfig.dev.prebuildTimeoutMs` (threaded through by the
+ *           CLI in `packages/cli/src/commands/dev.ts`)
+ *        d. Default: 120_000 ms
+ *
+ *      When the timer fires we throw `PrebuildTimeoutError` with the
+ *      script path + limit so `error.message` alone carries enough info
+ *      to let the user pick their override path without re-reading docs.
+ *
+ *   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)$/;
+
+/**
+ * Default per-script timeout. Matches the MCP `runCommand()` convention
+ * (#136). Exported so `@mandujs/core` consumers (validators, tests) can
+ * reference the same constant instead of re-hardcoding `2 * 60 * 1000`.
+ */
+export const DEFAULT_PREBUILD_TIMEOUT_MS = 2 * 60 * 1000;
+
+/**
+ * Env var name for the runtime override. Checked inside
+ * `resolvePrebuildTimeout` when the caller does not pass an explicit
+ * `timeoutMs`. Invalid values (non-numeric, <= 0) are ignored with a
+ * single stderr warning so a typo does not silently break the default.
+ */
+export const PREBUILD_TIMEOUT_ENV = "MANDU_PREBUILD_TIMEOUT_MS";
+
+/**
+ * Resolve the timeout to apply for a single prebuild script, with
+ * precedence (highest first):
+ *
+ *   1. `explicit` argument — if the CLI or a test passes an explicit
+ *      `timeoutMs`, we honour it verbatim (no env lookup). This keeps
+ *      the injected-spawn unit tests deterministic.
+ *   2. `MANDU_PREBUILD_TIMEOUT_MS` environment variable (runtime knob
+ *      for ops — set once in CI / docker env without re-deploying code).
+ *   3. `DEFAULT_PREBUILD_TIMEOUT_MS`.
+ *
+ * Separated from `runPrebuildScripts` so the CLI can log the resolved
+ * value without re-implementing the lookup.
+ */
+export function resolvePrebuildTimeout(explicit?: number): number {
+  if (typeof explicit === "number" && explicit > 0) {
+    return explicit;
+  }
+  const envRaw = process.env[PREBUILD_TIMEOUT_ENV];
+  if (typeof envRaw === "string" && envRaw.length > 0) {
+    const parsed = Number(envRaw);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+    // Warn once per process — a typoed env var silently falling back to
+    // the default is the kind of issue #203 was reported to fix.
+    console.warn(
+      `[Mandu prebuild] ignoring invalid ${PREBUILD_TIMEOUT_ENV}='${envRaw}' (expected positive number of milliseconds). Falling back to default ${DEFAULT_PREBUILD_TIMEOUT_MS}ms.`,
+    );
+  }
+  return DEFAULT_PREBUILD_TIMEOUT_MS;
+}
+
+/**
+ * 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 when we could not
+ * complete the spawn (e.g. `bun` binary missing, ENOENT on the script
+ * path). The `scriptPath` + `exitCode` fields are stable so callers can
+ * decide recovery policy without string-matching the message.
+ *
+ * Issue #203: when wrapping an inner `Error`, we preserve the inner
+ * `.message` (shown in the message) AND set `this.cause = err` so
+ * runtimes that render `err.cause` get the full stack. Previously we
+ * sometimes lost the inner error entirely, producing a useless
+ * `"non-Error thrown"` surface.
+ */
+export class PrebuildError extends Error {
+  readonly scriptPath: string;
+  readonly exitCode: number | null;
+  readonly durationMs: number;
+  /** Last ~10 lines of stdout captured from the child process, if any. */
+  readonly stdoutTail?: string;
+  /** Last ~10 lines of stderr captured from the child process, if any. */
+  readonly stderrTail?: string;
+
+  constructor(
+    message: string,
+    options: {
+      scriptPath: string;
+      exitCode: number | null;
+      durationMs: number;
+      cause?: unknown;
+      stdoutTail?: string;
+      stderrTail?: string;
+    },
+  ) {
+    super(message);
+    this.name = "PrebuildError";
+    this.scriptPath = options.scriptPath;
+    this.exitCode = options.exitCode;
+    this.durationMs = options.durationMs;
+    if (options.stdoutTail !== undefined) this.stdoutTail = options.stdoutTail;
+    if (options.stderrTail !== undefined) this.stderrTail = options.stderrTail;
+    if (options.cause !== undefined) {
+      (this as Error & { cause?: unknown }).cause = options.cause;
+    }
+  }
+}
+
+/**
+ * Error thrown specifically when the per-script wall-clock timer elapses
+ * before the subprocess exits. Separate class (a subclass of
+ * `PrebuildError`) so callers can pattern-match:
+ *
+ *     if (err instanceof PrebuildTimeoutError) { showTimeoutHint(); }
+ *     else if (err instanceof PrebuildError)   { showGenericHint(); }
+ *
+ * Without the subclass they would have to grep the `.message` string,
+ * which is the exact anti-pattern Issue #203 flagged.
+ *
+ * The message always ends with an actionable hint naming the three
+ * override paths (config field, env var, CLI flag) so the user can pick
+ * one without reading the docs.
+ */
+export class PrebuildTimeoutError extends PrebuildError {
+  readonly timeoutMs: number;
+
+  constructor(options: {
+    scriptPath: string;
+    timeoutMs: number;
+    durationMs: number;
+    stdoutTail?: string;
+    stderrTail?: string;
+  }) {
+    const { scriptPath, timeoutMs, durationMs } = options;
+    super(
+      `PrebuildTimeoutError: ${scriptPath} exceeded ${timeoutMs}ms (set dev.prebuildTimeoutMs in mandu.config.ts or ${PREBUILD_TIMEOUT_ENV} env var to override).`,
+      {
+        scriptPath,
+        exitCode: null,
+        durationMs,
+        stdoutTail: options.stdoutTail,
+        stderrTail: options.stderrTail,
+      },
+    );
+    this.name = "PrebuildTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+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. Precedence matches
+   * `resolvePrebuildTimeout`: explicit arg > `MANDU_PREBUILD_TIMEOUT_MS`
+   * > `DEFAULT_PREBUILD_TIMEOUT_MS` (120_000).
+   *
+   * The CLI threads `ManduConfig.dev.prebuildTimeoutMs` into this field
+   * so end-users typically configure the timeout declaratively without
+   * passing an arg to this API.
+   */
+  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 `{ exitCode, durationMs }`. May also return
+   * `stdoutTail` / `stderrTail` strings (the default spawn does not —
+   * it uses `stdio: "inherit"` so there is no captured output to tail).
+   * 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`.
+ *
+ * The hook is expected to self-enforce `timeoutMs` by killing the child
+ * when the timer fires, then throwing `PrebuildTimeoutError`. The
+ * default spawn follows this pattern. Custom hooks that skip the kill
+ * are responsible for any consequent zombie.
+ */
+export type SpawnHook = (args: {
+  scriptPath: string;
+  cwd: string;
+  timeoutMs: number;
+}) => Promise<{
+  exitCode: number | null;
+  durationMs: number;
+  stdoutTail?: string;
+  stderrTail?: string;
+}>;
+
+/**
+ * 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.
+ *
+ * Note: `stdio: "inherit"` means we cannot capture stdout/stderr to tail
+ * into the error message. The captured-tail feature is exercised by
+ * injected spawn hooks in the test suite and by any future
+ * capture-mode hook callers may want to wire (e.g. CI log bundling).
+ */
+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 PrebuildTimeoutError({
+        scriptPath,
+        timeoutMs,
+        durationMs,
+      });
+    }
+    return { exitCode, durationMs };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * Coerce an unknown rejection into a stable Error shape.
+ *
+ * Issue #203 root cause: the original wrap path did
+ *
+ *     throw new Error("non-Error thrown: " + String(e));
+ *
+ * when `e` was, say, a plain string — which destroyed stack info and
+ * yielded the "non-Error thrown" message the reporter saw. This helper
+ * preserves whatever signal we can extract:
+ *
+ *   - `Error` instance → use `err.message`, attach as `cause`.
+ *   - Non-Error (string / number / object)  → use `String(e)` as
+ *     message prefix AND attach the raw value as `cause` so debug
+ *     tooling can introspect it.
+ *
+ * Never produces the string "non-Error thrown" — that phrase was the
+ * explicit regression beacon.
+ */
+function describeInner(err: unknown): { message: string; cause: unknown } {
+  if (err instanceof Error) {
+    // `.message` may still be empty (hand-thrown `new Error()`); fall
+    // back to the class name so the user sees something.
+    const message = err.message.length > 0 ? err.message : err.name;
+    return { message, cause: err };
+  }
+  // Primitives / plain objects: coerce to string. We intentionally do NOT
+  // use the phrase "non-Error thrown" (the Issue #203 regression beacon).
+  let message: string;
+  try {
+    message = typeof err === "string" ? err : JSON.stringify(err);
+  } catch {
+    message = String(err);
+  }
+  if (!message || message === "{}") message = String(err);
+  return { message: message || "unknown spawn rejection", cause: err };
+}
+
+/**
+ * Run every `scripts/prebuild-*.ts` in sequence. Resolves with a summary
+ * of which scripts ran and how long each took. Rejects with
+ * `PrebuildError` (or `PrebuildTimeoutError` specifically) 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",
+    onStart,
+    onFinish,
+    spawn = defaultSpawn,
+  } = options;
+
+  // Resolve timeout with env-var awareness so both the CLI and direct
+  // programmatic callers pick up `MANDU_PREBUILD_TIMEOUT_MS` without
+  // plumbing.
+  const timeoutMs = resolvePrebuildTimeout(options.timeoutMs);
+
+  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;
+    let stdoutTail: string | undefined;
+    let stderrTail: string | undefined;
+    try {
+      const res = await spawn({ scriptPath, cwd: rootDir, timeoutMs });
+      exitCode = res.exitCode;
+      durationMs = res.durationMs;
+      stdoutTail = res.stdoutTail;
+      stderrTail = res.stderrTail;
+    } catch (err) {
+      // Already a PrebuildError (typically PrebuildTimeoutError from the
+      // default spawn): propagate as-is after notifying onFinish so the
+      // caller's UI ticks the row off.
+      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,
+        });
+        throw err;
+      }
+      // Non-PrebuildError rejection — wrap in a way that preserves the
+      // inner error's message + stack (Issue #203: previously this path
+      // produced a "non-Error thrown" surface with no useful info).
+      const { message, cause } = describeInner(err);
+      throw new PrebuildError(
+        `Prebuild script '${scriptPath}' failed: ${message}`,
+        {
+          scriptPath,
+          exitCode: null,
+          durationMs: 0,
+          cause,
+        },
+      );
+    }
+
+    onFinish?.({ scriptPath, exitCode, durationMs });
+    results.push({ scriptPath, exitCode, durationMs });
+
+    if (exitCode !== 0) {
+      // Include captured output tails in the error so logs are actionable
+      // even after the dev server aborts and wipes the scrollback.
+      const tailHint = formatTailHint({ stdoutTail, stderrTail });
+      throw new PrebuildError(
+        `Prebuild script '${scriptPath}' exited with code ${exitCode}. ` +
+          `Subsequent prebuild scripts were not run.` +
+          (tailHint ? `\n${tailHint}` : ""),
+        { scriptPath, exitCode, durationMs, stdoutTail, stderrTail },
+      );
+    }
+  }
+
+  return { ran: results.length, scripts: results };
+}
+
+/**
+ * Format the captured stdout/stderr tails into a human-readable multi-line
+ * hint suffix for `PrebuildError.message`. Returns an empty string when
+ * neither tail is present (the default spawn path) so we do not bloat the
+ * message with "[stdout tail]\n(empty)" noise in the common case.
+ */
+function formatTailHint(args: {
+  stdoutTail?: string;
+  stderrTail?: string;
+}): string {
+  const lines: string[] = [];
+  if (args.stderrTail && args.stderrTail.length > 0) {
+    lines.push("--- stderr (last 10 lines) ---");
+    lines.push(tailLines(args.stderrTail, 10));
+  }
+  if (args.stdoutTail && args.stdoutTail.length > 0) {
+    lines.push("--- stdout (last 10 lines) ---");
+    lines.push(tailLines(args.stdoutTail, 10));
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Keep only the last N lines of a string. Exported indirectly through
+ * `PrebuildError.message` formatting so test assertions can recompute
+ * the expected tail without importing this helper.
+ */
+function tailLines(text: string, n: number): string {
+  const normalized = text.replace(/\r\n/g, "\n");
+  const lines = normalized.split("\n");
+  // Strip one trailing empty line (shell output convention) so we count
+  // real lines only.
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines.slice(-n).join("\n");
+}
+
+/**
+ * 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;
+}