@mandujs/core 0.22.0 → 0.23.0

package/src/perf/hmr-markers.ts

@@ -175,6 +175,18 @@ export const HMR_PERF = {
    *  prewarm before the user hits a file save. */
   JIT_PREWARM: "boot:jit-prewarm",
 
+  /** Phase 11 C — Deep-path JIT prewarm extension. Phase 7.3 A closed the
+   *  first-iter gap from 41 ms to 25 ms by prewarming the React hot set;
+   *  R0.3 diagnostics traced the remaining ~15 ms to the
+   *  `registerManifestHandlers` deep-path (cli `util/handlers` +
+   *  `util/bun` bundledImport + `@mandujs/core/bundler/safe-build`
+   *  internals) which only execute on the FIRST SSR reload. This marker
+   *  measures the settling time of the deep-import Promise — still
+   *  fire-and-forget, still NOT on the critical path, so values are
+   *  informational only. Target: first-iter ≤ 15 ms (hard) / ≤ 20 ms
+   *  (soft). See `packages/cli/src/util/jit-prewarm.ts`. */
+  JIT_PREWARM_DEEP: "boot:jit-prewarm-deep",
+
   /** API route handler reload (`handleAPIChange`) — `.route.ts` /
    *  `.route.tsx` change. Symmetric to `SSR_HANDLER_RELOAD` for page /
    *  layout reloads. Phase 7.2 §7.4 flagged that `handleAPIChange` was

package/src/runtime/server.ts

@@ -449,6 +449,13 @@ export interface ServerRegistrySettings {
   cacheStore?: CacheStore;
   /** Internal management token for local runtime control */
   managementToken?: string;
+  /**
+   * Edge runtime flag — disables filesystem-dependent features (static file
+   * serving, Kitchen dashboard, image optimization, SSG fallback loaders).
+   * Set by `@mandujs/edge` adapters (Cloudflare Workers, Deno Deploy, Vercel Edge).
+   * Default: false (Bun/Node runtime with full FS access).
+   */
+  edge?: boolean;
 }
 
 export class ServerRegistry {
@@ -2408,18 +2415,23 @@ async function handleRequestInternal(
   }
 
   // 1. 정적 파일 서빙 시도 (최우선)
-  const staticFileResult = await serveStaticFile(pathname, settings, req);
-  if (staticFileResult.handled) {
-    const staticResponse = staticFileResult.response!;
-    if (settings.cors && isCorsRequest(req)) {
-      const corsOptions: CorsOptions = typeof settings.cors === 'object' ? settings.cors : {};
-      return ok(applyCorsToResponse(staticResponse, req, corsOptions));
+  // Edge runtimes (Cloudflare Workers, etc.) have no filesystem — skip and
+  // let the platform's asset pipeline (Wrangler [assets], Vercel _static, …)
+  // handle static routing instead.
+  if (!settings.edge) {
+    const staticFileResult = await serveStaticFile(pathname, settings, req);
+    if (staticFileResult.handled) {
+      const staticResponse = staticFileResult.response!;
+      if (settings.cors && isCorsRequest(req)) {
+        const corsOptions: CorsOptions = typeof settings.cors === 'object' ? settings.cors : {};
+        return ok(applyCorsToResponse(staticResponse, req, corsOptions));
+      }
+      return ok(staticResponse);
     }
-    return ok(staticResponse);
   }
 
   // 1.5. Image optimization handler (/_mandu/image)
-  if (pathname === "/_mandu/image") {
+  if (!settings.edge && pathname === "/_mandu/image") {
     const imageResponse = await handleImageRequest(req, settings.rootDir, settings.publicDir);
     if (imageResponse) return ok(imageResponse);
   }
@@ -2769,6 +2781,119 @@ export const pageLoaders = defaultRegistry.pageLoaders;
 export const pageHandlers = defaultRegistry.pageHandlers;
 export const routeComponents = defaultRegistry.routeComponents;
 
+// ========== Runtime-Neutral Fetch Handler Factory ==========
+
+/**
+ * Options for {@link createAppFetchHandler}. Subset of {@link ServerOptions}
+ * that makes sense in edge/serverless runtimes — no listen/port/hmr fields.
+ */
+export interface AppFetchHandlerOptions {
+  /** Project root (used for module path validation). Required. */
+  rootDir: string;
+  /** Bundle manifest (Island hydration). Optional in pure-SSR apps. */
+  bundleManifest?: BundleManifest;
+  /** CORS config — `true` allows all origins, object for fine-grained rules. */
+  cors?: boolean | CorsOptions;
+  /** Streaming SSR toggle. Default: `false`. */
+  streaming?: boolean;
+  /** Rate limit policy. Memory-backed; edge runtimes should prefer durable stores. */
+  rateLimit?: boolean | RateLimitOptions;
+  /**
+   * CSS link injection target for SSR. Typically `"/.mandu/client/globals.css"`
+   * when Tailwind is in use. `false` disables injection.
+   */
+  cssPath?: string | false;
+  /** Custom registry override (defaults to the global registry). */
+  registry?: ServerRegistry;
+  /**
+   * Mark this handler as edge-hosted. Skips filesystem-dependent features
+   * (static file serving, Kitchen dashboard, image optimization). Set to
+   * `true` by `@mandujs/edge` adapters.
+   */
+  edge?: boolean;
+  /**
+   * Optional global middleware function. When omitted, the handler does not
+   * attempt to auto-load `middleware.ts` from disk (important for edge
+   * bundles where FS is unavailable). Adapters should pass pre-compiled
+   * middleware at build time.
+   */
+  middleware?: {
+    fn: MiddlewareFn;
+    config?: MiddlewareConfig | null;
+  };
+}
+
+/**
+ * Build a runtime-neutral `fetch(req) → Promise<Response>` handler from a
+ * routes manifest. Reuses the same request pipeline as `startServer()`
+ * (CORS, middleware, router, SSR, API handlers) but without binding to
+ * `Bun.serve`. Suitable for Cloudflare Workers, Deno Deploy, Vercel Edge,
+ * Netlify Edge, and any other Web-Fetch host.
+ *
+ * Handler registration (`registerApiHandler`, `registerPageHandler`, …) must
+ * happen *before* calling this factory — same contract as `startServer`.
+ *
+ * @example
+ * ```ts
+ * // Cloudflare Workers entry
+ * import { createAppFetchHandler } from "@mandujs/core";
+ * import manifest from "./.mandu/routes.manifest.json";
+ * import "./.mandu/edge-workers/register.js"; // populates registries
+ *
+ * const fetch = createAppFetchHandler(manifest, {
+ *   rootDir: "/",
+ *   edge: true,
+ *   cssPath: false,
+ * });
+ *
+ * export default { fetch };
+ * ```
+ */
+export function createAppFetchHandler(
+  manifest: RoutesManifest,
+  options: AppFetchHandlerOptions
+): (req: Request) => Promise<Response> {
+  const {
+    rootDir,
+    bundleManifest,
+    cors = false,
+    streaming = false,
+    rateLimit = false,
+    cssPath = false,
+    registry = defaultRegistry,
+    edge = false,
+    middleware,
+  } = options;
+
+  const corsOptions: CorsOptions | false = cors === true ? {} : cors;
+  const rateLimitOptions = normalizeRateLimitOptions(rateLimit);
+
+  registry.settings = {
+    isDev: false,
+    bundleManifest,
+    rootDir,
+    publicDir: "public",
+    cors: corsOptions,
+    streaming,
+    rateLimit: rateLimitOptions,
+    cssPath,
+    edge,
+  };
+
+  registry.rateLimiter = rateLimitOptions ? new MemoryRateLimiter() : null;
+
+  const router = new Router(manifest.routes);
+
+  return createFetchHandler({
+    router,
+    registry,
+    corsOptions,
+    middlewareFn: middleware?.fn ?? null,
+    middlewareConfig: middleware?.config ?? null,
+    handleRequest,
+  });
+}
+
 // ========== Rate Limiting Public API ==========
 
 /**

package/src/testing/db.ts

@@ -0,0 +1,157 @@
+/**
+ * @mandujs/core/testing/db
+ *
+ * In-memory / file-backed SQLite fixture for integration tests.
+ *
+ * Wraps `@mandujs/core/db` so callers do not have to learn Bun.SQL's URL
+ * conventions just to stand up a throwaway database. The default is
+ * `sqlite::memory:` — fully isolated, survives exactly one test, zero
+ * filesystem footprint.
+ *
+ * ```ts
+ * import { createTestDb } from "@mandujs/core/testing";
+ *
+ * const db = await createTestDb({
+ *   schema: `
+ *     CREATE TABLE users (id TEXT PRIMARY KEY, email TEXT NOT NULL);
+ *     CREATE INDEX users_email ON users(email);
+ *   `,
+ * });
+ * afterEach(async () => await db.close());
+ *
+ * await db.db`INSERT INTO users (id, email) VALUES (${"u1"}, ${"a@b.c"})`;
+ * const rows = await db.db<{ id: string; email: string }>`SELECT * FROM users`;
+ * expect(rows).toHaveLength(1);
+ * ```
+ *
+ * ## Design
+ *
+ * - **Isolation first**: each call to `createTestDb()` returns a fresh
+ *   `Db` handle. SQLite in-memory dbs are scoped to the connection, so
+ *   there is no cross-fixture leakage.
+ * - **DDL delivered as plain SQL**: callers pass schema as a string (or an
+ *   array of statements). No dependency on the resource migration runner —
+ *   that's a Phase 12.3 concern.
+ * - **Transaction helper**: `transaction(fn)` is just a re-export of the
+ *   underlying `Db.transaction` — convenient to avoid threading `db.db.*`.
+ * - **Async-dispose**: `using db = await createTestDb(...)` works via
+ *   `Symbol.asyncDispose` (ES2023 Explicit Resource Management). Pair with
+ *   Bun.test's per-test cleanup for maximum terseness.
+ *
+ * ## SQLite caveats
+ *
+ * Bun.SQL's SQLite adapter requires non-null columns to be typed.
+ * Tests that want rich schemas should use `TEXT`, `INTEGER`, `REAL`,
+ * `BLOB`. Higher-level typed schemas come with the Phase 12.3 resource
+ * migration fixture.
+ *
+ * @module testing/db
+ */
+
+import { createDb, type Db } from "../db/index";
+
+/** Options for {@link createTestDb}. */
+export interface CreateTestDbOptions {
+  /**
+   * Connection URL. Default: `"sqlite::memory:"`.
+   *
+   * Any `sqlite:` URL is accepted — `sqlite:./fixture.db` for a file-backed
+   * fixture that survives across fixture instances, for example. Non-sqlite
+   * providers are accepted but not recommended for unit tests (you lose
+   * isolation across fixtures).
+   */
+  url?: string;
+  /**
+   * DDL to apply on open. Accepts a multi-statement SQL string or an array
+   * of pre-split statements. Statements are run sequentially — if any
+   * fails, subsequent ones are skipped and the error re-throws.
+   */
+  schema?: string | string[];
+  /** Optional seed block to run after `schema` — convenient for row-level setup. */
+  seed?: (db: Db) => Promise<void> | void;
+}
+
+/** Handle returned by {@link createTestDb}. */
+export interface TestDb {
+  /** The underlying Db handle — use as a tagged-template query function. */
+  readonly db: Db;
+  /** Re-export of `db.transaction`. */
+  transaction: Db["transaction"];
+  /**
+   * Apply additional DDL after the fixture has been created. Useful when the
+   * schema depends on per-test parameters (e.g., random suffixes to avoid
+   * SQLite's reserved-words).
+   */
+  apply(ddl: string | string[]): Promise<void>;
+  /** Idempotent cleanup — safe to call multiple times. */
+  close(): Promise<void>;
+  /** `using db = await createTestDb(...)` support. */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/** Split a multi-statement SQL string into individual statements. */
+function splitSql(source: string): string[] {
+  // Naïve splitter: works for vanilla DDL without embedded `;` inside quoted
+  // strings — the realistic shape of test fixtures. A full lexer lives in
+  // `db/migrations/runner.ts`; we intentionally do not re-use it here to
+  // avoid coupling the testing fixture to migration-runner internals.
+  return source
+    .split(";")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+async function applyDdl(db: Db, ddl: string | string[]): Promise<void> {
+  const statements = Array.isArray(ddl) ? ddl : splitSql(ddl);
+  for (const stmt of statements) {
+    // Bun.SQL's tagged-template form does not support raw DDL composition —
+    // but a 1-argument template with no placeholders is safe. The value
+    // inside `strings.raw[0]` is the literal SQL, never an interpolated value.
+    const raw = stmt.trim();
+    if (raw.length === 0) continue;
+    const strings = Object.assign([raw], { raw: [raw] }) as TemplateStringsArray;
+    await db(strings);
+  }
+}
+
+/**
+ * Boot a fixture-scoped database handle.
+ *
+ * The default URL (`sqlite::memory:`) creates a per-connection in-memory
+ * database — ideal for per-test isolation.
+ *
+ * @throws if `url` is non-empty but Bun.SQL rejects it on the first query.
+ *   Validation is lazy — construction never throws on unreachable targets.
+ */
+export async function createTestDb(
+  options: CreateTestDbOptions = {},
+): Promise<TestDb> {
+  const url = options.url ?? "sqlite::memory:";
+  const db = createDb({ url });
+
+  if (options.schema !== undefined) {
+    await applyDdl(db, options.schema);
+  }
+  if (options.seed) {
+    await options.seed(db);
+  }
+
+  let closed = false;
+  const close = async (): Promise<void> => {
+    if (closed) return;
+    closed = true;
+    await db.close();
+  };
+
+  return {
+    db,
+    transaction: db.transaction.bind(db),
+    async apply(ddl) {
+      await applyDdl(db, ddl);
+    },
+    close,
+    async [Symbol.asyncDispose]() {
+      await close();
+    },
+  };
+}

package/src/testing/index.ts

@@ -1,6 +1,21 @@
 /**
  * Mandu Testing Utilities
- * 서버 없이 라우트/filling 단위 테스트
+ *
+ * The `@mandujs/core/testing` barrel. Everything a test file needs:
+ *
+ * - Filling-level stubs (`testFilling`, `createTestRequest`, `createTestContext`)
+ * - Manifest / island factories (`createTestManifest`, `createTestIsland`)
+ * - MCP fixtures (`createMockMcpContext`)
+ * - **Phase 12.1** HTTP/session/db/mock fixtures:
+ *   - `createTestServer` — ephemeral-port in-process Bun.serve
+ *   - `createTestSession` — pre-signed session cookie (no login roundtrip)
+ *   - `createTestDb` — in-memory SQLite fixture
+ *   - `mockMail`, `mockStorage` — dependency-injectable I/O mocks
+ *
+ * All fixtures produced by this module support idempotent `close()`/`clear()`
+ * and, where applicable, `Symbol.asyncDispose` / `Symbol.dispose` for the
+ * ES2023 `using` syntax. Prefer those over hand-rolled afterEach chains —
+ * they stay correct even when a test throws mid-setup.
  */
 
 import path from "path";
@@ -245,3 +260,46 @@ export function createMockMcpContext(options: {
     readManifest: async () => manifest,
   };
 }
+
+// ========== Phase 12.1 — Integration fixtures ==========
+
+export {
+  createTestServer,
+  type CreateTestServerOptions,
+  type TestServer,
+} from "./server";
+
+export {
+  createTestSession,
+  readSession,
+  extractCookieValuePair,
+  type CreateTestSessionOptions,
+  type TestSession,
+} from "./session";
+
+export {
+  createTestDb,
+  type CreateTestDbOptions,
+  type TestDb,
+} from "./db";
+
+export {
+  mockMail,
+  mockStorage,
+  type MockMail,
+  type MockStorage,
+  type MockStoredObject,
+} from "./mocks";
+
+// ========== Phase 12.3 — Snapshot assertions ==========
+
+export {
+  matchSnapshot,
+  toMatchSnapshot,
+  stableStringify,
+  scrubVolatile,
+  deriveSnapshotPath,
+  isUpdateMode,
+  type SnapshotOptions,
+  type SnapshotResult,
+} from "./snapshot";

package/src/testing/mocks.ts

@@ -0,0 +1,203 @@
+/**
+ * @mandujs/core/testing/mocks
+ *
+ * Swap-in mocks for the I/O primitives tests typically stub:
+ *
+ * - `mockMail()` → the production `MemoryEmailSender` (Phase 5 email
+ *   primitive), wrapped so tests get a uniform async-dispose cleanup helper.
+ * - `mockStorage()` → an in-memory `S3Client`-shaped handle satisfying the
+ *   public `@mandujs/core/storage/s3` interface without booting `Bun.S3Client`.
+ *
+ * Both return objects that are **drop-in replacements** for their production
+ * counterparts. Pass them to the handler/service under test via whatever
+ * dependency-injection path your code already uses — there is no magic here.
+ *
+ * ```ts
+ * import { mockMail, mockStorage } from "@mandujs/core/testing";
+ *
+ * const mail = mockMail();
+ * const storage = mockStorage();
+ *
+ * await sendWelcomeEmail({ mail }, "u@x.com");
+ * expect(mail.sent[0].subject).toBe("Welcome");
+ *
+ * await uploadAvatar({ storage }, buffer);
+ * expect(await storage.exists("u/avatar.png")).toBe(true);
+ * ```
+ *
+ * @module testing/mocks
+ */
+
+import {
+  createMemoryEmailSender,
+  type EmailMessage,
+  type MemoryEmailSender,
+} from "../email/index";
+import { getContentType, type S3Client, type S3UploadOptions, type S3PresignOptions } from "../storage/s3/index";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Email mock
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Handle returned by {@link mockMail}. Extends the production sender 1:1. */
+export interface MockMail extends MemoryEmailSender {
+  /**
+   * Find the most recently sent message whose recipient matches `to`
+   * (single-address equality). Returns `undefined` if none matched.
+   *
+   * Convenience shortcut around a reverse scan of `sent` — the common
+   * assertion in verification / password-reset tests.
+   */
+  lastTo(to: string): (EmailMessage & { id: string; sentAt: number }) | undefined;
+  /** `using mail = mockMail()` — clears the outbox on exit. */
+  [Symbol.dispose](): void;
+}
+
+/**
+ * Create an in-process email sender. Backing store is a plain array —
+ * read via `mail.sent`, clear between cases with `mail.clear()`.
+ *
+ * This is a thin wrapper around the production `createMemoryEmailSender`
+ * so tests do not depend on an implementation detail of the email package.
+ */
+export function mockMail(): MockMail {
+  const inner = createMemoryEmailSender();
+
+  // MemoryEmailSender's `sent` is declared readonly at the type level; the
+  // runtime object exposes .push under the covers. We add the convenience
+  // helper without widening the surface.
+  //
+  // Reverse-iterating by index (vs. `.findLast`) avoids dependency on the
+  // ES2023 `Array.prototype.findLast` lib type — older tsconfig targets
+  // (`"lib": ["ES2022"]`) do not declare it. The runtime has it regardless.
+  return Object.assign(inner, {
+    lastTo(
+      to: string,
+    ): (EmailMessage & { id: string; sentAt: number }) | undefined {
+      for (let i = inner.sent.length - 1; i >= 0; i--) {
+        const m = inner.sent[i];
+        if (Array.isArray(m.to)) {
+          if (m.to.includes(to)) return m;
+        } else if (m.to === to) {
+          return m;
+        }
+      }
+      return undefined;
+    },
+    [Symbol.dispose]() {
+      inner.clear();
+    },
+  }) as MockMail;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Storage (S3-compatible) mock
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Stored blob + metadata for assertions. */
+export interface MockStoredObject {
+  readonly body: Uint8Array;
+  readonly contentType: string;
+  readonly acl?: "private" | "public-read";
+}
+
+/** Handle returned by {@link mockStorage}. Extends `S3Client` with test-only affordances. */
+export interface MockStorage extends S3Client {
+  /** Every key currently present. */
+  keys(): string[];
+  /** Raw access to a stored object. Returns `undefined` for missing keys. */
+  peek(key: string): MockStoredObject | undefined;
+  /** Wipe all stored objects. */
+  clear(): void;
+  /** `using s = mockStorage()` — clears the store on exit. */
+  [Symbol.dispose](): void;
+}
+
+/**
+ * Convert the production `S3Client` body types into a normalized Uint8Array
+ * so `peek()` returns a stable type regardless of what callers uploaded.
+ */
+function normalizeBody(body: Blob | ArrayBuffer | Uint8Array): Promise<Uint8Array> {
+  if (body instanceof Uint8Array) return Promise.resolve(new Uint8Array(body));
+  if (body instanceof ArrayBuffer) return Promise.resolve(new Uint8Array(body));
+  // Blob → ArrayBuffer → Uint8Array.
+  return body.arrayBuffer().then((ab) => new Uint8Array(ab));
+}
+
+/**
+ * Create an in-memory S3-compatible storage client. Satisfies the full
+ * `S3Client` interface — handlers written against the production API can
+ * be called with this mock unchanged.
+ *
+ * Presigned URLs are synthesized as opaque `mandu-mock://bucket/<key>`
+ * strings. They are not de-serializable back into real uploads — only used
+ * for identity assertions (presign returned? key matches?).
+ */
+export function mockStorage(options?: { bucket?: string }): MockStorage {
+  const bucket = options?.bucket ?? "mandu-test-bucket";
+  const store = new Map<string, MockStoredObject>();
+
+  async function upload(
+    body: Blob | ArrayBuffer | Uint8Array,
+    opts: S3UploadOptions,
+  ): Promise<string> {
+    if (!opts.key) {
+      throw new TypeError(
+        "[testing/mocks] mockStorage.upload: 'key' is required.",
+      );
+    }
+    const contentType = opts.contentType ?? getContentType(opts.key);
+    const bytes = await normalizeBody(body);
+    store.set(opts.key, { body: bytes, contentType, acl: opts.acl });
+    return `mandu-mock://${bucket}/${opts.key}`;
+  }
+
+  async function presign(opts: S3PresignOptions): Promise<string> {
+    if (!opts.key) {
+      throw new TypeError(
+        "[testing/mocks] mockStorage.presign: 'key' is required.",
+      );
+    }
+    const method = opts.method ?? "PUT";
+    const expiresIn = opts.expiresIn ?? 900;
+    return `mandu-mock://${bucket}/${opts.key}?method=${method}&expires=${expiresIn}`;
+  }
+
+  async function deleteObject(key: string): Promise<void> {
+    store.delete(key);
+  }
+
+  async function getReadable(key: string): Promise<ReadableStream> {
+    const obj = store.get(key);
+    if (!obj) {
+      throw new Error(
+        `[testing/mocks] mockStorage.getReadable: key not found: ${JSON.stringify(key)}`,
+      );
+    }
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(obj.body);
+        controller.close();
+      },
+    });
+  }
+
+  async function exists(key: string): Promise<boolean> {
+    return store.has(key);
+  }
+
+  const handle: MockStorage = {
+    upload,
+    presign,
+    delete: deleteObject,
+    getReadable,
+    exists,
+    keys: () => [...store.keys()],
+    peek: (key) => store.get(key),
+    clear: () => store.clear(),
+    [Symbol.dispose]() {
+      store.clear();
+    },
+  };
+  return handle;
+}