@mandujs/core 0.19.0 → 0.19.2

package/src/kitchen/stream/activity-sse.ts

@@ -0,0 +1,145 @@
+/**
+ * ActivitySSEBroadcaster - Broadcasts MCP activity events to Kitchen UI via SSE.
+ *
+ * Watches .mandu/activity.jsonl (written by MCP server process) and pushes
+ * new events to connected browser clients using Server-Sent Events.
+ *
+ * Uses 500ms throttle (AionUI pattern) to avoid overwhelming the browser.
+ */
+
+import path from "path";
+import { FileTailer } from "./file-tailer";
+
+interface SSEClient {
+  id: string;
+  controller: ReadableStreamDefaultController<Uint8Array>;
+  connectedAt: number;
+}
+
+const THROTTLE_MS = 500;
+const HEARTBEAT_MS = 30_000;
+
+export class ActivitySSEBroadcaster {
+  private clients = new Map<string, SSEClient>();
+  private tailer: FileTailer;
+  private pendingEvents: string[] = [];
+  private throttleTimer: ReturnType<typeof setTimeout> | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private started = false;
+
+  constructor(rootDir: string) {
+    const logPath = path.join(rootDir, ".mandu", "activity.jsonl");
+    this.tailer = new FileTailer(logPath, {
+      startAtEnd: true,
+      pollIntervalMs: 300,
+    });
+  }
+
+  start(): void {
+    if (this.started) return;
+    this.started = true;
+
+    this.tailer.on("line", (line: string) => {
+      this.pendingEvents.push(line);
+      this.scheduleFlush();
+    });
+    this.tailer.start();
+
+    // Heartbeat to keep connections alive and detect stale clients
+    this.heartbeatTimer = setInterval(() => {
+      this.broadcast(JSON.stringify({ type: "heartbeat", ts: new Date().toISOString() }));
+    }, HEARTBEAT_MS);
+  }
+
+  private scheduleFlush(): void {
+    if (this.throttleTimer) return;
+    this.throttleTimer = setTimeout(() => {
+      this.flush();
+      this.throttleTimer = null;
+    }, THROTTLE_MS);
+  }
+
+  private flush(): void {
+    const events = this.pendingEvents.splice(0);
+    for (const event of events) {
+      this.broadcast(event);
+    }
+  }
+
+  /** Broadcast a raw JSON string to all connected SSE clients */
+  broadcast(data: string): void {
+    const message = `data: ${data}\n\n`;
+    const encoded = new TextEncoder().encode(message);
+
+    for (const [id, client] of this.clients) {
+      try {
+        client.controller.enqueue(encoded);
+      } catch {
+        this.clients.delete(id);
+      }
+    }
+  }
+
+  /** Create an SSE Response for a new client connection */
+  createResponse(): Response {
+    const clientId = crypto.randomUUID();
+
+    const stream = new ReadableStream<Uint8Array>({
+      start: (controller) => {
+        this.clients.set(clientId, {
+          id: clientId,
+          controller,
+          connectedAt: Date.now(),
+        });
+
+        // Send connection confirmation
+        const welcome = `data: ${JSON.stringify({
+          type: "connected",
+          clientId,
+          ts: new Date().toISOString(),
+        })}\n\n`;
+        controller.enqueue(new TextEncoder().encode(welcome));
+      },
+      cancel: () => {
+        this.clients.delete(clientId);
+      },
+    });
+
+    return new Response(stream, {
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+        "X-Kitchen-Version": "1",
+      },
+    });
+  }
+
+  /** Get the number of connected clients */
+  get clientCount(): number {
+    return this.clients.size;
+  }
+
+  stop(): void {
+    if (!this.started) return;
+    this.started = false;
+
+    this.tailer.stop();
+
+    if (this.throttleTimer) {
+      clearTimeout(this.throttleTimer);
+      this.throttleTimer = null;
+    }
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+
+    for (const [, client] of this.clients) {
+      try {
+        client.controller.close();
+      } catch { /* ignore */ }
+    }
+    this.clients.clear();
+  }
+}

package/src/kitchen/stream/file-tailer.ts

@@ -0,0 +1,99 @@
+/**
+ * FileTailer - Tails a JSONL file and emits new lines as events.
+ *
+ * Used by Kitchen SSE to watch .mandu/activity.jsonl written by MCP server.
+ * Communication between MCP process and dev server is file-system based.
+ */
+
+import { EventEmitter } from "events";
+import fs from "fs";
+
+export interface FileTailerOptions {
+  /** Start reading from end of file (skip existing content) */
+  startAtEnd: boolean;
+  /** Polling interval in ms for fs.watchFile */
+  pollIntervalMs: number;
+}
+
+const DEFAULT_OPTIONS: FileTailerOptions = {
+  startAtEnd: true,
+  pollIntervalMs: 300,
+};
+
+export class FileTailer extends EventEmitter {
+  private position = 0;
+  private buffer = "";
+  private watching = false;
+
+  constructor(
+    private filePath: string,
+    private options: FileTailerOptions = DEFAULT_OPTIONS
+  ) {
+    super();
+  }
+
+  start(): void {
+    if (this.watching) return;
+    this.watching = true;
+
+    try {
+      const stat = fs.statSync(this.filePath);
+      this.position = this.options.startAtEnd ? stat.size : 0;
+    } catch {
+      // File doesn't exist yet — start from 0
+      this.position = 0;
+    }
+
+    fs.watchFile(
+      this.filePath,
+      { interval: this.options.pollIntervalMs },
+      (curr) => {
+        if (curr.size > this.position) {
+          this.readNewContent(curr.size);
+        } else if (curr.size < this.position) {
+          // File was truncated/recreated (MCP server restart)
+          this.position = 0;
+          this.buffer = "";
+          if (curr.size > 0) {
+            this.readNewContent(curr.size);
+          }
+        }
+      }
+    );
+  }
+
+  private readNewContent(newSize: number): void {
+    let fd: number | undefined;
+    try {
+      fd = fs.openSync(this.filePath, "r");
+      const length = newSize - this.position;
+      const buf = Buffer.alloc(length);
+      fs.readSync(fd, buf, 0, length, this.position);
+      this.position = newSize;
+
+      this.buffer += buf.toString("utf-8");
+      const lines = this.buffer.split("\n");
+      this.buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed) {
+          this.emit("line", trimmed);
+        }
+      }
+    } catch {
+      // File read error — will retry on next poll
+    } finally {
+      if (fd !== undefined) {
+        try { fs.closeSync(fd); } catch { /* ignore */ }
+      }
+    }
+  }
+
+  stop(): void {
+    if (!this.watching) return;
+    this.watching = false;
+    fs.unwatchFile(this.filePath);
+    this.removeAllListeners();
+  }
+}

package/src/middleware/compress.ts

@@ -0,0 +1,62 @@
+/**
+ * Compress Middleware Plugin
+ * filling.use(compress())
+ */
+
+import type { MiddlewarePlugin } from "../filling/filling";
+import type { ManduContext } from "../filling/context";
+
+export interface CompressMiddlewareOptions {
+  /** 압축 최소 크기 (바이트, 기본: 1024) */
+  threshold?: number;
+  /** 압축할 Content-Type (기본: text/*, application/json, application/xml) */
+  contentTypes?: string[];
+}
+
+const DEFAULT_COMPRESSIBLE = ["text/", "application/json", "application/xml", "application/javascript"];
+
+/**
+ * Gzip 압축 미들웨어
+ *
+ * @example
+ * ```typescript
+ * import { compress } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(compress({ threshold: 512 }))
+ *   .get((ctx) => ctx.ok({ largeData: "..." }));
+ * ```
+ */
+export function compress(options?: CompressMiddlewareOptions): MiddlewarePlugin {
+  const threshold = options?.threshold ?? 1024;
+  const types = options?.contentTypes ?? DEFAULT_COMPRESSIBLE;
+
+  return {
+    beforeHandle: async (ctx: ManduContext): Promise<void> => {
+      const acceptEncoding = ctx.headers.get("Accept-Encoding") ?? "";
+      if (acceptEncoding.includes("gzip")) {
+        ctx.set("_compress_enabled", true);
+      }
+    },
+    afterHandle: async (ctx: ManduContext, response: Response): Promise<Response> => {
+      if (!ctx.get<boolean>("_compress_enabled")) return response;
+
+      const contentType = response.headers.get("Content-Type") ?? "";
+      const isCompressible = types.some(t => contentType.includes(t));
+      if (!isCompressible) return response;
+
+      const body = await response.arrayBuffer();
+      if (body.byteLength < threshold) {
+        return new Response(body, { status: response.status, headers: response.headers });
+      }
+
+      const compressed = Bun.gzipSync(new Uint8Array(body));
+      const headers = new Headers(response.headers);
+      headers.set("Content-Encoding", "gzip");
+      headers.set("Vary", "Accept-Encoding");
+      headers.delete("Content-Length");
+
+      return new Response(compressed, { status: response.status, headers });
+    },
+  };
+}

package/src/middleware/cors.ts

@@ -0,0 +1,47 @@
+/**
+ * CORS Middleware Plugin
+ * filling.use(cors({ origin: "https://example.com" }))
+ */
+
+import type { MiddlewarePlugin } from "../filling/filling";
+import type { ManduContext } from "../filling/context";
+import {
+  type CorsOptions,
+  handlePreflightRequest,
+  applyCorsToResponse,
+} from "../runtime/cors";
+
+export type CorsMiddlewareOptions = CorsOptions;
+
+/**
+ * CORS 미들웨어
+ *
+ * @example
+ * ```typescript
+ * import { cors } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(cors({ origin: ["https://example.com"], credentials: true }))
+ *   .get((ctx) => ctx.ok({ data: "protected" }));
+ * ```
+ */
+export function cors(options?: CorsMiddlewareOptions): MiddlewarePlugin {
+  return {
+    beforeHandle: async (ctx: ManduContext): Promise<Response | void> => {
+      const origin = ctx.headers.get("Origin");
+      if (!origin) return;
+
+      // Preflight
+      if (ctx.request.method === "OPTIONS") {
+        return handlePreflightRequest(ctx.request, options);
+      }
+
+      // 실제 요청 — afterHandle에서 CORS 헤더 추가하기 위해 플래그 저장
+      ctx.set("_cors_apply", true);
+    },
+    afterHandle: async (ctx: ManduContext, response: Response): Promise<Response> => {
+      if (!ctx.get<boolean>("_cors_apply")) return response;
+      return applyCorsToResponse(response, ctx.request, options);
+    },
+  };
+}

package/src/middleware/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Mandu Middleware Plugins
+ * filling.use()로 조합 가능한 재사용 미들웨어
+ */
+
+export { cors, type CorsMiddlewareOptions } from "./cors";
+export { jwt, type JwtMiddlewareOptions } from "./jwt";
+export { compress, type CompressMiddlewareOptions } from "./compress";
+export { logger, type LoggerMiddlewareOptions } from "./logger";
+export { timeout, type TimeoutMiddlewareOptions } from "./timeout";

package/src/middleware/jwt.ts

@@ -0,0 +1,134 @@
+/**
+ * JWT Middleware Plugin
+ * filling.use(jwt({ secret: process.env.JWT_SECRET }))
+ */
+
+import type { ManduContext } from "../filling/context";
+
+export interface JwtMiddlewareOptions {
+  /** JWT 시크릿 키 */
+  secret: string;
+  /** 허용할 알고리즘 (기본: ["HS256"]) */
+  algorithms?: ("HS256" | "HS384" | "HS512")[];
+  /** 토큰 추출 위치 (기본: Authorization 헤더) */
+  extractFrom?: "header" | "cookie";
+  /** 쿠키 이름 (extractFrom: "cookie" 일 때) */
+  cookieName?: string;
+  /** ctx.set()에 저장할 키 (기본: "user") */
+  storeAs?: string;
+}
+
+/**
+ * JWT 인증 미들웨어
+ *
+ * @example
+ * ```typescript
+ * import { jwt } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(jwt({ secret: process.env.JWT_SECRET! }))
+ *   .get((ctx) => {
+ *     const user = ctx.get("user");
+ *     return ctx.ok({ user });
+ *   });
+ * ```
+ */
+export function jwt(options: JwtMiddlewareOptions) {
+  const { secret, algorithms = ["HS256"], extractFrom = "header", cookieName = "token", storeAs = "user" } = options;
+
+  return async (ctx: ManduContext): Promise<Response | void> => {
+    let token: string | null = null;
+
+    if (extractFrom === "header") {
+      const auth = ctx.headers.get("Authorization");
+      if (auth?.startsWith("Bearer ")) {
+        token = auth.slice(7);
+      }
+    } else {
+      token = ctx.cookies.get(cookieName) ?? null;
+    }
+
+    if (!token) {
+      return ctx.unauthorized("Missing authentication token");
+    }
+
+    // 토큰 크기 제한 (메모리 소모 공격 방지)
+    if (token.length > 8192) {
+      return ctx.unauthorized("Token too large");
+    }
+
+    try {
+      // Bun native JWT verification
+      const payload = await verifyJwtToken(token, secret, algorithms);
+      ctx.set(storeAs, payload);
+    } catch {
+      return ctx.unauthorized("Invalid or expired token");
+    }
+  };
+}
+
+const ALG_MAP: Record<string, string> = {
+  HS256: "SHA-256",
+  HS384: "SHA-384",
+  HS512: "SHA-512",
+};
+
+/** JWT 검증 (Bun crypto 기반, HS256/HS384/HS512 지원) */
+async function verifyJwtToken(
+  token: string,
+  secret: string,
+  allowedAlgorithms: string[]
+): Promise<Record<string, unknown>> {
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new Error("Invalid JWT format");
+
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  // 헤더에서 알고리즘 확인
+  const header = JSON.parse(atob(headerB64.replace(/-/g, "+").replace(/_/g, "/")));
+  const alg = header.alg as string;
+  if (!allowedAlgorithms.includes(alg)) {
+    throw new Error(`Algorithm "${alg}" not allowed. Allowed: ${allowedAlgorithms.join(", ")}`);
+  }
+
+  const hash = ALG_MAP[alg];
+  if (!hash) throw new Error(`Unsupported algorithm: ${alg}`);
+
+  // 서명 검증
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash },
+    false,
+    ["verify"]
+  );
+
+  const data = encoder.encode(`${headerB64}.${payloadB64}`);
+  const signature = base64UrlDecode(signatureB64);
+
+  const valid = await crypto.subtle.verify("HMAC", key, signature as BufferSource, data);
+  if (!valid) throw new Error("Invalid signature");
+
+  // 페이로드 디코딩
+  const payload = JSON.parse(atob(payloadB64.replace(/-/g, "+").replace(/_/g, "/")));
+
+  // 만료 확인
+  if (payload.exp && payload.exp * 1000 < Date.now()) {
+    throw new Error("Token expired");
+  }
+
+  // nbf (not-before) 확인 — 아직 유효하지 않은 토큰 거부
+  if (payload.nbf && payload.nbf * 1000 > Date.now()) {
+    throw new Error("Token not yet valid");
+  }
+
+  return payload;
+}
+
+function base64UrlDecode(str: string): Uint8Array {
+  const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  const binary = atob(padded);
+  return Uint8Array.from(binary, c => c.charCodeAt(0));
+}

package/src/middleware/logger.ts

@@ -0,0 +1,58 @@
+/**
+ * Logger Middleware Plugin
+ * filling.use(logger())
+ */
+
+import type { MiddlewarePlugin } from "../filling/filling";
+import type { ManduContext } from "../filling/context";
+
+export interface LoggerMiddlewareOptions {
+  /** 로그 포맷 (기본: "short") */
+  format?: "short" | "detailed";
+  /** 커스텀 로거 (기본: console.log) */
+  log?: (message: string) => void;
+  /** 느린 요청 경고 임계값 (ms, 기본: 3000) */
+  slowThreshold?: number;
+}
+
+/**
+ * 요청/응답 로깅 미들웨어
+ *
+ * @example
+ * ```typescript
+ * import { logger } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(logger({ format: "detailed", slowThreshold: 1000 }))
+ *   .get((ctx) => ctx.ok({ data: "logged" }));
+ * ```
+ */
+export function logger(options?: LoggerMiddlewareOptions): MiddlewarePlugin {
+  const format = options?.format ?? "short";
+  const log = options?.log ?? console.log;
+  const slowThreshold = options?.slowThreshold ?? 3000;
+
+  return {
+    beforeHandle: async (ctx: ManduContext): Promise<void> => {
+      ctx.set("_logger_start", Date.now());
+    },
+    afterHandle: async (ctx: ManduContext, response: Response): Promise<Response> => {
+      const start = ctx.get<number>("_logger_start");
+      if (start === undefined) return response;
+
+      const duration = Date.now() - start;
+      const method = ctx.request.method;
+      const pathname = new URL(ctx.request.url).pathname;
+      const status = response.status;
+      const slow = duration > slowThreshold ? " ⚠️ SLOW" : "";
+
+      if (format === "detailed") {
+        log(`${method} ${pathname} → ${status} (${duration}ms)${slow}`);
+      } else {
+        log(`${method} ${pathname} ${status} ${duration}ms${slow}`);
+      }
+
+      return response;
+    },
+  };
+}

package/src/middleware/timeout.ts

@@ -0,0 +1,55 @@
+/**
+ * Timeout Middleware Plugin
+ * filling.use(timeout(5000))
+ */
+
+import type { MiddlewarePlugin } from "../filling/filling";
+import type { ManduContext } from "../filling/context";
+
+export interface TimeoutMiddlewareOptions {
+  /** 타임아웃 (ms) */
+  ms: number;
+  /** 타임아웃 시 응답 메시지 */
+  message?: string;
+  /** 타임아웃 시 HTTP 상태 코드 (기본: 408) */
+  status?: number;
+}
+
+/**
+ * 요청 타임아웃 미들웨어
+ *
+ * @example
+ * ```typescript
+ * import { timeout } from "@mandujs/core/middleware";
+ *
+ * export default Mandu.filling()
+ *   .use(timeout({ ms: 5000 }))
+ *   .get(async (ctx) => { ... });
+ * ```
+ */
+export function timeout(options: TimeoutMiddlewareOptions | number): MiddlewarePlugin {
+  const config = typeof options === "number"
+    ? { ms: options, message: "Request Timeout", status: 408 }
+    : { message: "Request Timeout", status: 408, ...options };
+
+  return {
+    beforeHandle: async (ctx: ManduContext): Promise<Response | void> => {
+      // 타임아웃 타이머 설정 — 핸들러가 완료 전에 만료되면 408 반환
+      ctx.set("_timeout_timer", setTimeout(() => {
+        ctx.set("_timeout_expired", true);
+      }, config.ms));
+    },
+    afterHandle: async (ctx: ManduContext, response: Response): Promise<Response> => {
+      // 타이머 정리
+      const timer = ctx.get<ReturnType<typeof setTimeout>>("_timeout_timer");
+      if (timer) clearTimeout(timer);
+
+      // 타임아웃 만료 확인
+      if (ctx.get<boolean>("_timeout_expired")) {
+        return ctx.json({ error: config.message }, config.status);
+      }
+
+      return response;
+    },
+  };
+}

package/src/paths.ts

@@ -15,8 +15,6 @@ export interface GeneratedPaths {
   mapDir: string;
   /** 생성된 매니페스트 경로 */
   manifestPath: string;
-  /** 생성된 lock 경로 */
-  lockPath: string;
   /** Resource 관련 경로 */
   resourceContractsDir: string;
   resourceTypesDir: string;
@@ -35,7 +33,6 @@ export function resolveGeneratedPaths(rootDir: string): GeneratedPaths {
     typesDir: path.join(rootDir, ".mandu/generated/server/types"),
     mapDir: path.join(rootDir, ".mandu/generated"),
     manifestPath: path.join(rootDir, ".mandu/routes.manifest.json"),
-    lockPath: path.join(rootDir, ".mandu/spec.lock.json"),
     resourceContractsDir: path.join(rootDir, ".mandu/generated/server/contracts"),
     resourceTypesDir: path.join(rootDir, ".mandu/generated/server/types"),
     resourceSlotsDir: path.join(rootDir, "spec/slots"),
@@ -53,7 +50,6 @@ export const GENERATED_RELATIVE_PATHS = {
   types: ".mandu/generated/server/types",
   map: ".mandu/generated",
   manifest: ".mandu/routes.manifest.json",
-  lock: ".mandu/spec.lock.json",
   history: ".mandu/history",
   contracts: ".mandu/generated/server/contracts",
   resourceTypes: ".mandu/generated/server/types",