@mandujs/core 0.43.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/bundler/plugins/__tests__/react-compiler-config.test.ts

@@ -0,0 +1,83 @@
+/**
+ * `resolveReactCompilerConfig` — #240 Phase 2 auto-detect tests.
+ *
+ * The probe only fires when `enabled` is undefined. Explicit `true` /
+ * `false` veto the probe so user intent always wins.
+ *
+ * Cache lifetime is per-process; we reset it between cases so a probe
+ * from one fixture doesn't leak to the next.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  resolveReactCompilerConfig,
+  _resetReactCompilerConfigCache,
+} from "../react-compiler-config";
+
+async function makeRoot(prefix: string): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), `mandu-rc-${prefix}-`));
+}
+
+beforeEach(() => {
+  _resetReactCompilerConfigCache();
+});
+
+describe("resolveReactCompilerConfig", () => {
+  it("explicit enabled:true honours the user even when peers are missing", async () => {
+    const root = await makeRoot("explicit-on");
+    const result = resolveReactCompilerConfig({ enabled: true }, root);
+    expect(result.enabled).toBe(true);
+    expect(result.autoDetected).toBe(false);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("explicit enabled:false vetos the probe", async () => {
+    const root = await makeRoot("explicit-off");
+    const result = resolveReactCompilerConfig({ enabled: false }, root);
+    expect(result.enabled).toBe(false);
+    expect(result.autoDetected).toBe(false);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("undefined enabled + missing peers → disabled silently", async () => {
+    const root = await makeRoot("auto-no-peers");
+    // Empty rootDir — no node_modules, no package.json, no peer deps.
+    const result = resolveReactCompilerConfig(undefined, root);
+    expect(result.enabled).toBe(false);
+    expect(result.autoDetected).toBe(false);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("forwards compilerConfig regardless of enabled state", async () => {
+    const root = await makeRoot("compiler-config");
+    const cfg = { compilationMode: "annotation" };
+    const result = resolveReactCompilerConfig(
+      { enabled: true, compilerConfig: cfg },
+      root,
+    );
+    expect(result.compilerConfig).toBe(cfg);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("caches by (rootDir, explicit-enabled) — second call hits cache", async () => {
+    const root = await makeRoot("cache");
+    const a = resolveReactCompilerConfig(undefined, root);
+    const b = resolveReactCompilerConfig(undefined, root);
+    // Same identity — cache hit returns the stored object.
+    expect(a).toBe(b);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("treats explicit-true vs auto as separate cache keys", async () => {
+    const root = await makeRoot("cache-key");
+    const auto = resolveReactCompilerConfig(undefined, root);
+    const explicit = resolveReactCompilerConfig({ enabled: true }, root);
+    expect(auto).not.toBe(explicit);
+    expect(auto.enabled).toBe(false);
+    expect(explicit.enabled).toBe(true);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+});

package/src/bundler/plugins/index.ts

@@ -36,6 +36,12 @@ export {
   type FormatCompilerReportOptions,
 } from "./react-compiler-lint";
 
+export {
+  resolveReactCompilerConfig,
+  type RawReactCompilerConfig,
+  type ResolvedReactCompilerConfig,
+} from "./react-compiler-config";
+
 /**
  * Subset of `ManduConfig.guard` consumed by `defaultBundlerPlugins()`.
  * We deliberately don't import the full `ManduConfig` type to keep the

package/src/bundler/plugins/react-compiler-config.ts

@@ -0,0 +1,108 @@
+/**
+ * React Compiler config resolver (#240 Phase 2 — auto-detect).
+ *
+ * The `experimental.reactCompiler` block in `mandu.config.ts` has three
+ * meaningful states for the `enabled` field:
+ *
+ *   - `true`  — user explicitly opts in. The transform plugin runs and
+ *     warns if peer deps (`@babel/core`, `babel-plugin-react-compiler`)
+ *     are missing.
+ *   - `false` — user explicitly opts out. Plugin never runs.
+ *   - `undefined` (the default) — Phase 2: probe whether the peer deps
+ *     are installed in the project. If both resolve, treat as enabled
+ *     so installing `babel-plugin-react-compiler` is the only step
+ *     needed to turn auto-memoization on (zero-config goal of #240).
+ *     If either is missing, stay disabled silently — no warning, no
+ *     surface change for projects that haven't asked for the Compiler.
+ *
+ * The probe is synchronous (`Bun.resolveSync`) so it composes with the
+ * non-async `manduClientPlugins()` gate. Resolutions are cached per
+ * `(rootDir, enabled)` pair because the bundler asks for plugins many
+ * times during a single build (one for each entry / shim / island).
+ *
+ * @module core/bundler/plugins/react-compiler-config
+ */
+
+export interface RawReactCompilerConfig {
+  enabled?: boolean;
+  compilerConfig?: Record<string, unknown>;
+}
+
+export interface ResolvedReactCompilerConfig {
+  /**
+   * Final on/off decision after applying auto-detect. Always a concrete
+   * boolean — callers do not need to repeat the probe.
+   */
+  enabled: boolean;
+  /** Forwarded to `babel-plugin-react-compiler`. */
+  compilerConfig?: Record<string, unknown>;
+  /**
+   * `true` when `enabled` was implicitly resolved from peer-dep probe
+   * (vs. set explicitly by the user). Surfaced so the bundler's plugin
+   * can suppress the "peer dep missing" warning — the implicit path
+   * already short-circuits before the plugin runs, but a future caller
+   * that bypasses this resolver would otherwise spam the warning.
+   */
+  autoDetected: boolean;
+}
+
+const cache = new Map<string, ResolvedReactCompilerConfig>();
+
+/**
+ * Probe whether `@babel/core` and `babel-plugin-react-compiler` resolve
+ * from `rootDir`. Both must be present — the transform plugin loads
+ * them as a pair. Returns `false` on any resolution failure (missing
+ * dep, broken symlink, weird workspace layout) so the failure mode is
+ * "stay off" rather than "blow up boot".
+ */
+function peerDepsInstalled(rootDir: string): boolean {
+  try {
+    Bun.resolveSync("@babel/core", rootDir);
+    Bun.resolveSync("babel-plugin-react-compiler", rootDir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the user's `experimental.reactCompiler` block into a final
+ * on/off decision plus carried-over compiler options.
+ *
+ * Cache key includes `rootDir` and the explicit-enabled value so we
+ * can have, in tests, two projects in the same process with different
+ * enablement states.
+ */
+export function resolveReactCompilerConfig(
+  raw: RawReactCompilerConfig | undefined,
+  rootDir: string,
+): ResolvedReactCompilerConfig {
+  const explicit = raw?.enabled;
+  const cacheKey = `${rootDir}::${explicit ?? "auto"}`;
+  const hit = cache.get(cacheKey);
+  if (hit) return hit;
+
+  let enabled: boolean;
+  let autoDetected = false;
+  if (explicit === true) {
+    enabled = true;
+  } else if (explicit === false) {
+    enabled = false;
+  } else {
+    enabled = peerDepsInstalled(rootDir);
+    autoDetected = enabled;
+  }
+
+  const result: ResolvedReactCompilerConfig = {
+    enabled,
+    compilerConfig: raw?.compilerConfig,
+    autoDetected,
+  };
+  cache.set(cacheKey, result);
+  return result;
+}
+
+/** Test-only — drop cached probes between fixture setups. */
+export function _resetReactCompilerConfigCache(): void {
+  cache.clear();
+}

package/src/runtime/handlers.ts

@@ -0,0 +1,300 @@
+/**
+ * Manifest → runtime registry wiring.
+ *
+ * Lives in `@mandujs/core/runtime` (not in `@mandujs/cli`) because it
+ * runs at *server* boot, not at build time. Deploy adapters generate
+ * SSR entry files that need to call this — having it here means the
+ * generated entry imports a single, public package (`@mandujs/core`)
+ * instead of reaching into a CLI subpath that has no `exports` map.
+ *
+ * @module core/runtime/handlers
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  registerApiHandler,
+  registerPageLoader,
+  registerPageHandler,
+  registerLayoutLoader,
+  registerNotFoundHandler,
+  registerMetadataHandler,
+  registerWSHandler,
+  type PageRegistration,
+} from "./server";
+import { registerManifest } from "./registry";
+import { needsHydration, type RoutesManifest } from "../spec/schema";
+
+type RouteModule = Record<string, unknown>;
+
+/**
+ * Structural shape of a `ManduFilling` instance as seen by the registrar.
+ * Mirrors the subset of the public API we depend on (handle/hasWS/getWSHandlers)
+ * without importing the concrete class — that would pull in runtime deps
+ * the CLI shouldn't need at import time.
+ */
+interface FillingInstance {
+  handle: (req: Request, params?: Record<string, string>) => Response | Promise<Response>;
+  hasWS?: () => boolean;
+  getWSHandlers?: () => Parameters<typeof registerWSHandler>[1];
+}
+
+function isFillingInstance(value: unknown): value is FillingInstance {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { handle?: unknown }).handle === "function"
+  );
+}
+
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] as const;
+
+type HttpMethod = (typeof HTTP_METHODS)[number];
+
+function isHttpMethod(method: string): method is HttpMethod {
+  return (HTTP_METHODS as readonly string[]).includes(method);
+}
+
+function hasHttpMethodHandlers(module: RouteModule): boolean {
+  return HTTP_METHODS.some((method) => typeof module[method] === "function");
+}
+
+function createMethodDispatcher(module: RouteModule, routeId: string) {
+  return async (req: Request, params: Record<string, string> = {}) => {
+    const method = req.method.toUpperCase();
+    const handler = (isHttpMethod(method) ? module[method] : undefined) as
+      | ((request: Request, context?: { params: Record<string, string> }) => Response | Promise<Response>)
+      | undefined;
+
+    if (!handler) {
+      return Response.json(
+        {
+          error: `Method ${method} not allowed for route ${routeId}`,
+        },
+        {
+          status: 405,
+          headers: {
+            Allow: HTTP_METHODS.filter((m) => typeof module[m] === "function").join(", "),
+          },
+        }
+      );
+    }
+
+    return handler(req, { params });
+  };
+}
+
+export interface RegisterHandlersOptions {
+  /**
+   * Module import function (dev: importFresh, start: standard import).
+   * The optional `opts.changedFile` is forwarded into Phase 7.0 B5's
+   * incremental bundled-import: when the changed file is not in the
+   * module's import graph, `importFn` returns the cached bundle in ~0.1 ms
+   * instead of re-running Bun.build.
+   */
+  importFn: (modulePath: string, opts?: { changedFile?: string }) => Promise<unknown>;
+  /** Set for tracking already registered layout paths */
+  registeredLayouts: Set<string>;
+  /** Clear layout cache on reload */
+  isReload?: boolean;
+  /**
+   * Phase 7.0 B5 wire-up — on a live SSR reload, the changed file that
+   * triggered the reload. Omit for cold boot / wildcard (full
+   * invalidation). Forwarded to `importFn` so the incremental
+   * `bundledImport` can skip rebuilds for modules the file isn't part of.
+   */
+  changedFile?: string;
+}
+
+/**
+ * Register manifest routes as server handlers.
+ * Shared between dev/build/start commands and deploy-target SSR entries.
+ */
+export async function registerManifestHandlers(
+  manifest: RoutesManifest,
+  rootDir: string,
+  options: RegisterHandlersOptions
+): Promise<void> {
+  const { importFn, registeredLayouts, isReload = false, changedFile } = options;
+  const importOpts: { changedFile?: string } | undefined =
+    changedFile !== undefined ? { changedFile } : undefined;
+
+  if (isReload) {
+    registeredLayouts.clear();
+  }
+
+  // Expose the live manifest through the runtime registry so user code can
+  // read generated artifacts via `getGenerated("routes")` / `getManifest()`
+  // — the only official path. See `packages/core/src/runtime/registry.ts`.
+  registerManifest("routes", manifest);
+
+  for (const route of manifest.routes) {
+    // Issue #206: metadata routes (sitemap/robots/llms.txt/manifest)
+    // register a thunk that lazily imports the user module. The
+    // runtime dispatcher invokes the default export on each request
+    // so HMR reloads pick up edits automatically (same pattern as
+    // API routes below).
+    if (route.kind === "metadata") {
+      const modulePath = path.resolve(rootDir, route.module);
+      registerMetadataHandler(route.id, async () => {
+        return importFn(modulePath, importOpts);
+      });
+      console.log(`  🗺️  Metadata: ${route.pattern} -> ${route.id}`);
+      continue;
+    }
+
+    if (route.kind === "api") {
+      const modulePath = path.resolve(rootDir, route.module);
+      try {
+        const module = (await importFn(modulePath, importOpts)) as RouteModule;
+        let handler: unknown = module.default ?? module.handler ?? module;
+
+        // 1) ManduFilling instance
+        if (isFillingInstance(handler)) {
+          console.log(`  🔄 ManduFilling wrapped: ${route.id}`);
+          const filling = handler;
+
+          // WebSocket 핸들러 등록
+          if (typeof filling.hasWS === "function" && filling.hasWS() && filling.getWSHandlers) {
+            registerWSHandler(route.id, filling.getWSHandlers());
+            console.log(`  🔌 WebSocket: ${route.pattern} -> ${route.id}`);
+          }
+
+          handler = async (req: Request, params?: Record<string, string>) => {
+            return filling.handle(req, params);
+          };
+        }
+        // 2) Route module with HTTP method exports (GET/POST/...)
+        else if (handler && typeof handler === "object" && hasHttpMethodHandlers(handler as RouteModule)) {
+          handler = createMethodDispatcher(handler as RouteModule, route.id);
+        }
+
+        if (typeof handler !== "function") {
+          console.warn(`  ⚠️ API handler conversion failed: ${route.id} (type: ${typeof handler})`);
+          continue;
+        }
+
+        registerApiHandler(route.id, handler as (req: Request, params?: Record<string, string>) => Response | Promise<Response>);
+        console.log(`  📡 API: ${route.pattern} -> ${route.id}`);
+      } catch (error) {
+        console.error(`  ❌ Failed to load API handler: ${route.id}`, error);
+      }
+    } else if (route.kind === "page" && route.componentModule) {
+      const componentPath = path.resolve(rootDir, route.componentModule);
+      const isIsland = needsHydration(route);
+      const hasLayout = route.layoutChain && route.layoutChain.length > 0;
+
+      // Register layout loaders
+      if (route.layoutChain) {
+        for (const layoutPath of route.layoutChain) {
+          if (!registeredLayouts.has(layoutPath)) {
+            const absLayoutPath = path.resolve(rootDir, layoutPath);
+            registerLayoutLoader(layoutPath, (async () => {
+              // Layout modules must export a default component. Runtime
+              // validation in `renderToHTML` / page-loader asserts this —
+              // so casting the unknown `importFn` result is safe here.
+              return importFn(absLayoutPath, importOpts);
+            }) as Parameters<typeof registerLayoutLoader>[1]);
+            registeredLayouts.add(layoutPath);
+            console.log(`  🎨 Layout: ${layoutPath}`);
+          }
+        }
+      }
+
+      // Use PageHandler if slotModule exists (filling.loader support)
+      if (route.slotModule) {
+        registerPageHandler(route.id, async () => {
+          const mod = (await importFn(componentPath, importOpts)) as Record<string, unknown>;
+          // Normalize the page module shape. Users write pages in two styles:
+          //   (a) `export default function Page() {…}` + `export const filling = …`
+          //   (b) `export default { component: …, filling: … }`
+          // Spreading a function default drops the component silently (you get
+          // the function's own props like `name`/`length`, not the function).
+          // Auto-promote form (a) to form (b) so both work without surprises.
+          const rawDefault = mod.default as unknown;
+
+          let registration: PageRegistration;
+          if (typeof rawDefault === "function") {
+            registration = {
+              component: rawDefault as PageRegistration["component"],
+              filling: mod.filling as PageRegistration["filling"],
+            };
+          } else if (typeof rawDefault === "object" && rawDefault !== null) {
+            registration = { ...(rawDefault as unknown as PageRegistration) };
+          } else {
+            throw new Error(
+              `[Mandu] Page module '${route.id}' has no default export. ` +
+                `Expected a React component or { component, filling } object.`,
+            );
+          }
+
+          // #186: page 모듈의 metadata / generateMetadata 를 registration에 실어서
+          // ensurePageRouteMetadata가 registry 캐시에 저장할 수 있게 전달.
+          if (mod.metadata && typeof mod.metadata === "object") {
+            registration.metadata = mod.metadata as PageRegistration["metadata"];
+          }
+          if (typeof mod.generateMetadata === "function") {
+            registration.generateMetadata = mod.generateMetadata as PageRegistration["generateMetadata"];
+          }
+          return registration;
+        });
+        console.log(
+          `  📄 Page: ${route.pattern} -> ${route.id} (with loader)${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`
+        );
+      } else {
+        registerPageLoader(route.id, (() => importFn(componentPath, importOpts)) as Parameters<typeof registerPageLoader>[1]);
+        console.log(
+          `  📄 Page: ${route.pattern} -> ${route.id}${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`
+        );
+      }
+    }
+  }
+
+  // Phase 6.3: register `app/not-found.tsx` if it exists. Global, one per
+  // app — the server falls through to the built-in 404 if unregistered.
+  await registerAppNotFound(rootDir, importFn, importOpts);
+}
+
+/**
+ * Phase 6.3: look for `app/not-found.tsx` (or its variants) at the
+ * project root and register it as the app-level 404 handler. Silent
+ * no-op if no file exists — the server's built-in 404 covers that case.
+ */
+async function registerAppNotFound(
+  rootDir: string,
+  importFn: (modulePath: string, opts?: { changedFile?: string }) => Promise<unknown>,
+  importOpts?: { changedFile?: string },
+): Promise<void> {
+  const candidates = [
+    "app/not-found.tsx",
+    "app/not-found.ts",
+    "app/not-found.jsx",
+    "app/not-found.js",
+  ];
+  for (const rel of candidates) {
+    const abs = path.resolve(rootDir, rel);
+    try {
+      await fs.access(abs);
+    } catch {
+      continue;
+    }
+    registerNotFoundHandler(async () => {
+      const module = (await importFn(abs, importOpts)) as Record<string, unknown>;
+      const rawDefault = module.default as unknown;
+      if (typeof rawDefault === "function") {
+        return {
+          component: rawDefault as PageRegistration["component"],
+          filling: module.filling as PageRegistration["filling"],
+        };
+      }
+      if (typeof rawDefault === "object" && rawDefault !== null) {
+        return { ...(rawDefault as PageRegistration) };
+      }
+      throw new Error(
+        `[Mandu] app/not-found.tsx has no valid default export (type: ${typeof rawDefault})`,
+      );
+    });
+    console.log(`  🚫 Not-Found: ${rel}`);
+    return;
+  }
+}

package/src/runtime/index.ts

@@ -3,6 +3,10 @@ export * from "./streaming-ssr";
 export { extractShellHtml, createPPRResponse, PPR_SHELL_MARKER } from "./ppr";
 export * from "./router";
 export * from "./server";
+export {
+  registerManifestHandlers,
+  type RegisterHandlersOptions,
+} from "./handlers";
 export { redirect, isManduRedirect, isRedirectResponse, REDIRECT_BRAND } from "./redirect";
 export type { RedirectStatus, RedirectOptions } from "./redirect";
 export { notFound, isNotFoundResponse, NOT_FOUND_BRAND } from "./not-found";