@mandujs/core 0.54.3 → 0.54.4

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

@@ -54,16 +54,36 @@
 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: [
-    {
+const rootDir = process.argv[2];
+if (!rootDir) {
+  console.error("usage: build-runner.ts <rootDir>");
+  process.exit(2);
+}
+const mode = process.argv[3] ?? "default";
+
+const manifest: RoutesManifest = mode === "server-page-client-module"
+  ? {
+      version: 1,
+      routes: [
+        {
+          id: "index",
+          kind: "page",
+          pattern: "/",
+          module: "app/page.tsx",
+          componentModule: "app/page.tsx",
+          clientModule: "app/page.tsx",
+          hydration: {
+            strategy: "island",
+            priority: "visible",
+            preload: false,
+          },
+        },
+      ],
+    }
+  : {
+  version: 1,
+  routes: [
+    {
       id: "demo",
       kind: "page",
       pattern: "/",
@@ -75,9 +95,9 @@ const manifest: RoutesManifest = {
         priority: "visible",
         preload: false,
       },
-    },
-  ],
-};
+    },
+  ],
+};
 
 try {
   const result = await buildClientBundles(manifest, rootDir, {

package/src/bundler/__tests__/css.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { __private } from "../css";
+
+describe("CSS Tailwind command resolution", () => {
+  test("uses process.execPath when it is Bun", () => {
+    expect(
+      __private.getTailwindCommand(["@tailwindcss/cli"], "C:\\tools\\bun.exe"),
+    ).toEqual(["C:\\tools\\bun.exe", "x", "@tailwindcss/cli"]);
+  });
+
+  test("does not treat standalone mandu.exe as Bun", () => {
+    expect(
+      __private.getTailwindCommand(
+        ["@tailwindcss/cli"],
+        "C:\\Users\\User\\AppData\\Local\\Mandu\\bin\\mandu.exe",
+        () => "C:\\Users\\User\\.bun\\bin\\bun.exe",
+      ),
+    ).toEqual(["C:\\Users\\User\\.bun\\bin\\bun.exe", "x", "@tailwindcss/cli"]);
+  });
+});

package/src/bundler/build.test.ts

@@ -24,17 +24,19 @@ async function importBuiltModule(relativePath: string): Promise<Record<string, u
  * See `__tests__/build-runner.ts` for the subprocess entrypoint and more
  * background.
  */
-async function runBuildInSubprocess(root: string): Promise<{
-  success: boolean;
-  errors: string[];
-}> {
+async function runBuildInSubprocess(root: string, mode?: string): Promise<{
+  success: boolean;
+  errors: string[];
+}> {
   const runner = path.join(
     import.meta.dir,
     "__tests__",
     "build-runner.ts",
   );
   try {
-    const proc = Bun.spawn([process.execPath, "run", runner, root], {
+    const args = [process.execPath, "run", runner, root];
+    if (mode) args.push(mode);
+    const proc = Bun.spawn(args, {
       cwd: path.resolve(import.meta.dir, "..", ".."),
       stdin: "ignore",
       stdout: "pipe",
@@ -183,4 +185,37 @@ describe("buildClientBundles vendor shims", () => {
     expect(runtimeSource).toContain("document.getElementById(\"__MANDU_DATA__\")");
     expect(runtimeSource).toContain("JSON.parse");
   });
+
+  test("does not bundle a server page when stale manifest marks page.tsx as clientModule", async () => {
+    const staleRoot = await mkdtemp(path.join(import.meta.dir, ".tmp-stale-client-module-"));
+    try {
+      await mkdir(path.join(staleRoot, "app"), { recursive: true });
+      await mkdir(path.join(staleRoot, "src", "shared", "contracts"), { recursive: true });
+      await writeFile(
+        path.join(staleRoot, "package.json"),
+        JSON.stringify({ name: "mandu-stale-client-module-test", type: "module" }, null, 2),
+        "utf-8",
+      );
+      await writeFile(
+        path.join(staleRoot, "src", "shared", "contracts", "api.ts"),
+        'export const INTERNAL_BASE = process.env.MANDU_INTERNAL_URL ?? "http://localhost:3333";\n',
+        "utf-8",
+      );
+      await writeFile(
+        path.join(staleRoot, "app", "page.tsx"),
+        'import { INTERNAL_BASE } from "../src/shared/contracts/api";\n' +
+          "export default async function HomePage() {\n" +
+          "  return <main>{INTERNAL_BASE}</main>;\n" +
+          "}\n",
+        "utf-8",
+      );
+
+      const staleResult = await runBuildInSubprocess(staleRoot, "server-page-client-module");
+      expect(staleResult.success).toBe(false);
+      expect(staleResult.errors.join("\n")).toContain("missing \"use client\"");
+      expect(await Bun.file(path.join(staleRoot, ".mandu", "client", "index.island.js")).exists()).toBe(false);
+    } finally {
+      await rm(staleRoot, { recursive: true, force: true });
+    }
+  });
 });

package/src/bundler/build.ts

@@ -20,9 +20,10 @@ import { safeBuild } from "./safe-build";
 import { fastRefreshPlugin } from "./fast-refresh-plugin";
 import { defaultBundlerPlugins } from "./plugins";
 import type { BunPlugin } from "bun";
-import { mark, measure } from "../perf";
-import { HMR_PERF } from "../perf/hmr-markers";
-import { runOnBundleComplete } from "../plugins/runner";
+import { mark, measure } from "../perf";
+import { HMR_PERF } from "../perf/hmr-markers";
+import { runOnBundleComplete } from "../plugins/runner";
+import { validateClientModuleForBrowserBundle } from "../router/client-entry";
 import {
   readVendorCache,
   writeVendorCache,
@@ -2122,7 +2123,21 @@ export async function buildClientBundles(
   const env = resolveBundlerMode(options);
 
   // 1. Hydration이 필요한 라우트 필터링
-  const hydratedRoutes = getHydratedRoutes(manifest);
+  const invalidClientRouteIds = new Set<string>();
+  let hydratedRoutes = getHydratedRoutes(manifest);
+  if (hydratedRoutes.length > 0) {
+    const validRoutes: RouteSpec[] = [];
+    for (const route of hydratedRoutes) {
+      const validationError = await validateClientModuleForBrowserBundle(route, rootDir);
+      if (validationError) {
+        invalidClientRouteIds.add(route.id);
+        errors.push(validationError);
+        continue;
+      }
+      validRoutes.push(route);
+    }
+    hydratedRoutes = validRoutes;
+  }
   const runtimeRoutes = manifest.routes.filter((route) => route.kind === "page" && needsHydration(route));
   const partialFiles = runtimeRoutes.length > 0 ? await scanPartialFiles(rootDir) : [];
 
@@ -2134,7 +2149,7 @@ export async function buildClientBundles(
   // (이전 빌드의 stale 매니페스트 참조 방지)
   if (hydratedRoutes.length === 0 && partialFiles.length === 0) {
     // #185: skipFrameworkBundles 모드에서는 기존 manifest를 그대로 유지 (devtools 재빌드도 스킵)
-    if (options.skipFrameworkBundles) {
+    if (options.skipFrameworkBundles && errors.length === 0) {
       const manifestPath = path.join(rootDir, ".mandu/manifest.json");
       try {
         const manifestRaw = await fs.readFile(manifestPath, "utf-8");
@@ -2185,11 +2200,11 @@ export async function buildClientBundles(
       path.join(rootDir, ".mandu/manifest.json"),
       JSON.stringify(emptyManifest, null, 2)
     );
-    return {
-      success: true,
-      outputs: [],
-      errors: [],
-      manifest: emptyManifest,
+    return {
+      success: errors.length === 0,
+      outputs: [],
+      errors,
+      manifest: emptyManifest,
       stats: {
         totalSize: 0,
         totalGzipSize: 0,
@@ -2228,11 +2243,14 @@ export async function buildClientBundles(
       return buildClientBundles(manifest, rootDir, { ...options, targetRouteIds: undefined });
     }
 
-    // Only update manifest with successfully built outputs (#10: preserve previous good manifest on failure)
-    if (outputs.length > 0) {
-      for (const output of outputs) {
-        if (existingManifest.bundles[output.routeId]) {
-          existingManifest.bundles[output.routeId].js = output.outputPath;
+    // Only update manifest with successfully built outputs (#10: preserve previous good manifest on failure)
+    for (const routeId of invalidClientRouteIds) {
+      delete existingManifest.bundles[routeId];
+    }
+    if (outputs.length > 0 || invalidClientRouteIds.size > 0) {
+      for (const output of outputs) {
+        if (existingManifest.bundles[output.routeId]) {
+          existingManifest.bundles[output.routeId].js = output.outputPath;
         } else {
           const route = targetRoutes.find((r) => r.id === output.routeId);
           const hydration = route ? getRouteHydration(route) : null;
@@ -2244,11 +2262,11 @@ export async function buildClientBundles(
         }
       }
 
-      await fs.writeFile(
-        path.join(rootDir, ".mandu/manifest.json"),
-        JSON.stringify(existingManifest, null, 2)
-      );
-    }
+      await fs.writeFile(
+        path.join(rootDir, ".mandu/manifest.json"),
+        JSON.stringify(existingManifest, null, 2)
+      );
+    }
     // When all builds failed, do NOT overwrite manifest — keep previous good state
 
     const stats = calculateStats(outputs, startTime);
@@ -2284,9 +2302,13 @@ export async function buildClientBundles(
         "[Mandu] Existing manifest missing required fields (shared/bundles), falling back to full build",
       );
       return buildClientBundles(manifest, rootDir, { ...options, skipFrameworkBundles: false });
-    }
-
-    // Pre-build validation + 병렬 island 빌드 (framework 번들은 스킵)
+    }
+
+    for (const routeId of invalidClientRouteIds) {
+      delete existingManifest.bundles[routeId];
+    }
+
+    // Pre-build validation + 병렬 island 빌드 (framework 번들은 스킵)
     for (const route of hydratedRoutes) {
       if (!route.clientModule) continue;
       const clientModulePath = path.join(rootDir, route.clientModule);

package/src/bundler/css.ts

@@ -18,14 +18,38 @@ import fs from "fs/promises";
 import { watch as fsWatch, type FSWatcher } from "fs";
 import { withPerf } from "../perf";
 
-/**
- * Tailwind CLI 실행 명령어를 결정한다.
- * Windows에서 Bun.spawn은 PATH 기반 명령어 해석이 불안정하므로 (#152)
- * process.execPath (절대 경로)를 사용해 안정적으로 실행한다.
- */
-function getTailwindCommand(args: string[]): string[] {
-  return [process.execPath, "x", ...args];
-}
+/**
+ * Tailwind CLI 실행 명령어를 결정한다.
+ * Windows에서 Bun.spawn은 PATH 기반 명령어 해석이 불안정하므로 (#152)
+ * `bun run mandu` 환경에서는 process.execPath (bun 절대 경로)를 사용한다.
+ * Standalone Mandu binary에서는 process.execPath가 mandu.exe를 가리키므로
+ * `mandu x @tailwindcss/cli`로 오해석된다. 이 경우 PATH에서 Bun을 찾는다.
+ */
+function isBunExecutable(executablePath: string | undefined): boolean {
+  if (!executablePath) return false;
+  const base = path.basename(executablePath).toLowerCase();
+  return base === "bun" || base === "bun.exe";
+}
+
+type WhichExecutable = (command: string) => string | null | undefined;
+
+function resolveBunExecutable(
+  execPath = process.execPath,
+  which: WhichExecutable = (command) => Bun.which(command),
+): string {
+  if (isBunExecutable(execPath)) return execPath;
+  const fromPath = which("bun");
+  if (fromPath) return fromPath;
+  return process.platform === "win32" ? "bun.exe" : "bun";
+}
+
+function getTailwindCommand(
+  args: string[],
+  execPath = process.execPath,
+  which?: WhichExecutable,
+): string[] {
+  return [resolveBunExecutable(execPath, which), "x", ...args];
+}
 
 // ========== Types ==========
 
@@ -320,7 +344,13 @@ export function getCSSServerPath(): string {
 /**
  * CSS 링크 태그 생성
  */
-export function generateCSSLinkTag(isDev: boolean = false): string {
-  const cacheBust = isDev ? `?t=${Date.now()}` : "";
-  return `<link rel="stylesheet" href="${SERVER_CSS_PATH}${cacheBust}">`;
-}
+export function generateCSSLinkTag(isDev: boolean = false): string {
+  const cacheBust = isDev ? `?t=${Date.now()}` : "";
+  return `<link rel="stylesheet" href="${SERVER_CSS_PATH}${cacheBust}">`;
+}
+
+export const __private = {
+  getTailwindCommand,
+  isBunExecutable,
+  resolveBunExecutable,
+};

package/src/index.ts

@@ -21,8 +21,9 @@ export const __MANDU_CORE_VERSION__: string = (() => {
   }
 })();
 
-export * from "./spec";
-export * from "./runtime";
+export * from "./spec";
+export * from "./agent";
+export * from "./runtime";
 export * from "./generator";
 export * from "./guard";
 export * from "./report";

package/src/router/client-entry.ts

@@ -0,0 +1,71 @@
+import { readFile } from "fs/promises";
+import path from "path";
+import type { RouteSpec } from "../spec/schema";
+
+export function normalizeRouteModulePath(value: string | undefined): string {
+  return (value ?? "").replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+export function hasUseClientDirective(source: string): boolean {
+  return /^(?:\uFEFF)?\s*(?:(?:\/\/[^\r\n]*(?:\r?\n|$))|(?:\/\*[\s\S]*?\*\/\s*))*["']use client["']\s*;?/.test(source);
+}
+
+export function hasUseServerDirective(source: string): boolean {
+  return /^(?:\uFEFF)?\s*(?:(?:\/\/[^\r\n]*(?:\r?\n|$))|(?:\/\*[\s\S]*?\*\/\s*))*["']use server["']\s*;?/.test(source);
+}
+
+export function clientModuleIsRouteComponent(route: RouteSpec, clientModule = route.clientModule): boolean {
+  if (route.kind !== "page" || !clientModule) return false;
+
+  const client = normalizeRouteModulePath(clientModule);
+  return (
+    client === normalizeRouteModulePath(route.componentModule) ||
+    client === normalizeRouteModulePath(route.module)
+  );
+}
+
+async function readRouteModule(rootDir: string, modulePath: string): Promise<string | null> {
+  try {
+    return await readFile(path.resolve(rootDir, modulePath), "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export async function shouldPreserveExistingClientModule(
+  route: RouteSpec,
+  clientModule: string,
+  rootDir: string,
+): Promise<boolean> {
+  const source = await readRouteModule(rootDir, clientModule);
+  if (source === null) return false;
+  if (hasUseServerDirective(source)) return false;
+  if (clientModuleIsRouteComponent(route, clientModule)) {
+    return hasUseClientDirective(source);
+  }
+  return true;
+}
+
+export async function validateClientModuleForBrowserBundle(
+  route: RouteSpec,
+  rootDir: string,
+): Promise<string | null> {
+  if (!route.clientModule) return null;
+
+  const source = await readRouteModule(rootDir, route.clientModule);
+  if (source === null) return null;
+
+  if (hasUseServerDirective(source)) {
+    return `[${route.id}] Client module "${route.clientModule}" has a "use server" directive and cannot be bundled for the browser.`;
+  }
+
+  if (clientModuleIsRouteComponent(route) && !hasUseClientDirective(source)) {
+    return (
+      `[${route.id}] Route component "${route.clientModule}" is configured as clientModule, ` +
+      `but it is a server page (missing "use client"). Mandu will not bundle server pages into client islands. ` +
+      `Remove the stale clientModule from .mandu/routes.manifest.json or use a *.partial.tsx / spec/slots/${route.id}.client.tsx client entry.`
+    );
+  }
+
+  return null;
+}

package/src/router/fs-routes.ts

@@ -14,10 +14,11 @@ import { DEFAULT_SCANNER_CONFIG } from "./fs-types";
 import { scanRoutes } from "./fs-scanner";
 import { loadManduConfig } from "../config";
 import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
-import {
-  runOnRouteRegistered,
-  runOnManifestBuilt,
-} from "../plugins/runner";
+import {
+  runOnRouteRegistered,
+  runOnManifestBuilt,
+} from "../plugins/runner";
+import { shouldPreserveExistingClientModule } from "./client-entry";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Types
@@ -308,10 +309,17 @@ export async function generateManifest(
       for (const route of manifest.routes) {
         const prev = existingMap.get(route.id);
         if (!prev) continue;
-        // 사용자가 설정한 clientModule/hydration 보존
-        if (prev.clientModule && !route.clientModule) {
-          route.clientModule = prev.clientModule;
-        }
+        // 사용자가 설정한 clientModule/hydration 보존.
+        // If app/page.tsx used to be a client page and later becomes a server
+        // page, preserving the old clientModule would leak the server graph into
+        // the browser bundle.
+        if (
+          prev.clientModule &&
+          !route.clientModule &&
+          await shouldPreserveExistingClientModule(route, prev.clientModule, rootDir)
+        ) {
+          route.clientModule = prev.clientModule;
+        }
         if (prev.hydration && !route.hydration) {
           route.hydration = prev.hydration;
         }

package/src/router/fs-scanner.ts

@@ -28,8 +28,9 @@ import {
   sortRoutesByPriority,
   getPatternShape,
 } from "./fs-patterns";
-import { mark, measure } from "../perf";
-import { METADATA_ROUTES } from "../routes/types";
+import { mark, measure } from "../perf";
+import { METADATA_ROUTES } from "../routes/types";
+import { hasUseClientDirective } from "./client-entry";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Scanner Class
@@ -390,7 +391,7 @@ export class FSScanner {
         }
       } else if (file.type === "page" && pageFileContent) {
         // page 파일 자체에서 "use client" 확인
-        const hasUseClient = /^\s*["']use client["']/m.test(pageFileContent);
+        const hasUseClient = hasUseClientDirective(pageFileContent);
         if (hasUseClient) {
           clientModule = modulePath;
         }