@mandujs/core 0.20.6 → 0.20.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.20.6",
+  "version": "0.20.8",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -12,6 +12,7 @@
     "./testing": "./src/testing/index.ts",
     "./plugins": "./src/plugins/index.ts",
     "./error": "./src/error/index.ts",
+    "./observability": "./src/observability/index.ts",
     "./bundler/prerender": "./src/bundler/prerender.ts",
     "./*": "./src/*"
   },

package/src/bundler/build.ts

@@ -64,7 +64,10 @@ async function buildPerIslandBundle(
       define: { "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"), ...options.define },
     });
     await fs.unlink(entryPath).catch(() => {});
-    if (!result.success) throw new Error(result.logs.map((l) => l.message).join("\n"));
+    if (!result.success) {
+      const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
+      throw new Error(`Island build failed for '${entry.name}' (source: ${entry.filePath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types in this island file.`);
+    }
     return { name: entry.name, js: `/.mandu/client/${outputName}`, route: entry.routeId, priority: entry.priority };
   } catch (error) {
     await fs.unlink(entryPath).catch(() => {});
@@ -986,10 +989,11 @@ if (typeof window !== 'undefined') {
     await fs.unlink(srcPath).catch(() => {});
 
     if (!result.success) {
+      const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
       return {
         success: false,
         outputPath: "",
-        errors: result.logs.map((l) => l.message),
+        errors: [`DevTools client build failed (source: ${srcPath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types.`],
       };
     }
 
@@ -1003,7 +1007,7 @@ if (typeof window !== 'undefined') {
     return {
       success: false,
       outputPath: "",
-      errors: [String(error)],
+      errors: [`DevTools client build threw an exception (source: ${srcPath}): ${String(error)}`],
     };
   }
 }
@@ -1037,10 +1041,11 @@ async function buildRouterRuntime(
     await fs.unlink(routerPath).catch(() => {});
 
     if (!result.success) {
+      const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
       return {
         success: false,
         outputPath: "",
-        errors: result.logs.map((l) => l.message),
+        errors: [`Router runtime build failed (source: ${routerPath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types.`],
       };
     }
 
@@ -1054,7 +1059,7 @@ async function buildRouterRuntime(
     return {
       success: false,
       outputPath: "",
-      errors: [String(error)],
+      errors: [`Router runtime build threw an exception (source: ${routerPath}): ${String(error)}`],
     };
   }
 }
@@ -1111,10 +1116,11 @@ async function buildRuntime(
 
     if (!result.success) {
       // 실패 시 디버깅을 위해 소스 파일을 남겨둠 (_runtime.src.js)
+      const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
       return {
         success: false,
         outputPath: "",
-        errors: result.logs.map((l) => l.message),
+        errors: [`Runtime bundle build failed (source: ${runtimePath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types. The source file has been kept for debugging.`],
       };
     }
 
@@ -1140,7 +1146,7 @@ async function buildRuntime(
     return {
       success: false,
       outputPath: "",
-      errors: [String(error), ...extra].filter(Boolean),
+      errors: [`Runtime bundle build threw an exception (source: ${runtimePath}): ${String(error)}`, ...extra].filter(Boolean),
     };
   }
 }
@@ -1219,9 +1225,10 @@ async function buildVendorShims(
       await fs.unlink(srcPath).catch(() => {});
 
       if (!result.success) {
+        const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
         return {
           key: shim.key,
-          error: `[${shim.name}] ${result.logs.map((l) => l.message).join(", ")}`,
+          error: `Vendor shim '${shim.name}' build failed (source: ${srcPath}):\n${grouped}\n  Hint: Check the import paths and ensure the vendor package is installed.`,
         };
       }
 
@@ -1296,7 +1303,8 @@ async function buildIsland(
     await fs.unlink(entryPath).catch(() => {});
 
     if (!result.success) {
-      throw new Error(result.logs.map((l) => l.message).join("\n"));
+      const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
+      throw new Error(`Island build failed for route '${route.id}' (source: ${clientModulePath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types in this island file.`);
     }
 
     // 출력 파일 정보

package/src/bundler/dev.ts

@@ -24,6 +24,11 @@ export interface DevBundlerOptions {
    * 클라이언트 번들 리빌드 없이 서버 핸들러 재등록이 필요한 경우 호출
    */
   onSSRChange?: (filePath: string) => void;
+  /**
+   * API route 파일 변경 콜백 (route.ts 등)
+   * API 핸들러 재등록이 필요한 경우 호출
+   */
+  onAPIChange?: (filePath: string) => void;
   /**
    * 추가 watch 디렉토리 (공통 컴포넌트 등)
    * 상대 경로 또는 절대 경로 모두 지원
@@ -81,6 +86,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     onRebuild,
     onError,
     onSSRChange,
+    onAPIChange,
     watchDirs: customWatchDirs = [],
     disableDefaultWatchDirs = false,
   } = options;
@@ -101,6 +107,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
   // clientModule 경로에서 routeId 매핑 생성
   const clientModuleToRoute = new Map<string, string>();
   const serverModuleSet = new Set<string>(); // SSR 모듈 (page.tsx, layout.tsx)
+  const apiModuleSet = new Set<string>(); // API 모듈 (route.ts)
   const watchDirs = new Set<string>();
   const commonWatchDirs = new Set<string>(); // 공통 디렉토리 (전체 재빌드 트리거)
 
@@ -138,6 +145,13 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
         watchDirs.add(path.dirname(path.resolve(rootDir, layoutPath)));
       }
     }
+
+    // Track API route modules for hot-reload
+    if (route.kind === "api" && route.module) {
+      const absPath = path.resolve(rootDir, route.module).replace(/\\/g, "/");
+      apiModuleSet.add(absPath);
+      watchDirs.add(path.dirname(path.resolve(rootDir, route.module)));
+    }
   }
 
   // spec/slots 디렉토리도 추가
@@ -281,6 +295,12 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       if (onSSRChange && serverModuleSet.has(normalizedPath)) {
         console.log(`\n🔄 SSR file changed: ${path.basename(changedFile)}`);
         onSSRChange(normalizedPath);
+        return;
+      }
+      // API 모듈 변경 감지 (route.ts)
+      if (onAPIChange && apiModuleSet.has(normalizedPath)) {
+        console.log(`\n🔄 API route changed: ${path.basename(changedFile)}`);
+        onAPIChange(normalizedPath);
       }
       return;
     }

package/src/config/validate.ts

@@ -233,19 +233,33 @@ export async function validateConfig(rootDir: string): Promise<ValidationResult>
           path: e.path.join("."),
           message: e.message,
         }));
-        return { valid: false, errors, source: fileName };
+        return {
+          valid: false,
+          errors: [
+            { path: "", message: `Config validation failed in '${filePath}'. Fix the following field errors:` },
+            ...errors,
+          ],
+          source: fileName,
+        };
+      }
+
+      // Differentiate file-not-found from parse/import errors
+      const errMsg = error instanceof Error ? error.message : String(error);
+      const isModuleError = errMsg.includes("Cannot find module") || errMsg.includes("MODULE_NOT_FOUND");
+      const isSyntaxError = error instanceof SyntaxError || errMsg.includes("SyntaxError");
+
+      let detail: string;
+      if (isModuleError) {
+        detail = `Could not resolve config file '${filePath}'. Check that the file exists and all its imports are installed.`;
+      } else if (isSyntaxError) {
+        detail = `Syntax error while parsing '${filePath}': ${errMsg}. Verify the file contains valid TypeScript/JSON.`;
+      } else {
+        detail = `Failed to load config from '${filePath}': ${errMsg}`;
       }
 
       return {
         valid: false,
-        errors: [
-          {
-            path: "",
-            message: `Failed to load config: ${
-              error instanceof Error ? error.message : String(error)
-            }`,
-          },
-        ],
+        errors: [{ path: "", message: detail }],
         source: fileName,
       };
     }

package/src/contract/validator.ts

@@ -13,32 +13,32 @@
  */
 
 import type { z } from "zod";
-import type {
-  ContractSchema,
-  ContractValidationResult,
-  ContractValidationError,
-  ContractValidationIssue,
-  MethodRequestSchema,
-  ContractNormalizeMode,
-  ResponseSchemaWithExamples,
-} from "./schema";
+import type {
+  ContractSchema,
+  ContractValidationResult,
+  ContractValidationError,
+  ContractValidationIssue,
+  MethodRequestSchema,
+  ContractNormalizeMode,
+  ResponseSchemaWithExamples,
+} from "./schema";
 import {
   type NormalizeMode,
   type NormalizeOptions,
   normalizeSchema,
   createCoerceSchema,
 } from "./normalize";
-import { ZodObject } from "zod";
-
-function isResponseSchemaWithExamples(
-  schema: z.ZodTypeAny | ResponseSchemaWithExamples | undefined
-): schema is ResponseSchemaWithExamples {
-  return (
-    schema !== undefined &&
-    typeof schema === "object" &&
-    "schema" in schema
-  );
-}
+import { ZodObject } from "zod";
+
+function isResponseSchemaWithExamples(
+  schema: z.ZodTypeAny | ResponseSchemaWithExamples | undefined
+): schema is ResponseSchemaWithExamples {
+  return (
+    schema !== undefined &&
+    typeof schema === "object" &&
+    "schema" in schema
+  );
+}
 
 /**
  * Validator 옵션
@@ -248,18 +248,23 @@ export class ContractValidator {
 
         const result = methodSchema.body.safeParse(body);
         if (!result.success) {
+          const enrichedIssues = zodErrorToIssues(result.error).map((issue) => ({
+            ...issue,
+            message: `${issue.path.length > 0 ? `At '${issue.path.join(".")}': ` : ""}${issue.message}`,
+          }));
           errors.push({
             type: "body",
-            issues: zodErrorToIssues(result.error),
+            issues: enrichedIssues,
           });
         }
       } catch (error) {
+        const contentType = req.headers.get("content-type") || "(not set)";
         errors.push({
           type: "body",
           issues: [
             {
               path: [],
-              message: `Failed to parse request body: ${error instanceof Error ? error.message : "Unknown error"}`,
+              message: `Failed to parse request body (received Content-Type: '${contentType}'): ${error instanceof Error ? error.message : "Unknown error"}. Ensure the body matches the declared Content-Type and is well-formed.`,
               code: "invalid_type",
             },
           ],
@@ -420,20 +425,25 @@ export class ContractValidator {
         const bodySchema = normalizeSchema(methodSchema.body, normalizeOpts);
         const result = bodySchema.safeParse(body);
         if (!result.success) {
+          const enrichedIssues = zodErrorToIssues(result.error).map((issue) => ({
+            ...issue,
+            message: `${issue.path.length > 0 ? `At '${issue.path.join(".")}': ` : ""}${issue.message}`,
+          }));
           errors.push({
             type: "body",
-            issues: zodErrorToIssues(result.error),
+            issues: enrichedIssues,
           });
         } else {
           normalizedData.body = result.data;
         }
       } catch (error) {
+        const contentType = req.headers.get("content-type") || "(not set)";
         errors.push({
           type: "body",
           issues: [
             {
               path: [],
-              message: `Failed to parse request body: ${error instanceof Error ? error.message : "Unknown error"}`,
+              message: `Failed to parse request body (received Content-Type: '${contentType}'): ${error instanceof Error ? error.message : "Unknown error"}. Ensure the body matches the declared Content-Type and is well-formed.`,
               code: "invalid_type",
             },
           ],
@@ -453,18 +463,18 @@ export class ContractValidator {
    * @param responseBody - The response body (already parsed)
    * @param statusCode - HTTP status code
    */
-  validateResponse(responseBody: unknown, statusCode: number): ContractValidationResult {
-    const responseSchemaOrWithExamples = this.contract.response[statusCode];
-    if (!responseSchemaOrWithExamples) {
-      // No schema defined for this status code, pass through
-      return { success: true };
-    }
-
-    const responseSchema = isResponseSchemaWithExamples(responseSchemaOrWithExamples)
-      ? responseSchemaOrWithExamples.schema
-      : responseSchemaOrWithExamples;
-
-    const result = responseSchema.safeParse(responseBody);
+  validateResponse(responseBody: unknown, statusCode: number): ContractValidationResult {
+    const responseSchemaOrWithExamples = this.contract.response[statusCode];
+    if (!responseSchemaOrWithExamples) {
+      // No schema defined for this status code, pass through
+      return { success: true };
+    }
+
+    const responseSchema = isResponseSchemaWithExamples(responseSchemaOrWithExamples)
+      ? responseSchemaOrWithExamples.schema
+      : responseSchemaOrWithExamples;
+
+    const result = responseSchema.safeParse(responseBody);
     if (!result.success) {
       const errors: ContractValidationError[] = [
         {

package/src/runtime/server.ts

@@ -40,6 +40,7 @@ import {
 } from "./cors";
 import { validateImportPath } from "./security";
 import { KITCHEN_PREFIX, KitchenHandler, recordRequest } from "../kitchen/kitchen-handler";
+import { eventBus } from "../observability/event-bus";
 import {
   type MiddlewareFn,
   type MiddlewareConfig,
@@ -984,8 +985,9 @@ async function handleInternalCacheControlRequest(
     if (req.method === "POST") {
       try {
         payload = await req.json() as Record<string, unknown>;
-      } catch {
-        return Response.json({ error: "Invalid JSON body" }, { status: 400 });
+      } catch (parseErr) {
+        const detail = parseErr instanceof Error ? parseErr.message : "Invalid JSON";
+        return Response.json({ error: "Invalid JSON body", detail, hint: "Ensure the request body is valid JSON (e.g., no trailing commas, unquoted keys, or truncated input)." }, { status: 400 });
       }
     } else {
       payload = { all: true };
@@ -1015,11 +1017,13 @@ async function handleInternalCacheControlRequest(
     });
   }
 
-  return Response.json({ error: "Method not allowed" }, { status: 405 });
+  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") ?? crypto.randomUUID();
   const result = await handleRequestInternal(req, router, registry);
 
   if (!result.ok) {
@@ -1034,7 +1038,17 @@ async function handleRequest(req: Request, router: Router, registry: ServerRegis
       if (!p.startsWith("/.mandu/") && !p.startsWith("/__kitchen")) {
         const elapsed = Date.now() - requestStart;
         console.log(`[${new Date().toLocaleTimeString()}] ${req.method} ${p} ${errorResponse.status} ${elapsed}ms`);
-        recordRequest({ id: crypto.randomUUID(), method: req.method, path: p, status: errorResponse.status, duration: elapsed, timestamp: Date.now() });
+        recordRequest({ id: correlationId, method: req.method, path: p, status: errorResponse.status, duration: elapsed, timestamp: Date.now() });
+        // Phase 1-2: HTTP 요청 → EventBus
+        eventBus.emit({
+          type: "http",
+          severity: errorResponse.status >= 500 ? "error" : errorResponse.status >= 400 ? "warn" : "info",
+          source: "server",
+          correlationId,
+          message: `${req.method} ${p} ${errorResponse.status}`,
+          duration: elapsed,
+          data: { method: req.method, path: p, status: errorResponse.status, error: true },
+        });
       }
     }
     return errorResponse;
@@ -1056,7 +1070,17 @@ async function handleRequest(req: Request, router: Router, registry: ServerRegis
       const cacheHdr = result.value.headers.get("X-Mandu-Cache") ?? "";
       const cacheTag = cacheHdr ? ` ${cacheHdr}` : "";
       console.log(`[${new Date().toLocaleTimeString()}] ${req.method} ${p} ${status} ${elapsed}ms${cacheTag}`);
-      recordRequest({ id: crypto.randomUUID(), method: req.method, path: p, status, duration: elapsed, timestamp: Date.now(), cacheStatus: cacheHdr || undefined });
+      recordRequest({ id: correlationId, method: req.method, path: p, status, duration: elapsed, timestamp: Date.now(), cacheStatus: cacheHdr || undefined });
+      // Phase 1-2: HTTP 요청 → EventBus
+      eventBus.emit({
+        type: "http",
+        severity: status >= 500 ? "error" : status >= 400 ? "warn" : "info",
+        source: "server",
+        correlationId,
+        message: `${req.method} ${p} ${status}${cacheTag}`,
+        duration: elapsed,
+        data: { method: req.method, path: p, status, cache: cacheHdr || undefined },
+      });
     }
   }
 
@@ -1609,7 +1633,7 @@ async function ensurePageRouteMetadata(
 ): Promise<PageRegistration> {
   const handler = pageHandler ?? registry.pageHandlers.get(routeId);
   if (!handler) {
-    throw new Error(`Page handler not found for route: ${routeId}`);
+    throw new Error(`Page handler not found for route: '${routeId}'. Ensure this route is registered in the manifest. If you are running in development, restart 'mandu dev' to pick up new routes. In production, verify that the route module exists and was included in the build.`);
   }
 
   const existingComponent = registry.routeComponents.get(routeId);