@mandujs/core 0.18.22 → 0.19.2

package/src/bundler/dev.ts

@@ -206,7 +206,13 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       if (pendingBuildFile) {
         const next = pendingBuildFile;
         pendingBuildFile = null;
-        await handleFileChange(next);
+        // Catch errors to prevent unhandled promise rejection from killing the watcher (#10)
+        try {
+          await handleFileChange(next);
+        } catch (retryError) {
+          console.error(`❌ Retry build error:`, retryError instanceof Error ? retryError.message : String(retryError));
+          console.log(`   ⏳ Waiting for next file change to retry...`);
+        }
       }
     }
   };
@@ -247,6 +253,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
         console.error(`❌ Build error:`, err.message);
+        console.log(`   ⏳ Waiting for next file change to retry...`);
         onError?.(err, "*");
       }
       return;
@@ -303,6 +310,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
         });
       } else {
         console.error(`❌ Build failed:`, result.errors);
+        console.log(`   ⏳ Previous bundle preserved. Waiting for next file change to retry...`);
         onRebuild?.({
           routeId,
           success: false,
@@ -313,6 +321,7 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
       console.error(`❌ Build error:`, err.message);
+      console.log(`   ⏳ Previous bundle preserved. Waiting for next file change to retry...`);
       onError?.(err, routeId);
     }
   };
@@ -380,7 +389,17 @@ export interface HMRServer {
 }
 
 export interface HMRMessage {
-  type: "connected" | "reload" | "island-update" | "layout-update" | "css-update" | "error" | "ping" | "guard-violation";
+  type:
+    | "connected"
+    | "reload"
+    | "island-update"
+    | "layout-update"
+    | "css-update"
+    | "error"
+    | "ping"
+    | "guard-violation"
+    | "kitchen:file-change"
+    | "kitchen:guard-decision";
   data?: {
     routeId?: string;
     layoutPath?: string;
@@ -389,6 +408,9 @@ export interface HMRMessage {
     timestamp?: number;
     file?: string;
     violations?: Array<{ line: number; message: string }>;
+    changeType?: "add" | "change" | "delete";
+    action?: "approve" | "reject";
+    ruleId?: string;
   };
 }
 
@@ -627,6 +649,37 @@ export function generateHMRClientScript(port: number): string {
         showErrorOverlay(message.data?.message);
         break;
 
+      case 'guard-violation':
+        console.warn('[Mandu HMR] Guard violation:', message.data?.file);
+        if (window.__MANDU_DEVTOOLS_HOOK__) {
+          window.__MANDU_DEVTOOLS_HOOK__.emit({
+            type: 'guard:violation',
+            timestamp: Date.now(),
+            data: message.data
+          });
+        }
+        break;
+
+      case 'kitchen:file-change':
+        if (window.__MANDU_DEVTOOLS_HOOK__) {
+          window.__MANDU_DEVTOOLS_HOOK__.emit({
+            type: 'kitchen:file-change',
+            timestamp: Date.now(),
+            data: message.data
+          });
+        }
+        break;
+
+      case 'kitchen:guard-decision':
+        if (window.__MANDU_DEVTOOLS_HOOK__) {
+          window.__MANDU_DEVTOOLS_HOOK__.emit({
+            type: 'kitchen:guard-decision',
+            timestamp: Date.now(),
+            data: message.data
+          });
+        }
+        break;
+
       case 'pong':
         // 연결 확인
         break;

package/src/bundler/prerender.ts

@@ -0,0 +1,195 @@
+/**
+ * Mandu Prerender Engine
+ * 빌드 타임에 정적 HTML 생성 (SSG)
+ */
+
+import path from "path";
+import fs from "fs/promises";
+import type { RoutesManifest } from "../spec/schema";
+
+// ========== Types ==========
+
+export interface PrerenderOptions {
+  /** 프로젝트 루트 */
+  rootDir: string;
+  /** 출력 디렉토리 (기본: ".mandu/static") */
+  outDir?: string;
+  /** 프리렌더할 추가 경로 목록 */
+  routes?: string[];
+  /** 링크 크롤링으로 자동 발견 (기본: false) */
+  crawl?: boolean;
+}
+
+export interface PrerenderResult {
+  /** 생성된 페이지 수 */
+  generated: number;
+  /** 생성된 경로별 정보 */
+  pages: PrerenderPageResult[];
+  /** 에러 목록 */
+  errors: string[];
+}
+
+export interface PrerenderPageResult {
+  path: string;
+  size: number;
+  duration: number;
+}
+
+// ========== Implementation ==========
+
+/**
+ * 정적 라우트를 HTML로 프리렌더링
+ *
+ * @example
+ * ```typescript
+ * const result = await prerenderRoutes(manifest, fetchHandler, {
+ *   rootDir: process.cwd(),
+ *   routes: ["/about", "/blog/hello-world"],
+ * });
+ * ```
+ */
+export async function prerenderRoutes(
+  manifest: RoutesManifest,
+  fetchHandler: (req: Request) => Promise<Response>,
+  options: PrerenderOptions
+): Promise<PrerenderResult> {
+  const { rootDir, outDir = ".mandu/static", crawl = false } = options;
+  const outputDir = path.isAbsolute(outDir) ? outDir : path.join(rootDir, outDir);
+
+  await fs.mkdir(outputDir, { recursive: true });
+
+  const pages: PrerenderPageResult[] = [];
+  const errors: string[] = [];
+  const renderedPaths = new Set<string>();
+
+  // 1. 명시적으로 지정된 경로 수집
+  const pathsToRender = new Set<string>(options.routes ?? []);
+
+  // 2. 매니페스트에서 정적 페이지 라우트 수집 (동적 파라미터 없는 것)
+  for (const route of manifest.routes) {
+    if (route.kind === "page" && !route.pattern.includes(":")) {
+      pathsToRender.add(route.pattern);
+    }
+  }
+
+  // 3. 동적 라우트의 generateStaticParams 수집
+  for (const route of manifest.routes) {
+    if (route.kind === "page" && route.pattern.includes(":")) {
+      try {
+        const modulePath = path.join(rootDir, route.module).replace(/\\/g, "/");
+        const mod = await import(modulePath);
+        if (typeof mod.generateStaticParams === "function") {
+          const paramSets = await mod.generateStaticParams();
+          if (Array.isArray(paramSets)) {
+            for (const params of paramSets) {
+              const resolvedPath = resolvePattern(route.pattern, params);
+              pathsToRender.add(resolvedPath);
+            }
+          } else if (paramSets) {
+            console.warn(`[Mandu Prerender] generateStaticParams() for ${route.pattern} returned non-array. Expected an array of param objects.`);
+          }
+        }
+      } catch {
+        // generateStaticParams 없으면 스킵
+      }
+    }
+  }
+
+  // 4. 각 경로를 렌더링
+  for (const pathname of pathsToRender) {
+    if (renderedPaths.has(pathname)) continue;
+    renderedPaths.add(pathname);
+
+    const start = Date.now();
+    try {
+      const request = new Request(`http://localhost${pathname}`);
+      const response = await fetchHandler(request);
+
+      if (!response.ok) {
+        errors.push(`[${pathname}] HTTP ${response.status}`);
+        continue;
+      }
+
+      const html = await response.text();
+      const filePath = getOutputPath(outputDir, pathname);
+
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.writeFile(filePath, html, "utf-8");
+
+      const duration = Date.now() - start;
+      pages.push({ path: pathname, size: html.length, duration });
+
+      // 5. 크롤링: 생성된 HTML에서 내부 링크 추출
+      if (crawl) {
+        const links = extractInternalLinks(html, pathname);
+        for (const link of links) {
+          if (!renderedPaths.has(link) && !pathsToRender.has(link)) {
+            pathsToRender.add(link);
+          }
+        }
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      errors.push(`[${pathname}] ${message}`);
+    }
+  }
+
+  return { generated: pages.length, pages, errors };
+}
+
+// ========== Helpers ==========
+
+/**
+ * 라우트 패턴에 파라미터를 대입하여 실제 경로 생성
+ */
+function resolvePattern(pattern: string, params: Record<string, string>): string {
+  let result = pattern;
+  for (const [key, value] of Object.entries(params)) {
+    // catch-all (:param*) / optional catch-all (:param*?) 지원
+    const paramRegex = new RegExp(`:${key}\\*\\??`);
+    if (paramRegex.test(result)) {
+      // catch-all: 각 세그먼트를 개별 인코딩 (슬래시 보존)
+      const encoded = value.split("/").map(encodeURIComponent).join("/");
+      result = result.replace(paramRegex, encoded);
+    } else {
+      result = result.replace(`:${key}`, encodeURIComponent(value));
+    }
+  }
+  return result;
+}
+
+/**
+ * 출력 파일 경로 생성
+ * /about → .mandu/static/about/index.html
+ * / → .mandu/static/index.html
+ */
+function getOutputPath(outDir: string, pathname: string): string {
+  const trimmed = pathname === "/" ? "/" : pathname.replace(/\/+$/, "");
+  if (trimmed === "/") return path.join(outDir, "index.html");
+  // /blog/post → .mandu/static/blog/post/index.html (clean URL)
+  return path.join(outDir, trimmed, "index.html");
+}
+
+/**
+ * HTML에서 내부 링크 추출 (크롤링용)
+ */
+function extractInternalLinks(html: string, currentPath: string): string[] {
+  const links: string[] = [];
+  const hrefRegex = /href=["']([^"']+)["']/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = hrefRegex.exec(html)) !== null) {
+    const href = match[1];
+    // 내부 링크만 (절대 경로이면서 프로토콜 없는 것)
+    if (href.startsWith("/") && !href.startsWith("//")) {
+      // 쿼리스트링/해시 제거
+      const cleanPath = href.split("?")[0].split("#")[0];
+      // 정적 파일 제외
+      if (!cleanPath.match(/\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$/)) {
+        links.push(cleanPath);
+      }
+    }
+  }
+
+  return [...new Set(links)];
+}

package/src/change/snapshot.ts

@@ -1,7 +1,6 @@
 import path from "path";
 import type { Snapshot, RestoreResult, ConfigSnapshot } from "./types";
 import type { RoutesManifest } from "../spec/schema";
-import type { SpecLock } from "../spec/lock";
 import {
   readLockfile,
   writeLockfile,
@@ -14,7 +13,6 @@ import { validateAndReport } from "../config";
 const MANDU_DIR = ".mandu";
 const SPEC_DIR = "spec";
 const MANIFEST_FILE = "routes.manifest.json";
-const LOCK_FILE = "spec.lock.json";
 const SLOTS_DIR = "slots";
 const HISTORY_DIR = "history";
 const SNAPSHOTS_DIR = "snapshots";
@@ -74,7 +72,6 @@ async function collectSlotContents(rootDir: string): Promise<Record<string, stri
 export async function createSnapshot(rootDir: string): Promise<Snapshot> {
   const manduDir = path.join(rootDir, MANDU_DIR);
   const manifestPath = path.join(manduDir, MANIFEST_FILE);
-  const lockPath = path.join(manduDir, LOCK_FILE);
 
   // Manifest 읽기 (필수)
   const manifestFile = Bun.file(manifestPath);
@@ -83,12 +80,8 @@ export async function createSnapshot(rootDir: string): Promise<Snapshot> {
   }
   const manifest: RoutesManifest = await manifestFile.json();
 
-  // Lock 읽기 (선택)
-  let lock: SpecLock | null = null;
-  const lockFile = Bun.file(lockPath);
-  if (await lockFile.exists()) {
-    lock = await lockFile.json();
-  }
+  // Lock은 FS-First 전환으로 제거됨 - 하위호환을 위해 null 유지
+  const lock = null;
 
   // Slot 내용 수집
   const slotContents = await collectSlotContents(rootDir);
@@ -171,7 +164,6 @@ export async function readSnapshotById(rootDir: string, snapshotId: string): Pro
 export async function restoreSnapshot(rootDir: string, snapshot: Snapshot): Promise<RestoreResult> {
   const manduDir = path.join(rootDir, MANDU_DIR);
   const manifestPath = path.join(manduDir, MANIFEST_FILE);
-  const lockPath = path.join(manduDir, LOCK_FILE);
   const slotsDir = path.join(rootDir, SPEC_DIR, SLOTS_DIR);
 
   const restoredFiles: string[] = [];
@@ -187,18 +179,7 @@ export async function restoreSnapshot(rootDir: string, snapshot: Snapshot): Prom
     errors.push(`Failed to restore manifest: ${error instanceof Error ? error.message : String(error)}`);
   }
 
-  // 2. Lock 복원 (있는 경우)
-  if (snapshot.lock) {
-    try {
-      await Bun.write(lockPath, JSON.stringify(snapshot.lock, null, 2));
-      restoredFiles.push(LOCK_FILE);
-    } catch (error) {
-      failedFiles.push(LOCK_FILE);
-      errors.push(`Failed to restore lock: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  // 3. Slot 파일들 복원
+  // 2. Slot 파일들 복원
   for (const [relativePath, content] of Object.entries(snapshot.slotContents)) {
     const filePath = path.join(slotsDir, relativePath);
     try {
@@ -216,7 +197,7 @@ export async function restoreSnapshot(rootDir: string, snapshot: Snapshot): Prom
     }
   }
 
-  // 4. Config Lockfile 복원 (있는 경우)
+  // 3. Config Lockfile 복원 (있는 경우)
   if (snapshot.configSnapshot) {
     try {
       await writeLockfile(rootDir, snapshot.configSnapshot.lockfile);

package/src/change/types.ts

@@ -1,5 +1,4 @@
 import type { RoutesManifest } from "../spec/schema";
-import type { SpecLock } from "../spec/lock";
 import type { ManduLockfile } from "../lockfile";
 
 /**
@@ -30,8 +29,8 @@ export interface Snapshot {
   timestamp: string;
   /** routes.manifest.json 내용 (~1KB) */
   manifest: RoutesManifest;
-  /** spec.lock.json 내용 (~0.1KB, 없을 수 있음) */
-  lock: SpecLock | null;
+  /** Legacy lock 데이터 (하위호환용, 새 스냅샷에서는 항상 null) */
+  lock: { routesHash: string; updatedAt: string } | null;
   /** Slot 파일 내용만 저장 (Generated 파일은 재생성 가능) */
   slotContents: Record<string, string>;
   /** 설정 스냅샷 (Lockfile 포함) - ont-run 통합 */

package/src/client/Form.tsx

@@ -0,0 +1,105 @@
+/**
+ * Mandu <Form> Component
+ * Progressive Enhancement: JS 없으면 일반 HTML form, JS 있으면 fetch 기반 제출
+ */
+
+import { useState, useCallback, useRef, type FormEvent, type ReactNode } from "react";
+import { submitAction, type ActionResult } from "./router";
+
+export interface FormState {
+  submitting: boolean;
+  error: string | null;
+}
+
+export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "action" | "children"> {
+  /** 제출 대상 URL */
+  action: string;
+  /** Action 이름 (서버의 filling.action(name)과 매칭) */
+  actionName?: string;
+  /** HTTP 메서드 */
+  method?: "post" | "put" | "patch" | "delete";
+  /** JS에서 fetch 방식으로 전환 (기본: true, false면 일반 HTML form 제출) */
+  enhance?: boolean;
+  /** Action 성공 후 콜백 */
+  onActionSuccess?: (result: ActionResult) => void;
+  /** Action 실패 후 콜백 */
+  onActionError?: (error: Error) => void;
+  /** render props 또는 일반 children */
+  children: ReactNode | ((state: FormState) => ReactNode);
+}
+
+/**
+ * Progressive Enhancement Form 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * <Form action="/api/todos" actionName="create">
+ *   <input name="title" required />
+ *   <button type="submit">추가</button>
+ * </Form>
+ *
+ * // render props로 제출 상태 접근
+ * <Form action="/api/todos" actionName="create">
+ *   {({ submitting, error }) => (
+ *     <>
+ *       <input name="title" required />
+ *       <button type="submit" disabled={submitting}>
+ *         {submitting ? "처리 중..." : "추가"}
+ *       </button>
+ *       {error && <p>{error}</p>}
+ *     </>
+ *   )}
+ * </Form>
+ * ```
+ */
+export function Form({
+  action,
+  actionName = "default",
+  method = "post",
+  enhance = true,
+  onActionSuccess,
+  onActionError,
+  children,
+  ...rest
+}: FormProps) {
+  const [state, setState] = useState<FormState>({ submitting: false, error: null });
+  const submittingRef = useRef(false);
+  const formMethod = method === "post" ? "post" : "post";
+
+  const handleSubmit = useCallback(async (e: FormEvent<HTMLFormElement>) => {
+    if (!enhance) return;
+    if (submittingRef.current) return; // 이중 제출 방지
+
+    e.preventDefault();
+    submittingRef.current = true;
+    setState({ submitting: true, error: null });
+
+    try {
+      const formData = new FormData(e.currentTarget);
+      const result = await submitAction(action, formData, actionName, method);
+
+      if (result.ok) {
+        setState({ submitting: false, error: null });
+        onActionSuccess?.(result);
+      } else {
+        const message = "요청이 실패했습니다.";
+        setState({ submitting: false, error: message });
+        onActionError?.(new Error(message));
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "요청 실패";
+      setState({ submitting: false, error: message });
+      onActionError?.(error instanceof Error ? error : new Error(message));
+    } finally {
+      submittingRef.current = false;
+    }
+  }, [action, actionName, enhance, method, onActionSuccess, onActionError]);
+
+  return (
+    <form action={action} method={formMethod} onSubmit={handleSubmit} {...rest}>
+      <input type="hidden" name="_action" value={actionName} />
+      {method !== "post" && <input type="hidden" name="_method" value={method.toUpperCase()} />}
+      {typeof children === "function" ? children(state) : children}
+    </form>
+  );
+}

package/src/client/__tests__/use-sse.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Tests for useSSE hook and readStreamWithYield utility
+ *
+ * These tests verify the microtask-starvation-safe ReadableStream reading
+ * utilities work correctly.
+ */
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+import { readStreamWithYield } from "../use-sse";
+
+// Note: useSSE is a React hook and would need a React testing environment.
+// We test the lower-level readStreamWithYield utility here since it contains
+// the core macrotask-yielding logic that prevents main thread blocking.
+
+/**
+ * Helper: create a ReadableStream from an array of strings
+ */
+function createMockStream(chunks: string[]): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  let index = 0;
+
+  return new ReadableStream({
+    pull(controller) {
+      if (index < chunks.length) {
+        controller.enqueue(encoder.encode(chunks[index++]));
+      } else {
+        controller.close();
+      }
+    },
+  });
+}
+
+describe("readStreamWithYield", () => {
+  test("should read all chunks from a stream", async () => {
+    const chunks = ["Hello", " ", "World"];
+    const stream = createMockStream(chunks);
+    const received: string[] = [];
+
+    await readStreamWithYield(stream, {
+      onChunk: (text) => received.push(text),
+      onDone: () => {},
+    });
+
+    expect(received).toEqual(chunks);
+  });
+
+  test("should call onDone when stream completes", async () => {
+    const stream = createMockStream(["a", "b"]);
+    let doneCalled = false;
+
+    await readStreamWithYield(stream, {
+      onChunk: () => {},
+      onDone: () => {
+        doneCalled = true;
+      },
+    });
+
+    expect(doneCalled).toBe(true);
+  });
+
+  test("should call onError on stream failure", async () => {
+    const stream = new ReadableStream({
+      start(controller) {
+        controller.error(new Error("test error"));
+      },
+    });
+
+    let errorCaught: Error | null = null;
+
+    await readStreamWithYield(stream, {
+      onChunk: () => {},
+      onError: (err) => {
+        errorCaught = err;
+      },
+    });
+
+    expect(errorCaught).not.toBeNull();
+    expect(errorCaught!.message).toBe("test error");
+  });
+
+  test("should respect abort signal", async () => {
+    const controller = new AbortController();
+    const chunks = ["a", "b", "c", "d", "e"];
+    const stream = createMockStream(chunks);
+    const received: string[] = [];
+
+    // Abort after first chunk
+    let chunkCount = 0;
+
+    await readStreamWithYield(stream, {
+      onChunk: (text) => {
+        received.push(text);
+        chunkCount++;
+        if (chunkCount >= 2) {
+          controller.abort();
+        }
+      },
+      signal: controller.signal,
+    });
+
+    // Should have received at most 2-3 chunks (abort may not be immediate)
+    expect(received.length).toBeLessThanOrEqual(3);
+    expect(received.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("should handle empty stream", async () => {
+    const stream = createMockStream([]);
+    const received: string[] = [];
+    let doneCalled = false;
+
+    await readStreamWithYield(stream, {
+      onChunk: (text) => received.push(text),
+      onDone: () => {
+        doneCalled = true;
+      },
+    });
+
+    expect(received).toEqual([]);
+    expect(doneCalled).toBe(true);
+  });
+
+  test("should yield between chunks (non-blocking)", async () => {
+    // Create a stream with many rapid chunks
+    const chunkCount = 50;
+    const chunks = Array.from({ length: chunkCount }, (_, i) => `chunk-${i}`);
+    const stream = createMockStream(chunks);
+    const received: string[] = [];
+
+    // Track that setTimeout(0) yields are happening by checking
+    // that the promise resolves in multiple event loop ticks
+    let macrotaskCount = 0;
+    const originalSetTimeout = globalThis.setTimeout;
+
+    // Count macrotask yields (setTimeout(0) calls from yieldToMacrotask)
+    const timeoutSpy = mock((fn: Function, ms: number) => {
+      if (ms === 0) macrotaskCount++;
+      return originalSetTimeout(fn, ms);
+    });
+    // @ts-expect-error - mock override
+    globalThis.setTimeout = timeoutSpy;
+
+    try {
+      await readStreamWithYield(stream, {
+        onChunk: (text) => received.push(text),
+      });
+
+      // Every chunk should cause a macrotask yield
+      expect(received.length).toBe(chunkCount);
+      expect(macrotaskCount).toBeGreaterThanOrEqual(chunkCount);
+    } finally {
+      globalThis.setTimeout = originalSetTimeout;
+    }
+  });
+});