@mandujs/core 0.18.22 → 0.19.2

package/src/filling/session.ts

@@ -0,0 +1,216 @@
+/**
+ * Mandu Session Storage
+ * 쿠키 기반 서버 사이드 세션 관리
+ */
+
+import { type CookieManager, type CookieOptions } from "./context";
+
+// ========== Types ==========
+
+export interface SessionData {
+  [key: string]: unknown;
+}
+
+export interface SessionStorage {
+  /** 요청의 쿠키에서 세션 가져오기 */
+  getSession(cookies: CookieManager): Promise<Session>;
+  /** 세션을 직렬화하여 Set-Cookie 헤더 문자열 반환 */
+  commitSession(session: Session): Promise<string>;
+  /** 세션 파기 (쿠키 삭제) */
+  destroySession(session: Session): Promise<string>;
+}
+
+export interface CookieSessionOptions {
+  cookie: {
+    /** 쿠키 이름 (기본: "__session") */
+    name?: string;
+    /** HMAC 서명 시크릿 */
+    secrets: string[];
+    /** 기본 쿠키 옵션 */
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+  };
+}
+
+// ========== Session Class ==========
+
+export class Session {
+  private data: SessionData;
+  private flash: Map<string, unknown> = new Map();
+  readonly id: string;
+
+  constructor(data: SessionData = {}, id?: string) {
+    this.data = { ...data };
+    this.id = id ?? crypto.randomUUID();
+  }
+
+  get<T = unknown>(key: string): T | undefined {
+    // flash 데이터는 한번 읽으면 제거
+    if (this.flash.has(key)) {
+      const value = this.flash.get(key);
+      this.flash.delete(key);
+      return value as T;
+    }
+    return this.data[key] as T | undefined;
+  }
+
+  set(key: string, value: unknown): void {
+    this.data[key] = value;
+  }
+
+  has(key: string): boolean {
+    return key in this.data || this.flash.has(key);
+  }
+
+  unset(key: string): void {
+    delete this.data[key];
+  }
+
+  /**
+   * Flash 메시지 — 다음 요청에서 한번만 읽을 수 있는 데이터
+   * 로그인 성공 메시지, 에러 알림 등에 사용
+   */
+  setFlash(key: string, value: unknown): void {
+    this.flash.set(key, value);
+    // flash 데이터도 직렬화에 포함
+    this.data[`__flash_${key}`] = value;
+  }
+
+  /** 내부 직렬화용 */
+  toJSON(): SessionData {
+    return { ...this.data };
+  }
+
+  /** flash 데이터 복원 */
+  static fromJSON(data: SessionData): Session {
+    const session = new Session();
+    const flashKeys: string[] = [];
+
+    for (const [key, value] of Object.entries(data)) {
+      if (key.startsWith("__flash_")) {
+        const realKey = key.slice(8);
+        session.flash.set(realKey, value);
+        flashKeys.push(key);
+      } else {
+        session.data[key] = value;
+      }
+    }
+
+    // flash 키는 data에서 제거 (한번 복원되면 끝)
+    for (const key of flashKeys) {
+      delete session.data[key];
+    }
+
+    return session;
+  }
+}
+
+// ========== Cookie Session Storage ==========
+
+/**
+ * 쿠키 기반 세션 스토리지 생성
+ *
+ * @example
+ * ```typescript
+ * import { createCookieSessionStorage } from "@mandujs/core";
+ *
+ * const sessionStorage = createCookieSessionStorage({
+ *   cookie: {
+ *     name: "__session",
+ *     secrets: [process.env.SESSION_SECRET!],
+ *     httpOnly: true,
+ *     secure: true,
+ *     sameSite: "lax",
+ *     maxAge: 60 * 60 * 24, // 1일
+ *   },
+ * });
+ *
+ * // filling에서 사용
+ * .action("login", async (ctx) => {
+ *   const session = await sessionStorage.getSession(ctx.cookies);
+ *   session.set("userId", user.id);
+ *   session.setFlash("message", "로그인 성공!");
+ *   const setCookie = await sessionStorage.commitSession(session);
+ *   return ctx.redirect("/dashboard", {
+ *     headers: { "Set-Cookie": setCookie },
+ *   });
+ * });
+ * ```
+ */
+export function createCookieSessionStorage(options: CookieSessionOptions): SessionStorage {
+  const {
+    name = "__session",
+    secrets,
+    httpOnly = true,
+    secure = process.env.NODE_ENV === "production",
+    sameSite = "lax",
+    maxAge = 86400,
+    path = "/",
+    domain,
+  } = options.cookie;
+
+  if (!secrets.length) {
+    throw new Error("[Mandu Session] At least one secret is required");
+  }
+
+  const cookieOptions: CookieOptions = {
+    httpOnly,
+    secure,
+    sameSite,
+    maxAge,
+    path,
+    domain,
+  };
+
+  return {
+    async getSession(cookies: CookieManager): Promise<Session> {
+      // Secret rotation: 모든 시크릿으로 검증 시도 (서명은 항상 secrets[0]으로)
+      for (const secret of secrets) {
+        const raw = await cookies.getSigned(name, secret);
+        if (typeof raw === "string" && raw.length > 0) {
+          try {
+            const data = JSON.parse(raw) as SessionData;
+            return Session.fromJSON(data);
+          } catch {
+            continue;
+          }
+        }
+      }
+      return new Session();
+    },
+
+    async commitSession(session: Session): Promise<string> {
+      const value = JSON.stringify(session.toJSON());
+      // 서명된 쿠키로 직렬화
+      const encoder = new TextEncoder();
+      const key = await crypto.subtle.importKey(
+        "raw",
+        encoder.encode(secrets[0]),
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign"]
+      );
+      const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(value));
+      const sigBase64 = btoa(String.fromCharCode(...new Uint8Array(signature))).replace(/=+$/, "");
+
+      const cookieValue = `${value}.${sigBase64}`;
+      const parts = [`${name}=${encodeURIComponent(cookieValue)}`];
+      if (cookieOptions.path) parts.push(`Path=${cookieOptions.path}`);
+      if (cookieOptions.domain) parts.push(`Domain=${cookieOptions.domain}`);
+      if (cookieOptions.maxAge) parts.push(`Max-Age=${cookieOptions.maxAge}`);
+      if (cookieOptions.httpOnly) parts.push("HttpOnly");
+      if (cookieOptions.secure) parts.push("Secure");
+      if (cookieOptions.sameSite) parts.push(`SameSite=${cookieOptions.sameSite}`);
+
+      return parts.join("; ");
+    },
+
+    async destroySession(_session: Session): Promise<string> {
+      return `${name}=; Path=${path}; Max-Age=0; HttpOnly${secure ? "; Secure" : ""}`;
+    },
+  };
+}

package/src/filling/ws.ts

@@ -0,0 +1,78 @@
+/**
+ * Mandu WebSocket Handler
+ * filling.ws({ open, message, close }) 패턴
+ */
+
+// ========== Types ==========
+
+export interface ManduWebSocket {
+  /** 고유 연결 ID */
+  readonly id: string;
+  /** 연결에 첨부된 데이터 */
+  readonly data: Record<string, unknown>;
+
+  /** 메시지 전송 */
+  send(data: string | ArrayBuffer | Uint8Array): void;
+  /** 토픽 구독 (pub/sub) */
+  subscribe(topic: string): void;
+  /** 토픽 구독 해제 */
+  unsubscribe(topic: string): void;
+  /** 토픽에 브로드캐스트 (자신 제외) */
+  publish(topic: string, data: string | ArrayBuffer | Uint8Array): void;
+  /** 연결 종료 */
+  close(code?: number, reason?: string): void;
+  /** JSON 전송 헬퍼 */
+  sendJSON(data: unknown): void;
+}
+
+export interface WSHandlers {
+  /** 연결 시 */
+  open?(ws: ManduWebSocket): void;
+  /** 메시지 수신 시 */
+  message?(ws: ManduWebSocket, message: string | ArrayBuffer): void;
+  /** 연결 종료 시 */
+  close?(ws: ManduWebSocket, code: number, reason: string): void;
+  /** 백프레셔 해소 시 */
+  drain?(ws: ManduWebSocket): void;
+}
+
+export interface WSUpgradeData {
+  routeId: string;
+  params: Record<string, string>;
+  id: string;
+}
+
+// ========== Implementation ==========
+
+/**
+ * Bun WebSocket을 ManduWebSocket으로 래핑
+ */
+export function wrapBunWebSocket(
+  bunWs: { send: Function; subscribe: Function; unsubscribe: Function; publish: Function; close: Function; data: unknown }
+): ManduWebSocket {
+  const wsData = bunWs.data as WSUpgradeData;
+
+  return {
+    get id() { return wsData.id; },
+    get data() { return wsData as unknown as Record<string, unknown>; },
+
+    send(data: string | ArrayBuffer | Uint8Array) {
+      bunWs.send(data);
+    },
+    subscribe(topic: string) {
+      bunWs.subscribe(topic);
+    },
+    unsubscribe(topic: string) {
+      bunWs.unsubscribe(topic);
+    },
+    publish(topic: string, data: string | ArrayBuffer | Uint8Array) {
+      bunWs.publish(topic, data);
+    },
+    close(code?: number, reason?: string) {
+      bunWs.close(code, reason);
+    },
+    sendJSON(data: unknown) {
+      bunWs.send(JSON.stringify(data));
+    },
+  };
+}

package/src/generator/generate.ts

@@ -1,7 +1,7 @@
 import type { RoutesManifest, RouteSpec } from "../spec/schema";
 import { generateApiHandler, generatePageComponent, generateSlotLogic } from "./templates";
 import { generateContractTypeGlue, generateContractTemplate, generateContractTypesIndex } from "./contract-glue";
-import { computeHash } from "../spec/lock";
+import { createHash } from "crypto";
 import { getWatcher } from "../watcher/watcher";
 import { resolveGeneratedPaths, GENERATED_RELATIVE_PATHS } from "../paths";
 import path from "path";
@@ -158,7 +158,7 @@ export async function generateRoutes(
     generatedAt: new Date().toISOString(),
     specSource: {
       path: ".mandu/routes.manifest.json",
-      hash: computeHash(manifest),
+      hash: createHash("sha256").update(JSON.stringify(manifest)).digest("hex"),
     },
     files: {},
     frameworkPaths: [

package/src/guard/auto-correct.ts

@@ -2,7 +2,6 @@ import type { RoutesManifest } from "../spec/schema";
 import type { GuardViolation } from "./rules";
 import { GUARD_RULES } from "./rules";
 import { runGuardCheck } from "./check";
-import { writeLock } from "../spec/lock";
 import { generateRoutes } from "../generator/generate";
 import { beginChange, commitChange, rollbackChange } from "../change";
 import path from "path";
@@ -27,7 +26,6 @@ export interface AutoCorrectResult {
 
 // 자동 수정 가능한 규칙들
 const AUTO_CORRECTABLE_RULES = new Set([
-  GUARD_RULES.SPEC_HASH_MISMATCH.id,
   GUARD_RULES.GENERATED_MANUAL_EDIT.id,
   GUARD_RULES.SLOT_NOT_FOUND.id,
 ]);
@@ -148,9 +146,6 @@ async function correctViolation(
   rootDir: string
 ): Promise<AutoCorrectStep> {
   switch (violation.ruleId) {
-    case GUARD_RULES.SPEC_HASH_MISMATCH.id:
-      return await correctSpecHashMismatch(manifest, rootDir);
-
     case GUARD_RULES.GENERATED_MANUAL_EDIT.id:
       return await correctGeneratedManualEdit(manifest, rootDir);
 
@@ -167,30 +162,6 @@ async function correctViolation(
   }
 }
 
-async function correctSpecHashMismatch(
-  manifest: RoutesManifest,
-  rootDir: string
-): Promise<AutoCorrectStep> {
-  try {
-    const lockPath = path.join(rootDir, ".mandu/spec.lock.json");
-    await writeLock(lockPath, manifest);
-
-    return {
-      ruleId: GUARD_RULES.SPEC_HASH_MISMATCH.id,
-      action: "spec-upsert",
-      success: true,
-      message: "spec.lock.json 업데이트 완료",
-    };
-  } catch (error) {
-    return {
-      ruleId: GUARD_RULES.SPEC_HASH_MISMATCH.id,
-      action: "spec-upsert",
-      success: false,
-      message: `spec.lock.json 업데이트 실패: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-}
-
 async function correctGeneratedManualEdit(
   manifest: RoutesManifest,
   rootDir: string

package/src/guard/check.ts

@@ -1,5 +1,4 @@
 import { GUARD_RULES, FORBIDDEN_IMPORTS, type GuardViolation } from "./rules";
-import { verifyLock, computeHash } from "../spec/lock";
 import { runContractGuardCheck } from "./contract-guard";
 import { validateSlotContent } from "../slot/validator";
 import type { RoutesManifest } from "../spec/schema";
@@ -59,27 +58,6 @@ async function readFileContent(filePath: string): Promise<string | null> {
   }
 }
 
-// Rule 1: Spec hash mismatch
-export async function checkSpecHashMismatch(
-  manifest: RoutesManifest,
-  lockPath: string
-): Promise<GuardViolation | null> {
-  const result = await verifyLock(lockPath, manifest);
-
-  if (!result.valid) {
-    return {
-      ruleId: GUARD_RULES.SPEC_HASH_MISMATCH.id,
-      file: lockPath,
-      message: result.lockHash
-        ? `Spec 해시 불일치: lock(${result.lockHash.slice(0, 8)}...) != current(${result.currentHash.slice(0, 8)}...)`
-        : "spec.lock.json 파일이 없습니다",
-      suggestion: "bunx mandu spec-upsert를 실행하여 변경사항을 반영하세요",
-    };
-  }
-
-  return null;
-}
-
 // Rule 2: Generated file manual edit detection
 export async function checkGeneratedManualEdit(
   rootDir: string,
@@ -247,16 +225,25 @@ export async function checkIslandFirstIntegrity(
       continue;
     }
 
-    // 2. componentModule이 island을 import하는지 확인
-    if (route.componentModule) {
+    // 2. Island-First integrity: verify that a .island.tsx or .client.tsx file
+    //    exists alongside the page's componentModule. The page does NOT need to
+    //    directly import the island - the framework auto-links them via
+    //    data-island attributes and the manifest's clientModule field.
+    if (route.componentModule && route.clientModule) {
       const componentPath = path.join(rootDir, route.componentModule);
       const content = await readFileContent(componentPath);
-      if (content && !content.includes("islandModule") && !content.includes("Island-First")) {
+      // Check if the island file actually exists on disk
+      const clientPath = path.join(rootDir, route.clientModule);
+      const clientExists = await fileExists(clientPath);
+      if (content && !clientExists && !content.includes("data-island") && !content.includes("data-mandu-island")) {
         violations.push({
           ruleId: "ISLAND_FIRST_INTEGRITY",
           file: route.componentModule,
-          message: `componentModule이 island을 import하지 않습니다 (routeId: ${route.id})`,
-          suggestion: "mandu generate를 실행하여 Island-First 템플릿으로 재생성하세요",
+          message: `No island file found for page route (routeId: ${route.id}). The clientModule '${route.clientModule}' does not exist.`,
+          suggestion:
+            "Create a .island.tsx file in the same app/ directory as page.tsx. " +
+            "The page should reference islands via data-island attributes, NOT by directly importing or re-exporting the island. " +
+            "Importing island() return values into page.tsx causes a runtime crash because they are config objects, not React components.",
         });
       }
     }
@@ -370,20 +357,17 @@ export async function runGuardCheck(
 ): Promise<GuardCheckResult> {
   const config = await loadManduConfig(rootDir);
 
-  const lockPath = path.join(rootDir, ".mandu/spec.lock.json");
   const mapPath = path.join(rootDir, ".mandu/generated/generated.map.json");
 
   // ============================================
   // Phase 1: 독립적인 검사 병렬 실행
   // ============================================
   const [
-    hashViolation,
     importViolations,
     slotViolations,
     specDirViolations,
     islandViolations,
   ] = await Promise.all([
-    checkSpecHashMismatch(manifest, lockPath),
     checkInvalidGeneratedImport(rootDir),
     checkSlotFileExists(manifest, rootDir),
     checkSpecDirNaming(rootDir),
@@ -391,7 +375,6 @@ export async function runGuardCheck(
   ]);
 
   const violations: GuardViolation[] = [];
-  if (hashViolation) violations.push(hashViolation);
   violations.push(...importViolations);
   violations.push(...slotViolations);
   violations.push(...specDirViolations);