@lark-apaas/devtool-kits 1.2.24 → 1.2.25-alpha.20260819082505

package/dist/index.d.cts

@@ -274,6 +274,133 @@ declare function getQueryParam(req: AnyRequest, key: string): string | undefined
  */
 declare function registerMiddlewares(server: ExpressApp | ViteMiddleware, middlewares: Middleware[], options?: Partial<MiddlewareContext>): void;
 
+/**
+ * 妙搭应用 Health Check 接口类型定义。
+ *
+ * 协议（飞书文档 - 妙搭应用 Health Check 接口规范）：
+ *   - HTTP connection refused / timeout → dev server 没起来 → 外壳重启沙箱
+ *   - 200 + { ready: true }                    → 应用已就绪，放行
+ *   - 200 + { ready: false, failed: false }    → 还在启动，继续轮询
+ *   - 200 + { ready: false, failed: true }     → 终态失败，停止轮询并把 message 呈现给用户
+ *
+ * 约束：`ready: true` 时 `failed` 必须为 false。
+ */
+interface HealthPayload {
+    /** 应用是否已就绪。client-only 栈等价于 dev server 自身就绪。 */
+    ready: boolean;
+    /** 终态失败：等下去也不会好。缺省 false。 */
+    failed: boolean;
+    /** 失败时的人类可读说明，仅用于展示与排查，外壳不得用于流程决策。 */
+    message?: string;
+}
+/** 单个信号的判定结果，仅内部使用。 */
+interface ServerLiveness {
+    /** Nest 服务当前是否存活 */
+    alive: boolean;
+    /** 最近一次成功 listen 的进程 pid（无则 null） */
+    pid: number | null;
+    /** 最近一次成功 listen 的时间（ISO，无则 null） */
+    listenAt: string | null;
+}
+interface ResolveHealthOptions {
+    /** 项目根目录 */
+    rootDir: string;
+    /** 日志目录，默认 `<rootDir>/logs` */
+    logDir?: string;
+    /**
+     * 本栈是否包含 Node 服务端。
+     * false（vite-react / html 等 client-only 栈）时直接返回 dev server 自身状态，
+     * 行为与改造前完全一致。
+     */
+    hasServer: boolean;
+    /** dev server 自身是否已 listen */
+    clientReady: boolean;
+    /** 本次 dev 会话首次拉起 server 的时间戳（ms）。缺省时不做超时判定。 */
+    firstStartedAt?: number | null;
+    /** 编译产物入口，默认 `<rootDir>/dist/server/main.js` */
+    serverEntry?: string;
+    /** 超时上限（ms），超过则判 failed。默认 300000。 */
+    timeoutMs?: number;
+    /**
+     * 本次 dev 会话的启动时间（ms），用于排除 pid 复用导致的陈旧 marker。
+     * 与 `firstStartedAt` 分开：后者是「超时从何时起算」的锚点，崩溃后会前移。
+     */
+    sessionStartedAt?: number | null;
+    /** 探测到 server 存活时回调，供宿主记录「最后一次存活时刻」 */
+    onServerAlive?: () => void;
+    /** 注入点，便于测试 */
+    now?: () => number;
+}
+
+/**
+ * 判定应用健康状态。
+ *
+ * 设计原则：**`failed: true` 只能由肯定性事实触发，绝不能由否定性推断触发。**
+ * 「读不到日志」「匹配不到 marker」「产物看不见」都属于否定性推断，
+ * 一律降级为「还在启动」（`ready:false, failed:false`），让外壳继续等。
+ * 只有「超过 timeoutMs 仍未就绪」这一个时间事实可以判 failed。
+ */
+declare function resolveHealth(options: ResolveHealthOptions): HealthPayload;
+
+/**
+ * `process.kill(pid, 0)` 不发信号，只做存在性检查。
+ * EPERM 表示进程存在但当前用户无权发信号 —— 仍算存活。
+ */
+declare function isPidAlive(pid: number): boolean;
+/**
+ * 判定 Nest 服务当前是否存活。
+ *
+ * 两步都是「肯定性事实」：
+ *   1. 日志里存在 listen marker  → 曾经成功启动过（匹配不到就不下结论）
+ *   2. 该 marker 的 pid 仍然存活 → 现在确实还活着
+ *
+ * 只有第 1 步会导致误判：`dev.js` 以 append 模式写日志，历史成功记录会长期留存，
+ * 因此第 2 步的 pid 验活不可省略。
+ *
+ * `sessionStartedAt` 用于排除 pid 复用：marker 时间早于本次会话启动时间的，一律不采信。
+ */
+declare function resolveServerLiveness(logDir: string, sessionStartedAt?: number | null): ServerLiveness;
+
+/** 沙箱外壳探测的是固定根路径，不跟 clientBasePath 走 */
+declare const HEALTH_ENDPOINT = "/dev/health";
+interface HealthHandlerOptions {
+    /** 项目根目录 */
+    rootDir: string;
+    /** 日志目录，默认 `<rootDir>/logs` */
+    logDir?: string;
+    /** 本栈是否包含 Node 服务端 */
+    hasServer: boolean;
+    /** dev server 自身是否已 listen（由各 preset 注入） */
+    isClientReady: () => boolean;
+    /** 超时上限（ms）；未传时读环境变量 MIAODA_HEALTH_TIMEOUT_MS，再兜底 5min */
+    timeoutMs?: number;
+}
+/**
+ * 构造一个有状态的健康探测函数。宿主自行决定怎么把结果写进响应
+ * （Express 用 `res.status().json()`，Connect/Vite 用 `res.end()`）。
+ *
+ * 之所以有状态：超时窗口必须从「最后一次确认存活」起算，而不是从会话启动起算。
+ * 否则一个健康跑了 10 分钟的服务一旦崩溃，会因为 `now - firstStartedAt` 早已超限
+ * 而被**立刻**判成终态失败，supervisor 连重启的机会都没有。
+ *
+ * 判定本身出任何错都降级为「还在启动」——health 是旁路能力，
+ * 绝不能因为它自己的异常而让外壳误判失败、阻塞用户启动。
+ */
+declare function createHealthProbe(options: HealthHandlerOptions): () => HealthPayload;
+/**
+ * 单次计算健康状态（无状态版本）。
+ * 长驻宿主请用 {@link createHealthProbe}，它会正确处理「崩溃后重新计时」。
+ */
+declare function getHealthPayload(options: HealthHandlerOptions): HealthPayload;
+/**
+ * 构造 `/dev/health` 的 Connect / Vite 中间件。
+ *
+ * 响应码恒 200：`connection refused` / `timeout` 已被外壳用来表示
+ * 「dev server 自身没起来 → 重启沙箱」，应用级失败必须走 body，
+ * 否则会和传输层失败混淆。
+ */
+declare function createHealthHandler(options: HealthHandlerOptions): (req: IncomingMessage, res: ServerResponse, next?: () => void) => void;
+
 interface PageRouteInfo {
     path?: string;
     index?: boolean;
@@ -300,4 +427,4 @@ declare function parseRoutesFromFile(appPath: string, basePath: string, options?
     path: string;
 }>;
 
-export { type GlobalMiddleware, type Middleware, type MiddlewareContext, type Options, type PageRouteInfo, type ParseRoutesOptions, type RouteInfo, type RouteMiddleware, buildFullPath, calculateFileHash, createCollectLogsMiddleware, createDevLogsMiddleware, createOpenapiMiddleware, evaluateTemplateLiteral, extractPageRouteInfo, getQuery, getQueryParam, handleDevProxyError, isRouteComponent, normalizeBasePath, parseAndGenerateNestResourceTemplate, parseApiRoutes, parseRoutesFromFile, postprocessDrizzleSchema, registerMiddlewares, routeParserLog, sendError, sendJson, sendSuccess };
+export { type GlobalMiddleware, HEALTH_ENDPOINT, type HealthHandlerOptions, type HealthPayload, type Middleware, type MiddlewareContext, type Options, type PageRouteInfo, type ParseRoutesOptions, type ResolveHealthOptions, type RouteInfo, type RouteMiddleware, type ServerLiveness, buildFullPath, calculateFileHash, createCollectLogsMiddleware, createDevLogsMiddleware, createHealthHandler, createHealthProbe, createOpenapiMiddleware, evaluateTemplateLiteral, extractPageRouteInfo, getHealthPayload, getQuery, getQueryParam, handleDevProxyError, isPidAlive, isRouteComponent, normalizeBasePath, parseAndGenerateNestResourceTemplate, parseApiRoutes, parseRoutesFromFile, postprocessDrizzleSchema, registerMiddlewares, resolveHealth, resolveServerLiveness, routeParserLog, sendError, sendJson, sendSuccess };

package/dist/index.d.ts

@@ -274,6 +274,133 @@ declare function getQueryParam(req: AnyRequest, key: string): string | undefined
  */
 declare function registerMiddlewares(server: ExpressApp | ViteMiddleware, middlewares: Middleware[], options?: Partial<MiddlewareContext>): void;
 
+/**
+ * 妙搭应用 Health Check 接口类型定义。
+ *
+ * 协议（飞书文档 - 妙搭应用 Health Check 接口规范）：
+ *   - HTTP connection refused / timeout → dev server 没起来 → 外壳重启沙箱
+ *   - 200 + { ready: true }                    → 应用已就绪，放行
+ *   - 200 + { ready: false, failed: false }    → 还在启动，继续轮询
+ *   - 200 + { ready: false, failed: true }     → 终态失败，停止轮询并把 message 呈现给用户
+ *
+ * 约束：`ready: true` 时 `failed` 必须为 false。
+ */
+interface HealthPayload {
+    /** 应用是否已就绪。client-only 栈等价于 dev server 自身就绪。 */
+    ready: boolean;
+    /** 终态失败：等下去也不会好。缺省 false。 */
+    failed: boolean;
+    /** 失败时的人类可读说明，仅用于展示与排查，外壳不得用于流程决策。 */
+    message?: string;
+}
+/** 单个信号的判定结果，仅内部使用。 */
+interface ServerLiveness {
+    /** Nest 服务当前是否存活 */
+    alive: boolean;
+    /** 最近一次成功 listen 的进程 pid（无则 null） */
+    pid: number | null;
+    /** 最近一次成功 listen 的时间（ISO，无则 null） */
+    listenAt: string | null;
+}
+interface ResolveHealthOptions {
+    /** 项目根目录 */
+    rootDir: string;
+    /** 日志目录，默认 `<rootDir>/logs` */
+    logDir?: string;
+    /**
+     * 本栈是否包含 Node 服务端。
+     * false（vite-react / html 等 client-only 栈）时直接返回 dev server 自身状态，
+     * 行为与改造前完全一致。
+     */
+    hasServer: boolean;
+    /** dev server 自身是否已 listen */
+    clientReady: boolean;
+    /** 本次 dev 会话首次拉起 server 的时间戳（ms）。缺省时不做超时判定。 */
+    firstStartedAt?: number | null;
+    /** 编译产物入口，默认 `<rootDir>/dist/server/main.js` */
+    serverEntry?: string;
+    /** 超时上限（ms），超过则判 failed。默认 300000。 */
+    timeoutMs?: number;
+    /**
+     * 本次 dev 会话的启动时间（ms），用于排除 pid 复用导致的陈旧 marker。
+     * 与 `firstStartedAt` 分开：后者是「超时从何时起算」的锚点，崩溃后会前移。
+     */
+    sessionStartedAt?: number | null;
+    /** 探测到 server 存活时回调，供宿主记录「最后一次存活时刻」 */
+    onServerAlive?: () => void;
+    /** 注入点，便于测试 */
+    now?: () => number;
+}
+
+/**
+ * 判定应用健康状态。
+ *
+ * 设计原则：**`failed: true` 只能由肯定性事实触发，绝不能由否定性推断触发。**
+ * 「读不到日志」「匹配不到 marker」「产物看不见」都属于否定性推断，
+ * 一律降级为「还在启动」（`ready:false, failed:false`），让外壳继续等。
+ * 只有「超过 timeoutMs 仍未就绪」这一个时间事实可以判 failed。
+ */
+declare function resolveHealth(options: ResolveHealthOptions): HealthPayload;
+
+/**
+ * `process.kill(pid, 0)` 不发信号，只做存在性检查。
+ * EPERM 表示进程存在但当前用户无权发信号 —— 仍算存活。
+ */
+declare function isPidAlive(pid: number): boolean;
+/**
+ * 判定 Nest 服务当前是否存活。
+ *
+ * 两步都是「肯定性事实」：
+ *   1. 日志里存在 listen marker  → 曾经成功启动过（匹配不到就不下结论）
+ *   2. 该 marker 的 pid 仍然存活 → 现在确实还活着
+ *
+ * 只有第 1 步会导致误判：`dev.js` 以 append 模式写日志，历史成功记录会长期留存，
+ * 因此第 2 步的 pid 验活不可省略。
+ *
+ * `sessionStartedAt` 用于排除 pid 复用：marker 时间早于本次会话启动时间的，一律不采信。
+ */
+declare function resolveServerLiveness(logDir: string, sessionStartedAt?: number | null): ServerLiveness;
+
+/** 沙箱外壳探测的是固定根路径，不跟 clientBasePath 走 */
+declare const HEALTH_ENDPOINT = "/dev/health";
+interface HealthHandlerOptions {
+    /** 项目根目录 */
+    rootDir: string;
+    /** 日志目录，默认 `<rootDir>/logs` */
+    logDir?: string;
+    /** 本栈是否包含 Node 服务端 */
+    hasServer: boolean;
+    /** dev server 自身是否已 listen（由各 preset 注入） */
+    isClientReady: () => boolean;
+    /** 超时上限（ms）；未传时读环境变量 MIAODA_HEALTH_TIMEOUT_MS，再兜底 5min */
+    timeoutMs?: number;
+}
+/**
+ * 构造一个有状态的健康探测函数。宿主自行决定怎么把结果写进响应
+ * （Express 用 `res.status().json()`，Connect/Vite 用 `res.end()`）。
+ *
+ * 之所以有状态：超时窗口必须从「最后一次确认存活」起算，而不是从会话启动起算。
+ * 否则一个健康跑了 10 分钟的服务一旦崩溃，会因为 `now - firstStartedAt` 早已超限
+ * 而被**立刻**判成终态失败，supervisor 连重启的机会都没有。
+ *
+ * 判定本身出任何错都降级为「还在启动」——health 是旁路能力，
+ * 绝不能因为它自己的异常而让外壳误判失败、阻塞用户启动。
+ */
+declare function createHealthProbe(options: HealthHandlerOptions): () => HealthPayload;
+/**
+ * 单次计算健康状态（无状态版本）。
+ * 长驻宿主请用 {@link createHealthProbe}，它会正确处理「崩溃后重新计时」。
+ */
+declare function getHealthPayload(options: HealthHandlerOptions): HealthPayload;
+/**
+ * 构造 `/dev/health` 的 Connect / Vite 中间件。
+ *
+ * 响应码恒 200：`connection refused` / `timeout` 已被外壳用来表示
+ * 「dev server 自身没起来 → 重启沙箱」，应用级失败必须走 body，
+ * 否则会和传输层失败混淆。
+ */
+declare function createHealthHandler(options: HealthHandlerOptions): (req: IncomingMessage, res: ServerResponse, next?: () => void) => void;
+
 interface PageRouteInfo {
     path?: string;
     index?: boolean;
@@ -300,4 +427,4 @@ declare function parseRoutesFromFile(appPath: string, basePath: string, options?
     path: string;
 }>;
 
-export { type GlobalMiddleware, type Middleware, type MiddlewareContext, type Options, type PageRouteInfo, type ParseRoutesOptions, type RouteInfo, type RouteMiddleware, buildFullPath, calculateFileHash, createCollectLogsMiddleware, createDevLogsMiddleware, createOpenapiMiddleware, evaluateTemplateLiteral, extractPageRouteInfo, getQuery, getQueryParam, handleDevProxyError, isRouteComponent, normalizeBasePath, parseAndGenerateNestResourceTemplate, parseApiRoutes, parseRoutesFromFile, postprocessDrizzleSchema, registerMiddlewares, routeParserLog, sendError, sendJson, sendSuccess };
+export { type GlobalMiddleware, HEALTH_ENDPOINT, type HealthHandlerOptions, type HealthPayload, type Middleware, type MiddlewareContext, type Options, type PageRouteInfo, type ParseRoutesOptions, type ResolveHealthOptions, type RouteInfo, type RouteMiddleware, type ServerLiveness, buildFullPath, calculateFileHash, createCollectLogsMiddleware, createDevLogsMiddleware, createHealthHandler, createHealthProbe, createOpenapiMiddleware, evaluateTemplateLiteral, extractPageRouteInfo, getHealthPayload, getQuery, getQueryParam, handleDevProxyError, isPidAlive, isRouteComponent, normalizeBasePath, parseAndGenerateNestResourceTemplate, parseApiRoutes, parseRoutesFromFile, postprocessDrizzleSchema, registerMiddlewares, resolveHealth, resolveServerLiveness, routeParserLog, sendError, sendJson, sendSuccess };

package/dist/index.js

@@ -1610,8 +1610,8 @@ function hasSpecialPatterns(pattern) {
   return /[{*]/.test(pattern);
 }
 __name(hasSpecialPatterns, "hasSpecialPatterns");
-function normalizePathForMatching(path5) {
-  return path5.replace(/\/+/g, "/").replace(/\/+$/, "");
+function normalizePathForMatching(path8) {
+  return path8.replace(/\/+/g, "/").replace(/\/+$/, "");
 }
 __name(normalizePathForMatching, "normalizePathForMatching");
 
@@ -2160,7 +2160,7 @@ __name(readLogsBySource, "readLogsBySource");
 // src/middlewares/dev-logs/services/trigger.service.ts
 import { createReadStream as createReadStream3 } from "fs";
 import { createInterface as createInterface3 } from "readline";
-async function readTriggerList(filePath, trigger, path5, limit, triggerID) {
+async function readTriggerList(filePath, trigger, path8, limit, triggerID) {
   if (!await fileExists(filePath)) {
     return void 0;
   }
@@ -2186,7 +2186,7 @@ async function readTriggerList(filePath, trigger, path5, limit, triggerID) {
     if (alreadyAdded) {
       return false;
     }
-    const isAutomationTrigger = builder.path?.endsWith(path5);
+    const isAutomationTrigger = builder.path?.endsWith(path8);
     if (!isAutomationTrigger) {
       return false;
     }
@@ -2269,7 +2269,7 @@ async function readTriggerList(filePath, trigger, path5, limit, triggerID) {
   };
 }
 __name(readTriggerList, "readTriggerList");
-async function readTriggerDetail(filePath, path5, instanceID) {
+async function readTriggerDetail(filePath, path8, instanceID) {
   const exists = await fileExists(filePath);
   if (!exists) {
     return void 0;
@@ -2285,7 +2285,7 @@ async function readTriggerDetail(filePath, path5, instanceID) {
   for await (const line of rl) {
     const entry = parseLogLine(line);
     if (!entry) continue;
-    const isAutomationTrigger = entry.path?.endsWith(path5);
+    const isAutomationTrigger = entry.path?.endsWith(path8);
     const hasInstanceID = entry.instance_id === instanceID && entry.trigger;
     if (!isAutomationTrigger || !hasInstanceID) continue;
     matches.push(entry);
@@ -2539,16 +2539,16 @@ function createGetTriggerListHandler(logDir) {
       });
     }
     const triggerID = typeof req.query.triggerID === "string" ? req.query.triggerID.trim() : void 0;
-    const path5 = typeof req.query.path === "string" ? req.query.path.trim() : "/__innerapi__/automation/invoke";
+    const path8 = typeof req.query.path === "string" ? req.query.path.trim() : "/__innerapi__/automation/invoke";
     const limit = parseLimit(req.query.limit, 10, 200);
     try {
-      const result = await readTriggerList(traceLogPath, trigger, path5, limit, triggerID);
+      const result = await readTriggerList(traceLogPath, trigger, path8, limit, triggerID);
       if (!result) {
         return handleNotFound(res, traceLogPath);
       }
       res.json({
         file: getRelativePath(traceLogPath),
-        path: path5,
+        path: path8,
         ...result
       });
     } catch (error) {
@@ -2566,9 +2566,9 @@ function createGetTriggerDetailHandler(logDir) {
         message: "instanceID is required"
       });
     }
-    const path5 = typeof req.query.path === "string" ? req.query.path.trim() : "/__innerapi__/automation/invoke";
+    const path8 = typeof req.query.path === "string" ? req.query.path.trim() : "/__innerapi__/automation/invoke";
     try {
-      const result = await readTriggerDetail(traceLogPath, path5, instanceID);
+      const result = await readTriggerDetail(traceLogPath, path8, instanceID);
       if (!result) {
         return handleNotFound(res, traceLogPath);
       }
@@ -3194,8 +3194,8 @@ __name(createSSEHandler, "createSSEHandler");
 
 // src/middlewares/dev-logs/api-list-handler.ts
 var SERVER_PORT = process.env.SERVER_PORT || "3000";
-function extractModuleFromPath(path5) {
-  const segments = path5.split("/").filter(Boolean);
+function extractModuleFromPath(path8) {
+  const segments = path8.split("/").filter(Boolean);
   let startIndex = 0;
   if (segments[0] === "api") {
     startIndex = 1;
@@ -3210,8 +3210,8 @@ function extractModuleFromPath(path5) {
   return moduleName;
 }
 __name(extractModuleFromPath, "extractModuleFromPath");
-function generateRouteId(method, path5) {
-  const cleanPath = path5.replace(/[/:]/g, "_").replace(/^_+|_+$/g, "");
+function generateRouteId(method, path8) {
+  const cleanPath = path8.replace(/[/:]/g, "_").replace(/^_+|_+$/g, "");
   return `${method.toLowerCase()}_${cleanPath}`;
 }
 __name(generateRouteId, "generateRouteId");
@@ -3685,17 +3685,217 @@ function registerMiddlewares(server, middlewares, options) {
   }
 }
 __name(registerMiddlewares, "registerMiddlewares");
+
+// src/health/resolve.ts
+import fs11 from "fs";
+import path6 from "path";
+
+// src/health/server-liveness.ts
+import fs10 from "fs";
+import path5 from "path";
+var TAIL_BYTES = 64 * 1024;
+function isListenMarker(line) {
+  const message = String(line.message ?? "");
+  if (line.context === "Bootstrap" && message.startsWith("Server running on")) {
+    return true;
+  }
+  return line.context === "PlatformHealth" && message.startsWith("listening");
+}
+__name(isListenMarker, "isListenMarker");
+function readLastListenMarker(logFile) {
+  let fd;
+  try {
+    const size = fs10.statSync(logFile).size;
+    if (size === 0) return null;
+    const length = Math.min(size, TAIL_BYTES);
+    const buf = Buffer.alloc(length);
+    fd = fs10.openSync(logFile, "r");
+    fs10.readSync(fd, buf, 0, length, size - length);
+    const lines = buf.toString("utf8").split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const raw = lines[i].trim();
+      if (!raw.startsWith("{")) continue;
+      try {
+        const parsed = JSON.parse(raw);
+        if (isListenMarker(parsed)) return parsed;
+      } catch {
+      }
+    }
+  } catch {
+  } finally {
+    if (fd !== void 0) {
+      try {
+        fs10.closeSync(fd);
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+__name(readLastListenMarker, "readLastListenMarker");
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === "EPERM";
+  }
+}
+__name(isPidAlive, "isPidAlive");
+function resolveServerLiveness(logDir, sessionStartedAt) {
+  const marker = readLastListenMarker(path5.join(logDir, "server.log"));
+  if (!marker || typeof marker.pid !== "number") {
+    return {
+      alive: false,
+      pid: null,
+      listenAt: null
+    };
+  }
+  const listenAt = typeof marker.time === "string" ? marker.time : null;
+  if (sessionStartedAt && listenAt) {
+    const markerMs = Date.parse(listenAt);
+    if (Number.isFinite(markerMs) && markerMs < sessionStartedAt - 5e3) {
+      return {
+        alive: false,
+        pid: marker.pid,
+        listenAt
+      };
+    }
+  }
+  return {
+    alive: isPidAlive(marker.pid),
+    pid: marker.pid,
+    listenAt
+  };
+}
+__name(resolveServerLiveness, "resolveServerLiveness");
+
+// src/health/resolve.ts
+var DEFAULT_TIMEOUT_MS = 5 * 60 * 1e3;
+function resolveHealth(options) {
+  const { rootDir, hasServer, clientReady, firstStartedAt, logDir = path6.join(rootDir, "logs"), serverEntry = path6.join(rootDir, "dist", "server", "main.js"), timeoutMs = DEFAULT_TIMEOUT_MS, now = Date.now, sessionStartedAt = null, onServerAlive } = options;
+  if (!hasServer) {
+    return {
+      ready: clientReady,
+      failed: false
+    };
+  }
+  const liveness = resolveServerLiveness(logDir, sessionStartedAt);
+  if (liveness.alive) {
+    onServerAlive?.();
+    return {
+      ready: clientReady,
+      failed: false
+    };
+  }
+  const elapsed = firstStartedAt ? now() - firstStartedAt : 0;
+  if (!firstStartedAt || elapsed <= timeoutMs) {
+    return {
+      ready: false,
+      failed: false
+    };
+  }
+  const seconds = Math.round(elapsed / 1e3);
+  const compiled = safeExists(serverEntry);
+  const message = compiled ? `\u540E\u7AEF\u670D\u52A1\u542F\u52A8\u8D85\u65F6\uFF08\u5DF2\u7B49\u5F85 ${seconds}s\uFF09\uFF1A\u7F16\u8BD1\u4EA7\u7269\u5DF2\u751F\u6210\u4F46\u670D\u52A1\u672A\u76D1\u542C\uFF0C\u8BF7\u67E5\u770B ${path6.join(logDir, "server.std.log")}` : `\u540E\u7AEF\u670D\u52A1\u7F16\u8BD1\u672A\u901A\u8FC7\uFF08\u5DF2\u7B49\u5F85 ${seconds}s\uFF09\uFF1A\u672A\u751F\u6210 ${path6.relative(rootDir, serverEntry)}\uFF0C\u8BF7\u67E5\u770B ${path6.join(logDir, "server.std.log")}`;
+  return {
+    ready: false,
+    failed: true,
+    message
+  };
+}
+__name(resolveHealth, "resolveHealth");
+function safeExists(file) {
+  try {
+    return fs11.existsSync(file);
+  } catch {
+    return false;
+  }
+}
+__name(safeExists, "safeExists");
+
+// src/health/handler.ts
+import fs12 from "fs";
+import path7 from "path";
+var HEALTH_ENDPOINT = "/dev/health";
+function resolveTimeoutMs(explicit) {
+  if (typeof explicit === "number") return explicit;
+  const raw = Number(process.env.MIAODA_HEALTH_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : void 0;
+}
+__name(resolveTimeoutMs, "resolveTimeoutMs");
+function readSessionStartedAt(logDir) {
+  try {
+    const raw = fs12.readFileSync(path7.join(logDir, "dev-status.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed.firstStartedAt === "number" ? parsed.firstStartedAt : null;
+  } catch {
+    return null;
+  }
+}
+__name(readSessionStartedAt, "readSessionStartedAt");
+function createHealthProbe(options) {
+  const logDir = options.logDir ?? path7.join(options.rootDir, "logs");
+  let lastAliveAt = null;
+  return /* @__PURE__ */ __name(function probe() {
+    try {
+      const sessionStartedAt = readSessionStartedAt(logDir);
+      const since = lastAliveAt !== null && (sessionStartedAt === null || lastAliveAt > sessionStartedAt) ? lastAliveAt : sessionStartedAt;
+      const payload = resolveHealth({
+        rootDir: options.rootDir,
+        logDir,
+        hasServer: options.hasServer,
+        clientReady: options.isClientReady(),
+        firstStartedAt: since,
+        timeoutMs: resolveTimeoutMs(options.timeoutMs),
+        onServerAlive: /* @__PURE__ */ __name(() => {
+          lastAliveAt = Date.now();
+        }, "onServerAlive")
+      });
+      return payload;
+    } catch {
+      return {
+        ready: false,
+        failed: false
+      };
+    }
+  }, "probe");
+}
+__name(createHealthProbe, "createHealthProbe");
+function getHealthPayload(options) {
+  return createHealthProbe(options)();
+}
+__name(getHealthPayload, "getHealthPayload");
+function createHealthHandler(options) {
+  const probe = createHealthProbe(options);
+  return /* @__PURE__ */ __name(function healthHandler(req, res, next) {
+    if (req.method && req.method !== "GET" && next) {
+      return next();
+    }
+    res.setHeader("Content-Type", "application/json");
+    res.setHeader("Cache-Control", "no-store");
+    res.statusCode = 200;
+    res.end(JSON.stringify(probe()));
+  }, "healthHandler");
+}
+__name(createHealthHandler, "createHealthHandler");
 export {
+  HEALTH_ENDPOINT,
   buildFullPath,
   calculateFileHash,
   createCollectLogsMiddleware,
   createDevLogsMiddleware,
+  createHealthHandler,
+  createHealthProbe,
   createOpenapiMiddleware,
   evaluateTemplateLiteral,
   extractPageRouteInfo,
+  getHealthPayload,
   getQuery,
   getQueryParam,
   handleDevProxyError,
+  isPidAlive,
   isRouteComponent,
   normalizeBasePath,
   parseAndGenerateNestResourceTemplate,
@@ -3703,6 +3903,8 @@ export {
   parseRoutesFromFile,
   postprocessDrizzleSchema,
   registerMiddlewares,
+  resolveHealth,
+  resolveServerLiveness,
   routeParserLog,
   sendError,
   sendJson,