@mandujs/core 0.5.5 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -22,7 +22,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/konamgil/mandu.git",
+    "url": "git+https://github.com/konamgil/mandu.git",
     "directory": "packages/core"
   },
   "author": "konamgil",

package/src/bundler/build.ts

@@ -249,6 +249,36 @@ export default ReactDOMClient;
 `;
 }
 
+/**
+ * JSX Runtime shim 소스 생성
+ */
+function generateJsxRuntimeShimSource(): string {
+  return `
+/**
+ * Mandu JSX Runtime Shim (Generated)
+ * Production JSX 변환용
+ */
+import * as jsxRuntime from 'react/jsx-runtime';
+export * from 'react/jsx-runtime';
+export default jsxRuntime;
+`;
+}
+
+/**
+ * JSX Dev Runtime shim 소스 생성
+ */
+function generateJsxDevRuntimeShimSource(): string {
+  return `
+/**
+ * Mandu JSX Dev Runtime Shim (Generated)
+ * Development JSX 변환용
+ */
+import * as jsxDevRuntime from 'react/jsx-dev-runtime';
+export * from 'react/jsx-dev-runtime';
+export default jsxDevRuntime;
+`;
+}
+
 /**
  * Island 엔트리 래퍼 생성
  */
@@ -332,6 +362,8 @@ interface VendorBuildResult {
   react: string;
   reactDom: string;
   reactDomClient: string;
+  jsxRuntime: string;
+  jsxDevRuntime: string;
   errors: string[];
 }
 
@@ -348,12 +380,16 @@ async function buildVendorShims(
     react: "",
     reactDom: "",
     reactDomClient: "",
+    jsxRuntime: "",
+    jsxDevRuntime: "",
   };
 
   const shims = [
     { name: "_react", source: generateReactShimSource(), key: "react" },
     { name: "_react-dom", source: generateReactDOMShimSource(), key: "reactDom" },
     { name: "_react-dom-client", source: generateReactDOMClientShimSource(), key: "reactDomClient" },
+    { name: "_jsx-runtime", source: generateJsxRuntimeShimSource(), key: "jsxRuntime" },
+    { name: "_jsx-dev-runtime", source: generateJsxDevRuntimeShimSource(), key: "jsxDevRuntime" },
   ];
 
   for (const shim of shims) {
@@ -394,6 +430,8 @@ async function buildVendorShims(
     react: results.react,
     reactDom: results.reactDom,
     reactDomClient: results.reactDomClient,
+    jsxRuntime: results.jsxRuntime,
+    jsxDevRuntime: results.jsxDevRuntime,
     errors,
   };
 }
@@ -494,6 +532,8 @@ function createBundleManifest(
         "react": vendorResult.react,
         "react-dom": vendorResult.reactDom,
         "react-dom/client": vendorResult.reactDomClient,
+        "react/jsx-runtime": vendorResult.jsxRuntime,
+        "react/jsx-dev-runtime": vendorResult.jsxDevRuntime,
       },
     },
   };

package/src/filling/auth.ts

@@ -0,0 +1,308 @@
+/**
+ * Mandu Auth Guards - 인증/인가 헬퍼 🔐
+ *
+ * Guard에서 사용할 수 있는 타입-안전 인증 헬퍼
+ * 인증 실패 시 적절한 에러를 throw하여 Guard 체인 중단
+ */
+
+import type { ManduContext } from "./context";
+
+/**
+ * 인증 실패 에러 (401 Unauthorized)
+ */
+export class AuthenticationError extends Error {
+  readonly statusCode = 401;
+
+  constructor(message: string = "Authentication required") {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+}
+
+/**
+ * 인가 실패 에러 (403 Forbidden)
+ */
+export class AuthorizationError extends Error {
+  readonly statusCode = 403;
+  readonly requiredRoles?: string[];
+
+  constructor(message: string = "Access denied", requiredRoles?: string[]) {
+    super(message);
+    this.name = "AuthorizationError";
+    this.requiredRoles = requiredRoles;
+  }
+}
+
+/**
+ * 기본 User 인터페이스
+ * 프로젝트에서 확장하여 사용
+ */
+export interface BaseUser {
+  id: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Role을 가진 User 인터페이스
+ */
+export interface UserWithRole extends BaseUser {
+  role: string;
+}
+
+/**
+ * Roles 배열을 가진 User 인터페이스
+ */
+export interface UserWithRoles extends BaseUser {
+  roles: string[];
+}
+
+// ============================================
+// 🔐 Auth Guard Helpers
+// ============================================
+
+/**
+ * 인증된 사용자 필수
+ * Guard에서 user가 없으면 AuthenticationError throw
+ *
+ * @param ctx ManduContext
+ * @param key store에서 user를 찾을 키 (기본: 'user')
+ * @returns 인증된 User (타입 확정)
+ * @throws AuthenticationError
+ *
+ * @example
+ * ```typescript
+ * import { requireUser } from '@mandujs/core'
+ *
+ * export default Mandu.filling()
+ *   .guard(async (ctx) => {
+ *     // JWT 토큰 검증 후 user 저장
+ *     const user = await verifyToken(ctx.headers.get('Authorization'));
+ *     ctx.set('user', user);
+ *     return ctx.next();
+ *   })
+ *   .get((ctx) => {
+ *     const user = requireUser(ctx);  // User 타입 확정, 없으면 401
+ *     return ctx.ok({ message: `Hello, ${user.id}!` });
+ *   })
+ * ```
+ */
+export function requireUser<T extends BaseUser = BaseUser>(
+  ctx: ManduContext,
+  key: string = "user"
+): T {
+  const user = ctx.get<T>(key);
+
+  if (!user) {
+    throw new AuthenticationError("User context is required");
+  }
+
+  if (typeof user !== "object" || !("id" in user)) {
+    throw new AuthenticationError("Invalid user context");
+  }
+
+  return user;
+}
+
+/**
+ * 특정 역할 필수 (단일 role 필드)
+ *
+ * @param ctx ManduContext
+ * @param roles 허용된 역할 목록
+ * @param key store에서 user를 찾을 키 (기본: 'user')
+ * @returns 인증된 User (타입 확정)
+ * @throws AuthenticationError (user 없음)
+ * @throws AuthorizationError (역할 불일치)
+ *
+ * @example
+ * ```typescript
+ * .guard((ctx) => {
+ *   requireRole(ctx, 'admin', 'moderator');  // admin 또는 moderator만 허용
+ *   return ctx.next();
+ * })
+ * ```
+ */
+export function requireRole<T extends UserWithRole = UserWithRole>(
+  ctx: ManduContext,
+  ...roles: string[]
+): T {
+  const user = requireUser<T>(ctx);
+
+  if (!("role" in user) || typeof user.role !== "string") {
+    throw new AuthorizationError("User has no role defined");
+  }
+
+  if (!roles.includes(user.role)) {
+    throw new AuthorizationError(
+      `Required role: ${roles.join(" or ")}`,
+      roles
+    );
+  }
+
+  return user;
+}
+
+/**
+ * 특정 역할 중 하나 필수 (roles 배열 필드)
+ *
+ * @param ctx ManduContext
+ * @param roles 허용된 역할 목록 (하나라도 있으면 통과)
+ * @param key store에서 user를 찾을 키 (기본: 'user')
+ * @returns 인증된 User (타입 확정)
+ * @throws AuthenticationError (user 없음)
+ * @throws AuthorizationError (역할 불일치)
+ *
+ * @example
+ * ```typescript
+ * .guard((ctx) => {
+ *   requireAnyRole(ctx, 'editor', 'admin');  // editor 또는 admin 역할 필요
+ *   return ctx.next();
+ * })
+ * ```
+ */
+export function requireAnyRole<T extends UserWithRoles = UserWithRoles>(
+  ctx: ManduContext,
+  ...roles: string[]
+): T {
+  const user = requireUser<T>(ctx);
+
+  if (!("roles" in user) || !Array.isArray(user.roles)) {
+    throw new AuthorizationError("User has no roles defined");
+  }
+
+  const hasRole = roles.some((role) => user.roles.includes(role));
+
+  if (!hasRole) {
+    throw new AuthorizationError(
+      `Required one of roles: ${roles.join(", ")}`,
+      roles
+    );
+  }
+
+  return user;
+}
+
+/**
+ * 모든 역할 필수 (roles 배열 필드)
+ *
+ * @param ctx ManduContext
+ * @param roles 필요한 역할 목록 (모두 있어야 통과)
+ * @returns 인증된 User (타입 확정)
+ * @throws AuthenticationError (user 없음)
+ * @throws AuthorizationError (역할 불일치)
+ *
+ * @example
+ * ```typescript
+ * .guard((ctx) => {
+ *   requireAllRoles(ctx, 'verified', 'premium');  // verified AND premium 필요
+ *   return ctx.next();
+ * })
+ * ```
+ */
+export function requireAllRoles<T extends UserWithRoles = UserWithRoles>(
+  ctx: ManduContext,
+  ...roles: string[]
+): T {
+  const user = requireUser<T>(ctx);
+
+  if (!("roles" in user) || !Array.isArray(user.roles)) {
+    throw new AuthorizationError("User has no roles defined");
+  }
+
+  const missingRoles = roles.filter((role) => !user.roles.includes(role));
+
+  if (missingRoles.length > 0) {
+    throw new AuthorizationError(
+      `Missing required roles: ${missingRoles.join(", ")}`,
+      roles
+    );
+  }
+
+  return user;
+}
+
+// ============================================
+// 🔐 Auth Guard Factory
+// ============================================
+
+/**
+ * 인증 Guard 생성 팩토리
+ * 반복되는 인증 로직을 Guard로 변환
+ *
+ * @example
+ * ```typescript
+ * const authGuard = createAuthGuard(async (ctx) => {
+ *   const token = ctx.headers.get('Authorization')?.replace('Bearer ', '');
+ *   if (!token) return null;
+ *   return await verifyJwt(token);
+ * });
+ *
+ * export default Mandu.filling()
+ *   .guard(authGuard)
+ *   .get((ctx) => {
+ *     const user = requireUser(ctx);
+ *     return ctx.ok({ user });
+ *   })
+ * ```
+ */
+export function createAuthGuard<T extends BaseUser>(
+  authenticator: (ctx: ManduContext) => T | null | Promise<T | null>,
+  options: {
+    key?: string;
+    onUnauthenticated?: (ctx: ManduContext) => Response;
+  } = {}
+) {
+  const { key = "user", onUnauthenticated } = options;
+
+  return async (ctx: ManduContext): Promise<symbol | Response> => {
+    try {
+      const user = await authenticator(ctx);
+
+      if (user) {
+        ctx.set(key, user);
+        return ctx.next();
+      }
+
+      if (onUnauthenticated) {
+        return onUnauthenticated(ctx);
+      }
+
+      return ctx.unauthorized("Authentication required");
+    } catch (error) {
+      if (error instanceof AuthenticationError) {
+        return ctx.unauthorized(error.message);
+      }
+      throw error;
+    }
+  };
+}
+
+/**
+ * 역할 기반 Guard 생성 팩토리
+ *
+ * @example
+ * ```typescript
+ * const adminOnly = createRoleGuard('admin');
+ * const editorOrAdmin = createRoleGuard('editor', 'admin');
+ *
+ * export default Mandu.filling()
+ *   .guard(authGuard)
+ *   .guard(adminOnly)  // admin만 접근 가능
+ *   .delete((ctx) => ctx.noContent())
+ * ```
+ */
+export function createRoleGuard(...allowedRoles: string[]) {
+  return (ctx: ManduContext): symbol | Response => {
+    try {
+      requireRole(ctx, ...allowedRoles);
+      return ctx.next();
+    } catch (error) {
+      if (error instanceof AuthenticationError) {
+        return ctx.unauthorized(error.message);
+      }
+      if (error instanceof AuthorizationError) {
+        return ctx.forbidden(error.message);
+      }
+      throw error;
+    }
+  };
+}

package/src/filling/filling.ts

@@ -4,6 +4,7 @@
  */
 
 import { ManduContext, NEXT_SYMBOL, ValidationError } from "./context";
+import { AuthenticationError, AuthorizationError } from "./auth";
 import { ErrorClassifier, formatErrorResponse, ErrorCode } from "../error";
 import { createContract, type ContractDefinition, type ContractInstance } from "../contract";
 
@@ -284,6 +285,35 @@ export class ManduFilling<TLoaderData = unknown> {
       // Execute handler
       return await handler(ctx);
     } catch (error) {
+      // Handle authentication errors
+      if (error instanceof AuthenticationError) {
+        return ctx.json(
+          {
+            errorType: "AUTH_ERROR",
+            code: "AUTHENTICATION_REQUIRED",
+            message: error.message,
+            summary: "인증 필요 - 로그인 후 다시 시도하세요",
+            timestamp: new Date().toISOString(),
+          },
+          401
+        );
+      }
+
+      // Handle authorization errors
+      if (error instanceof AuthorizationError) {
+        return ctx.json(
+          {
+            errorType: "AUTH_ERROR",
+            code: "ACCESS_DENIED",
+            message: error.message,
+            summary: "권한 없음 - 접근 권한이 부족합니다",
+            requiredRoles: error.requiredRoles,
+            timestamp: new Date().toISOString(),
+          },
+          403
+        );
+      }
+
       // Handle validation errors with enhanced error format
       if (error instanceof ValidationError) {
         return ctx.json(

package/src/filling/index.ts

@@ -6,3 +6,16 @@ export { ManduContext, NEXT_SYMBOL, ValidationError, CookieManager } from "./con
 export type { CookieOptions } from "./context";
 export { ManduFilling, Mandu, LoaderTimeoutError } from "./filling";
 export type { Handler, Guard, HttpMethod, Loader, LoaderOptions } from "./filling";
+
+// Auth Guards
+export {
+  AuthenticationError,
+  AuthorizationError,
+  requireUser,
+  requireRole,
+  requireAnyRole,
+  requireAllRoles,
+  createAuthGuard,
+  createRoleGuard,
+} from "./auth";
+export type { BaseUser, UserWithRole, UserWithRoles } from "./auth";

package/src/generator/templates.ts

@@ -190,6 +190,13 @@ function computeSlotImportPath(slotModule: string, fromDir: string): string {
 
 export function generatePageComponent(route: RouteSpec): string {
   const pageName = toPascalCase(route.id);
+
+  // slotModule이 있으면 PageHandler 형식으로 생성 (filling 포함)
+  if (route.slotModule) {
+    return generatePageHandlerWithSlot(route);
+  }
+
+  // slotModule이 없으면 기존 방식
   return `// Generated by Mandu - DO NOT EDIT DIRECTLY
 // Route ID: ${route.id}
 // Pattern: ${route.pattern}
@@ -198,6 +205,7 @@ import React from "react";
 
 interface Props {
   params: Record<string, string>;
+  loaderData?: unknown;
 }
 
 export default function ${pageName}Page({ params }: Props): React.ReactElement {
@@ -210,6 +218,45 @@ export default function ${pageName}Page({ params }: Props): React.ReactElement {
 `;
 }
 
+/**
+ * slotModule이 있는 Page Route용 Handler 생성
+ * - component와 filling을 함께 export
+ * - server.ts에서 filling.executeLoader() 호출 가능
+ */
+export function generatePageHandlerWithSlot(route: RouteSpec): string {
+  const pageName = toPascalCase(route.id);
+  const slotImportPath = computeSlotImportPath(route.slotModule!, "apps/server/generated/routes");
+
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+// Slot Module: ${route.slotModule}
+
+import React from "react";
+import filling from "${slotImportPath}";
+
+interface Props {
+  params: Record<string, string>;
+  loaderData?: unknown;
+}
+
+function ${pageName}Page({ params, loaderData }: Props): React.ReactElement {
+  return React.createElement("div", null,
+    React.createElement("h1", null, "${pageName} Page"),
+    React.createElement("p", null, "Route ID: ${route.id}"),
+    React.createElement("p", null, "Pattern: ${route.pattern}"),
+    loaderData ? React.createElement("pre", null, JSON.stringify(loaderData, null, 2)) : null
+  );
+}
+
+// PageRegistration 형식으로 export (server.ts의 registerPageHandler용)
+export default {
+  component: ${pageName}Page,
+  filling: filling,
+};
+`;
+}
+
 /**
  * Convert string to PascalCase (handles kebab-case, snake_case)
  * "todo-page" → "TodoPage"

package/src/runtime/server.ts

@@ -1,6 +1,8 @@
 import type { Server } from "bun";
 import type { RoutesManifest } from "../spec/schema";
 import type { BundleManifest } from "../bundler/types";
+import type { ManduFilling } from "../filling/filling";
+import { ManduContext } from "../filling/context";
 import { Router } from "./router";
 import { renderSSR } from "./ssr";
 import React from "react";
@@ -103,18 +105,36 @@ export interface ManduServer {
 export type ApiHandler = (req: Request, params: Record<string, string>) => Response | Promise<Response>;
 export type PageLoader = () => Promise<{ default: React.ComponentType<{ params: Record<string, string> }> }>;
 
+/**
+ * Page 등록 정보
+ * - component: React 컴포넌트
+ * - filling: Slot의 ManduFilling 인스턴스 (loader 포함)
+ */
+export interface PageRegistration {
+  component: React.ComponentType<{ params: Record<string, string>; loaderData?: unknown }>;
+  filling?: ManduFilling<unknown>;
+}
+
+/**
+ * Page Handler - 컴포넌트와 filling을 함께 반환
+ */
+export type PageHandler = () => Promise<PageRegistration>;
+
 export interface AppContext {
   routeId: string;
   url: string;
   params: Record<string, string>;
+  /** SSR loader에서 로드한 데이터 */
+  loaderData?: unknown;
 }
 
-type RouteComponent = (props: { params: Record<string, string> }) => React.ReactElement;
+type RouteComponent = (props: { params: Record<string, string>; loaderData?: unknown }) => React.ReactElement;
 type CreateAppFn = (context: AppContext) => React.ReactElement;
 
 // Registry
 const apiHandlers: Map<string, ApiHandler> = new Map();
 const pageLoaders: Map<string, PageLoader> = new Map();
+const pageHandlers: Map<string, PageHandler> = new Map();
 const routeComponents: Map<string, RouteComponent> = new Map();
 let createAppFn: CreateAppFn | null = null;
 
@@ -141,6 +161,14 @@ export function registerPageLoader(routeId: string, loader: PageLoader): void {
   pageLoaders.set(routeId, loader);
 }
 
+/**
+ * Page Handler 등록 (컴포넌트 + filling)
+ * filling이 있으면 loader를 실행하여 serverData 전달
+ */
+export function registerPageHandler(routeId: string, handler: PageHandler): void {
+  pageHandlers.set(routeId, handler);
+}
+
 export function registerRouteComponent(routeId: string, component: RouteComponent): void {
   routeComponents.set(routeId, component);
 }
@@ -160,7 +188,10 @@ function defaultCreateApp(context: AppContext): React.ReactElement {
     );
   }
 
-  return React.createElement(Component, { params: context.params });
+  return React.createElement(Component, {
+    params: context.params,
+    loaderData: context.loaderData,
+  });
 }
 
 // ========== Static File Serving ==========
@@ -281,11 +312,22 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
   }
 
   if (route.kind === "page") {
-    const loader = pageLoaders.get(route.id);
-    if (loader) {
+    let loaderData: unknown;
+    let component: RouteComponent | undefined;
+
+    // 1. PageHandler 방식 (신규 - filling 포함)
+    const pageHandler = pageHandlers.get(route.id);
+    if (pageHandler) {
       try {
-        const module = await loader();
-        registerRouteComponent(route.id, module.default);
+        const registration = await pageHandler();
+        component = registration.component as RouteComponent;
+        registerRouteComponent(route.id, component);
+
+        // Filling의 loader 실행
+        if (registration.filling?.hasLoader()) {
+          const ctx = new ManduContext(req, params);
+          loaderData = await registration.filling.executeLoader(ctx);
+        }
       } catch (err) {
         const pageError = createPageLoadErrorResponse(
           route.id,
@@ -299,6 +341,27 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
         return Response.json(response, { status: 500 });
       }
     }
+    // 2. PageLoader 방식 (레거시 호환)
+    else {
+      const loader = pageLoaders.get(route.id);
+      if (loader) {
+        try {
+          const module = await loader();
+          registerRouteComponent(route.id, module.default);
+        } catch (err) {
+          const pageError = createPageLoadErrorResponse(
+            route.id,
+            route.pattern,
+            err instanceof Error ? err : new Error(String(err))
+          );
+          console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
+          const response = formatErrorResponse(pageError, {
+            isDev: process.env.NODE_ENV !== "production",
+          });
+          return Response.json(response, { status: 500 });
+        }
+      }
+    }
 
     const appCreator = createAppFn || defaultCreateApp;
     try {
@@ -306,8 +369,14 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
         routeId: route.id,
         url: req.url,
         params,
+        loaderData,
       });
 
+      // serverData 구조: { [routeId]: { serverData: loaderData } }
+      const serverData = loaderData
+        ? { [route.id]: { serverData: loaderData } }
+        : undefined;
+
       return renderSSR(app, {
         title: `${route.id} - Mandu`,
         isDev: serverSettings.isDev,
@@ -315,6 +384,7 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
         routeId: route.id,
         hydration: route.hydration,
         bundleManifest: serverSettings.bundleManifest,
+        serverData,
       });
     } catch (err) {
       const ssrError = createSSRErrorResponse(
@@ -418,8 +488,9 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
 export function clearRegistry(): void {
   apiHandlers.clear();
   pageLoaders.clear();
+  pageHandlers.clear();
   routeComponents.clear();
   createAppFn = null;
 }
 
-export { apiHandlers, pageLoaders, routeComponents };
+export { apiHandlers, pageLoaders, pageHandlers, routeComponents };