@mandujs/core 0.25.0 → 0.25.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "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 () => {
@@ -62,14 +94,30 @@ afterAll(async () => {
   }
 });
 
-// Bun.build has observed cross-worker races under bun:test's parallel file
-// execution — when tests shuffle under --randomize, this file sometimes
-// collides with another bundler test in a sibling worker and fails with
-// "AggregateError: Bundle failed" + missing shim outputs. Gate on an env
-// var so CI can run randomize-mode across everything else, then run this
-// suite in a dedicated serial pass. Local `bun run test:core` (no env set)
-// still runs these tests fully. Tracked as Phase 0.6.
-describe.skipIf(process.env.MANDU_SKIP_BUNDLER_TESTS === "1")("buildClientBundles vendor shims", () => {
+// Historical note — `MANDU_SKIP_BUNDLER_TESTS` gate REMOVED.
+//
+// A previous revision gated this describe block behind
+// `describe.skipIf(MANDU_SKIP_BUNDLER_TESTS === "1")` because running
+// `bun test src/bundler/` without the gate hung indefinitely on Windows
+// (see Phase 0.6 and `docs/qa/wave-R2-integration-report.md`). Root cause
+// was NOT actually in THIS file — it was a deadlock in `safe-build.test.ts`'s
+// "slot handoff" regression test, which drove Bun's microtask queue with a
+// `while (!stop) { await Promise.resolve() }` sampler. That starved libuv
+// I/O callbacks, so the 7 parallel `safeBuild()` calls never completed, the
+// whole test process hung, and downstream test files (including this one
+// when run in the same invocation) looked flaky when they were simply
+// never reached. The handoff sampler now yields via `setImmediate`, which
+// unblocks Bun.build completion and makes `bun test src/bundler/` finish
+// 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) {
       console.error("[build.test] errors:", result.errors);

package/src/bundler/safe-build.test.ts

@@ -141,16 +141,34 @@ describe("safeBuild", () => {
 
     let peak = 0;
     let samples = 0;
-    // Sample at microtask granularity — more aggressive than the setInterval
-    // sampler in the earlier test — so the cap+1 window has a realistic
-    // chance of being observed if the bug returned.
+    // Sample active-slot count while the build burst is in flight. An earlier
+    // revision of this test used a `while (!stop) { await Promise.resolve() }`
+    // microtask busy-loop to push sampling granularity below setInterval's
+    // Windows 4ms-ish clamp. That deadlocks under Bun 1.3.x on Windows:
+    // `await Promise.resolve()` stays on the microtask queue, which runs
+    // to exhaustion before Bun's libuv I/O phase — so Bun.build completion
+    // callbacks never fire, `releaseSlot()` never runs, and the promises
+    // returned by the 7 parallel `safeBuild()` calls hang indefinitely.
+    // Reproduction: `bun test src/bundler/safe-build.test.ts` times out with
+    // only the banner printed (confirmed with a standalone repro of the
+    // sampler + 7 safeBuild calls — hung at "start" past 60s).
+    //
+    // Fix: yield to the macrotask queue via `setImmediate`. This lets
+    // libuv I/O callbacks run between samples, so Bun.build completes and
+    // `releaseSlot()` advances the queue. Per-tick granularity on Node/Bun
+    // is still sub-millisecond and fires ~hundreds of times during a 7-
+    // build burst — more than enough to statistically catch the cap+1
+    // regression window if it ever returned (the window is microtask-sized,
+    // but any cross-tick sampling with high fan-out has a realistic chance
+    // of landing inside it). The strict assertion is still `peak <= max`.
     let stop = false;
     const sample = async () => {
       while (!stop) {
         const { active } = _getConcurrencyState();
         if (active > peak) peak = active;
         samples++;
-        await Promise.resolve(); // yield to microtask queue
+        // Yield to libuv I/O phase so Bun.build callbacks can fire.
+        await new Promise<void>((resolve) => setImmediate(resolve));
       }
     };
     const sampler = sample();