@mandujs/core 0.41.2 → 0.43.0

package/src/runtime/fast-refresh-types.ts

@@ -1,128 +1,126 @@
-/**
- * Phase 7.1 — Fast Refresh shared types
- *
- * Bun 1.3.12 ships a native `Bun.build({ reactFastRefresh: true })` flag
- * that performs the `$RefreshReg$` / `$RefreshSig$` source transform
- * (equivalent to `babel-plugin-react-refresh`). Agent B's implementation
- * wires this into Mandu's bundler + a browser-side runtime that glues
- * `react-refresh/runtime` to our existing `ManduHot` dispatcher from
- * Phase 7.0.C.
- *
- * This file is the CONTRACT. Types only — the implementation lives in:
- *   - packages/core/src/bundler/fast-refresh-plugin.ts (Agent B new)
- *   - packages/core/src/runtime/fast-refresh-runtime.ts (Agent B new)
- *   - packages/core/src/bundler/build.ts (Agent B extend — vendor shim)
- *   - packages/core/src/bundler/dev.ts (Agent B extend — HTML preamble)
- *
- * References:
- *   docs/bun/phase-7-1-diagnostics/fast-refresh-strategy.md
- *   docs/bun/phase-7-1-team-plan.md §3.2
- *   https://bun.com/reference/bun/NormalBuildConfig/reactFastRefresh
- */
-
-// ============================================
-// Browser-side `__MANDU_HMR__` global
-// ============================================
-
-/**
- * The single global object Mandu's bundler-emitted boundary code talks
- * to. Installed by the HTML preamble script before any island runs.
- *
- * Keeping all Fast Refresh wiring behind this single namespace makes
- * the attack surface (Phase 7.1.E security audit) a single module.
- */
-export interface ManduHMRGlobal {
-  /**
-   * Register a module URL as an HMR boundary. Emitted by the bundler
-   * onLoad plugin (Agent B) for each `.client.tsx` / `.island.tsx`.
-   * Idempotent — registering the same URL twice is a no-op.
-   */
-  acceptFile(moduleUrl: string): void;
-
-  /**
-   * Invoke `react-refresh/runtime.performReactRefresh()` on the next
-   * microtask. Coalesces multiple calls within the same tick into a
-   * single refresh, so a batched rebuild that swaps 3 modules only
-   * re-renders the React tree once.
-   */
-  performReactRefresh(): void;
-
-  /**
-   * Whether `moduleUrl` was ever registered via `acceptFile`. Used by
-   * `dispatchReplacement` (Phase 7.0.C runtime/hmr-client.ts) to decide
-   * between "call performReactRefresh" vs "full reload fallback".
-   */
-  isBoundary(moduleUrl: string): boolean;
-
-  /**
-   * Reset state — test-only. Clears the boundary registry and React
-   * refresh runtime scheduling state. Must NOT be exposed in production
-   * bundles; tests import this via the `runtime/fast-refresh-runtime.ts`
-   * module directly.
-   */
-  _testOnly_reset(): void;
-}
-
-/**
- * Metadata the bundler attaches to each emitted boundary. Not part of
- * the runtime API — consumed only by dev-mode tooling (hmr-bench,
- * Kitchen DevTools) and by the security audit (Phase 7.1.E) to verify
- * that every injected boundary traces back to a real source file.
- */
-export interface RefreshBoundaryMetadata {
-  /** URL the module is served under (e.g. `/.mandu/client/home.island.js`). */
-  moduleUrl: string;
-  /** Source files that were bundled into this module, from Bun.build's
-   *  inline sourcemap `sources[]` (same mechanism Phase 7.0.B uses). */
-  sources: readonly string[];
-  /** Unix ms when the boundary was registered — for debug log ordering. */
-  registeredAt: number;
-}
-
-// ============================================
-// Bundler side
-// ============================================
-
-/**
- * Options passed to the Fast Refresh Bun.build plugin (Agent B new file
- * `bundler/fast-refresh-plugin.ts`). All optional — sensible defaults
- * match Vite's `@vitejs/plugin-react` behavior.
- */
-export interface FastRefreshPluginOptions {
-  /** Only transform files matching this test. Default: `/\.(client|island)\.tsx?$/`. */
-  include?: RegExp;
-  /** Bypass the transform entirely. Used for prod builds. Default: `false`. */
-  disabled?: boolean;
-  /**
-   * Runtime module specifier the plugin's injected import points at.
-   * Default: `"@mandujs/core/runtime/fast-refresh-runtime"`. Tests can
-   * override to a tmpdir-local stub.
-   */
-  runtimeImport?: string;
-}
-
-/**
- * Classification of why a module was (or wasn't) made a Fast Refresh
- * boundary. Used by the plugin's debug log + Agent D's E2E assertions.
- */
-export type BoundaryDecision =
-  | { accepted: true; reason: "matched-include"; source: string }
-  | { accepted: false; reason: "excluded-by-include" | "disabled" | "non-react" };
-
-// ============================================
-// Global augmentation — Window type
-// ============================================
-
-/**
- * Expose `__MANDU_HMR__` on the browser Window without polluting Node
- * typings. Users of the plugin see `window.__MANDU_HMR__.acceptFile(...)`
- * as strongly typed in TSX files.
- */
-declare global {
-  interface Window {
-    /** Phase 7.1 Fast Refresh glue. Installed by HTML preamble. */
-    __MANDU_HMR__?: ManduHMRGlobal;
-  }
-}
-
-export {}; // ensure this file is a module for `declare global`
+/**
+ * Phase 7.1 — Fast Refresh shared types
+ *
+ * Bun 1.3.12 ships a native `Bun.build({ reactFastRefresh: true })` flag
+ * that performs the `$RefreshReg$` / `$RefreshSig$` source transform
+ * (equivalent to `babel-plugin-react-refresh`). Agent B's implementation
+ * wires this into Mandu's bundler + a browser-side runtime that glues
+ * `react-refresh/runtime` to our existing `ManduHot` dispatcher from
+ * Phase 7.0.C.
+ *
+ * This file is the CONTRACT. Types only — the implementation lives in:
+ *   - packages/core/src/bundler/fast-refresh-plugin.ts (Agent B new)
+ *   - packages/core/src/runtime/fast-refresh-runtime.ts (Agent B new)
+ *   - packages/core/src/bundler/build.ts (Agent B extend — vendor shim)
+ *   - packages/core/src/bundler/dev.ts (Agent B extend — HTML preamble)
+ *
+ * References:
+ *   docs/bun/phase-7-1-diagnostics/fast-refresh-strategy.md
+ *   docs/bun/phase-7-1-team-plan.md §3.2
+ *   https://bun.com/reference/bun/NormalBuildConfig/reactFastRefresh
+ */
+
+// ============================================
+// Browser-side `__MANDU_HMR__` global
+// ============================================
+
+/**
+ * The single global object Mandu's bundler-emitted boundary code talks
+ * to. Installed by the HTML preamble script before any island runs.
+ *
+ * Keeping all Fast Refresh wiring behind this single namespace makes
+ * the attack surface (Phase 7.1.E security audit) a single module.
+ */
+export interface ManduHMRGlobal {
+  /**
+   * Register a module URL as an HMR boundary. Emitted by the bundler
+   * onLoad plugin (Agent B) for each `.client.tsx` / `.island.tsx`.
+   * Idempotent — registering the same URL twice is a no-op.
+   */
+  acceptFile(moduleUrl: string): void;
+
+  /**
+   * Invoke `react-refresh/runtime.performReactRefresh()` on the next
+   * microtask. Coalesces multiple calls within the same tick into a
+   * single refresh, so a batched rebuild that swaps 3 modules only
+   * re-renders the React tree once.
+   */
+  performReactRefresh(): void;
+
+  /**
+   * Whether `moduleUrl` was ever registered via `acceptFile`. Used by
+   * `dispatchReplacement` (Phase 7.0.C runtime/hmr-client.ts) to decide
+   * between "call performReactRefresh" vs "full reload fallback".
+   */
+  isBoundary(moduleUrl: string): boolean;
+
+  /**
+   * Reset state — test-only. Clears the boundary registry and React
+   * refresh runtime scheduling state. Must NOT be exposed in production
+   * bundles; tests import this via the `runtime/fast-refresh-runtime.ts`
+   * module directly.
+   */
+  _testOnly_reset(): void;
+}
+
+/**
+ * Metadata the bundler attaches to each emitted boundary. Not part of
+ * the runtime API — consumed only by dev-mode tooling (hmr-bench,
+ * Kitchen DevTools) and by the security audit (Phase 7.1.E) to verify
+ * that every injected boundary traces back to a real source file.
+ */
+export interface RefreshBoundaryMetadata {
+  /** URL the module is served under (e.g. `/.mandu/client/home.island.js`). */
+  moduleUrl: string;
+  /** Source files that were bundled into this module, from Bun.build's
+   *  inline sourcemap `sources[]` (same mechanism Phase 7.0.B uses). */
+  sources: readonly string[];
+  /** Unix ms when the boundary was registered — for debug log ordering. */
+  registeredAt: number;
+}
+
+// ============================================
+// Bundler side
+// ============================================
+
+/**
+ * Options passed to the Fast Refresh Bun.build plugin (Agent B new file
+ * `bundler/fast-refresh-plugin.ts`). All optional — sensible defaults
+ * match Vite's `@vitejs/plugin-react` behavior.
+ */
+export interface FastRefreshPluginOptions {
+  /** Only transform files matching this test. Default: `/\.(client|island)\.tsx?$/`. */
+  include?: RegExp;
+  /** Bypass the transform entirely. Used for prod builds. Default: `false`. */
+  disabled?: boolean;
+  /**
+   * Runtime module specifier the plugin's injected import points at.
+   * Default: `"@mandujs/core/runtime/fast-refresh-runtime"`. Tests can
+   * override to a tmpdir-local stub.
+   */
+  runtimeImport?: string;
+}
+
+/**
+ * Classification of why a module was (or wasn't) made a Fast Refresh
+ * boundary. Used by the plugin's debug log + Agent D's E2E assertions.
+ */
+export type BoundaryDecision =
+  | { accepted: true; reason: "matched-include"; source: string }
+  | { accepted: false; reason: "excluded-by-include" | "disabled" | "non-react" };
+
+// ============================================
+// Global augmentation — Window type
+// ============================================
+
+/**
+ * Expose `__MANDU_HMR__` on the browser Window without polluting Node
+ * typings. Users of the plugin see `window.__MANDU_HMR__.acceptFile(...)`
+ * as strongly typed in TSX files.
+ */
+declare global {
+  interface Window {
+    /** Phase 7.1 Fast Refresh glue. Installed by HTML preamble. */
+    __MANDU_HMR__?: ManduHMRGlobal;
+  }
+}

package/src/runtime/image-handler.ts

@@ -1,195 +1,206 @@
-/**
- * Mandu Image Handler
- * /_mandu/image?url=...&w=...&q=... 엔드포인트
- * 온디맨드 리사이즈 + WebP/AVIF 포맷 협상 + 캐시
- */
-
-import path from "path";
-
-// ========== Types ==========
-
-interface ImageOptions {
-  width: number;
-  quality: number;
-  format: "webp" | "jpeg" | "png" | "avif";
-  sourceContentType?: string;
-}
-
-interface ProcessedImageResult {
-  data: Uint8Array;
-  contentType: string;
-}
-
-// ========== Cache ==========
-
-const imageCache = new Map<string, { data: Uint8Array; contentType: string }>();
-const MAX_IMAGE_CACHE = 500;
-
-// ========== Handler ==========
-
-/**
- * 이미지 최적화 요청 처리
- * /_mandu/image?url=/photos/hero.jpg&w=800&q=80
- */
-export async function handleImageRequest(
-  request: Request,
-  rootDir: string,
-  publicDir: string = "public"
-): Promise<Response | null> {
-  const url = new URL(request.url);
-  if (url.pathname !== "/_mandu/image") return null;
-
-  const src = url.searchParams.get("url");
-  const width = Number(url.searchParams.get("w") ?? 800);
-  const quality = Number(url.searchParams.get("q") ?? 80);
-
-  if (!src || width < 1 || width > 4096 || quality < 1 || quality > 100) {
-    return new Response("Invalid image parameters", { status: 400 });
-  }
-
-  // 보안: src가 /로 시작하고 traversal/null byte 없는지 확인
-  if (!src.startsWith("/") || src.includes("..") || src.includes("\0")) {
-    return new Response("Invalid image path", { status: 400 });
-  }
-
-  // 포맷 협상 (Accept 헤더 기반)
-  const format = negotiateFormat(request);
-  const cacheKey = `${src}:${width}:${quality}:${format}`;
-
-  // 캐시 확인
-  const cached = imageCache.get(cacheKey);
-  if (cached) {
-    return new Response(cached.data as unknown as BodyInit, {
-      headers: {
-        "Content-Type": cached.contentType,
-        "Cache-Control": "public, max-age=31536000, immutable",
-        "Vary": "Accept",
-        "X-Mandu-Image-Cache": "HIT",
-      },
-    });
-  }
-
-  // 원본 파일 경로 해석 + symlink traversal 방지
-  const allowedBaseDir = path.resolve(rootDir, publicDir);
-  const filePath = path.join(allowedBaseDir, src.slice(1));
-
-  // realpath로 symlink를 해석한 후 allowedBaseDir 내부인지 검증
-  let resolvedPath: string;
-  try {
-    const realFs = require("fs") as typeof import("fs");
-    resolvedPath = realFs.realpathSync(filePath);
-    const resolvedBase = realFs.realpathSync(allowedBaseDir);
-    if (!resolvedPath.startsWith(resolvedBase + path.sep) && resolvedPath !== resolvedBase) {
-      return new Response("Forbidden", { status: 403 });
-    }
-  } catch {
-    // realpath 실패 (broken symlink, 파일 없음) → 안전하게 404 반환
-    return new Response("Image not found", { status: 404 });
-  }
-  const file = Bun.file(resolvedPath);
-
-  if (!await file.exists()) {
-    return new Response("Image not found", { status: 404 });
-  }
-
-  try {
-    const original = await file.arrayBuffer();
-    const processed = await processImage(new Uint8Array(original), {
-      width,
-      quality,
-      format,
-      sourceContentType: getMimeForExtension(src),
-    });
-
-    // 캐시 저장 (LRU)
-    if (imageCache.size >= MAX_IMAGE_CACHE) {
-      const oldest = imageCache.keys().next().value;
-      if (oldest !== undefined) imageCache.delete(oldest);
-    }
-    imageCache.set(cacheKey, {
-      data: processed.data,
-      contentType: processed.contentType,
-    });
-
-    return new Response(processed.data as unknown as BodyInit, {
-      headers: {
-        "Content-Type": processed.contentType,
-        "Cache-Control": "public, max-age=31536000, immutable",
-        "Vary": "Accept",
-      },
-    });
-  } catch (error) {
-    console.error(`[Mandu Image] Processing failed for ${src}:`, error);
-    // 원본 파일 그대로 반환 (fallback)
-    return new Response(file, {
-      headers: {
-        "Content-Type": getMimeForExtension(src),
-        "Cache-Control": "public, max-age=86400",
-      },
-    });
-  }
-}
-
-// ========== Format Negotiation ==========
-
-function negotiateFormat(request: Request): "webp" | "jpeg" | "png" | "avif" {
-  const accept = request.headers.get("Accept") ?? "";
-  if (accept.includes("image/avif")) return "avif";
-  if (accept.includes("image/webp")) return "webp";
-  return "jpeg";
-}
-
-function getMimeForExtension(src: string): string {
-  const ext = path.extname(src).toLowerCase();
-  const map: Record<string, string> = {
-    ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
-    ".png": "image/png", ".gif": "image/gif",
-    ".webp": "image/webp", ".avif": "image/avif",
-    ".svg": "image/svg+xml",
-  };
-  return map[ext] ?? "application/octet-stream";
-}
-
-// ========== Image Processing ==========
-
-/**
- * 이미지 리사이즈 + 포맷 변환
- * Bun의 내장 sharp 미지원 시 원본 반환 (graceful degradation)
- */
-async function processImage(
-  data: Uint8Array,
-  options: ImageOptions
-): Promise<ProcessedImageResult> {
-  // sharp 사용 시도 (선택적 의존성)
-  try {
-    const sharp = require("sharp") as any;
-    let pipeline = sharp(Buffer.from(data)).resize(options.width);
-
-    switch (options.format) {
-      case "webp":
-        pipeline = pipeline.webp({ quality: options.quality });
-        break;
-      case "avif":
-        pipeline = pipeline.avif({ quality: options.quality });
-        break;
-      case "jpeg":
-        pipeline = pipeline.jpeg({ quality: options.quality });
-        break;
-      case "png":
-        pipeline = pipeline.png({ quality: options.quality });
-        break;
-    }
-
-    const result = await pipeline.toBuffer();
-    return {
-      data: new Uint8Array(result),
-      contentType: `image/${options.format}`,
-    };
-  } catch {
-    // sharp 미설치 시 원본 반환
-    return {
-      data,
-      contentType: options.sourceContentType ?? "application/octet-stream",
-    };
-  }
-}
+/**
+ * Mandu Image Handler
+ * /_mandu/image?url=...&w=...&q=... 엔드포인트
+ * 온디맨드 리사이즈 + WebP/AVIF 포맷 협상 + 캐시
+ */
+
+import path from "path";
+
+// ========== Types ==========
+
+interface ImageOptions {
+  width: number;
+  quality: number;
+  format: "webp" | "jpeg" | "png" | "avif";
+  sourceContentType?: string;
+}
+
+interface ProcessedImageResult {
+  data: Uint8Array;
+  contentType: string;
+}
+
+// ========== Cache ==========
+
+const imageCache = new Map<string, { data: Uint8Array; contentType: string }>();
+const MAX_IMAGE_CACHE = 500;
+
+// ========== Handler ==========
+
+/**
+ * 이미지 최적화 요청 처리
+ * /_mandu/image?url=/photos/hero.jpg&w=800&q=80
+ */
+export async function handleImageRequest(
+  request: Request,
+  rootDir: string,
+  publicDir: string = "public"
+): Promise<Response | null> {
+  const url = new URL(request.url);
+  if (url.pathname !== "/_mandu/image") return null;
+
+  const src = url.searchParams.get("url");
+  const width = Number(url.searchParams.get("w") ?? 800);
+  const quality = Number(url.searchParams.get("q") ?? 80);
+
+  if (!src || width < 1 || width > 4096 || quality < 1 || quality > 100) {
+    return new Response("Invalid image parameters", { status: 400 });
+  }
+
+  // 보안: src가 /로 시작하고 traversal/null byte 없는지 확인
+  if (!src.startsWith("/") || src.includes("..") || src.includes("\0")) {
+    return new Response("Invalid image path", { status: 400 });
+  }
+
+  // 포맷 협상 (Accept 헤더 기반)
+  const format = negotiateFormat(request);
+  const cacheKey = `${src}:${width}:${quality}:${format}`;
+
+  // 캐시 확인
+  const cached = imageCache.get(cacheKey);
+  if (cached) {
+    return new Response(cached.data as unknown as BodyInit, {
+      headers: {
+        "Content-Type": cached.contentType,
+        "Cache-Control": "public, max-age=31536000, immutable",
+        "Vary": "Accept",
+        "X-Mandu-Image-Cache": "HIT",
+      },
+    });
+  }
+
+  // 원본 파일 경로 해석 + symlink traversal 방지
+  const allowedBaseDir = path.resolve(rootDir, publicDir);
+  const filePath = path.join(allowedBaseDir, src.slice(1));
+
+  // realpath로 symlink를 해석한 후 allowedBaseDir 내부인지 검증
+  let resolvedPath: string;
+  try {
+    const realFs = require("fs") as typeof import("fs");
+    resolvedPath = realFs.realpathSync(filePath);
+    const resolvedBase = realFs.realpathSync(allowedBaseDir);
+    if (!resolvedPath.startsWith(resolvedBase + path.sep) && resolvedPath !== resolvedBase) {
+      return new Response("Forbidden", { status: 403 });
+    }
+  } catch {
+    // realpath 실패 (broken symlink, 파일 없음) → 안전하게 404 반환
+    return new Response("Image not found", { status: 404 });
+  }
+  const file = Bun.file(resolvedPath);
+
+  if (!await file.exists()) {
+    return new Response("Image not found", { status: 404 });
+  }
+
+  try {
+    const original = await file.arrayBuffer();
+    const processed = await processImage(new Uint8Array(original), {
+      width,
+      quality,
+      format,
+      sourceContentType: getMimeForExtension(src),
+    });
+
+    // 캐시 저장 (LRU)
+    if (imageCache.size >= MAX_IMAGE_CACHE) {
+      const oldest = imageCache.keys().next().value;
+      if (oldest !== undefined) imageCache.delete(oldest);
+    }
+    imageCache.set(cacheKey, {
+      data: processed.data,
+      contentType: processed.contentType,
+    });
+
+    return new Response(processed.data as unknown as BodyInit, {
+      headers: {
+        "Content-Type": processed.contentType,
+        "Cache-Control": "public, max-age=31536000, immutable",
+        "Vary": "Accept",
+      },
+    });
+  } catch (error) {
+    console.error(`[Mandu Image] Processing failed for ${src}:`, error);
+    // 원본 파일 그대로 반환 (fallback)
+    return new Response(file, {
+      headers: {
+        "Content-Type": getMimeForExtension(src),
+        "Cache-Control": "public, max-age=86400",
+      },
+    });
+  }
+}
+
+// ========== Format Negotiation ==========
+
+function negotiateFormat(request: Request): "webp" | "jpeg" | "png" | "avif" {
+  const accept = request.headers.get("Accept") ?? "";
+  if (accept.includes("image/avif")) return "avif";
+  if (accept.includes("image/webp")) return "webp";
+  return "jpeg";
+}
+
+function getMimeForExtension(src: string): string {
+  const ext = path.extname(src).toLowerCase();
+  const map: Record<string, string> = {
+    ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+    ".png": "image/png", ".gif": "image/gif",
+    ".webp": "image/webp", ".avif": "image/avif",
+    ".svg": "image/svg+xml",
+  };
+  return map[ext] ?? "application/octet-stream";
+}
+
+// ========== Image Processing ==========
+
+/**
+ * 이미지 리사이즈 + 포맷 변환
+ * Bun의 내장 sharp 미지원 시 원본 반환 (graceful degradation)
+ */
+async function processImage(
+  data: Uint8Array,
+  options: ImageOptions
+): Promise<ProcessedImageResult> {
+  // sharp 사용 시도 (선택적 의존성)
+  try {
+    // sharp is a heavyweight optional native dep. Type it minimally to the
+    // tiny surface we actually call — `resize/webp/avif/jpeg/png/toBuffer`.
+    interface SharpPipeline {
+      resize(width: number): SharpPipeline;
+      webp(opts: { quality: number }): SharpPipeline;
+      avif(opts: { quality: number }): SharpPipeline;
+      jpeg(opts: { quality: number }): SharpPipeline;
+      png(opts: { quality: number }): SharpPipeline;
+      toBuffer(): Promise<Buffer>;
+    }
+    type SharpFn = (input: Buffer) => SharpPipeline;
+    const sharp = require("sharp") as SharpFn;
+    let pipeline = sharp(Buffer.from(data)).resize(options.width);
+
+    switch (options.format) {
+      case "webp":
+        pipeline = pipeline.webp({ quality: options.quality });
+        break;
+      case "avif":
+        pipeline = pipeline.avif({ quality: options.quality });
+        break;
+      case "jpeg":
+        pipeline = pipeline.jpeg({ quality: options.quality });
+        break;
+      case "png":
+        pipeline = pipeline.png({ quality: options.quality });
+        break;
+    }
+
+    const result = await pipeline.toBuffer();
+    return {
+      data: new Uint8Array(result),
+      contentType: `image/${options.format}`,
+    };
+  } catch {
+    // sharp 미설치 시 원본 반환
+    return {
+      data,
+      contentType: options.sourceContentType ?? "application/octet-stream",
+    };
+  }
+}