@mandujs/core 0.5.0 → 0.5.2

package/package.json

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

package/src/filling/context.ts

@@ -5,12 +5,211 @@
 
 import type { ZodSchema } from "zod";
 
+// ========== Cookie Types ==========
+
+export interface CookieOptions {
+  /** 쿠키 만료 시간 (Date 객체 또는 문자열) */
+  expires?: Date | string;
+  /** 쿠키 유효 기간 (초) */
+  maxAge?: number;
+  /** 쿠키 도메인 */
+  domain?: string;
+  /** 쿠키 경로 */
+  path?: string;
+  /** HTTPS에서만 전송 */
+  secure?: boolean;
+  /** JavaScript에서 접근 불가 */
+  httpOnly?: boolean;
+  /** Same-Site 정책 */
+  sameSite?: "strict" | "lax" | "none";
+  /** 파티션 키 (CHIPS) */
+  partitioned?: boolean;
+}
+
+/**
+ * Cookie Manager - 쿠키 읽기/쓰기 관리
+ */
+export class CookieManager {
+  private requestCookies: Map<string, string>;
+  private responseCookies: Map<string, { value: string; options: CookieOptions }>;
+  private deletedCookies: Set<string>;
+
+  constructor(request: Request) {
+    this.requestCookies = this.parseRequestCookies(request);
+    this.responseCookies = new Map();
+    this.deletedCookies = new Set();
+  }
+
+  private parseRequestCookies(request: Request): Map<string, string> {
+    const cookies = new Map<string, string>();
+    const cookieHeader = request.headers.get("cookie");
+
+    if (cookieHeader) {
+      const pairs = cookieHeader.split(";");
+      for (const pair of pairs) {
+        const [name, ...rest] = pair.trim().split("=");
+        if (name) {
+          cookies.set(name, decodeURIComponent(rest.join("=")));
+        }
+      }
+    }
+
+    return cookies;
+  }
+
+  /**
+   * 쿠키 값 읽기
+   * @example
+   * const session = ctx.cookies.get('session');
+   */
+  get(name: string): string | undefined {
+    return this.requestCookies.get(name);
+  }
+
+  /**
+   * 쿠키 존재 여부 확인
+   */
+  has(name: string): boolean {
+    return this.requestCookies.has(name);
+  }
+
+  /**
+   * 모든 쿠키 가져오기
+   */
+  getAll(): Record<string, string> {
+    return Object.fromEntries(this.requestCookies);
+  }
+
+  /**
+   * 쿠키 설정
+   * @example
+   * ctx.cookies.set('session', 'abc123', { httpOnly: true, maxAge: 3600 });
+   */
+  set(name: string, value: string, options: CookieOptions = {}): void {
+    this.responseCookies.set(name, { value, options });
+    this.deletedCookies.delete(name);
+  }
+
+  /**
+   * 쿠키 삭제
+   * @example
+   * ctx.cookies.delete('session');
+   */
+  delete(name: string, options: Pick<CookieOptions, "domain" | "path"> = {}): void {
+    this.responseCookies.delete(name);
+    this.deletedCookies.add(name);
+    // 삭제용 쿠키 설정 (maxAge=0)
+    this.responseCookies.set(name, {
+      value: "",
+      options: {
+        ...options,
+        maxAge: 0,
+        expires: new Date(0),
+      },
+    });
+  }
+
+  /**
+   * Set-Cookie 헤더 값들 생성
+   */
+  getSetCookieHeaders(): string[] {
+    const headers: string[] = [];
+
+    for (const [name, { value, options }] of this.responseCookies) {
+      headers.push(this.serializeCookie(name, value, options));
+    }
+
+    return headers;
+  }
+
+  /**
+   * 쿠키를 Set-Cookie 헤더 형식으로 직렬화
+   */
+  private serializeCookie(name: string, value: string, options: CookieOptions): string {
+    const parts: string[] = [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
+
+    if (options.maxAge !== undefined) {
+      parts.push(`Max-Age=${options.maxAge}`);
+    }
+
+    if (options.expires) {
+      const expires =
+        options.expires instanceof Date
+          ? options.expires.toUTCString()
+          : options.expires;
+      parts.push(`Expires=${expires}`);
+    }
+
+    if (options.domain) {
+      parts.push(`Domain=${options.domain}`);
+    }
+
+    if (options.path) {
+      parts.push(`Path=${options.path}`);
+    } else {
+      parts.push("Path=/"); // 기본값
+    }
+
+    if (options.secure) {
+      parts.push("Secure");
+    }
+
+    if (options.httpOnly) {
+      parts.push("HttpOnly");
+    }
+
+    if (options.sameSite) {
+      parts.push(`SameSite=${options.sameSite.charAt(0).toUpperCase() + options.sameSite.slice(1)}`);
+    }
+
+    if (options.partitioned) {
+      parts.push("Partitioned");
+    }
+
+    return parts.join("; ");
+  }
+
+  /**
+   * Response에 Set-Cookie 헤더들 적용
+   */
+  applyToResponse(response: Response): Response {
+    const setCookieHeaders = this.getSetCookieHeaders();
+
+    if (setCookieHeaders.length === 0) {
+      return response;
+    }
+
+    // Headers를 복사하여 수정
+    const newHeaders = new Headers(response.headers);
+
+    for (const setCookie of setCookieHeaders) {
+      newHeaders.append("Set-Cookie", setCookie);
+    }
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: newHeaders,
+    });
+  }
+
+  /**
+   * 응답에 적용할 쿠키가 있는지 확인
+   */
+  hasPendingCookies(): boolean {
+    return this.responseCookies.size > 0;
+  }
+}
+
+// ========== ManduContext ==========
+
 export class ManduContext {
   private store: Map<string, unknown> = new Map();
   private _params: Record<string, string>;
   private _query: Record<string, string>;
   private _shouldContinue: boolean = true;
   private _response: Response | null = null;
+  private _cookies: CookieManager;
 
   constructor(
     public readonly request: Request,
@@ -18,6 +217,7 @@ export class ManduContext {
   ) {
     this._params = params;
     this._query = this.parseQuery();
+    this._cookies = new CookieManager(request);
   }
 
   private parseQuery(): Record<string, string> {
@@ -58,6 +258,22 @@ export class ManduContext {
     return this.request.url;
   }
 
+  /**
+   * Cookie Manager
+   * @example
+   * // 쿠키 읽기
+   * const session = ctx.cookies.get('session');
+   *
+   * // 쿠키 설정
+   * ctx.cookies.set('session', 'abc123', { httpOnly: true, maxAge: 3600 });
+   *
+   * // 쿠키 삭제
+   * ctx.cookies.delete('session');
+   */
+  get cookies(): CookieManager {
+    return this._cookies;
+  }
+
   /**
    * Parse request body with optional Zod validation
    * @example
@@ -95,6 +311,16 @@ export class ManduContext {
   // 🥟 Response 보내기
   // ============================================
 
+  /**
+   * Response에 쿠키 헤더 적용 (내부 사용)
+   */
+  private withCookies(response: Response): Response {
+    if (this._cookies.hasPendingCookies()) {
+      return this._cookies.applyToResponse(response);
+    }
+    return response;
+  }
+
   /** 200 OK */
   ok<T>(data: T): Response {
     return this.json(data, 200);
@@ -107,7 +333,7 @@ export class ManduContext {
 
   /** 204 No Content */
   noContent(): Response {
-    return new Response(null, { status: 204 });
+    return this.withCookies(new Response(null, { status: 204 }));
   }
 
   /** 400 Bad Request */
@@ -137,28 +363,32 @@ export class ManduContext {
 
   /** Custom JSON response */
   json<T>(data: T, status: number = 200): Response {
-    return Response.json(data, { status });
+    const response = Response.json(data, { status });
+    return this.withCookies(response);
   }
 
   /** Custom text response */
   text(data: string, status: number = 200): Response {
-    return new Response(data, {
+    const response = new Response(data, {
       status,
       headers: { "Content-Type": "text/plain" },
     });
+    return this.withCookies(response);
   }
 
   /** Custom HTML response */
   html(data: string, status: number = 200): Response {
-    return new Response(data, {
+    const response = new Response(data, {
       status,
       headers: { "Content-Type": "text/html" },
     });
+    return this.withCookies(response);
   }
 
   /** Redirect response */
   redirect(url: string, status: 301 | 302 | 307 | 308 = 302): Response {
-    return Response.redirect(url, status);
+    const response = Response.redirect(url, status);
+    return this.withCookies(response);
   }
 
   // ============================================

package/src/filling/index.ts

@@ -2,6 +2,7 @@
  * Mandu Filling Module - 만두소 🥟
  */
 
-export { ManduContext, NEXT_SYMBOL, ValidationError } from "./context";
+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";

package/src/runtime/cors.ts

@@ -0,0 +1,277 @@
+/**
+ * Mandu CORS Support
+ *
+ * Cross-Origin Resource Sharing (CORS) 미들웨어
+ */
+
+export interface CorsOptions {
+  /**
+   * 허용할 Origin 목록
+   * - "*" : 모든 Origin 허용
+   * - string : 특정 Origin만 허용
+   * - string[] : 여러 Origin 허용
+   * - RegExp : 정규식으로 Origin 매칭
+   * - (origin: string) => boolean : 커스텀 함수로 판단
+   */
+  origin?: "*" | string | string[] | RegExp | ((origin: string) => boolean);
+
+  /**
+   * 허용할 HTTP 메서드 목록
+   * @default ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"]
+   */
+  methods?: string[];
+
+  /**
+   * 허용할 요청 헤더 목록
+   * @default ["Content-Type", "Authorization", "X-Requested-With"]
+   */
+  allowedHeaders?: string[];
+
+  /**
+   * 클라이언트에게 노출할 응답 헤더 목록
+   */
+  exposedHeaders?: string[];
+
+  /**
+   * 자격 증명(쿠키, 인증 헤더) 포함 허용 여부
+   * @default false
+   */
+  credentials?: boolean;
+
+  /**
+   * Preflight 요청 캐시 시간 (초)
+   * @default 86400 (24시간)
+   */
+  maxAge?: number;
+
+  /**
+   * Preflight OPTIONS 요청 자동 처리 여부
+   * @default true
+   */
+  preflightContinue?: boolean;
+
+  /**
+   * OPTIONS 요청 성공 응답 상태 코드
+   * @default 204
+   */
+  optionsSuccessStatus?: number;
+}
+
+/**
+ * 기본 CORS 옵션
+ */
+export const DEFAULT_CORS_OPTIONS: Required<CorsOptions> = {
+  origin: "*",
+  methods: ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"],
+  allowedHeaders: ["Content-Type", "Authorization", "X-Requested-With"],
+  exposedHeaders: [],
+  credentials: false,
+  maxAge: 86400,
+  preflightContinue: false,
+  optionsSuccessStatus: 204,
+};
+
+/**
+ * Origin 검증
+ */
+function isOriginAllowed(
+  requestOrigin: string | null,
+  allowedOrigin: CorsOptions["origin"]
+): boolean {
+  if (!requestOrigin) return false;
+
+  if (allowedOrigin === "*") {
+    return true;
+  }
+
+  if (typeof allowedOrigin === "string") {
+    return requestOrigin === allowedOrigin;
+  }
+
+  if (Array.isArray(allowedOrigin)) {
+    return allowedOrigin.includes(requestOrigin);
+  }
+
+  if (allowedOrigin instanceof RegExp) {
+    return allowedOrigin.test(requestOrigin);
+  }
+
+  if (typeof allowedOrigin === "function") {
+    return allowedOrigin(requestOrigin);
+  }
+
+  return false;
+}
+
+/**
+ * CORS 헤더 생성
+ */
+export function createCorsHeaders(
+  req: Request,
+  options: CorsOptions = {}
+): Headers {
+  const opts = { ...DEFAULT_CORS_OPTIONS, ...options };
+  const headers = new Headers();
+  const requestOrigin = req.headers.get("origin");
+
+  // Access-Control-Allow-Origin
+  if (opts.origin === "*" && !opts.credentials) {
+    headers.set("Access-Control-Allow-Origin", "*");
+  } else if (requestOrigin && isOriginAllowed(requestOrigin, opts.origin)) {
+    headers.set("Access-Control-Allow-Origin", requestOrigin);
+    headers.set("Vary", "Origin");
+  }
+
+  // Access-Control-Allow-Credentials
+  if (opts.credentials) {
+    headers.set("Access-Control-Allow-Credentials", "true");
+  }
+
+  // Access-Control-Expose-Headers
+  if (opts.exposedHeaders && opts.exposedHeaders.length > 0) {
+    headers.set("Access-Control-Expose-Headers", opts.exposedHeaders.join(", "));
+  }
+
+  return headers;
+}
+
+/**
+ * Preflight 요청 헤더 생성
+ */
+export function createPreflightHeaders(
+  req: Request,
+  options: CorsOptions = {}
+): Headers {
+  const opts = { ...DEFAULT_CORS_OPTIONS, ...options };
+  const headers = createCorsHeaders(req, options);
+
+  // Access-Control-Allow-Methods
+  headers.set("Access-Control-Allow-Methods", opts.methods.join(", "));
+
+  // Access-Control-Allow-Headers
+  const requestHeaders = req.headers.get("access-control-request-headers");
+  if (requestHeaders) {
+    // Echo back requested headers (or use allowedHeaders)
+    headers.set("Access-Control-Allow-Headers", requestHeaders);
+  } else if (opts.allowedHeaders && opts.allowedHeaders.length > 0) {
+    headers.set("Access-Control-Allow-Headers", opts.allowedHeaders.join(", "));
+  }
+
+  // Access-Control-Max-Age
+  if (opts.maxAge) {
+    headers.set("Access-Control-Max-Age", String(opts.maxAge));
+  }
+
+  return headers;
+}
+
+/**
+ * Preflight OPTIONS 요청 처리
+ */
+export function handlePreflightRequest(
+  req: Request,
+  options: CorsOptions = {}
+): Response {
+  const opts = { ...DEFAULT_CORS_OPTIONS, ...options };
+  const headers = createPreflightHeaders(req, options);
+
+  return new Response(null, {
+    status: opts.optionsSuccessStatus,
+    headers,
+  });
+}
+
+/**
+ * CORS 적용된 Response 생성
+ */
+export function applyCorsToResponse(
+  response: Response,
+  req: Request,
+  options: CorsOptions = {}
+): Response {
+  const corsHeaders = createCorsHeaders(req, options);
+
+  // 기존 응답 헤더에 CORS 헤더 추가
+  const newHeaders = new Headers(response.headers);
+  corsHeaders.forEach((value, key) => {
+    newHeaders.set(key, value);
+  });
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: newHeaders,
+  });
+}
+
+/**
+ * CORS 검사 (요청이 CORS 요청인지)
+ */
+export function isCorsRequest(req: Request): boolean {
+  return req.headers.has("origin");
+}
+
+/**
+ * Preflight 요청인지 확인
+ */
+export function isPreflightRequest(req: Request): boolean {
+  return (
+    req.method === "OPTIONS" &&
+    req.headers.has("origin") &&
+    req.headers.has("access-control-request-method")
+  );
+}
+
+/**
+ * 간편 CORS 헬퍼 - Guard에서 사용
+ *
+ * @example
+ * ```typescript
+ * import { Mandu, cors } from "@mandujs/core";
+ *
+ * export default Mandu.filling()
+ *   .guard(cors({ origin: "https://example.com" }))
+ *   .get((ctx) => ctx.ok({ data: "hello" }));
+ * ```
+ */
+export function cors(options: CorsOptions = {}) {
+  return async (ctx: { request: Request; next: () => symbol }) => {
+    // Preflight 요청 처리
+    if (isPreflightRequest(ctx.request)) {
+      return handlePreflightRequest(ctx.request, options);
+    }
+
+    // 일반 요청 - next()로 계속 진행
+    return ctx.next();
+  };
+}
+
+/**
+ * CORS 옵션 프리셋
+ */
+export const corsPresets = {
+  /**
+   * 모든 Origin 허용 (개발용)
+   */
+  development: (): CorsOptions => ({
+    origin: "*",
+    credentials: false,
+  }),
+
+  /**
+   * 특정 도메인만 허용
+   */
+  production: (allowedOrigins: string[]): CorsOptions => ({
+    origin: allowedOrigins,
+    credentials: true,
+    maxAge: 86400,
+  }),
+
+  /**
+   * 동일 도메인 + 특정 서브도메인 허용
+   */
+  sameOriginWithSubdomains: (baseDomain: string): CorsOptions => ({
+    origin: new RegExp(`^https?://([a-z0-9-]+\\.)?${baseDomain.replace(".", "\\.")}$`),
+    credentials: true,
+  }),
+};

package/src/runtime/env.ts

@@ -0,0 +1,386 @@
+/**
+ * Mandu Environment Configuration
+ *
+ * .env 파일 로딩 및 환경 변수 관리
+ * Bun의 내장 .env 지원을 확장하여 환경별 설정 제공
+ */
+
+import path from "path";
+
+// ========== Types ==========
+
+export interface EnvConfig {
+  /**
+   * 프로젝트 루트 디렉토리
+   * @default process.cwd()
+   */
+  rootDir?: string;
+
+  /**
+   * 환경 이름 (development, production, test 등)
+   * @default process.env.NODE_ENV || 'development'
+   */
+  env?: string;
+
+  /**
+   * .env 파일 경로 목록 (우선순위 순서)
+   * @default ['.env.local', '.env.{env}', '.env']
+   */
+  files?: string[];
+
+  /**
+   * 필수 환경 변수 목록
+   * 없으면 에러 발생
+   */
+  required?: string[];
+
+  /**
+   * 기본값 설정
+   */
+  defaults?: Record<string, string>;
+}
+
+export interface EnvValidationResult {
+  success: boolean;
+  loaded: string[];
+  missing: string[];
+  errors: string[];
+}
+
+// ========== Internal Helpers ==========
+
+/**
+ * .env 파일 파싱
+ */
+function parseEnvFile(content: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  const lines = content.split("\n");
+
+  for (const line of lines) {
+    // 빈 줄이나 주석 건너뛰기
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    // KEY=VALUE 파싱
+    const equalIndex = trimmed.indexOf("=");
+    if (equalIndex === -1) {
+      continue;
+    }
+
+    const key = trimmed.substring(0, equalIndex).trim();
+    let value = trimmed.substring(equalIndex + 1).trim();
+
+    // 따옴표 제거
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+
+    // 이스케이프 문자 처리
+    value = value
+      .replace(/\\n/g, "\n")
+      .replace(/\\r/g, "\r")
+      .replace(/\\t/g, "\t");
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * 파일이 존재하는지 확인
+ */
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    const file = Bun.file(filePath);
+    return await file.exists();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 파일 내용 읽기
+ */
+async function readFile(filePath: string): Promise<string | null> {
+  try {
+    const file = Bun.file(filePath);
+    if (await file.exists()) {
+      return await file.text();
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ========== Main Functions ==========
+
+/**
+ * .env 파일들 로드
+ *
+ * 로드 순서 (나중에 로드된 것이 우선):
+ * 1. .env (기본 설정)
+ * 2. .env.{environment} (환경별 설정)
+ * 3. .env.local (로컬 오버라이드, git에 포함하지 않음)
+ *
+ * @example
+ * ```typescript
+ * await loadEnv(); // 기본 설정
+ *
+ * await loadEnv({
+ *   env: 'production',
+ *   required: ['DATABASE_URL', 'API_KEY'],
+ * });
+ * ```
+ */
+export async function loadEnv(config: EnvConfig = {}): Promise<EnvValidationResult> {
+  const {
+    rootDir = process.cwd(),
+    env = process.env.NODE_ENV || "development",
+    files,
+    required = [],
+    defaults = {},
+  } = config;
+
+  const result: EnvValidationResult = {
+    success: true,
+    loaded: [],
+    missing: [],
+    errors: [],
+  };
+
+  // 기본 파일 순서
+  const envFiles = files || [
+    ".env",
+    `.env.${env}`,
+    ".env.local",
+  ];
+
+  // 기본값 먼저 적용
+  for (const [key, value] of Object.entries(defaults)) {
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+
+  // .env 파일들 로드
+  for (const envFile of envFiles) {
+    const filePath = path.join(rootDir, envFile);
+
+    const content = await readFile(filePath);
+    if (content !== null) {
+      const parsed = parseEnvFile(content);
+
+      for (const [key, value] of Object.entries(parsed)) {
+        process.env[key] = value;
+      }
+
+      result.loaded.push(envFile);
+    }
+  }
+
+  // 필수 환경 변수 검증
+  for (const key of required) {
+    if (!process.env[key]) {
+      result.missing.push(key);
+      result.errors.push(`Missing required environment variable: ${key}`);
+    }
+  }
+
+  if (result.missing.length > 0) {
+    result.success = false;
+  }
+
+  return result;
+}
+
+/**
+ * 환경 변수 타입 안전하게 가져오기
+ *
+ * @example
+ * ```typescript
+ * const port = env('PORT', '3000'); // string
+ * const debug = env.bool('DEBUG', false); // boolean
+ * const timeout = env.number('TIMEOUT', 5000); // number
+ * ```
+ */
+export function env(key: string, defaultValue?: string): string {
+  return process.env[key] ?? defaultValue ?? "";
+}
+
+/**
+ * 환경 변수 헬퍼 함수들
+ */
+export const envHelpers = {
+  /**
+   * 문자열 환경 변수
+   */
+  string(key: string, defaultValue: string = ""): string {
+    return process.env[key] ?? defaultValue;
+  },
+
+  /**
+   * 숫자 환경 변수
+   */
+  number(key: string, defaultValue: number = 0): number {
+    const value = process.env[key];
+    if (value === undefined) return defaultValue;
+    const parsed = Number(value);
+    return isNaN(parsed) ? defaultValue : parsed;
+  },
+
+  /**
+   * 불리언 환경 변수
+   */
+  bool(key: string, defaultValue: boolean = false): boolean {
+    const value = process.env[key];
+    if (value === undefined) return defaultValue;
+    return value === "true" || value === "1" || value === "yes";
+  },
+
+  /**
+   * 배열 환경 변수 (쉼표로 구분)
+   */
+  array(key: string, defaultValue: string[] = []): string[] {
+    const value = process.env[key];
+    if (value === undefined) return defaultValue;
+    return value.split(",").map((s) => s.trim()).filter(Boolean);
+  },
+
+  /**
+   * JSON 환경 변수
+   */
+  json<T>(key: string, defaultValue: T): T {
+    const value = process.env[key];
+    if (value === undefined) return defaultValue;
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return defaultValue;
+    }
+  },
+
+  /**
+   * 필수 환경 변수 (없으면 에러)
+   */
+  required(key: string): string {
+    const value = process.env[key];
+    if (value === undefined) {
+      throw new Error(`Missing required environment variable: ${key}`);
+    }
+    return value;
+  },
+
+  /**
+   * 현재 환경 이름
+   */
+  get NODE_ENV(): string {
+    return process.env.NODE_ENV || "development";
+  },
+
+  /**
+   * 개발 환경 여부
+   */
+  get isDevelopment(): boolean {
+    return this.NODE_ENV === "development";
+  },
+
+  /**
+   * 프로덕션 환경 여부
+   */
+  get isProduction(): boolean {
+    return this.NODE_ENV === "production";
+  },
+
+  /**
+   * 테스트 환경 여부
+   */
+  get isTest(): boolean {
+    return this.NODE_ENV === "test";
+  },
+};
+
+/**
+ * 환경 변수 스키마 정의 및 검증
+ *
+ * @example
+ * ```typescript
+ * const config = defineEnvSchema({
+ *   DATABASE_URL: { type: 'string', required: true },
+ *   PORT: { type: 'number', default: 3000 },
+ *   DEBUG: { type: 'boolean', default: false },
+ * });
+ *
+ * // 자동으로 타입 추론됨
+ * config.DATABASE_URL // string
+ * config.PORT // number
+ * config.DEBUG // boolean
+ * ```
+ */
+export interface EnvSchemaField {
+  type: "string" | "number" | "boolean" | "array" | "json";
+  required?: boolean;
+  default?: unknown;
+  description?: string;
+}
+
+export type EnvSchema = Record<string, EnvSchemaField>;
+
+export type InferEnvSchema<T extends EnvSchema> = {
+  [K in keyof T]: T[K]["type"] extends "string"
+    ? string
+    : T[K]["type"] extends "number"
+      ? number
+      : T[K]["type"] extends "boolean"
+        ? boolean
+        : T[K]["type"] extends "array"
+          ? string[]
+          : unknown;
+};
+
+export function defineEnvSchema<T extends EnvSchema>(
+  schema: T
+): InferEnvSchema<T> {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, field] of Object.entries(schema)) {
+    const { type, required = false, default: defaultValue } = field;
+
+    let value: unknown;
+
+    switch (type) {
+      case "string":
+        value = envHelpers.string(key, defaultValue as string);
+        break;
+      case "number":
+        value = envHelpers.number(key, defaultValue as number);
+        break;
+      case "boolean":
+        value = envHelpers.bool(key, defaultValue as boolean);
+        break;
+      case "array":
+        value = envHelpers.array(key, defaultValue as string[]);
+        break;
+      case "json":
+        value = envHelpers.json(key, defaultValue);
+        break;
+    }
+
+    if (required && (value === undefined || value === "")) {
+      throw new Error(
+        `Missing required environment variable: ${key}${field.description ? ` (${field.description})` : ""}`
+      );
+    }
+
+    result[key] = value;
+  }
+
+  return result as InferEnvSchema<T>;
+}
+
+// Re-export for convenience
+export { env as getEnv };

package/src/runtime/index.ts

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

package/src/runtime/server.ts

@@ -1,8 +1,10 @@
 import type { Server } from "bun";
 import type { RoutesManifest } from "../spec/schema";
+import type { BundleManifest } from "../bundler/types";
 import { Router } from "./router";
 import { renderSSR } from "./ssr";
 import React from "react";
+import path from "path";
 import {
   formatErrorResponse,
   createNotFoundResponse,
@@ -10,14 +12,86 @@ import {
   createPageLoadErrorResponse,
   createSSRErrorResponse,
 } from "../error";
+import {
+  type CorsOptions,
+  isPreflightRequest,
+  handlePreflightRequest,
+  applyCorsToResponse,
+  isCorsRequest,
+} from "./cors";
+
+// ========== MIME Types ==========
+const MIME_TYPES: Record<string, string> = {
+  // JavaScript
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".ts": "application/typescript",
+  // CSS
+  ".css": "text/css",
+  // HTML
+  ".html": "text/html",
+  ".htm": "text/html",
+  // JSON
+  ".json": "application/json",
+  // Images
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  // Fonts
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".eot": "application/vnd.ms-fontobject",
+  // Documents
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".xml": "application/xml",
+  // Media
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".ogg": "audio/ogg",
+  // Archives
+  ".zip": "application/zip",
+  ".gz": "application/gzip",
+  // WebAssembly
+  ".wasm": "application/wasm",
+  // Source maps
+  ".map": "application/json",
+};
 
+function getMimeType(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] || "application/octet-stream";
+}
+
+// ========== Server Options ==========
 export interface ServerOptions {
   port?: number;
   hostname?: string;
+  /** 프로젝트 루트 디렉토리 */
+  rootDir?: string;
   /** 개발 모드 여부 */
   isDev?: boolean;
   /** HMR 포트 (개발 모드에서 사용) */
   hmrPort?: number;
+  /** 번들 매니페스트 (Island hydration용) */
+  bundleManifest?: BundleManifest;
+  /** Public 디렉토리 경로 (기본: 'public') */
+  publicDir?: string;
+  /**
+   * CORS 설정
+   * - true: 모든 Origin 허용
+   * - false: CORS 비활성화 (기본값)
+   * - CorsOptions: 세부 설정
+   */
+  cors?: boolean | CorsOptions;
 }
 
 export interface ManduServer {
@@ -44,8 +118,20 @@ const pageLoaders: Map<string, PageLoader> = new Map();
 const routeComponents: Map<string, RouteComponent> = new Map();
 let createAppFn: CreateAppFn | null = null;
 
-// Dev mode settings (module-level for handleRequest access)
-let devModeSettings: { isDev: boolean; hmrPort?: number } = { isDev: false };
+// Server settings (module-level for handleRequest access)
+let serverSettings: {
+  isDev: boolean;
+  hmrPort?: number;
+  bundleManifest?: BundleManifest;
+  rootDir: string;
+  publicDir: string;
+  cors?: CorsOptions | false;
+} = {
+  isDev: false,
+  rootDir: process.cwd(),
+  publicDir: "public",
+  cors: false,
+};
 
 export function registerApiHandler(routeId: string, handler: ApiHandler): void {
   apiHandlers.set(routeId, handler);
@@ -77,10 +163,99 @@ function defaultCreateApp(context: AppContext): React.ReactElement {
   return React.createElement(Component, { params: context.params });
 }
 
+// ========== Static File Serving ==========
+
+/**
+ * 정적 파일 서빙
+ * - /.mandu/client/* : 클라이언트 번들 (Island hydration)
+ * - /public/* : 정적 에셋 (이미지, CSS 등)
+ * - /favicon.ico : 파비콘
+ */
+async function serveStaticFile(pathname: string): Promise<Response | null> {
+  let filePath: string | null = null;
+  let isBundleFile = false;
+
+  // 1. 클라이언트 번들 파일 (/.mandu/client/*)
+  if (pathname.startsWith("/.mandu/client/")) {
+    filePath = path.join(serverSettings.rootDir, pathname);
+    isBundleFile = true;
+  }
+  // 2. Public 폴더 파일 (/public/* 또는 직접 접근)
+  else if (pathname.startsWith("/public/")) {
+    filePath = path.join(serverSettings.rootDir, pathname);
+  }
+  // 3. Public 폴더의 루트 파일 (favicon.ico, robots.txt 등)
+  else if (
+    pathname === "/favicon.ico" ||
+    pathname === "/robots.txt" ||
+    pathname === "/sitemap.xml" ||
+    pathname === "/manifest.json"
+  ) {
+    filePath = path.join(serverSettings.rootDir, serverSettings.publicDir, pathname);
+  }
+
+  if (!filePath) {
+    return null; // 정적 파일이 아님
+  }
+
+  try {
+    const file = Bun.file(filePath);
+    const exists = await file.exists();
+
+    if (!exists) {
+      return null; // 파일 없음 - 라우트 매칭으로 넘김
+    }
+
+    const mimeType = getMimeType(filePath);
+
+    // Cache-Control 헤더 설정
+    let cacheControl: string;
+    if (serverSettings.isDev) {
+      // 개발 모드: 캐시 없음
+      cacheControl = "no-cache, no-store, must-revalidate";
+    } else if (isBundleFile) {
+      // 프로덕션 번들: 1년 캐시 (파일명에 해시 포함 가정)
+      cacheControl = "public, max-age=31536000, immutable";
+    } else {
+      // 프로덕션 일반 정적 파일: 1일 캐시
+      cacheControl = "public, max-age=86400";
+    }
+
+    return new Response(file, {
+      headers: {
+        "Content-Type": mimeType,
+        "Cache-Control": cacheControl,
+      },
+    });
+  } catch {
+    return null; // 파일 읽기 실패 - 라우트 매칭으로 넘김
+  }
+}
+
+// ========== Request Handler ==========
+
 async function handleRequest(req: Request, router: Router): Promise<Response> {
   const url = new URL(req.url);
   const pathname = url.pathname;
 
+  // 0. CORS Preflight 요청 처리
+  if (serverSettings.cors && isPreflightRequest(req)) {
+    const corsOptions = serverSettings.cors === true ? {} : serverSettings.cors;
+    return handlePreflightRequest(req, corsOptions);
+  }
+
+  // 1. 정적 파일 서빙 시도 (최우선)
+  const staticResponse = await serveStaticFile(pathname);
+  if (staticResponse) {
+    // 정적 파일에도 CORS 헤더 적용
+    if (serverSettings.cors && isCorsRequest(req)) {
+      const corsOptions = serverSettings.cors === true ? {} : serverSettings.cors;
+      return applyCorsToResponse(staticResponse, req, corsOptions);
+    }
+    return staticResponse;
+  }
+
+  // 2. 라우트 매칭
   const match = router.match(pathname);
 
   if (!match) {
@@ -135,8 +310,11 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
 
       return renderSSR(app, {
         title: `${route.id} - Mandu`,
-        isDev: devModeSettings.isDev,
-        hmrPort: devModeSettings.hmrPort,
+        isDev: serverSettings.isDev,
+        hmrPort: serverSettings.hmrPort,
+        routeId: route.id,
+        hydration: route.hydration,
+        bundleManifest: serverSettings.bundleManifest,
       });
     } catch (err) {
       const ssrError = createSSRErrorResponse(
@@ -169,18 +347,51 @@ async function handleRequest(req: Request, router: Router): Promise<Response> {
   }, { status: 500 });
 }
 
+// ========== Server Startup ==========
+
 export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
-  const { port = 3000, hostname = "localhost", isDev = false, hmrPort } = options;
+  const {
+    port = 3000,
+    hostname = "localhost",
+    rootDir = process.cwd(),
+    isDev = false,
+    hmrPort,
+    bundleManifest,
+    publicDir = "public",
+    cors = false,
+  } = options;
+
+  // CORS 옵션 파싱
+  const corsOptions: CorsOptions | false = cors === true ? {} : cors;
 
-  // Dev mode settings 저장
-  devModeSettings = { isDev, hmrPort };
+  // Server settings 저장
+  serverSettings = {
+    isDev,
+    hmrPort,
+    bundleManifest,
+    rootDir,
+    publicDir,
+    cors: corsOptions,
+  };
 
   const router = new Router(manifest.routes);
 
+  // Fetch handler with CORS support
+  const fetchHandler = async (req: Request): Promise<Response> => {
+    const response = await handleRequest(req, router);
+
+    // API 라우트 응답에 CORS 헤더 적용
+    if (corsOptions && isCorsRequest(req)) {
+      return applyCorsToResponse(response, req, corsOptions);
+    }
+
+    return response;
+  };
+
   const server = Bun.serve({
     port,
     hostname,
-    fetch: (req) => handleRequest(req, router),
+    fetch: fetchHandler,
   });
 
   if (isDev) {
@@ -188,6 +399,10 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     if (hmrPort) {
       console.log(`🔥 HMR enabled on port ${hmrPort + 1}`);
     }
+    console.log(`📂 Static files: /${publicDir}/, /.mandu/client/`);
+    if (corsOptions) {
+      console.log(`🌐 CORS enabled`);
+    }
   } else {
     console.log(`🥟 Mandu server running at http://${hostname}:${port}`);
   }