@mandujs/core 0.54.9 → 0.54.11

package/src/runtime/server.ts

@@ -1,10 +1,10 @@
-import type { Server, ServerWebSocket } from "bun";
+import type { Server, ServerWebSocket } from "bun";
 import type { RoutesManifest, RouteSpec, HydrationConfig, StaticParamSetSchema } from "../spec/schema";
 import type { BundleManifest } from "../bundler/types";
-import type { ManduFilling, RenderMode } from "../filling/filling";
-import { ManduContext, CookieManager } from "../filling/context";
-import { Router } from "./router";
-import { renderSSR, resolveAsyncElement } from "./ssr";
+import type { ManduFilling, RenderMode } from "../filling/filling";
+import { ManduContext, CookieManager } from "../filling/context";
+import { Router } from "./router";
+import { renderSSR, resolveAsyncElement } from "./ssr";
 import {
   resolveMetadata,
   renderMetadata,
@@ -50,34 +50,34 @@ import {
   isCorsRequest,
 } from "./cors";
 import { validateImportPath } from "./security";
-import {
-  createRuntimeDevtoolsAdapter,
-  recordRuntimeRequest,
-  shouldRecordRuntimeRequest,
-  type RuntimeDevtoolsAdapter,
-  type RuntimeKitchenHandler,
-} from "./devtools-adapter";
-import {
-  createRuntimeObservabilityLifecycle,
-  type RuntimeObservabilityLifecycle,
-} from "./observability-lifecycle";
-import {
-  handleOpenAPIRequest,
-  isOpenAPIEndpointEnabled,
-  resolveOpenAPIEndpointSettings,
-  type OpenAPIEndpointSettings,
-} from "./openapi-endpoint";
-import {
-  type MiddlewareFn,
-  type MiddlewareConfig,
-  loadMiddlewareSync,
-} from "./middleware";
-import {
-  buildRequestMiddlewareChain,
-  runRequestMiddleware,
-  type ComposedHandler,
-} from "./request-middleware";
-import type { Middleware } from "../middleware/define";
+import {
+  createRuntimeDevtoolsAdapter,
+  recordRuntimeRequest,
+  shouldRecordRuntimeRequest,
+  type RuntimeDevtoolsAdapter,
+  type RuntimeKitchenHandler,
+} from "./devtools-adapter";
+import {
+  createRuntimeObservabilityLifecycle,
+  type RuntimeObservabilityLifecycle,
+} from "./observability-lifecycle";
+import {
+  handleOpenAPIRequest,
+  isOpenAPIEndpointEnabled,
+  resolveOpenAPIEndpointSettings,
+  type OpenAPIEndpointSettings,
+} from "./openapi-endpoint";
+import {
+  type MiddlewareFn,
+  type MiddlewareConfig,
+  loadMiddlewareSync,
+} from "./middleware";
+import {
+  buildRequestMiddlewareChain,
+  runRequestMiddleware,
+  type ComposedHandler,
+} from "./request-middleware";
+import type { Middleware } from "../middleware/define";
 // Phase 18.λ — scheduler wiring (statically imported so `startServer` stays
 // synchronous; the cost of unused code is trivial — `defineCron` is a thin
 // wrapper around `Bun.cron`).
@@ -85,16 +85,16 @@ import { defineCron as schedulerDefineCron, type CronDef, type CronRegistration
 import { setActiveSchedulerRegistration } from "../middleware/scheduler-cron";
 import { createFetchHandler } from "./handler";
 import { wrapBunWebSocket, type WSHandlers, type WSUpgradeData } from "../filling/ws";
-import { handleImageRequest } from "./image-handler";
-import {
-  serveStaticFile,
-  computeStrongEtag,
-  computeStaticCacheControl,
-  matchesEtag,
-} from "./static-files";
-export { __clearStaticEtagCacheForTests } from "./static-files";
-import { extractShellHtml, createPPRResponse } from "./ppr";
-import { renderPageResponse } from "./page-render-response";
+import { handleImageRequest } from "./image-handler";
+import {
+  serveStaticFile,
+  computeStrongEtag,
+  computeStaticCacheControl,
+  matchesEtag,
+} from "./static-files";
+export { __clearStaticEtagCacheForTests } from "./static-files";
+import { extractShellHtml, createPPRResponse } from "./ppr";
+import { renderPageResponse } from "./page-render-response";
 import { isRedirectResponse } from "./redirect";
 import { isNotFoundResponse } from "./not-found";
 import { newId } from "../id";
@@ -315,8 +315,8 @@ function createRateLimitResponse(decision: RateLimitDecision, options: Normalize
   return appendRateLimitHeaders(response, decision, options);
 }
 
-// ========== Server Options ==========
-export interface ServerOptions {
+// ========== Server Options ==========
+export interface ServerOptions {
   port?: number;
   hostname?: string;
   /** 프로젝트 루트 디렉토리 */
@@ -599,15 +599,15 @@ export interface ServerOptions {
   silent?: boolean;
 }
 
-export interface ManduServer {
-  server: Server<undefined>;
-  router: Router;
-  /** 이 서버 인스턴스의 레지스트리 */
-  registry: ServerRegistry;
-  /** Replace the live dispatch table after FS routes change in dev mode. */
-  updateManifest: (nextManifest: RoutesManifest) => void;
-  stop: () => void;
-}
+export interface ManduServer {
+  server: Server<undefined>;
+  router: Router;
+  /** 이 서버 인스턴스의 레지스트리 */
+  registry: ServerRegistry;
+  /** Replace the live dispatch table after FS routes change in dev mode. */
+  updateManifest: (nextManifest: RoutesManifest) => void;
+  stop: () => void;
+}
 
 export type ApiHandler = (req: Request, params: Record<string, string>) => Response | Promise<Response>;
 export type PageLoader = () => Promise<{ default: React.ComponentType<{ params: Record<string, string> }> }>;
@@ -746,8 +746,8 @@ export interface ServerRegistrySettings {
    * in-head `<script>` and the 500-response HTML overlay. No-op in prod.
    */
   errorOverlay?: boolean;
-  /** Runtime observability lifecycle: endpoints, tracing, perf, counters. */
-  observability?: RuntimeObservabilityLifecycle;
+  /** Runtime observability lifecycle: endpoints, tracing, perf, counters. */
+  observability?: RuntimeObservabilityLifecycle;
   /**
    * Production OpenAPI endpoint — resolved from `ServerOptions.openapi`.
    * `undefined` means the endpoint is disabled (hot path branch-free).
@@ -832,10 +832,10 @@ export class ServerRegistry {
    * to the framework's built-in 404 JSON error.
    */
   notFoundHandler: PageHandler | null = null;
-  /** Runtime devtools adapter (dev mode only) */
-  devtoolsAdapter: RuntimeDevtoolsAdapter | null = null;
-  /** Kitchen dev dashboard handler (dev mode only, kept for compatibility) */
-  kitchen: RuntimeKitchenHandler | null = null;
+  /** Runtime devtools adapter (dev mode only) */
+  devtoolsAdapter: RuntimeDevtoolsAdapter | null = null;
+  /** Kitchen dev dashboard handler (dev mode only, kept for compatibility) */
+  kitchen: RuntimeKitchenHandler | null = null;
   /** 라우트별 캐시 옵션 (filling.loader()의 cacheOptions에서 등록) */
   readonly cacheOptions: Map<string, { revalidate?: number; staleWhileRevalidate?: number; tags?: string[] }> = new Map();
   /** 라우트별 렌더 모드 */
@@ -1272,9 +1272,9 @@ function createDefaultAppFactory(registry: ServerRegistry) {
   };
 }
 
-const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
-
-// ========== Request Handler ==========
+const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
+
+// ========== Request Handler ==========
 
 function unauthorizedControlResponse(): Response {
   return Response.json({ error: "Unauthorized runtime control request" }, { status: 401 });
@@ -1362,29 +1362,29 @@ async function handleInternalCacheControlRequest(
   return new Response(JSON.stringify({ error: "Method not allowed", allowed: ["GET", "POST", "DELETE"], hint: `Received '${req.method}'. This endpoint accepts GET (read stats), POST (clear by path/tag), and DELETE (clear all).` }), { status: 405, headers: { "Content-Type": "application/json", "Allow": "GET, POST, DELETE" } });
 }
 
-async function handleRequest(req: Request, router: Router, registry: ServerRegistry): Promise<Response> {
-  const requestStart = Date.now();
-  // Phase 1-4: Correlation ID — 한 요청에서 발생하는 모든 이벤트를 추적
-  const correlationId = req.headers.get("x-mandu-request-id") ?? newId();
-
-  const observability = registry.settings.observability;
-  if (observability) {
-    return await observability.runRequest(
-      req,
-      requestStart,
-      correlationId,
-      () => handleRequestObserved(req, router, registry, requestStart, correlationId)
-    );
-  }
-  return await handleRequestObserved(req, router, registry, requestStart, correlationId);
-}
-
-/**
- * Inner request handler. Observability lifecycle wrapping happens at
- * {@link handleRequest}; this function keeps response post-processing in one
- * place without owning tracing or metrics wiring directly.
- */
-async function handleRequestObserved(
+async function handleRequest(req: Request, router: Router, registry: ServerRegistry): Promise<Response> {
+  const requestStart = Date.now();
+  // Phase 1-4: Correlation ID — 한 요청에서 발생하는 모든 이벤트를 추적
+  const correlationId = req.headers.get("x-mandu-request-id") ?? newId();
+
+  const observability = registry.settings.observability;
+  if (observability) {
+    return await observability.runRequest(
+      req,
+      requestStart,
+      correlationId,
+      () => handleRequestObserved(req, router, registry, requestStart, correlationId)
+    );
+  }
+  return await handleRequestObserved(req, router, registry, requestStart, correlationId);
+}
+
+/**
+ * Inner request handler. Observability lifecycle wrapping happens at
+ * {@link handleRequest}; this function keeps response post-processing in one
+ * place without owning tracing or metrics wiring directly.
+ */
+async function handleRequestObserved(
   req: Request,
   router: Router,
   registry: ServerRegistry,
@@ -1396,24 +1396,24 @@ async function handleRequestObserved(
   if (!result.ok) {
     const errorResponse = errorToResponse(result.error, registry.settings.isDev);
     if (registry.settings.isDev) {
-      // #177: dev 모드 에러 응답도 캐시 방지
-      if (!errorResponse.headers.has("Cache-Control")) {
-        errorResponse.headers.set("Cache-Control", "no-cache, no-store, must-revalidate");
-      }
-      const url = new URL(req.url);
-      const p = url.pathname;
-      if (shouldRecordRuntimeRequest(p)) {
-        const elapsed = Date.now() - requestStart;
-        registry.settings.observability?.recordDevRequest({
-          req,
-          path: p,
-          status: errorResponse.status,
-          duration: elapsed,
-          correlationId,
-          error: true,
-          recordRequest: recordRuntimeRequest,
-        });
-      }
+      // #177: dev 모드 에러 응답도 캐시 방지
+      if (!errorResponse.headers.has("Cache-Control")) {
+        errorResponse.headers.set("Cache-Control", "no-cache, no-store, must-revalidate");
+      }
+      const url = new URL(req.url);
+      const p = url.pathname;
+      if (shouldRecordRuntimeRequest(p)) {
+        const elapsed = Date.now() - requestStart;
+        registry.settings.observability?.recordDevRequest({
+          req,
+          path: p,
+          status: errorResponse.status,
+          duration: elapsed,
+          correlationId,
+          error: true,
+          recordRequest: recordRuntimeRequest,
+        });
+      }
     }
     // Phase 18.μ — stamp locale hint on error responses too.
     const errI18nState = i18nRequestState.get(req);
@@ -1437,21 +1437,21 @@ async function handleRequestObserved(
       result.value.headers.set("Cache-Control", "no-cache, no-store, must-revalidate");
     }
 
-    if (shouldRecordRuntimeRequest(p)) {
-      const elapsed = Date.now() - requestStart;
-      const status = result.value.status;
-      const cacheHdr = result.value.headers.get("X-Mandu-Cache") ?? "";
-      registry.settings.observability?.recordDevRequest({
-        req,
-        path: p,
-        status,
-        duration: elapsed,
-        correlationId,
-        cacheStatus: cacheHdr || undefined,
-        recordRequest: recordRuntimeRequest,
-      });
-    }
-  }
+    if (shouldRecordRuntimeRequest(p)) {
+      const elapsed = Date.now() - requestStart;
+      const status = result.value.status;
+      const cacheHdr = result.value.headers.get("X-Mandu-Cache") ?? "";
+      registry.settings.observability?.recordDevRequest({
+        req,
+        path: p,
+        status,
+        duration: elapsed,
+        correlationId,
+        cacheStatus: cacheHdr || undefined,
+        recordRequest: recordRuntimeRequest,
+      });
+    }
+  }
 
   // Phase 18.μ — stamp locale-sensitive caching hints onto the final
   // response. `Vary: Accept-Language, Cookie` ensures upstream caches
@@ -2232,26 +2232,26 @@ async function renderPageSSR(
 
     // Island 래핑: 레이아웃 적용 전에 페이지 콘텐츠만 island div로 감쌈
     // 이렇게 하면 레이아웃은 island 바깥에 위치하여 하이드레이션 시 레이아웃이 유지됨
-    const needsIslandHydration = !!(
-      route.hydration &&
-      route.hydration.strategy !== "none" &&
-      settings.bundleManifest
-    );
-    const routeBundle = settings.bundleManifest?.bundles[route.id];
-    const bundleSrc = routeBundle?.js ? `${routeBundle.js}?t=${Date.now()}` : "";
-    const needsIslandWrap = needsIslandHydration && bundleSrc.length > 0;
-
-    if (needsIslandHydration && !needsIslandWrap && settings.isDev) {
-      console.warn(
-        `[Mandu] Hydration requested for route "${route.id}" but no client bundle was found. ` +
-        `Run mandu build/generate and ensure the route has a clientModule.`,
-      );
-    }
-
-    if (needsIslandWrap) {
-      const priority = route.hydration!.priority || "visible";
-      app = React.createElement("div", {
-        "data-mandu-island": route.id,
+    const needsIslandHydration = !!(
+      route.hydration &&
+      route.hydration.strategy !== "none" &&
+      settings.bundleManifest
+    );
+    const routeBundle = settings.bundleManifest?.bundles[route.id];
+    const bundleSrc = routeBundle?.js ? `${routeBundle.js}?t=${Date.now()}` : "";
+    const needsIslandWrap = needsIslandHydration && bundleSrc.length > 0;
+
+    if (needsIslandHydration && !needsIslandWrap && settings.isDev) {
+      console.warn(
+        `[Mandu] Hydration requested for route "${route.id}" but no client bundle was found. ` +
+        `Run mandu build/generate and ensure the route has a clientModule.`,
+      );
+    }
+
+    if (needsIslandWrap) {
+      const priority = route.hydration!.priority || "visible";
+      app = React.createElement("div", {
+        "data-mandu-island": route.id,
         "data-mandu-src": bundleSrc,
         "data-mandu-priority": priority,
         style: { display: "contents" },
@@ -2263,37 +2263,37 @@ async function renderPageSSR(
       app = await wrapWithLayouts(app, route.layoutChain, registry, params, layoutData);
     }
 
-    // #186: layout chain + page metadata 병합
-    const builtMeta = await buildSSRMetadata(route, params, url, registry);
-
+    // #186: layout chain + page metadata 병합
+    const builtMeta = await buildSSRMetadata(route, params, url, registry);
+
     // Streaming SSR 모드 결정
     const useStreaming = route.streaming !== undefined
       ? route.streaming
       : settings.streaming;
 
-    const pageResponse = await renderPageResponse({
-      app,
-      useStreaming,
-      title: builtMeta.title,
-      headTags: builtMeta.headTags,
-      isDev: settings.isDev,
-      hmrPort: settings.hmrPort,
-      routeId: route.id,
-      routePattern: route.pattern,
-      layoutChain: route.layoutChain,
-      hydration: route.hydration,
-      bundleManifest: settings.bundleManifest,
-      loaderData,
-      cssPath: settings.cssPath,
-      islandPreWrapped: needsIslandWrap,
-      transitions: settings.transitions,
-      prefetch: settings.prefetch,
-      spa: settings.spa,
-      devtools: settings.devtools,
-      cookies,
-    });
-    return ok(pageResponse);
-  } catch (error) {
+    const pageResponse = await renderPageResponse({
+      app,
+      useStreaming,
+      title: builtMeta.title,
+      headTags: builtMeta.headTags,
+      isDev: settings.isDev,
+      hmrPort: settings.hmrPort,
+      routeId: route.id,
+      routePattern: route.pattern,
+      layoutChain: route.layoutChain,
+      hydration: route.hydration,
+      bundleManifest: settings.bundleManifest,
+      loaderData,
+      cssPath: settings.cssPath,
+      islandPreWrapped: needsIslandWrap,
+      transitions: settings.transitions,
+      prefetch: settings.prefetch,
+      spa: settings.spa,
+      devtools: settings.devtools,
+      cookies,
+    });
+    return ok(pageResponse);
+  } catch (error) {
     const renderError = error instanceof Error ? error : new Error(String(error));
 
     // Route-level ErrorBoundary: errorModule이 있으면 해당 컴포넌트로 에러 렌더링
@@ -3377,14 +3377,14 @@ async function handleRequestInternal(
     return ok(await handleInternalCacheControlRequest(req, settings));
   }
 
-  // 1.7. Internal observability endpoints: EventBus stream/recent, heap,
-  // Prometheus metrics, and user perf snapshot composition.
-  const observabilityResponse = settings.observability?.handleEndpoint(req, pathname);
-  if (observabilityResponse) {
-    return ok(observabilityResponse);
-  }
-
-  // Production OpenAPI endpoint — `/__mandu/openapi.json` + `.yaml`.
+  // 1.7. Internal observability endpoints: EventBus stream/recent, heap,
+  // Prometheus metrics, and user perf snapshot composition.
+  const observabilityResponse = settings.observability?.handleEndpoint(req, pathname);
+  if (observabilityResponse) {
+    return ok(observabilityResponse);
+  }
+
+  // Production OpenAPI endpoint — `/__mandu/openapi.json` + `.yaml`.
   // Gated behind `ManduConfig.openapi.enabled` (or MANDU_OPENAPI_ENABLED=1).
   // Every response carries an ETag so CDNs / browsers revalidate cheaply
   // after a deploy. Falls through to route dispatch if disabled OR the
@@ -3404,35 +3404,35 @@ async function handleRequestInternal(
     if (openapiResponse) return ok(openapiResponse);
   }
 
-  // 2. Runtime devtools / Kitchen dashboard (dev mode only)
-  if (registry.devtoolsAdapter) {
-    const devtoolsResponse = await registry.devtoolsAdapter.handleRequest(req, pathname);
-    if (devtoolsResponse) return ok(devtoolsResponse);
-  }
-
-  // ─── Phase 18.ε — canonical request-level middleware chain ───────────────
-  // Runs BEFORE route dispatch, AFTER infrastructure fast-paths (static
-  // files, CORS preflight, internal endpoints, γ's prerendered pass-through,
-  // Kitchen). Each composed layer can short-circuit with its own Response
-  // or wrap the downstream Response after `next()` returns. Zero overhead
-  // when no middleware is configured (settings.middlewareChain === undefined).
-  const middlewareResponse = await runRequestMiddleware({
-    req,
-    middlewareChain: settings.middlewareChain,
-    skipMiddleware,
-    finalHandler: async (finalReq) => {
-      const result = await handleRequestInternal(finalReq, router, registry, true);
-      if (result.ok) return result.value;
-      // Surface error-path responses to the chain so logging / metrics
-      // layers see the final status. The outer `handleRequest` still owns
-      // dev-mode Cache-Control stamping + observability lifecycle emission.
-      return errorToResponse(result.error, settings.isDev);
-    },
-  });
-  if (middlewareResponse) {
-    return ok(middlewareResponse);
-  }
-  // ─── End Phase 18.ε ──────────────────────────────────────────────────────
+  // 2. Runtime devtools / Kitchen dashboard (dev mode only)
+  if (registry.devtoolsAdapter) {
+    const devtoolsResponse = await registry.devtoolsAdapter.handleRequest(req, pathname);
+    if (devtoolsResponse) return ok(devtoolsResponse);
+  }
+
+  // ─── Phase 18.ε — canonical request-level middleware chain ───────────────
+  // Runs BEFORE route dispatch, AFTER infrastructure fast-paths (static
+  // files, CORS preflight, internal endpoints, γ's prerendered pass-through,
+  // Kitchen). Each composed layer can short-circuit with its own Response
+  // or wrap the downstream Response after `next()` returns. Zero overhead
+  // when no middleware is configured (settings.middlewareChain === undefined).
+  const middlewareResponse = await runRequestMiddleware({
+    req,
+    middlewareChain: settings.middlewareChain,
+    skipMiddleware,
+    finalHandler: async (finalReq) => {
+      const result = await handleRequestInternal(finalReq, router, registry, true);
+      if (result.ok) return result.value;
+      // Surface error-path responses to the chain so logging / metrics
+      // layers see the final status. The outer `handleRequest` still owns
+      // dev-mode Cache-Control stamping + observability lifecycle emission.
+      return errorToResponse(result.error, settings.isDev);
+    },
+  });
+  if (middlewareResponse) {
+    return ok(middlewareResponse);
+  }
+  // ─── End Phase 18.ε ──────────────────────────────────────────────────────
 
   // ─── Phase 18.κ — typed RPC dispatch ──────────────────────────────────────
   // Runs AFTER γ's prerendered pass-through (handled earlier at step 0.5),
@@ -3754,9 +3754,9 @@ export function formatServerAddresses(
   return { primary: `http://${hosts[0]}:${port}`, additional: [] };
 }
 
-export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
-  const {
-    port = 3333,
+export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
+  const {
+    port = 3333,
     // Default to `"::"` (IPv6 wildcard, dual-stack). Bun leaves IPV6_V6ONLY
     // off, so this single socket accepts both IPv4 (as IPv4-mapped IPv6)
     // and IPv6 clients — covering `127.0.0.1`, `[::1]`, and LAN addresses
@@ -3838,8 +3838,8 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
   // are NOT consulted for the middleware chain itself.
   void pluginsOption;
   void configHooksOption;
-  const middlewareChain: ComposedHandler | undefined =
-    buildRequestMiddlewareChain(middlewareOption);
+  const middlewareChain: ComposedHandler | undefined =
+    buildRequestMiddlewareChain(middlewareOption);
 
   // Phase 18 — normalize prerender pass-through settings. `undefined`
   // defaults to enabled (Next.js parity); explicit `false` opts out.
@@ -3880,12 +3880,12 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     console.warn("   cors: { origin: ['https://yourdomain.com'] }");
   }
 
-  const observabilityLifecycle = createRuntimeObservabilityLifecycle({
-    isDev,
-    heapEndpoint: observabilityOption?.heapEndpoint,
-    metricsEndpoint: observabilityOption?.metricsEndpoint,
-    tracing: observabilityOption?.tracing,
-  });
+  const observabilityLifecycle = createRuntimeObservabilityLifecycle({
+    isDev,
+    heapEndpoint: observabilityOption?.heapEndpoint,
+    metricsEndpoint: observabilityOption?.metricsEndpoint,
+    tracing: observabilityOption?.tracing,
+  });
 
   // Registry settings 저장 (초기값)
   registry.settings = {
@@ -3903,7 +3903,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     prefetch,
     spa,
     devtools,
-    observability: observabilityLifecycle,
+    observability: observabilityLifecycle,
     // Production OpenAPI endpoint — default OFF so an internet-facing
     // deployment does not leak its API surface without explicit opt-in.
     // `MANDU_OPENAPI_ENABLED=1` in the environment forces-on without a
@@ -3975,16 +3975,16 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
   }
   // ─── End Phase 18.ζ ────────────────────────────────────────────────────
 
-  // Runtime devtools / Kitchen dashboard (dev mode only)
-  const devtoolsAdapter = createRuntimeDevtoolsAdapter({
-    isDev,
-    rootDir,
-    manifest,
-    guardConfig,
-  });
-  devtoolsAdapter.start();
-  registry.devtoolsAdapter = devtoolsAdapter;
-  registry.kitchen = devtoolsAdapter.kitchen;
+  // Runtime devtools / Kitchen dashboard (dev mode only)
+  const devtoolsAdapter = createRuntimeDevtoolsAdapter({
+    isDev,
+    rootDir,
+    manifest,
+    guardConfig,
+  });
+  devtoolsAdapter.start();
+  registry.devtoolsAdapter = devtoolsAdapter;
+  registry.kitchen = devtoolsAdapter.kitchen;
 
   const router = new Router(manifest.routes);
 
@@ -4033,9 +4033,9 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     },
   } : undefined;
 
-  const bumpCounter = (req: Request, res: Response | undefined): void => {
-    registry.settings.observability?.recordHttpResponse(req, res);
-  };
+  const bumpCounter = (req: Request, res: Response | undefined): void => {
+    registry.settings.observability?.recordHttpResponse(req, res);
+  };
 
   // fetch handler: WS upgrade 감지 추가
   //
@@ -4135,9 +4135,9 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
       if (streaming) {
         console.log(`🌊 Streaming SSR enabled`);
       }
-      if (registry.devtoolsAdapter?.dashboardPath) {
-        console.log(`🍳 Kitchen dashboard at ${addresses.primary}${registry.devtoolsAdapter.dashboardPath}`);
-      }
+      if (registry.devtoolsAdapter?.dashboardPath) {
+        console.log(`🍳 Kitchen dashboard at ${addresses.primary}${registry.devtoolsAdapter.dashboardPath}`);
+      }
     } else {
       console.log(`🥟 Mandu server listening at ${addresses.primary}`);
       if (addresses.additional.length > 0) {
@@ -4187,19 +4187,19 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     }
   }
 
-  return {
-    server,
-    router,
-    registry,
-    updateManifest: (nextManifest: RoutesManifest) => {
-      router.setRoutes(nextManifest.routes);
-      registry.devtoolsAdapter?.updateManifest(nextManifest);
-    },
-    stop: () => {
-      registry.devtoolsAdapter?.stop();
-      registry.devtoolsAdapter = null;
-      registry.kitchen = null;
-      // Fire-and-forget the async scheduler drain so `stop()` stays
+  return {
+    server,
+    router,
+    registry,
+    updateManifest: (nextManifest: RoutesManifest) => {
+      router.setRoutes(nextManifest.routes);
+      registry.devtoolsAdapter?.updateManifest(nextManifest);
+    },
+    stop: () => {
+      registry.devtoolsAdapter?.stop();
+      registry.devtoolsAdapter = null;
+      registry.kitchen = null;
+      // Fire-and-forget the async scheduler drain so `stop()` stays
       // synchronous for backwards compatibility with existing consumers.
       // Tests that need to await drain can reach for `registration.stop()`
       // directly; `server.stop()` triggers shutdown but doesn't block on