@mandujs/core 0.25.1 → 0.25.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -14,6 +14,12 @@
     "./auth/verification": "./src/auth/verification.ts",
     "./client": "./src/client/index.ts",
     "./content": "./src/content/index.ts",
+    "./content/prebuild": "./src/content/prebuild.ts",
+    "./content/collection": "./src/content/collection.ts",
+    "./content/sidebar": "./src/content/sidebar.ts",
+    "./content/slug": "./src/content/slug.ts",
+    "./content/llms-txt": "./src/content/llms-txt.ts",
+    "./content/schema": "./src/content/schema.ts",
     "./db": "./src/db/index.ts",
     "./desktop": "./src/desktop/index.ts",
     "./desktop/worker": "./src/desktop/worker.ts",

package/src/bundler/__tests__/build-runner.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env bun
+/**
+ * Internal helper used by `build.test.ts` + `fast-refresh.test.ts` to run
+ * `buildClientBundles` in an isolated `bun` subprocess.
+ *
+ * # Why this exists
+ *
+ * When the parent `bun test` process has loaded `react` or `react-dom`
+ * (transitively through most test files that import from `src/testing/*`
+ * or `src/runtime/*`), Bun 1.3.x's bundler resolver state interacts with
+ * `buildClientBundles`' 7-parallel shim fan-out (runtime + router +
+ * vendor[5] + devtools) to produce `AggregateError: Bundle failed` on
+ * one or more shims. Which shim fails is non-deterministic per run;
+ * retrying in-process does not recover because the state is sticky.
+ * Running the build in a fresh `bun` subprocess has a clean module graph
+ * and builds successfully on the first attempt.
+ *
+ * Reproducer (in-process): import `"react"` or `"./src/testing/server.ts"`
+ * in ANY other test file that ships with `src/bundler/build.test.ts`, and
+ * `bun test src/bundler/build.test.ts <that file>` fails ~100 %.
+ *
+ * # Contract
+ *
+ * - Invocation: `bun run src/bundler/__tests__/build-runner.ts <rootDir>`
+ * - The caller must pre-create `rootDir` with:
+ *     - `package.json` (any valid contents; shim cache keys walk up to
+ *       find `node_modules/react`)
+ *     - `app/demo.client.tsx` (the fixed manifest references this as an
+ *       island client module)
+ * - stdout: JSON blob terminated by `\n`:
+ *     { "success": boolean,
+ *       "errors": string[],
+ *       "manifest": { shared: { fastRefresh?: { runtime: string; glue: string } } }
+ *     }
+ *   Only the fields tests consume are serialized; the in-memory manifest
+ *   is also persisted at `<rootDir>/.mandu/manifest.json` by the build.
+ * - exit code: 0 on successful build, 1 on failure (for scripting).
+ *
+ * # Lifetime
+ *
+ * Each test spawns, awaits, and discards the subprocess. The subprocess
+ * does NOT reuse a vendor cache across runs — every fresh `rootDir` is a
+ * clean tmpdir with no prior `.mandu/vendor-cache/`.
+ */
+
+import { buildClientBundles } from "../build";
+import type { RoutesManifest } from "../../spec/schema";
+
+const rootDir = process.argv[2];
+if (!rootDir) {
+  console.error("usage: build-runner.ts <rootDir>");
+  process.exit(2);
+}
+
+const manifest: RoutesManifest = {
+  version: 1,
+  routes: [
+    {
+      id: "demo",
+      kind: "page",
+      pattern: "/",
+      module: "app/page.tsx",
+      componentModule: "app/page.tsx",
+      clientModule: "app/demo.client.tsx",
+      hydration: {
+        strategy: "island",
+        priority: "visible",
+        preload: false,
+      },
+    },
+  ],
+};
+
+try {
+  const result = await buildClientBundles(manifest, rootDir, {
+    minify: false,
+    sourcemap: false,
+    splitting: false,
+  });
+  process.stdout.write(
+    JSON.stringify({
+      success: result.success,
+      errors: result.errors,
+      manifest: {
+        shared: {
+          fastRefresh: result.manifest.shared?.fastRefresh ?? null,
+        },
+      },
+    }) + "\n",
+  );
+  process.exit(result.success ? 0 : 1);
+} catch (err) {
+  process.stdout.write(
+    JSON.stringify({
+      success: false,
+      errors: [String(err)],
+      manifest: null,
+    }) + "\n",
+  );
+  process.exit(1);
+}

package/src/bundler/__tests__/fast-refresh.test.ts

@@ -534,36 +534,46 @@ describe.skipIf(process.env.MANDU_SKIP_BUNDLER_TESTS === "1")(
     });
 
     test("[E1] dev build produces _vendor-react-refresh.js + _fast-refresh-runtime.js + manifest.shared.fastRefresh entry", async () => {
-      const { buildClientBundles } = await import("../build");
-      const manifest = {
-        version: 1 as const,
-        routes: [
-          {
-            id: "demo",
-            kind: "page" as const,
-            pattern: "/",
-            module: "app/page.tsx",
-            componentModule: "app/page.tsx",
-            clientModule: "app/demo.client.tsx",
-            hydration: {
-              strategy: "island" as const,
-              priority: "visible" as const,
-              preload: false,
-            },
-          },
-        ],
-      };
-      // Force dev-mode build by explicit `minify: false`. The build
-      // function's `isDev` branch is keyed off `options.minify`.
-      const result = await buildClientBundles(manifest, rootDir, {
-        minify: false,
-        sourcemap: false,
-        splitting: false,
+      // Force dev-mode build by spawning `buildClientBundles` in a fresh
+      // bun subprocess — see build-runner.ts header for the full story.
+      // In short: Bun 1.3.x's bundler resolver state gets poisoned when
+      // any sibling test file imports `react` / `react-dom`, making the
+      // 7-parallel shim fan-out fail with `AggregateError: Bundle failed`
+      // ~100 % of the time for the affected shim(s). A subprocess has a
+      // clean module graph.
+      const { spawn } = await import("node:child_process");
+      const runner = path.join(import.meta.dir, "build-runner.ts");
+      const cwd = path.resolve(import.meta.dir, "..", "..", "..");
+      const out = await new Promise<string>((resolve) => {
+        const proc = spawn(process.execPath, ["run", runner, rootDir], {
+          cwd,
+          stdio: ["ignore", "pipe", "inherit"],
+        });
+        let buf = "";
+        proc.stdout.on("data", (d: Buffer) => (buf += d.toString("utf-8")));
+        proc.on("close", () => resolve(buf));
       });
-      if (!result.success) {
-        console.error("[fr-vendor] errors:", result.errors);
+      const jsonLine =
+        out
+          .split(/\r?\n/)
+          .filter((l) => l.trim().length > 0)
+          .pop() ?? "";
+      let parsed: {
+        success: boolean;
+        errors: string[];
+        manifest: { shared: { fastRefresh: { runtime: string; glue: string } | null } } | null;
+      };
+      try {
+        parsed = JSON.parse(jsonLine);
+      } catch (e) {
+        throw new Error(
+          `build-runner stdout could not be parsed as JSON: ${String(e)}\nLast line: ${jsonLine}`,
+        );
       }
-      expect(result.success).toBe(true);
+      if (!parsed.success) {
+        console.error("[fr-vendor] errors:", parsed.errors);
+      }
+      expect(parsed.success).toBe(true);
       // Both shim files must exist on disk
       const glueFile = path.join(
         rootDir,
@@ -585,10 +595,10 @@ describe.skipIf(process.env.MANDU_SKIP_BUNDLER_TESTS === "1")(
       // bundle output — avoids requiring a full evaluation)
       expect(glueContents).toContain("installGlobal");
       // Manifest exposes the paths
-      expect(result.manifest.shared.fastRefresh?.runtime).toBe(
+      expect(parsed.manifest?.shared.fastRefresh?.runtime).toBe(
         "/.mandu/client/_vendor-react-refresh.js",
       );
-      expect(result.manifest.shared.fastRefresh?.glue).toBe(
+      expect(parsed.manifest?.shared.fastRefresh?.glue).toBe(
         "/.mandu/client/_fast-refresh-runtime.js",
       );
     });

package/src/bundler/build.test.ts

@@ -2,19 +2,74 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { mkdtemp, mkdir, readFile, rm, writeFile } from "fs/promises";
 import path from "path";
 import { pathToFileURL } from "url";
-import type { RoutesManifest } from "../spec/schema";
-import type { BundleResult } from "./types";
-import { buildClientBundles } from "./build";
+import { spawn } from "node:child_process";
 
 // 모든 테스트가 하나의 빌드 결과를 공유 — 병렬 Bun.build 충돌 방지
 let rootDir: string;
-let result: BundleResult;
+let result: { success: boolean; errors: string[] };
 
 async function importBuiltModule(relativePath: string): Promise<Record<string, unknown>> {
   const fileUrl = pathToFileURL(path.join(rootDir, relativePath)).href;
   return import(`${fileUrl}?t=${Date.now()}`);
 }
 
+/**
+ * Run `buildClientBundles` in an isolated `bun` subprocess.
+ *
+ * Bun 1.3.x exhibits a deterministic `AggregateError: Bundle failed` when
+ * `buildClientBundles` is called from a test file AND the same `bun test`
+ * process has previously imported `react` / `react-dom` through any sibling
+ * test file (happens transitively through almost every `src/testing/*` or
+ * `src/runtime/*` consumer). Retrying in-process does not recover — the
+ * resolver state is sticky. A fresh subprocess has a clean module graph.
+ * See `__tests__/build-runner.ts` for the subprocess entrypoint and more
+ * background.
+ */
+async function runBuildInSubprocess(root: string): Promise<{
+  success: boolean;
+  errors: string[];
+}> {
+  const runner = path.join(
+    import.meta.dir,
+    "__tests__",
+    "build-runner.ts",
+  );
+  return new Promise((resolve) => {
+    const proc = spawn(process.execPath, ["run", runner, root], {
+      cwd: path.resolve(import.meta.dir, "..", ".."),
+      stdio: ["ignore", "pipe", "inherit"],
+    });
+    let out = "";
+    proc.stdout.on("data", (chunk: Buffer) => {
+      out += chunk.toString("utf-8");
+    });
+    proc.on("close", () => {
+      // Find the final JSON line — the runner may log Mandu dev banners
+      // (e.g. "[Mandu] DevTools …") before emitting the payload. The
+      // contract is: last non-empty line is the JSON blob.
+      const lines = out.split(/\r?\n/).filter((l) => l.trim().length > 0);
+      const last = lines[lines.length - 1] ?? "";
+      try {
+        const parsed = JSON.parse(last);
+        resolve({
+          success: parsed.success === true,
+          errors: Array.isArray(parsed.errors) ? parsed.errors : [],
+        });
+      } catch (e) {
+        resolve({
+          success: false,
+          errors: [
+            `build-runner output could not be parsed as JSON: ${String(e)}\nLast stdout line: ${last}`,
+          ],
+        });
+      }
+    });
+    proc.on("error", (err) => {
+      resolve({ success: false, errors: [`spawn failed: ${String(err)}`] });
+    });
+  });
+}
+
 beforeAll(async () => {
   rootDir = await mkdtemp(path.join(import.meta.dir, ".tmp-bundler-"));
 
@@ -30,30 +85,7 @@ beforeAll(async () => {
     "utf-8",
   );
 
-  const manifest: RoutesManifest = {
-    version: 1,
-    routes: [
-      {
-        id: "demo",
-        kind: "page",
-        pattern: "/",
-        module: "app/page.tsx",
-        componentModule: "app/page.tsx",
-        clientModule: "app/demo.client.tsx",
-        hydration: {
-          strategy: "island",
-          priority: "visible",
-          preload: false,
-        },
-      },
-    ],
-  };
-
-  result = await buildClientBundles(manifest, rootDir, {
-    minify: false,
-    sourcemap: false,
-    splitting: false,
-  });
+  result = await runBuildInSubprocess(rootDir);
 });
 
 afterAll(async () => {
@@ -79,6 +111,12 @@ afterAll(async () => {
 // deterministically in ~35s on Windows. Confirmed green 3/3 runs without
 // the gate on 2026-04-20. If you are tempted to re-introduce the skip here,
 // first check whether a sibling test is starving the event loop.
+//
+// A second, independent flake — Bun.build `AggregateError: Bundle failed`
+// when another test file in the same invocation has imported `react` —
+// is now sidestepped by running `buildClientBundles` in a spawned `bun`
+// subprocess via `__tests__/build-runner.ts`. In-process retry does not
+// recover from that one; a fresh module graph does.
 describe("buildClientBundles vendor shims", () => {
   test("build succeeds", () => {
     if (!result.success) {

package/src/config/mandu.ts

@@ -198,6 +198,24 @@ export interface ManduConfig {
      * `autoPrebuild === false`. Relative to project root.
      */
     contentDir?: string;
+    /**
+     * Issue #203 — Per-script wall-clock timeout for prebuild scripts
+     * (milliseconds). Default: `120_000` (2 minutes), matching the MCP
+     * `runCommand()` convention (#136). Override for projects that ship
+     * slow seed generators (e.g. large docs indexers, image pipelines).
+     *
+     * Precedence at runtime, highest first:
+     *   1. `MANDU_PREBUILD_TIMEOUT_MS` env var — useful for one-off CI
+     *      overrides without committing to the config.
+     *   2. This field (`dev.prebuildTimeoutMs`).
+     *   3. Default 120_000 ms.
+     *
+     * When the timeout fires, `runPrebuildScripts` throws a
+     * `PrebuildTimeoutError` whose message names the failing script path,
+     * the limit, AND the two override paths — so the user does not need
+     * to re-read this comment to recover.
+     */
+    prebuildTimeoutMs?: number;
   };
   fsRoutes?: {
     routesDir?: string;

package/src/config/validate.ts

@@ -122,6 +122,14 @@ const DevConfigSchema = z
      * an empty pattern. Default `"content"`.
      */
     contentDir: z.string().min(1).default("content"),
+    /**
+     * Issue #203 — per-script wall-clock timeout (ms) for
+     * `scripts/prebuild-*.ts`. `undefined` = use default (120_000 ms) or
+     * the `MANDU_PREBUILD_TIMEOUT_MS` env var if set. Explicit positive
+     * integer overrides both. The boundary check mirrors
+     * `server.rateLimit.windowMs` style — positive integers only.
+     */
+    prebuildTimeoutMs: z.number().int().positive().optional(),
   })
   .strict();