clawfire 0.1.0

package/dist/dev-server-QAVWINAT.js

@@ -0,0 +1,973 @@
+#!/usr/bin/env node
+import {
+  discoverRoutes
+} from "./chunk-37Y2XI7X.js";
+import {
+  generatePlaygroundHtml
+} from "./chunk-YGIPORYL.js";
+
+// src/dev/dev-server.ts
+import http from "http";
+import { resolve, relative } from "path";
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { pathToFileURL } from "url";
+
+// src/core/schema.ts
+import { z } from "zod";
+function zodToJsonSchema(schema) {
+  return extractZodShape(schema);
+}
+function extractZodShape(schema) {
+  const def = schema._def;
+  if (!def) return { type: "unknown" };
+  switch (def.typeName) {
+    case "ZodObject": {
+      const shape = schema.shape;
+      const properties = {};
+      const required = [];
+      for (const [key, value] of Object.entries(shape)) {
+        properties[key] = extractZodShape(value);
+        if (!value.isOptional?.()) {
+          const innerDef = value._def;
+          if (innerDef?.typeName !== "ZodOptional" && innerDef?.typeName !== "ZodDefault") {
+            required.push(key);
+          }
+        }
+      }
+      return { type: "object", properties, ...required.length > 0 ? { required } : {} };
+    }
+    case "ZodString":
+      return { type: "string", ...def.checks?.length ? extractStringChecks(def.checks) : {} };
+    case "ZodNumber":
+      return { type: "number" };
+    case "ZodBoolean":
+      return { type: "boolean" };
+    case "ZodArray":
+      return { type: "array", items: extractZodShape(def.type) };
+    case "ZodEnum":
+      return { type: "string", enum: def.values };
+    case "ZodOptional":
+      return { ...extractZodShape(def.innerType), optional: true };
+    case "ZodDefault":
+      return { ...extractZodShape(def.innerType), default: def.defaultValue() };
+    case "ZodNullable":
+      return { ...extractZodShape(def.innerType), nullable: true };
+    case "ZodLiteral":
+      return { type: typeof def.value, const: def.value };
+    case "ZodUnion":
+      return { oneOf: def.options.map((o) => extractZodShape(o)) };
+    case "ZodRecord":
+      return { type: "object", additionalProperties: extractZodShape(def.valueType) };
+    case "ZodDate":
+      return { type: "string", format: "date-time" };
+    default:
+      return { type: "unknown" };
+  }
+}
+function extractStringChecks(checks) {
+  const result = {};
+  for (const check of checks) {
+    switch (check.kind) {
+      case "min":
+        result.minLength = check.value;
+        break;
+      case "max":
+        result.maxLength = check.value;
+        break;
+      case "email":
+        result.format = "email";
+        break;
+      case "url":
+        result.format = "uri";
+        break;
+      case "uuid":
+        result.format = "uuid";
+        break;
+    }
+  }
+  return result;
+}
+function contractToManifest(path, contract) {
+  return {
+    path,
+    method: "POST",
+    meta: contract.meta,
+    inputSchema: zodToJsonSchema(contract.input),
+    outputSchema: zodToJsonSchema(contract.output)
+  };
+}
+
+// src/core/errors.ts
+var HTTP_STATUS_MAP = {
+  VALIDATION_ERROR: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  RATE_LIMITED: 429,
+  REAUTH_REQUIRED: 401,
+  INTERNAL_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503
+};
+var ClawfireError = class extends Error {
+  code;
+  statusCode;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "ClawfireError";
+    this.code = code;
+    this.statusCode = HTTP_STATUS_MAP[code];
+    this.details = details;
+  }
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...this.details ? { details: this.details } : {}
+      }
+    };
+  }
+};
+var Errors = {
+  validation: (message, details) => new ClawfireError("VALIDATION_ERROR", message, details),
+  unauthorized: (message = "Authentication required") => new ClawfireError("UNAUTHORIZED", message),
+  forbidden: (message = "Insufficient permissions") => new ClawfireError("FORBIDDEN", message),
+  notFound: (message = "Resource not found") => new ClawfireError("NOT_FOUND", message),
+  conflict: (message) => new ClawfireError("CONFLICT", message),
+  rateLimited: (message = "Too many requests") => new ClawfireError("RATE_LIMITED", message),
+  reauthRequired: (message = "Re-authentication required for this action") => new ClawfireError("REAUTH_REQUIRED", message),
+  internal: (message = "Internal server error") => new ClawfireError("INTERNAL_ERROR", message),
+  unavailable: (message = "Service temporarily unavailable") => new ClawfireError("SERVICE_UNAVAILABLE", message)
+};
+
+// src/core/logger.ts
+var SENSITIVE_FIELDS = [
+  "password",
+  "token",
+  "secret",
+  "apiKey",
+  "api_key",
+  "authorization",
+  "credit_card",
+  "creditCard",
+  "ssn",
+  "cardNumber",
+  "card_number",
+  "cvv",
+  "pin"
+];
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var currentLevel = "info";
+function shouldLog(level) {
+  return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+function maskSensitive(obj) {
+  if (obj === null || obj === void 0) return obj;
+  if (typeof obj === "string") return obj;
+  if (typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) {
+    return obj.map(maskSensitive);
+  }
+  const masked = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (SENSITIVE_FIELDS.some((f) => key.toLowerCase().includes(f.toLowerCase()))) {
+      masked[key] = "***MASKED***";
+    } else if (typeof value === "object" && value !== null) {
+      masked[key] = maskSensitive(value);
+    } else {
+      masked[key] = value;
+    }
+  }
+  return masked;
+}
+function formatLog(level, message, data) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const prefix = `[${timestamp}] [CLAWFIRE] [${level.toUpperCase()}]`;
+  if (data !== void 0) {
+    return `${prefix} ${message} ${JSON.stringify(maskSensitive(data))}`;
+  }
+  return `${prefix} ${message}`;
+}
+var logger = {
+  debug(message, data) {
+    if (shouldLog("debug")) console.debug(formatLog("debug", message, data));
+  },
+  info(message, data) {
+    if (shouldLog("info")) console.info(formatLog("info", message, data));
+  },
+  warn(message, data) {
+    if (shouldLog("warn")) console.warn(formatLog("warn", message, data));
+  },
+  error(message, data) {
+    if (shouldLog("error")) console.error(formatLog("error", message, data));
+  }
+};
+
+// src/firebase/auth.ts
+async function verifyToken(auth, idToken) {
+  const decoded = await auth.verifyIdToken(idToken);
+  return {
+    uid: decoded.uid,
+    email: decoded.email,
+    emailVerified: decoded.email_verified,
+    role: decoded.role || decoded.customClaims?.role,
+    customClaims: decoded,
+    token: idToken
+  };
+}
+async function verifyReauth(auth, idToken, maxAgeSeconds = 300) {
+  const decoded = await auth.verifyIdToken(idToken, true);
+  const authTime = decoded.auth_time * 1e3;
+  const now = Date.now();
+  if (now - authTime > maxAgeSeconds * 1e3) {
+    throw Errors.reauthRequired(
+      `Re-authentication required. Last auth was ${Math.floor((now - authTime) / 1e3)}s ago.`
+    );
+  }
+  return {
+    uid: decoded.uid,
+    email: decoded.email,
+    emailVerified: decoded.email_verified,
+    role: decoded.role || decoded.customClaims?.role,
+    customClaims: decoded,
+    token: idToken
+  };
+}
+function extractBearerToken(authHeader) {
+  if (!authHeader) return null;
+  const parts = authHeader.split(" ");
+  if (parts.length !== 2 || parts[0] !== "Bearer") return null;
+  return parts[1];
+}
+function checkAuthLevel(authCtx, level, roles, reauthenticated) {
+  switch (level) {
+    case "public":
+      return;
+    // 누구나 접근 가능
+    case "authenticated":
+      if (!authCtx) throw Errors.unauthorized();
+      return;
+    case "role":
+      if (!authCtx) throw Errors.unauthorized();
+      if (!roles || roles.length === 0) return;
+      if (!authCtx.role || !roles.includes(authCtx.role)) {
+        throw Errors.forbidden(`Required role: ${roles.join(" or ")}`);
+      }
+      return;
+    case "reauth":
+      if (!authCtx) throw Errors.unauthorized();
+      if (!reauthenticated) {
+        throw Errors.reauthRequired();
+      }
+      return;
+  }
+}
+
+// src/routing/router.ts
+var RateLimiter = class {
+  store = /* @__PURE__ */ new Map();
+  defaultLimit;
+  constructor(defaultLimit) {
+    this.defaultLimit = defaultLimit;
+  }
+  check(key, limit) {
+    const max = limit || this.defaultLimit;
+    const now = Date.now();
+    const entry = this.store.get(key);
+    if (!entry || now > entry.resetAt) {
+      this.store.set(key, { count: 1, resetAt: now + 6e4 });
+      return true;
+    }
+    if (entry.count >= max) {
+      return false;
+    }
+    entry.count++;
+    return true;
+  }
+  // 오래된 엔트리 정리
+  cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now > entry.resetAt) this.store.delete(key);
+    }
+  }
+};
+var ClawfireRouter = class {
+  routes = /* @__PURE__ */ new Map();
+  options;
+  rateLimiter;
+  cleanupInterval;
+  constructor(options = {}) {
+    this.options = options;
+    this.rateLimiter = new RateLimiter(options.rateLimit || 100);
+    this.cleanupInterval = setInterval(() => this.rateLimiter.cleanup(), 6e4);
+  }
+  /** 라우트 등록 */
+  register(path, contract) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    this.routes.set(normalizedPath, { path: normalizedPath, contract });
+    logger.debug(`Route registered: ${normalizedPath}`);
+    return this;
+  }
+  /** 여러 라우트 한 번에 등록 */
+  registerAll(routes) {
+    for (const [path, contract] of Object.entries(routes)) {
+      this.register(path, contract);
+    }
+    return this;
+  }
+  /** 매니페스트 생성 */
+  getManifest() {
+    const apis = [];
+    for (const [path, route] of this.routes) {
+      apis.push(contractToManifest(path, route.contract));
+    }
+    return {
+      version: "1.0.0",
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      apis,
+      models: {}
+    };
+  }
+  /** HTTP 요청 핸들러 (Firebase Functions에서 사용) */
+  async handleRequest(req, res) {
+    const corsOrigins = this.options.cors || [];
+    const origin = req.headers?.origin || req.headers?.Origin || "";
+    if (corsOrigins.length > 0 && corsOrigins.includes(origin)) {
+      res.set({
+        "Access-Control-Allow-Origin": origin,
+        "Access-Control-Allow-Methods": "POST, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type, Authorization",
+        "Access-Control-Max-Age": "86400"
+      });
+    } else if (corsOrigins.length === 0) {
+      res.set({
+        "Access-Control-Allow-Origin": "",
+        "Access-Control-Allow-Methods": "POST, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type, Authorization"
+      });
+    }
+    if (req.method === "OPTIONS") {
+      res.status(204).end();
+      return;
+    }
+    res.set({
+      "X-Content-Type-Options": "nosniff",
+      "X-Frame-Options": "DENY",
+      "X-XSS-Protection": "1; mode=block",
+      "Content-Type": "application/json"
+    });
+    let routePath = req.path || req.url || "";
+    if (routePath.startsWith("/api")) {
+      routePath = routePath.slice(4);
+    }
+    if (routePath === "/__manifest") {
+      res.status(200).json(this.getManifest());
+      return;
+    }
+    if (req.method && req.method !== "POST") {
+      res.status(405).json({ error: { code: "METHOD_NOT_ALLOWED", message: "Only POST is allowed" } });
+      return;
+    }
+    const route = this.matchRoute(routePath);
+    if (!route) {
+      res.status(404).json({ error: { code: "NOT_FOUND", message: `API not found: ${routePath}` } });
+      return;
+    }
+    try {
+      const clientKey = req.ip || "unknown";
+      const rateLimit = route.contract.meta.rateLimit || this.options.rateLimit;
+      if (rateLimit && !this.rateLimiter.check(clientKey, rateLimit)) {
+        throw Errors.rateLimited();
+      }
+      let authCtx = null;
+      let reauthenticated = false;
+      const authHeader = req.headers?.authorization || req.headers?.Authorization;
+      if (authHeader && this.options.auth) {
+        const token = extractBearerToken(authHeader);
+        if (token) {
+          if (route.contract.meta.reauth || route.contract.meta.auth === "reauth") {
+            authCtx = await verifyReauth(this.options.auth, token);
+            reauthenticated = true;
+          } else {
+            authCtx = await verifyToken(this.options.auth, token);
+          }
+        }
+      }
+      if (route.contract.meta.auth) {
+        checkAuthLevel(authCtx, route.contract.meta.auth, route.contract.meta.roles, reauthenticated);
+      }
+      const rawInput = req.body || {};
+      const parsed = route.contract.input.safeParse(rawInput);
+      if (!parsed.success) {
+        throw Errors.validation("Invalid input", parsed.error.flatten());
+      }
+      const ctx = {
+        auth: authCtx,
+        reauthenticated,
+        headers: req.headers,
+        ip: req.ip
+      };
+      let result;
+      if (this.options.middleware && this.options.middleware.length > 0) {
+        result = await this.runMiddleware(
+          this.options.middleware,
+          parsed.data,
+          ctx,
+          () => route.contract.handler(parsed.data, ctx)
+        );
+      } else {
+        result = await route.contract.handler(parsed.data, ctx);
+      }
+      res.status(200).json({ data: result });
+    } catch (err) {
+      if (err instanceof ClawfireError) {
+        logger.warn(`API error [${err.code}]: ${err.message}`);
+        res.status(err.statusCode).json(err.toJSON());
+      } else {
+        logger.error("Unhandled error", err);
+        res.status(500).json({
+          error: {
+            code: "INTERNAL_ERROR",
+            message: "An unexpected error occurred"
+          }
+        });
+      }
+    }
+  }
+  /** 라우트 매칭 (동적 파라미터 지원) */
+  matchRoute(path) {
+    const exact = this.routes.get(path);
+    if (exact) return exact;
+    for (const [routePath, route] of this.routes) {
+      if (this.matchDynamicRoute(routePath, path)) {
+        return route;
+      }
+    }
+    return void 0;
+  }
+  matchDynamicRoute(pattern, actual) {
+    const patternParts = pattern.split("/").filter(Boolean);
+    const actualParts = actual.split("/").filter(Boolean);
+    if (patternParts.length !== actualParts.length) return false;
+    return patternParts.every(
+      (part, i) => part.startsWith(":") || part.startsWith("[") || part === actualParts[i]
+    );
+  }
+  /** 미들웨어 체인 실행 */
+  async runMiddleware(middlewares, input, ctx, handler) {
+    let index = 0;
+    const next = async () => {
+      if (index >= middlewares.length) {
+        return handler();
+      }
+      const mw = middlewares[index++];
+      return mw(input, ctx, next);
+    };
+    return next();
+  }
+  /** 등록된 라우트 목록 */
+  getRoutes() {
+    return Array.from(this.routes.values());
+  }
+  /** 리소스 정리 */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+    }
+  }
+};
+function createRouter(options) {
+  return new ClawfireRouter(options);
+}
+
+// src/dev/watcher.ts
+import { watch, existsSync, readdirSync } from "fs";
+import { join, extname } from "path";
+import { EventEmitter } from "events";
+var FileWatcher = class extends EventEmitter {
+  watchers = [];
+  debounceTimers = /* @__PURE__ */ new Map();
+  debounceMs;
+  constructor(debounceMs = 150) {
+    super();
+    this.debounceMs = debounceMs;
+  }
+  /**
+   * 디렉터리 감시 시작
+   */
+  watchDir(dir, eventType) {
+    if (!existsSync(dir)) return this;
+    try {
+      const watcher = watch(dir, { recursive: true }, (event, filename) => {
+        if (!filename) return;
+        const filePath = join(dir, filename);
+        if (!this.isWatchedFile(filePath)) return;
+        this.emitDebounced(filePath, eventType);
+      });
+      watcher.on("error", (err) => {
+        if (err.code === "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM") {
+          this.watchDirRecursiveManual(dir, eventType);
+        }
+      });
+      this.watchers.push(watcher);
+    } catch {
+      this.watchDirRecursiveManual(dir, eventType);
+    }
+    return this;
+  }
+  /**
+   * 단일 파일 감시
+   */
+  watchFile(filePath, eventType) {
+    if (!existsSync(filePath)) return this;
+    const watcher = watch(filePath, (event) => {
+      this.emitDebounced(filePath, eventType);
+    });
+    this.watchers.push(watcher);
+    return this;
+  }
+  /**
+   * Linux fallback: 디렉터리 수동 재귀 감시
+   */
+  watchDirRecursiveManual(dir, eventType) {
+    if (!existsSync(dir)) return;
+    const watcher = watch(dir, (event, filename) => {
+      if (!filename) return;
+      const filePath = join(dir, filename);
+      if (!this.isWatchedFile(filePath)) return;
+      this.emitDebounced(filePath, eventType);
+    });
+    this.watchers.push(watcher);
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+          this.watchDirRecursiveManual(join(dir, entry.name), eventType);
+        }
+      }
+    } catch {
+    }
+  }
+  /**
+   * 감시 대상 파일인지 확인
+   */
+  isWatchedFile(filePath) {
+    const ext = extname(filePath);
+    return [".ts", ".tsx", ".js", ".jsx", ".json"].includes(ext);
+  }
+  /**
+   * 디바운스 이벤트 발생
+   */
+  emitDebounced(filePath, type) {
+    const existing = this.debounceTimers.get(filePath);
+    if (existing) clearTimeout(existing);
+    this.debounceTimers.set(
+      filePath,
+      setTimeout(() => {
+        this.debounceTimers.delete(filePath);
+        const event = { type, filePath, timestamp: Date.now() };
+        this.emit("change", event);
+        this.emit(type, event);
+      }, this.debounceMs)
+    );
+  }
+  /**
+   * 모든 감시 중지
+   */
+  close() {
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+    this.watchers = [];
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+    this.removeAllListeners();
+  }
+};
+
+// src/dev/dev-server.ts
+var DevServer = class {
+  server = null;
+  router;
+  watcher = null;
+  sseClients = [];
+  sseIdCounter = 0;
+  options;
+  routesDir;
+  schemasDir;
+  playgroundHtml = "";
+  importCounter = 0;
+  // ESM 캐시 버스팅용
+  isReloading = false;
+  constructor(options = {}) {
+    this.options = {
+      projectDir: options.projectDir || process.cwd(),
+      port: options.port || 3456,
+      routerOptions: options.routerOptions || {},
+      hotReload: options.hotReload !== false,
+      debounceMs: options.debounceMs || 150,
+      onSetupRoutes: options.onSetupRoutes || (() => {
+      })
+    };
+    this.routesDir = resolve(this.options.projectDir, "app/routes");
+    this.schemasDir = resolve(this.options.projectDir, "app/schemas");
+    this.router = createRouter({
+      cors: ["*"],
+      // dev에서는 모든 origin 허용
+      rateLimit: 0,
+      // dev에서는 rate limit 비활성화
+      ...this.options.routerOptions
+    });
+  }
+  /**
+   * 개발 서버 시작
+   */
+  async start() {
+    await this.loadRoutes();
+    this.regeneratePlayground();
+    this.server = http.createServer((req, res) => this.handleHttpRequest(req, res));
+    if (this.options.hotReload) {
+      this.startWatcher();
+    }
+    await new Promise((resolve2, reject) => {
+      this.server.listen(this.options.port, () => {
+        resolve2();
+      });
+      this.server.on("error", reject);
+    });
+    this.printStartupBanner();
+  }
+  /**
+   * 서버 종료
+   */
+  async stop() {
+    this.watcher?.close();
+    for (const client of this.sseClients) {
+      client.res.end();
+    }
+    this.sseClients = [];
+    this.router.destroy();
+    if (this.server) {
+      await new Promise((resolve2) => {
+        this.server.close(() => resolve2());
+      });
+    }
+  }
+  // ─── Route Loading ─────────────────────────────────────────────────
+  /**
+   * 라우트 파일 로딩 (또는 수동 콜백)
+   */
+  async loadRoutes() {
+    this.router.destroy();
+    this.router = createRouter({
+      cors: ["*"],
+      rateLimit: 0,
+      ...this.options.routerOptions
+    });
+    if (this.options.onSetupRoutes) {
+      await this.options.onSetupRoutes(this.router);
+      if (this.router.getRoutes().length > 0) return;
+    }
+    if (!existsSync2(this.routesDir)) return;
+    const discovered = discoverRoutes(this.routesDir);
+    for (const route of discovered) {
+      try {
+        const fullPath = resolve(this.routesDir, route.filePath);
+        const fileUrl = pathToFileURL(fullPath).href;
+        const mod = await import(`${fileUrl}?v=${++this.importCounter}`);
+        const contract = mod.default;
+        if (contract && typeof contract.handler === "function" && contract.input && contract.output && contract.meta) {
+          this.router.register(route.apiPath, contract);
+        }
+      } catch (err) {
+        logger.warn(`Failed to load route: ${route.filePath}`, err);
+      }
+    }
+  }
+  /**
+   * 라우트 핫 리로드
+   */
+  async reloadRoutes(event) {
+    if (this.isReloading) return;
+    this.isReloading = true;
+    const relPath = relative(this.options.projectDir, event.filePath);
+    const timestamp = (/* @__PURE__ */ new Date()).toLocaleTimeString();
+    console.log(`
+  \x1B[33m[${timestamp}]\x1B[0m \x1B[36m${relPath}\x1B[0m changed`);
+    console.log("  Reloading routes...");
+    try {
+      await this.loadRoutes();
+      this.regeneratePlayground();
+      const routeCount = this.router.getRoutes().length;
+      console.log(`  \x1B[32m\u2713\x1B[0m ${routeCount} routes loaded`);
+      this.broadcastSSE({
+        type: event.type,
+        file: relPath,
+        timestamp: event.timestamp,
+        routes: routeCount
+      });
+    } catch (err) {
+      console.log(`  \x1B[31m\u2717\x1B[0m Reload failed:`, err);
+      this.broadcastSSE({
+        type: "error",
+        file: relPath,
+        message: err instanceof Error ? err.message : "Unknown error"
+      });
+    } finally {
+      this.isReloading = false;
+    }
+  }
+  // ─── File Watcher ──────────────────────────────────────────────────
+  startWatcher() {
+    this.watcher = new FileWatcher(this.options.debounceMs);
+    if (existsSync2(this.routesDir)) {
+      this.watcher.watchDir(this.routesDir, "route-change");
+    }
+    if (existsSync2(this.schemasDir)) {
+      this.watcher.watchDir(this.schemasDir, "schema-change");
+    }
+    const configFile = resolve(this.options.projectDir, "clawfire.config.ts");
+    if (existsSync2(configFile)) {
+      this.watcher.watchFile(configFile, "config-change");
+    }
+    this.watcher.on("change", (event) => {
+      this.reloadRoutes(event);
+    });
+  }
+  // ─── SSE (Server-Sent Events) ──────────────────────────────────────
+  handleSSE(req, res) {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      "Connection": "keep-alive",
+      "Access-Control-Allow-Origin": "*"
+    });
+    const clientId = ++this.sseIdCounter;
+    const client = { id: clientId, res };
+    this.sseClients.push(client);
+    res.write(`data: ${JSON.stringify({ type: "connected", id: clientId })}
+
+`);
+    req.on("close", () => {
+      this.sseClients = this.sseClients.filter((c) => c.id !== clientId);
+    });
+  }
+  broadcastSSE(data) {
+    const message = `data: ${JSON.stringify(data)}
+
+`;
+    for (const client of this.sseClients) {
+      try {
+        client.res.write(message);
+      } catch {
+      }
+    }
+  }
+  // ─── Playground ────────────────────────────────────────────────────
+  regeneratePlayground() {
+    const baseHtml = generatePlaygroundHtml({
+      title: "Clawfire Dev Playground",
+      apiBaseUrl: `http://localhost:${this.options.port}`
+    });
+    const liveReloadScript = `
+<script>
+(function() {
+  const banner = document.createElement('div');
+  banner.id = 'dev-banner';
+  banner.style.cssText = 'position:fixed;bottom:0;left:0;right:0;padding:6px 16px;background:#1a1a2e;color:#f97316;font-size:12px;font-family:monospace;z-index:9999;display:flex;align-items:center;gap:8px;border-top:1px solid #2a2a2a;';
+  banner.innerHTML = '<span style="width:8px;height:8px;border-radius:50%;background:#22c55e;display:inline-block;" id="dev-dot"></span><span>Clawfire Dev Server</span><span style="color:#666;margin-left:auto;" id="dev-status">Connected</span>';
+  document.body.appendChild(banner);
+
+  let reconnectTimer;
+  function connect() {
+    const es = new EventSource('http://localhost:${this.options.port}/__dev/events');
+
+    es.onopen = () => {
+      document.getElementById('dev-dot').style.background = '#22c55e';
+      document.getElementById('dev-status').textContent = 'Connected';
+      if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+    };
+
+    es.onmessage = (e) => {
+      try {
+        const data = JSON.parse(e.data);
+        if (data.type === 'connected') return;
+
+        if (data.type === 'error') {
+          document.getElementById('dev-dot').style.background = '#ef4444';
+          document.getElementById('dev-status').textContent = 'Error: ' + (data.message || 'reload failed');
+          return;
+        }
+
+        // \uD30C\uC77C \uBCC0\uACBD \u2192 \uD398\uC774\uC9C0 \uC0C8\uB85C\uACE0\uCE68
+        document.getElementById('dev-dot').style.background = '#eab308';
+        document.getElementById('dev-status').textContent = 'Reloading...';
+        setTimeout(() => window.location.reload(), 300);
+      } catch {}
+    };
+
+    es.onerror = () => {
+      es.close();
+      document.getElementById('dev-dot').style.background = '#ef4444';
+      document.getElementById('dev-status').textContent = 'Disconnected \u2014 reconnecting...';
+      reconnectTimer = setTimeout(connect, 2000);
+    };
+  }
+
+  connect();
+})();
+</script>`;
+    this.playgroundHtml = baseHtml.replace("</body>", liveReloadScript + "\n</body>");
+  }
+  // ─── HTTP Request Handler ──────────────────────────────────────────
+  handleHttpRequest(req, res) {
+    const url = new URL(req.url || "/", `http://localhost:${this.options.port}`);
+    if (url.pathname === "/__dev/events") {
+      this.handleSSE(req, res);
+      return;
+    }
+    if (url.pathname === "/" || url.pathname === "/__playground") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(this.playgroundHtml);
+      return;
+    }
+    if (!url.pathname.startsWith("/api") && !url.pathname.startsWith("/__")) {
+      const publicDir = resolve(this.options.projectDir, "public");
+      const filePath = resolve(publicDir, url.pathname.slice(1));
+      if (existsSync2(filePath) && !filePath.includes("..")) {
+        try {
+          const content = readFileSync(filePath);
+          const ext = filePath.split(".").pop() || "";
+          const mimeTypes = {
+            html: "text/html",
+            css: "text/css",
+            js: "application/javascript",
+            json: "application/json",
+            png: "image/png",
+            jpg: "image/jpeg",
+            svg: "image/svg+xml",
+            ico: "image/x-icon",
+            woff2: "font/woff2"
+          };
+          res.writeHead(200, { "Content-Type": mimeTypes[ext] || "application/octet-stream" });
+          res.end(content);
+          return;
+        } catch {
+        }
+      }
+    }
+    if (url.pathname.startsWith("/api")) {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "POST, GET, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+      let body = "";
+      req.on("data", (chunk) => {
+        body += chunk;
+      });
+      req.on("end", async () => {
+        let parsed = {};
+        try {
+          parsed = body ? JSON.parse(body) : {};
+        } catch {
+        }
+        await this.router.handleRequest(
+          {
+            method: req.method,
+            path: url.pathname,
+            body: parsed,
+            headers: req.headers,
+            ip: req.socket.remoteAddress || "127.0.0.1"
+          },
+          {
+            set(h) {
+              for (const [k, v] of Object.entries(h)) {
+                try {
+                  res.setHeader(k, v);
+                } catch {
+                }
+              }
+            },
+            status(code) {
+              return {
+                json(data) {
+                  res.writeHead(code, { "Content-Type": "application/json" });
+                  res.end(JSON.stringify(data));
+                },
+                send(data) {
+                  res.writeHead(code);
+                  res.end(data);
+                },
+                end() {
+                  res.writeHead(code);
+                  res.end();
+                }
+              };
+            }
+          }
+        );
+      });
+      return;
+    }
+    res.writeHead(404);
+    res.end("Not found");
+  }
+  // ─── Startup Banner ────────────────────────────────────────────────
+  printStartupBanner() {
+    const routes = this.router.getRoutes();
+    const watching = this.options.hotReload;
+    console.log("");
+    console.log("  \x1B[1m\x1B[33m\u26A1 Clawfire Dev Server\x1B[0m");
+    console.log("  \x1B[2m\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\x1B[0m");
+    console.log(`  \x1B[36mPlayground\x1B[0m : http://localhost:${this.options.port}`);
+    console.log(`  \x1B[36mAPI\x1B[0m        : http://localhost:${this.options.port}/api/...`);
+    console.log(`  \x1B[36mManifest\x1B[0m   : http://localhost:${this.options.port}/api/__manifest`);
+    console.log("");
+    console.log(`  \x1B[32mRoutes (${routes.length})\x1B[0m:`);
+    for (const route of routes) {
+      const auth = route.contract.meta.auth || "public";
+      const authColor = auth === "public" ? "32" : auth === "authenticated" ? "34" : auth === "role" ? "33" : "31";
+      console.log(`    POST /api\x1B[1m${route.path}\x1B[0m \x1B[${authColor}m[${auth}]\x1B[0m \x1B[2m${route.contract.meta.description}\x1B[0m`);
+    }
+    console.log("");
+    if (watching) {
+      console.log(`  \x1B[35mHot Reload\x1B[0m : \x1B[32mON\x1B[0m`);
+      console.log(`  \x1B[2mWatching: app/routes/, app/schemas/\x1B[0m`);
+    } else {
+      console.log(`  \x1B[35mHot Reload\x1B[0m : OFF`);
+    }
+    console.log(`
+  \x1B[2mPress Ctrl+C to stop\x1B[0m
+`);
+  }
+};
+async function startDevServer(options) {
+  const server = new DevServer(options);
+  await server.start();
+  const shutdown = async () => {
+    console.log("\n  Shutting down...");
+    await server.stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  return server;
+}
+export {
+  DevServer,
+  startDevServer
+};