@mandujs/core 0.9.9 → 0.9.11

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/generator/templates.ts

@@ -189,13 +189,18 @@ function computeSlotImportPath(slotModule: string, fromDir: string): string {
 }
 
 export function generatePageComponent(route: RouteSpec): string {
-  const pageName = toPascalCase(route.id);
+  // Island-First: clientModule이 있으면 Island render를 SSR에서 직접 사용
+  if (route.clientModule) {
+    return generatePageComponentWithIsland(route);
+  }
 
   // slotModule이 있으면 PageHandler 형식으로 생성 (filling 포함)
   if (route.slotModule) {
     return generatePageHandlerWithSlot(route);
   }
 
+  const pageName = toPascalCase(route.id);
+
   // slotModule이 없으면 기존 방식
   return `// Generated by Mandu - DO NOT EDIT DIRECTLY
 // Route ID: ${route.id}
@@ -218,6 +223,73 @@ export default function ${pageName}Page({ params }: Props): React.ReactElement {
 `;
 }
 
+/**
+ * Island-First Rendering: SSR이 island의 render 함수를 직접 사용
+ * - clientModule의 definition.setup() + definition.render() 호출
+ * - SSR과 클라이언트가 동일한 렌더링 로직 사용 → 불일치 구조적 방지
+ * - slotModule 유무에 따라 두 가지 변형 생성
+ */
+export function generatePageComponentWithIsland(route: RouteSpec): string {
+  const pageName = toPascalCase(route.id);
+  const clientImportPath = computeSlotImportPath(route.clientModule!, "apps/web/generated/routes");
+
+  // clientModule + slotModule → PageRegistration 형식
+  if (route.slotModule) {
+    const slotImportPath = computeSlotImportPath(route.slotModule!, "apps/web/generated/routes");
+
+    return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Island-First Rendering + Slot Module
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+// Client Module: ${route.clientModule}
+// Slot Module: ${route.slotModule}
+
+import React from "react";
+import filling from "${slotImportPath}";
+import islandModule from "${clientImportPath}";
+
+interface Props {
+  params: Record<string, string>;
+  loaderData?: unknown;
+}
+
+function ${pageName}Page({ params, loaderData }: Props): React.ReactElement {
+  const serverData = (loaderData || {}) as any;
+  const setupResult = islandModule.definition.setup(serverData);
+  return islandModule.definition.render(setupResult) as React.ReactElement;
+}
+
+// PageRegistration 형식으로 export (server.ts의 registerPageHandler용)
+export default {
+  component: ${pageName}Page,
+  filling: filling,
+};
+`;
+  }
+
+  // clientModule만 (slotModule 없음) → default export 컴포넌트
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Island-First Rendering: SSR이 island render 직접 사용
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+// Client Module: ${route.clientModule}
+
+import React from "react";
+import islandModule from "${clientImportPath}";
+
+interface Props {
+  params: Record<string, string>;
+  loaderData?: unknown;
+}
+
+export default function ${pageName}Page({ params, loaderData }: Props): React.ReactElement {
+  const serverData = (loaderData || {}) as any;
+  const setupResult = islandModule.definition.setup(serverData);
+  return islandModule.definition.render(setupResult) as React.ReactElement;
+}
+`;
+}
+
 /**
  * slotModule이 있는 Page Route용 Handler 생성
  * - component와 filling을 함께 export

package/src/guard/check.ts

@@ -193,6 +193,46 @@ export async function checkSlotContentValidation(
   return violations;
 }
 
+// Rule: Island-First Integrity
+export async function checkIslandFirstIntegrity(
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<GuardViolation[]> {
+  const violations: GuardViolation[] = [];
+
+  for (const route of manifest.routes) {
+    if (route.kind !== "page" || !route.clientModule) continue;
+
+    // 1. clientModule 파일 존재 여부
+    const clientPath = path.join(rootDir, route.clientModule);
+    if (!(await fileExists(clientPath))) {
+      violations.push({
+        ruleId: "CLIENT_MODULE_NOT_FOUND",
+        file: route.clientModule,
+        message: `clientModule 파일을 찾을 수 없습니다 (routeId: ${route.id})`,
+        suggestion: "clientModule 경로를 확인하거나 파일을 생성하세요",
+      });
+      continue;
+    }
+
+    // 2. componentModule이 island을 import하는지 확인
+    if (route.componentModule) {
+      const componentPath = path.join(rootDir, route.componentModule);
+      const content = await readFileContent(componentPath);
+      if (content && !content.includes("islandModule") && !content.includes("Island-First")) {
+        violations.push({
+          ruleId: "ISLAND_FIRST_INTEGRITY",
+          file: route.componentModule,
+          message: `componentModule이 island을 import하지 않습니다 (routeId: ${route.id})`,
+          suggestion: "mandu generate를 실행하여 Island-First 템플릿으로 재생성하세요",
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
 // Rule 4: Forbidden imports in generated files
 export async function checkForbiddenImportsInGenerated(
   rootDir: string,
@@ -303,6 +343,10 @@ export async function runGuardCheck(
   const contractViolations = await runContractGuardCheck(manifest, rootDir);
   violations.push(...contractViolations);
 
+  // Rule: Island-First Integrity
+  const islandViolations = await checkIslandFirstIntegrity(manifest, rootDir);
+  violations.push(...islandViolations);
+
   return {
     passed: violations.length === 0,
     violations,

package/src/guard/rules.ts

@@ -95,6 +95,19 @@ export const GUARD_RULES: Record<string, GuardRule> = {
     description: "Slot에 구현된 메서드가 Contract에 문서화되지 않았습니다",
     severity: "warning",
   },
+  // Island-First Rendering rules
+  ISLAND_FIRST_INTEGRITY: {
+    id: "ISLAND_FIRST_INTEGRITY",
+    name: "Island-First Integrity",
+    description: "clientModule이 있는 page route의 componentModule이 island을 import하지 않습니다",
+    severity: "error",
+  },
+  CLIENT_MODULE_NOT_FOUND: {
+    id: "CLIENT_MODULE_NOT_FOUND",
+    name: "Client Module Not Found",
+    description: "spec에 명시된 clientModule 파일을 찾을 수 없습니다",
+    severity: "error",
+  },
 };
 
 export const FORBIDDEN_IMPORTS = ["fs", "child_process", "cluster", "worker_threads"];

package/src/report/index.ts

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

package/src/runtime/compose.ts

@@ -1,222 +1,222 @@
-/**
- * Mandu Middleware Compose 🔗
- * Hono 스타일 미들웨어 조합 패턴
- *
- * @see https://github.com/honojs/hono/blob/main/src/compose.ts
- */
-
-import type { ManduContext } from "../filling/context";
-
-/**
- * Next 함수 타입
- */
-export type Next = () => Promise<void>;
-
-/**
- * 미들웨어 함수 타입
- * - Response 반환: 체인 중단 (Guard 역할)
- * - void 반환: 다음 미들웨어 실행
- */
-export type Middleware = (
-  ctx: ManduContext,
-  next: Next
-) => Response | void | Promise<Response | void>;
-
-/**
- * 에러 핸들러 타입
- */
-export type ErrorHandler = (
-  error: Error,
-  ctx: ManduContext
-) => Response | Promise<Response>;
-
-/**
- * NotFound 핸들러 타입
- */
-export type NotFoundHandler = (ctx: ManduContext) => Response | Promise<Response>;
-
-/**
- * 미들웨어 엔트리 (메타데이터 포함)
- */
-export interface MiddlewareEntry {
-  fn: Middleware;
-  name?: string;
-  isAsync?: boolean;
-}
-
-/**
- * Compose 옵션
- */
-export interface ComposeOptions {
-  onError?: ErrorHandler;
-  onNotFound?: NotFoundHandler;
-}
-
-/**
- * 미들웨어 함수들을 하나의 실행 함수로 조합
- *
- * @example
- * ```typescript
- * const middleware = [
- *   { fn: async (ctx, next) => { console.log('before'); await next(); console.log('after'); } },
- *   { fn: async (ctx, next) => { return ctx.ok({ data: 'hello' }); } },
- * ];
- *
- * const handler = compose(middleware, {
- *   onError: (err, ctx) => ctx.json({ error: err.message }, 500),
- *   onNotFound: (ctx) => ctx.notFound(),
- * });
- *
- * const response = await handler(context);
- * ```
- */
-export function compose(
-  middleware: MiddlewareEntry[],
-  options: ComposeOptions = {}
-): (ctx: ManduContext) => Promise<Response> {
-  const { onError, onNotFound } = options;
-
-  return async (ctx: ManduContext): Promise<Response> => {
-    let index = -1;
-    let finalResponse: Response | undefined;
-
-    /**
-     * 미들웨어 순차 실행
-     * @param i 현재 인덱스
-     */
-    async function dispatch(i: number): Promise<void> {
-      // next() 이중 호출 방지
-      if (i <= index) {
-        throw new Error("next() called multiple times");
-      }
-      index = i;
-
-      const entry = middleware[i];
-
-      if (!entry) {
-        // 모든 미들웨어 통과 후 핸들러 없음
-        if (!finalResponse && onNotFound) {
-          finalResponse = await onNotFound(ctx);
-        }
-        return;
-      }
-
-      try {
-        const result = await entry.fn(ctx, () => dispatch(i + 1));
-
-        // Response 반환 시 체인 중단
-        if (result instanceof Response) {
-          finalResponse = result;
-          return;
-        }
-      } catch (err) {
-        if (err instanceof Error && onError) {
-          finalResponse = await onError(err, ctx);
-          return;
-        }
-        throw err;
-      }
-    }
-
-    await dispatch(0);
-
-    // 응답이 없으면 404
-    if (!finalResponse) {
-      if (onNotFound) {
-        finalResponse = await onNotFound(ctx);
-      } else {
-        finalResponse = new Response("Not Found", { status: 404 });
-      }
-    }
-
-    return finalResponse;
-  };
-}
-
-/**
- * 미들웨어 배열 생성 헬퍼
- *
- * @example
- * ```typescript
- * const mw = createMiddleware([
- *   authGuard,
- *   rateLimitGuard,
- *   mainHandler,
- * ]);
- * ```
- */
-export function createMiddleware(
-  fns: Middleware[]
-): MiddlewareEntry[] {
-  return fns.map((fn, i) => ({
-    fn,
-    name: fn.name || `middleware_${i}`,
-    isAsync: fn.constructor.name === "AsyncFunction",
-  }));
-}
-
-/**
- * 미들웨어 체인 빌더
- *
- * @example
- * ```typescript
- * const chain = new MiddlewareChain()
- *   .use(authGuard)
- *   .use(rateLimitGuard)
- *   .use(mainHandler)
- *   .onError((err, ctx) => ctx.json({ error: err.message }, 500))
- *   .build();
- *
- * const response = await chain(ctx);
- * ```
- */
-export class MiddlewareChain {
-  private middleware: MiddlewareEntry[] = [];
-  private errorHandler?: ErrorHandler;
-  private notFoundHandler?: NotFoundHandler;
-
-  /**
-   * 미들웨어 추가
-   */
-  use(fn: Middleware, name?: string): this {
-    this.middleware.push({
-      fn,
-      name: name || fn.name || `middleware_${this.middleware.length}`,
-      isAsync: fn.constructor.name === "AsyncFunction",
-    });
-    return this;
-  }
-
-  /**
-   * 에러 핸들러 설정
-   */
-  onError(handler: ErrorHandler): this {
-    this.errorHandler = handler;
-    return this;
-  }
-
-  /**
-   * NotFound 핸들러 설정
-   */
-  onNotFound(handler: NotFoundHandler): this {
-    this.notFoundHandler = handler;
-    return this;
-  }
-
-  /**
-   * 미들웨어 체인 빌드
-   */
-  build(): (ctx: ManduContext) => Promise<Response> {
-    return compose(this.middleware, {
-      onError: this.errorHandler,
-      onNotFound: this.notFoundHandler,
-    });
-  }
-
-  /**
-   * 미들웨어 목록 조회
-   */
-  getMiddleware(): MiddlewareEntry[] {
-    return [...this.middleware];
-  }
-}
+/**
+ * Mandu Middleware Compose 🔗
+ * Hono 스타일 미들웨어 조합 패턴
+ *
+ * @see https://github.com/honojs/hono/blob/main/src/compose.ts
+ */
+
+import type { ManduContext } from "../filling/context";
+
+/**
+ * Next 함수 타입
+ */
+export type Next = () => Promise<void>;
+
+/**
+ * 미들웨어 함수 타입
+ * - Response 반환: 체인 중단 (Guard 역할)
+ * - void 반환: 다음 미들웨어 실행
+ */
+export type Middleware = (
+  ctx: ManduContext,
+  next: Next
+) => Response | void | Promise<Response | void>;
+
+/**
+ * 에러 핸들러 타입
+ */
+export type ErrorHandler = (
+  error: Error,
+  ctx: ManduContext
+) => Response | Promise<Response>;
+
+/**
+ * NotFound 핸들러 타입
+ */
+export type NotFoundHandler = (ctx: ManduContext) => Response | Promise<Response>;
+
+/**
+ * 미들웨어 엔트리 (메타데이터 포함)
+ */
+export interface MiddlewareEntry {
+  fn: Middleware;
+  name?: string;
+  isAsync?: boolean;
+}
+
+/**
+ * Compose 옵션
+ */
+export interface ComposeOptions {
+  onError?: ErrorHandler;
+  onNotFound?: NotFoundHandler;
+}
+
+/**
+ * 미들웨어 함수들을 하나의 실행 함수로 조합
+ *
+ * @example
+ * ```typescript
+ * const middleware = [
+ *   { fn: async (ctx, next) => { console.log('before'); await next(); console.log('after'); } },
+ *   { fn: async (ctx, next) => { return ctx.ok({ data: 'hello' }); } },
+ * ];
+ *
+ * const handler = compose(middleware, {
+ *   onError: (err, ctx) => ctx.json({ error: err.message }, 500),
+ *   onNotFound: (ctx) => ctx.notFound(),
+ * });
+ *
+ * const response = await handler(context);
+ * ```
+ */
+export function compose(
+  middleware: MiddlewareEntry[],
+  options: ComposeOptions = {}
+): (ctx: ManduContext) => Promise<Response> {
+  const { onError, onNotFound } = options;
+
+  return async (ctx: ManduContext): Promise<Response> => {
+    let index = -1;
+    let finalResponse: Response | undefined;
+
+    /**
+     * 미들웨어 순차 실행
+     * @param i 현재 인덱스
+     */
+    async function dispatch(i: number): Promise<void> {
+      // next() 이중 호출 방지
+      if (i <= index) {
+        throw new Error("next() called multiple times");
+      }
+      index = i;
+
+      const entry = middleware[i];
+
+      if (!entry) {
+        // 모든 미들웨어 통과 후 핸들러 없음
+        if (!finalResponse && onNotFound) {
+          finalResponse = await onNotFound(ctx);
+        }
+        return;
+      }
+
+      try {
+        const result = await entry.fn(ctx, () => dispatch(i + 1));
+
+        // Response 반환 시 체인 중단
+        if (result instanceof Response) {
+          finalResponse = result;
+          return;
+        }
+      } catch (err) {
+        if (err instanceof Error && onError) {
+          finalResponse = await onError(err, ctx);
+          return;
+        }
+        throw err;
+      }
+    }
+
+    await dispatch(0);
+
+    // 응답이 없으면 404
+    if (!finalResponse) {
+      if (onNotFound) {
+        finalResponse = await onNotFound(ctx);
+      } else {
+        finalResponse = new Response("Not Found", { status: 404 });
+      }
+    }
+
+    return finalResponse;
+  };
+}
+
+/**
+ * 미들웨어 배열 생성 헬퍼
+ *
+ * @example
+ * ```typescript
+ * const mw = createMiddleware([
+ *   authGuard,
+ *   rateLimitGuard,
+ *   mainHandler,
+ * ]);
+ * ```
+ */
+export function createMiddleware(
+  fns: Middleware[]
+): MiddlewareEntry[] {
+  return fns.map((fn, i) => ({
+    fn,
+    name: fn.name || `middleware_${i}`,
+    isAsync: fn.constructor.name === "AsyncFunction",
+  }));
+}
+
+/**
+ * 미들웨어 체인 빌더
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain()
+ *   .use(authGuard)
+ *   .use(rateLimitGuard)
+ *   .use(mainHandler)
+ *   .onError((err, ctx) => ctx.json({ error: err.message }, 500))
+ *   .build();
+ *
+ * const response = await chain(ctx);
+ * ```
+ */
+export class MiddlewareChain {
+  private middleware: MiddlewareEntry[] = [];
+  private errorHandler?: ErrorHandler;
+  private notFoundHandler?: NotFoundHandler;
+
+  /**
+   * 미들웨어 추가
+   */
+  use(fn: Middleware, name?: string): this {
+    this.middleware.push({
+      fn,
+      name: name || fn.name || `middleware_${this.middleware.length}`,
+      isAsync: fn.constructor.name === "AsyncFunction",
+    });
+    return this;
+  }
+
+  /**
+   * 에러 핸들러 설정
+   */
+  onError(handler: ErrorHandler): this {
+    this.errorHandler = handler;
+    return this;
+  }
+
+  /**
+   * NotFound 핸들러 설정
+   */
+  onNotFound(handler: NotFoundHandler): this {
+    this.notFoundHandler = handler;
+    return this;
+  }
+
+  /**
+   * 미들웨어 체인 빌드
+   */
+  build(): (ctx: ManduContext) => Promise<Response> {
+    return compose(this.middleware, {
+      onError: this.errorHandler,
+      onNotFound: this.notFoundHandler,
+    });
+  }
+
+  /**
+   * 미들웨어 목록 조회
+   */
+  getMiddleware(): MiddlewareEntry[] {
+    return [...this.middleware];
+  }
+}

package/src/runtime/index.ts

@@ -3,6 +3,6 @@ export * from "./router";
 export * from "./server";
 export * from "./cors";
 export * from "./env";
-export * from "./compose";
-export * from "./lifecycle";
-export * from "./trace";
+export * from "./compose";
+export * from "./lifecycle";
+export * from "./trace";