@mandujs/core 0.42.0 → 0.43.1

package/src/runtime/fast-refresh-types.ts

@@ -1,128 +1,126 @@
-/**
- * Phase 7.1 — Fast Refresh shared types
- *
- * Bun 1.3.12 ships a native `Bun.build({ reactFastRefresh: true })` flag
- * that performs the `$RefreshReg$` / `$RefreshSig$` source transform
- * (equivalent to `babel-plugin-react-refresh`). Agent B's implementation
- * wires this into Mandu's bundler + a browser-side runtime that glues
- * `react-refresh/runtime` to our existing `ManduHot` dispatcher from
- * Phase 7.0.C.
- *
- * This file is the CONTRACT. Types only — the implementation lives in:
- *   - packages/core/src/bundler/fast-refresh-plugin.ts (Agent B new)
- *   - packages/core/src/runtime/fast-refresh-runtime.ts (Agent B new)
- *   - packages/core/src/bundler/build.ts (Agent B extend — vendor shim)
- *   - packages/core/src/bundler/dev.ts (Agent B extend — HTML preamble)
- *
- * References:
- *   docs/bun/phase-7-1-diagnostics/fast-refresh-strategy.md
- *   docs/bun/phase-7-1-team-plan.md §3.2
- *   https://bun.com/reference/bun/NormalBuildConfig/reactFastRefresh
- */
-
-// ============================================
-// Browser-side `__MANDU_HMR__` global
-// ============================================
-
-/**
- * The single global object Mandu's bundler-emitted boundary code talks
- * to. Installed by the HTML preamble script before any island runs.
- *
- * Keeping all Fast Refresh wiring behind this single namespace makes
- * the attack surface (Phase 7.1.E security audit) a single module.
- */
-export interface ManduHMRGlobal {
-  /**
-   * Register a module URL as an HMR boundary. Emitted by the bundler
-   * onLoad plugin (Agent B) for each `.client.tsx` / `.island.tsx`.
-   * Idempotent — registering the same URL twice is a no-op.
-   */
-  acceptFile(moduleUrl: string): void;
-
-  /**
-   * Invoke `react-refresh/runtime.performReactRefresh()` on the next
-   * microtask. Coalesces multiple calls within the same tick into a
-   * single refresh, so a batched rebuild that swaps 3 modules only
-   * re-renders the React tree once.
-   */
-  performReactRefresh(): void;
-
-  /**
-   * Whether `moduleUrl` was ever registered via `acceptFile`. Used by
-   * `dispatchReplacement` (Phase 7.0.C runtime/hmr-client.ts) to decide
-   * between "call performReactRefresh" vs "full reload fallback".
-   */
-  isBoundary(moduleUrl: string): boolean;
-
-  /**
-   * Reset state — test-only. Clears the boundary registry and React
-   * refresh runtime scheduling state. Must NOT be exposed in production
-   * bundles; tests import this via the `runtime/fast-refresh-runtime.ts`
-   * module directly.
-   */
-  _testOnly_reset(): void;
-}
-
-/**
- * Metadata the bundler attaches to each emitted boundary. Not part of
- * the runtime API — consumed only by dev-mode tooling (hmr-bench,
- * Kitchen DevTools) and by the security audit (Phase 7.1.E) to verify
- * that every injected boundary traces back to a real source file.
- */
-export interface RefreshBoundaryMetadata {
-  /** URL the module is served under (e.g. `/.mandu/client/home.island.js`). */
-  moduleUrl: string;
-  /** Source files that were bundled into this module, from Bun.build's
-   *  inline sourcemap `sources[]` (same mechanism Phase 7.0.B uses). */
-  sources: readonly string[];
-  /** Unix ms when the boundary was registered — for debug log ordering. */
-  registeredAt: number;
-}
-
-// ============================================
-// Bundler side
-// ============================================
-
-/**
- * Options passed to the Fast Refresh Bun.build plugin (Agent B new file
- * `bundler/fast-refresh-plugin.ts`). All optional — sensible defaults
- * match Vite's `@vitejs/plugin-react` behavior.
- */
-export interface FastRefreshPluginOptions {
-  /** Only transform files matching this test. Default: `/\.(client|island)\.tsx?$/`. */
-  include?: RegExp;
-  /** Bypass the transform entirely. Used for prod builds. Default: `false`. */
-  disabled?: boolean;
-  /**
-   * Runtime module specifier the plugin's injected import points at.
-   * Default: `"@mandujs/core/runtime/fast-refresh-runtime"`. Tests can
-   * override to a tmpdir-local stub.
-   */
-  runtimeImport?: string;
-}
-
-/**
- * Classification of why a module was (or wasn't) made a Fast Refresh
- * boundary. Used by the plugin's debug log + Agent D's E2E assertions.
- */
-export type BoundaryDecision =
-  | { accepted: true; reason: "matched-include"; source: string }
-  | { accepted: false; reason: "excluded-by-include" | "disabled" | "non-react" };
-
-// ============================================
-// Global augmentation — Window type
-// ============================================
-
-/**
- * Expose `__MANDU_HMR__` on the browser Window without polluting Node
- * typings. Users of the plugin see `window.__MANDU_HMR__.acceptFile(...)`
- * as strongly typed in TSX files.
- */
-declare global {
-  interface Window {
-    /** Phase 7.1 Fast Refresh glue. Installed by HTML preamble. */
-    __MANDU_HMR__?: ManduHMRGlobal;
-  }
-}
-
-export {}; // ensure this file is a module for `declare global`
+/**
+ * Phase 7.1 — Fast Refresh shared types
+ *
+ * Bun 1.3.12 ships a native `Bun.build({ reactFastRefresh: true })` flag
+ * that performs the `$RefreshReg$` / `$RefreshSig$` source transform
+ * (equivalent to `babel-plugin-react-refresh`). Agent B's implementation
+ * wires this into Mandu's bundler + a browser-side runtime that glues
+ * `react-refresh/runtime` to our existing `ManduHot` dispatcher from
+ * Phase 7.0.C.
+ *
+ * This file is the CONTRACT. Types only — the implementation lives in:
+ *   - packages/core/src/bundler/fast-refresh-plugin.ts (Agent B new)
+ *   - packages/core/src/runtime/fast-refresh-runtime.ts (Agent B new)
+ *   - packages/core/src/bundler/build.ts (Agent B extend — vendor shim)
+ *   - packages/core/src/bundler/dev.ts (Agent B extend — HTML preamble)
+ *
+ * References:
+ *   docs/bun/phase-7-1-diagnostics/fast-refresh-strategy.md
+ *   docs/bun/phase-7-1-team-plan.md §3.2
+ *   https://bun.com/reference/bun/NormalBuildConfig/reactFastRefresh
+ */
+
+// ============================================
+// Browser-side `__MANDU_HMR__` global
+// ============================================
+
+/**
+ * The single global object Mandu's bundler-emitted boundary code talks
+ * to. Installed by the HTML preamble script before any island runs.
+ *
+ * Keeping all Fast Refresh wiring behind this single namespace makes
+ * the attack surface (Phase 7.1.E security audit) a single module.
+ */
+export interface ManduHMRGlobal {
+  /**
+   * Register a module URL as an HMR boundary. Emitted by the bundler
+   * onLoad plugin (Agent B) for each `.client.tsx` / `.island.tsx`.
+   * Idempotent — registering the same URL twice is a no-op.
+   */
+  acceptFile(moduleUrl: string): void;
+
+  /**
+   * Invoke `react-refresh/runtime.performReactRefresh()` on the next
+   * microtask. Coalesces multiple calls within the same tick into a
+   * single refresh, so a batched rebuild that swaps 3 modules only
+   * re-renders the React tree once.
+   */
+  performReactRefresh(): void;
+
+  /**
+   * Whether `moduleUrl` was ever registered via `acceptFile`. Used by
+   * `dispatchReplacement` (Phase 7.0.C runtime/hmr-client.ts) to decide
+   * between "call performReactRefresh" vs "full reload fallback".
+   */
+  isBoundary(moduleUrl: string): boolean;
+
+  /**
+   * Reset state — test-only. Clears the boundary registry and React
+   * refresh runtime scheduling state. Must NOT be exposed in production
+   * bundles; tests import this via the `runtime/fast-refresh-runtime.ts`
+   * module directly.
+   */
+  _testOnly_reset(): void;
+}
+
+/**
+ * Metadata the bundler attaches to each emitted boundary. Not part of
+ * the runtime API — consumed only by dev-mode tooling (hmr-bench,
+ * Kitchen DevTools) and by the security audit (Phase 7.1.E) to verify
+ * that every injected boundary traces back to a real source file.
+ */
+export interface RefreshBoundaryMetadata {
+  /** URL the module is served under (e.g. `/.mandu/client/home.island.js`). */
+  moduleUrl: string;
+  /** Source files that were bundled into this module, from Bun.build's
+   *  inline sourcemap `sources[]` (same mechanism Phase 7.0.B uses). */
+  sources: readonly string[];
+  /** Unix ms when the boundary was registered — for debug log ordering. */
+  registeredAt: number;
+}
+
+// ============================================
+// Bundler side
+// ============================================
+
+/**
+ * Options passed to the Fast Refresh Bun.build plugin (Agent B new file
+ * `bundler/fast-refresh-plugin.ts`). All optional — sensible defaults
+ * match Vite's `@vitejs/plugin-react` behavior.
+ */
+export interface FastRefreshPluginOptions {
+  /** Only transform files matching this test. Default: `/\.(client|island)\.tsx?$/`. */
+  include?: RegExp;
+  /** Bypass the transform entirely. Used for prod builds. Default: `false`. */
+  disabled?: boolean;
+  /**
+   * Runtime module specifier the plugin's injected import points at.
+   * Default: `"@mandujs/core/runtime/fast-refresh-runtime"`. Tests can
+   * override to a tmpdir-local stub.
+   */
+  runtimeImport?: string;
+}
+
+/**
+ * Classification of why a module was (or wasn't) made a Fast Refresh
+ * boundary. Used by the plugin's debug log + Agent D's E2E assertions.
+ */
+export type BoundaryDecision =
+  | { accepted: true; reason: "matched-include"; source: string }
+  | { accepted: false; reason: "excluded-by-include" | "disabled" | "non-react" };
+
+// ============================================
+// Global augmentation — Window type
+// ============================================
+
+/**
+ * Expose `__MANDU_HMR__` on the browser Window without polluting Node
+ * typings. Users of the plugin see `window.__MANDU_HMR__.acceptFile(...)`
+ * as strongly typed in TSX files.
+ */
+declare global {
+  interface Window {
+    /** Phase 7.1 Fast Refresh glue. Installed by HTML preamble. */
+    __MANDU_HMR__?: ManduHMRGlobal;
+  }
+}

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;
+  }
+}