@mandujs/core 0.5.3 → 0.5.5

package/README.md

@@ -1,200 +1,200 @@
-<p align="center">
-  <img src="https://raw.githubusercontent.com/konamgil/mandu/main/mandu_only_simbol.png" alt="Mandu" width="200" />
-</p>
-
-<h1 align="center">@mandujs/core</h1>
-
-<p align="center">
-  <strong>Mandu Framework Core</strong><br/>
-  Spec, Generator, Guard, Runtime, Filling
-</p>
-
-<p align="center">
-  English | <a href="./README.ko.md"><strong>한국어</strong></a>
-</p>
-
-## Installation
-
-```bash
-bun add @mandujs/core
-```
-
-> Typically used through `@mandujs/cli`. Direct usage is for advanced use cases.
-
-## Module Structure
-
-```
-@mandujs/core
-├── spec/      # Spec schema and loading
-├── generator/ # Code generation
-├── guard/     # Architecture checking and auto-correction
-├── runtime/   # Server and router
-└── report/    # Guard report generation
-```
-
-## Spec Module
-
-Route manifest schema definition and loading.
-
-```typescript
-import { loadManifest, RoutesManifest, RouteSpec } from "@mandujs/core";
-
-// Load and validate manifest
-const result = await loadManifest("spec/routes.manifest.json");
-
-if (result.success && result.data) {
-  const manifest: RoutesManifest = result.data;
-  manifest.routes.forEach((route: RouteSpec) => {
-    console.log(route.id, route.pattern, route.kind);
-  });
-}
-```
-
-### Lock File
-
-```typescript
-import { writeLock, readLock } from "@mandujs/core";
-
-// Write lock file
-const lock = await writeLock("spec/spec.lock.json", manifest);
-console.log(lock.routesHash);
-
-// Read lock file
-const existing = await readLock("spec/spec.lock.json");
-```
-
-## Generator Module
-
-Spec-based code generation.
-
-```typescript
-import { generateRoutes, GenerateResult } from "@mandujs/core";
-
-const result: GenerateResult = await generateRoutes(manifest, "./");
-
-console.log("Created:", result.created);
-console.log("Skipped:", result.skipped);  // Existing slot files
-```
-
-### Template Functions
-
-```typescript
-import {
-  generateApiHandler,
-  generateApiHandlerWithSlot,
-  generateSlotLogic,
-  generatePageComponent
-} from "@mandujs/core";
-
-// Generate API handler
-const code = generateApiHandler(route);
-
-// API handler with slot
-const codeWithSlot = generateApiHandlerWithSlot(route);
-
-// Slot logic file
-const slotCode = generateSlotLogic(route);
-```
-
-## Guard Module
-
-Architecture rule checking and auto-correction.
-
-```typescript
-import {
-  runGuardCheck,
-  runAutoCorrect,
-  GuardResult,
-  GuardViolation
-} from "@mandujs/core";
-
-// Run check
-const result: GuardResult = await runGuardCheck(manifest, "./");
-
-if (!result.passed) {
-  result.violations.forEach((v: GuardViolation) => {
-    console.log(`${v.rule}: ${v.message}`);
-  });
-
-  // Run auto-correction
-  const corrected = await runAutoCorrect(result.violations, manifest, "./");
-  console.log("Fixed:", corrected.steps);
-  console.log("Remaining violations:", corrected.remainingViolations);
-}
-```
-
-### Guard Rules
-
-| Rule ID | Description | Auto-correctable |
-|---------|-------------|------------------|
-| `SPEC_HASH_MISMATCH` | Spec and lock hash mismatch | ✅ |
-| `GENERATED_MANUAL_EDIT` | Manual edit to generated file | ✅ |
-| `HANDLER_NOT_FOUND` | Handler file not found | ❌ |
-| `COMPONENT_NOT_FOUND` | Component file not found | ❌ |
-| `SLOT_NOT_FOUND` | Slot file not found | ✅ |
-
-## Runtime Module
-
-Server startup and routing.
-
-```typescript
-import {
-  startServer,
-  registerApiHandler,
-  registerPageLoader
-} from "@mandujs/core";
-
-// Register API handler
-registerApiHandler("getUsers", async (req) => {
-  return { users: [] };
-});
-
-// Register page loader
-registerPageLoader("homePage", () => import("./pages/Home"));
-
-// Start server
-const server = startServer(manifest, { port: 3000 });
-
-// Stop
-server.stop();
-```
-
-## Report Module
-
-Guard result report generation.
-
-```typescript
-import { buildGuardReport } from "@mandujs/core";
-
-const report = buildGuardReport(guardResult, lockPath);
-console.log(report);  // Formatted text report
-```
-
-## Types
-
-```typescript
-import type {
-  RoutesManifest,
-  RouteSpec,
-  RouteKind,
-  SpecLock,
-  GuardResult,
-  GuardViolation,
-  GenerateResult,
-  AutoCorrectResult,
-} from "@mandujs/core";
-```
-
-## Requirements
-
-- Bun >= 1.0.0
-- React >= 18.0.0
-- Zod >= 3.0.0
-
-## Related Packages
-
-- [@mandujs/cli](https://www.npmjs.com/package/@mandujs/cli) - CLI tool
-
-## License
-
-MIT
+<p align="center">
+  <img src="https://raw.githubusercontent.com/konamgil/mandu/main/mandu_only_simbol.png" alt="Mandu" width="200" />
+</p>
+
+<h1 align="center">@mandujs/core</h1>
+
+<p align="center">
+  <strong>Mandu Framework Core</strong><br/>
+  Spec, Generator, Guard, Runtime, Filling
+</p>
+
+<p align="center">
+  English | <a href="./README.ko.md"><strong>한국어</strong></a>
+</p>
+
+## Installation
+
+```bash
+bun add @mandujs/core
+```
+
+> Typically used through `@mandujs/cli`. Direct usage is for advanced use cases.
+
+## Module Structure
+
+```
+@mandujs/core
+├── spec/      # Spec schema and loading
+├── generator/ # Code generation
+├── guard/     # Architecture checking and auto-correction
+├── runtime/   # Server and router
+└── report/    # Guard report generation
+```
+
+## Spec Module
+
+Route manifest schema definition and loading.
+
+```typescript
+import { loadManifest, RoutesManifest, RouteSpec } from "@mandujs/core";
+
+// Load and validate manifest
+const result = await loadManifest("spec/routes.manifest.json");
+
+if (result.success && result.data) {
+  const manifest: RoutesManifest = result.data;
+  manifest.routes.forEach((route: RouteSpec) => {
+    console.log(route.id, route.pattern, route.kind);
+  });
+}
+```
+
+### Lock File
+
+```typescript
+import { writeLock, readLock } from "@mandujs/core";
+
+// Write lock file
+const lock = await writeLock("spec/spec.lock.json", manifest);
+console.log(lock.routesHash);
+
+// Read lock file
+const existing = await readLock("spec/spec.lock.json");
+```
+
+## Generator Module
+
+Spec-based code generation.
+
+```typescript
+import { generateRoutes, GenerateResult } from "@mandujs/core";
+
+const result: GenerateResult = await generateRoutes(manifest, "./");
+
+console.log("Created:", result.created);
+console.log("Skipped:", result.skipped);  // Existing slot files
+```
+
+### Template Functions
+
+```typescript
+import {
+  generateApiHandler,
+  generateApiHandlerWithSlot,
+  generateSlotLogic,
+  generatePageComponent
+} from "@mandujs/core";
+
+// Generate API handler
+const code = generateApiHandler(route);
+
+// API handler with slot
+const codeWithSlot = generateApiHandlerWithSlot(route);
+
+// Slot logic file
+const slotCode = generateSlotLogic(route);
+```
+
+## Guard Module
+
+Architecture rule checking and auto-correction.
+
+```typescript
+import {
+  runGuardCheck,
+  runAutoCorrect,
+  GuardResult,
+  GuardViolation
+} from "@mandujs/core";
+
+// Run check
+const result: GuardResult = await runGuardCheck(manifest, "./");
+
+if (!result.passed) {
+  result.violations.forEach((v: GuardViolation) => {
+    console.log(`${v.rule}: ${v.message}`);
+  });
+
+  // Run auto-correction
+  const corrected = await runAutoCorrect(result.violations, manifest, "./");
+  console.log("Fixed:", corrected.steps);
+  console.log("Remaining violations:", corrected.remainingViolations);
+}
+```
+
+### Guard Rules
+
+| Rule ID | Description | Auto-correctable |
+|---------|-------------|------------------|
+| `SPEC_HASH_MISMATCH` | Spec and lock hash mismatch | ✅ |
+| `GENERATED_MANUAL_EDIT` | Manual edit to generated file | ✅ |
+| `HANDLER_NOT_FOUND` | Handler file not found | ❌ |
+| `COMPONENT_NOT_FOUND` | Component file not found | ❌ |
+| `SLOT_NOT_FOUND` | Slot file not found | ✅ |
+
+## Runtime Module
+
+Server startup and routing.
+
+```typescript
+import {
+  startServer,
+  registerApiHandler,
+  registerPageLoader
+} from "@mandujs/core";
+
+// Register API handler
+registerApiHandler("getUsers", async (req) => {
+  return { users: [] };
+});
+
+// Register page loader
+registerPageLoader("homePage", () => import("./pages/Home"));
+
+// Start server
+const server = startServer(manifest, { port: 3000 });
+
+// Stop
+server.stop();
+```
+
+## Report Module
+
+Guard result report generation.
+
+```typescript
+import { buildGuardReport } from "@mandujs/core";
+
+const report = buildGuardReport(guardResult, lockPath);
+console.log(report);  // Formatted text report
+```
+
+## Types
+
+```typescript
+import type {
+  RoutesManifest,
+  RouteSpec,
+  RouteKind,
+  SpecLock,
+  GuardResult,
+  GuardViolation,
+  GenerateResult,
+  AutoCorrectResult,
+} from "@mandujs/core";
+```
+
+## Requirements
+
+- Bun >= 1.0.0
+- React >= 18.0.0
+- Zod >= 3.0.0
+
+## Related Packages
+
+- [@mandujs/cli](https://www.npmjs.com/package/@mandujs/cli) - CLI tool
+
+## License
+
+MIT

package/package.json

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

package/src/bundler/build.ts

@@ -122,7 +122,8 @@ function scheduleHydration(element, id, priority, data) {
 }
 
 /**
- * 단일 Island hydrate
+ * 단일 Island hydrate (또는 mount)
+ * SSR 플레이스홀더를 Island 컴포넌트로 교체
  */
 async function hydrateIsland(element, id, data) {
   const loader = islandRegistry.get(id);
@@ -141,7 +142,7 @@ async function hydrateIsland(element, id, data) {
     }
 
     const { definition } = islandDef;
-    const { hydrateRoot } = await import('react-dom/client');
+    const { createRoot } = await import('react-dom/client');
     const React = await import('react');
 
     // Island 컴포넌트
@@ -150,8 +151,10 @@ async function hydrateIsland(element, id, data) {
       return definition.render(setupResult);
     }
 
-    // Hydrate
-    const root = hydrateRoot(element, React.createElement(IslandComponent));
+    // Mount (createRoot 사용 - SSR 플레이스홀더 교체)
+    // hydrateRoot 대신 createRoot 사용: Island는 SSR과 다른 컨텐츠를 렌더링할 수 있음
+    const root = createRoot(element);
+    root.render(React.createElement(IslandComponent));
     hydratedRoots.set(id, root);
 
     // 완료 표시

package/src/contract/validator.ts

@@ -205,8 +205,8 @@ export class ContractValidator {
    */
   getStatusCodes(): number[] {
     return Object.keys(this.contract.response)
-      .map((k) => parseInt(k, 10))
-      .filter((n) => !isNaN(n));
+      .filter((k) => /^\d+$/.test(k))
+      .map((k) => parseInt(k, 10));
   }
 
   /**

package/src/filling/context.ts

@@ -49,7 +49,13 @@ export class CookieManager {
       for (const pair of pairs) {
         const [name, ...rest] = pair.trim().split("=");
         if (name) {
-          cookies.set(name, decodeURIComponent(rest.join("=")));
+          const rawValue = rest.join("=");
+          try {
+            cookies.set(name, decodeURIComponent(rawValue));
+          } catch {
+            // 잘못된 URL 인코딩 시 원본 값 사용
+            cookies.set(name, rawValue);
+          }
         }
       }
     }

package/src/filling/filling.ts

@@ -19,6 +19,22 @@ export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" |
 /** Loader function type - SSR 데이터 로딩 */
 export type Loader<T = unknown> = (ctx: ManduContext) => T | Promise<T>;
 
+/** Loader 실행 옵션 */
+export interface LoaderOptions<T = unknown> {
+  /** 타임아웃 (ms), 기본값 5000 */
+  timeout?: number;
+  /** 타임아웃 또는 에러 시 반환할 fallback 데이터 */
+  fallback?: T;
+}
+
+/** Loader 타임아웃 에러 */
+export class LoaderTimeoutError extends Error {
+  constructor(timeout: number) {
+    super(`Loader timed out after ${timeout}ms`);
+    this.name = "LoaderTimeoutError";
+  }
+}
+
 interface FillingConfig<TLoaderData = unknown> {
   handlers: Map<HttpMethod, Handler>;
   guards: Guard[];
@@ -78,12 +94,37 @@ export class ManduFilling<TLoaderData = unknown> {
   /**
    * Execute loader and return data
    * @internal Used by SSR runtime
+   * @param ctx ManduContext
+   * @param options Loader 실행 옵션 (timeout, fallback)
    */
-  async executeLoader(ctx: ManduContext): Promise<TLoaderData | undefined> {
+  async executeLoader(
+    ctx: ManduContext,
+    options: LoaderOptions<TLoaderData> = {}
+  ): Promise<TLoaderData | undefined> {
     if (!this.config.loader) {
       return undefined;
     }
-    return await this.config.loader(ctx);
+
+    const { timeout = 5000, fallback } = options;
+
+    try {
+      const loaderPromise = Promise.resolve(this.config.loader(ctx));
+
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => reject(new LoaderTimeoutError(timeout)), timeout);
+      });
+
+      return await Promise.race([loaderPromise, timeoutPromise]);
+    } catch (error) {
+      if (fallback !== undefined) {
+        console.warn(
+          `[Mandu] Loader failed, using fallback:`,
+          error instanceof Error ? error.message : String(error)
+        );
+        return fallback;
+      }
+      throw error;
+    }
   }
 
   /**
@@ -203,7 +244,11 @@ export class ManduFilling<TLoaderData = unknown> {
           return result as Response;
         }
         if (!ctx.shouldContinue) {
-          return ctx.getResponse()!;
+          const response = ctx.getResponse();
+          if (!response) {
+            throw new Error("Guard set shouldContinue=false but no response was provided");
+          }
+          return response;
         }
       }
 
@@ -215,7 +260,11 @@ export class ManduFilling<TLoaderData = unknown> {
           return result as Response;
         }
         if (!ctx.shouldContinue) {
-          return ctx.getResponse()!;
+          const response = ctx.getResponse();
+          if (!response) {
+            throw new Error("Guard set shouldContinue=false but no response was provided");
+          }
+          return response;
         }
       }
 

package/src/filling/index.ts

@@ -4,5 +4,5 @@
 
 export { ManduContext, NEXT_SYMBOL, ValidationError, CookieManager } from "./context";
 export type { CookieOptions } from "./context";
-export { ManduFilling, Mandu } from "./filling";
-export type { Handler, Guard, HttpMethod } from "./filling";
+export { ManduFilling, Mandu, LoaderTimeoutError } from "./filling";
+export type { Handler, Guard, HttpMethod, Loader, LoaderOptions } from "./filling";

package/src/generator/generate.ts

@@ -20,6 +20,8 @@ export interface GenerateResult {
   deleted: string[];
   skipped: string[];
   errors: string[];
+  /** 삭제 실패 등 치명적이지 않은 경고 */
+  warnings: string[];
 }
 
 /**
@@ -130,6 +132,7 @@ export async function generateRoutes(
     deleted: [],
     skipped: [],
     errors: [],
+    warnings: [],
   };
 
   const serverRoutesDir = path.join(rootDir, "apps/server/generated/routes");
@@ -289,8 +292,14 @@ export async function generateRoutes(
   for (const file of existingServerFiles) {
     if (!expectedServerFiles.has(file)) {
       const filePath = path.join(serverRoutesDir, file);
-      await fs.unlink(filePath);
-      result.deleted.push(filePath);
+      try {
+        await fs.unlink(filePath);
+        result.deleted.push(filePath);
+      } catch (error) {
+        result.warnings.push(
+          `Failed to delete ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     }
   }
 
@@ -298,8 +307,14 @@ export async function generateRoutes(
   for (const file of existingWebFiles) {
     if (!expectedWebFiles.has(file)) {
       const filePath = path.join(webRoutesDir, file);
-      await fs.unlink(filePath);
-      result.deleted.push(filePath);
+      try {
+        await fs.unlink(filePath);
+        result.deleted.push(filePath);
+      } catch (error) {
+        result.warnings.push(
+          `Failed to delete ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     }
   }
 
@@ -308,8 +323,14 @@ export async function generateRoutes(
   for (const file of existingTypeFiles) {
     if (!expectedTypeFiles.has(file) && file !== "index.ts") {
       const filePath = path.join(typesDir, file);
-      await fs.unlink(filePath);
-      result.deleted.push(filePath);
+      try {
+        await fs.unlink(filePath);
+        result.deleted.push(filePath);
+      } catch (error) {
+        result.warnings.push(
+          `Failed to delete ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
     }
   }
 

package/src/generator/index.ts

@@ -1,3 +1,3 @@
-export * from "./generate";
-export * from "./templates";
-export * from "./contract-glue";
+export * from "./generate";
+export * from "./templates";
+export * from "./contract-glue";

package/src/report/index.ts

@@ -1 +1 @@
-export * from "./build";
+export * from "./build";

package/src/runtime/index.ts

@@ -1,5 +1,5 @@
-export * from "./ssr";
-export * from "./router";
-export * from "./server";
-export * from "./cors";
-export * from "./env";
+export * from "./ssr";
+export * from "./router";
+export * from "./server";
+export * from "./cors";
+export * from "./env";