@aipanel/core 1.2.9 → 1.2.10

package/es/client/logger.mjs

@@ -1,18 +1,12 @@
 import { LOG_PREFIX } from "../common/constants.mjs";
 import {
+  LEVEL_NAMES,
   LogLevel,
   getConfig,
   getTimestamp,
   formatContext,
   formatValue
 } from "../common/logger-core.mjs";
-const LEVEL_NAMES = {
-  [LogLevel.DEBUG]: "DEBUG",
-  [LogLevel.INFO]: "INFO ",
-  [LogLevel.WARN]: "WARN ",
-  [LogLevel.ERROR]: "ERROR",
-  [LogLevel.NONE]: "NONE "
-};
 const C = {
   dim: "color: #888",
   bright: "font-weight: bold",
@@ -39,7 +33,7 @@ function log(level, message, context, ...args) {
     segments.push("%c%s");
     styles.push(C.dim, getTimestamp());
   }
-  segments.push(`%c${LEVEL_NAMES[level]}`);
+  segments.push(`%c${LEVEL_NAMES[level].padEnd(5)}`);
   styles.push(LEVEL_COLORS[level]);
   segments.push(`%c${LOG_PREFIX}`);
   styles.push(C.bright);

package/es/client/storage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 浏览器存储辅助（window.localStorage/sessionStorage，仅 client 端；通过 @aipanel/core/client 导出）
+ */
+/**
+ * 安全读取浏览器存储（JSON 解码；不可用/异常返回 null）
+ */
+export declare function storageGet<T>(area: "local" | "session", key: string): T | null;
+/**
+ * 安全写入浏览器存储（JSON 序列化；异常忽略）
+ */
+export declare function storageSet(area: "local" | "session", key: string, value: unknown): void;
+/**
+ * 安全删除浏览器存储项
+ */
+export declare function storageRemove(area: "local" | "session", key: string): void;

package/es/client/storage.mjs

@@ -0,0 +1,33 @@
+function storageArea(area) {
+  try {
+    if (typeof window === "undefined") return void 0;
+    return area === "local" ? window.localStorage : window.sessionStorage;
+  } catch {
+    return void 0;
+  }
+}
+function storageGet(area, key) {
+  try {
+    const raw = storageArea(area)?.getItem(key);
+    return raw == null ? null : JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function storageSet(area, key, value) {
+  try {
+    storageArea(area)?.setItem(key, JSON.stringify(value));
+  } catch {
+  }
+}
+function storageRemove(area, key) {
+  try {
+    storageArea(area)?.removeItem(key);
+  } catch {
+  }
+}
+export {
+  storageGet,
+  storageRemove,
+  storageSet
+};

package/es/client/theme.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 浏览器主题辅助（依赖 window.matchMedia，仅 client 端使用；通过 @aipanel/core/client 导出）
+ */
+import type { AIPanelWidgetTheme } from "../common/types";
+/**
+ * 当前系统主题（仅浏览器有效；SSR/无 window 环境返回 light）
+ */
+export declare function getSystemTheme(): "light" | "dark";
+/**
+ * 挂件主题偏好解析：auto 按系统主题折算为 light/dark
+ * @param theme - 挂件主题偏好（AIPanelWidgetTheme）
+ * @param system - 系统主题（默认当前系统）
+ * @returns 实际应用主题
+ */
+export declare function resolveWidgetTheme(theme: AIPanelWidgetTheme, system?: "light" | "dark"): "light" | "dark";

package/es/client/theme.mjs

@@ -0,0 +1,11 @@
+function getSystemTheme() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function resolveWidgetTheme(theme, system = getSystemTheme()) {
+  return theme === "auto" ? system : theme;
+}
+export {
+  getSystemTheme,
+  resolveWidgetTheme
+};

package/es/client.d.ts

@@ -1 +1,3 @@
 export * from "./client/logger";
+export * from "./client/storage";
+export * from "./client/theme";

package/es/client.mjs

@@ -1 +1,3 @@
 export * from "./client/logger.mjs";
+export * from "./client/storage.mjs";
+export * from "./client/theme.mjs";

package/es/common/constants.d.ts

@@ -122,6 +122,8 @@ export declare const BRIDGE_SCRIPT_PATH = "/__aipanel_bridge__.js";
 export declare const LOGS_API_PATH = "/__aipanel_process_logs__";
 /** Widget 样式路径 */
 export declare const WIDGET_STYLE_PATH = "/__aipanel_widget__.css";
+/** Vue DevTools API 路径 */
+export declare const VUE_DEVTOOLS_API_PATH = "/__aipanel_vue_devtools__";
 /** ==================== 文本处理 ==================== */
 /** 元素文本最大显示长度 */
 export declare const MAX_TEXT_LENGTH = 100;
@@ -138,16 +140,6 @@ export declare const PAGE_CONTEXT_MAX_TEXT_LENGTH = 10000;
  */
 export declare const SEVERITY_ERROR = 1;
 export declare const SEVERITY_WARN = 2;
-/** ==================== VS Code 扩展桥接 ==================== */
-/** VS Code 扩展 HTTP 服务端口（vscode-extension ↔ provider 通信协议） */
-export declare const VSCODE_EXTENSION_PORT = 51939;
-/** VS Code 扩展 HTTP 路由：健康检查 */
-export declare const VSCODE_ROUTE_HEALTH = "/health";
-/** VS Code 扩展 HTTP 路由：文件格式化 */
-export declare const VSCODE_ROUTE_FORMAT = "/format";
-/** VS Code 扩展相关环境变量名 */
-export declare const ENV_VSCODE_MODE = "AIPANEL_VSCODE_MODE";
-export declare const ENV_VSCODE_PORT = "AIPANEL_VSCODE_PORT";
 /** ==================== Vue DevTools API ==================== */
 /** Vue DevTools API action 名称 */
 export declare const VUE_DEVTOOLS_ACTIONS: {
@@ -159,3 +151,31 @@ export declare const VUE_DEVTOOLS_ACTIONS: {
     readonly GET_ROUTER_INFO: "getRouterInfo";
 };
 export type VueDevtoolsAction = (typeof VUE_DEVTOOLS_ACTIONS)[keyof typeof VUE_DEVTOOLS_ACTIONS];
+/** ==================== 写类工具名单 ==================== */
+/** 会修改文件的工具名（host 插件与编辑后自动诊断共用的单一来源） */
+export declare const MUTATING_TOOLS: ReadonlySet<string>;
+/** ==================== 挂件主题 ==================== */
+/** 挂件主题可选值（对应 AIPanelWidgetTheme） */
+export declare const WIDGET_THEME_MODES: readonly ["auto", "light", "dark"];
+/** ==================== OpenCode 环境变量名 ==================== */
+/** OpenCode 相关环境变量名（opencode provider 写、es/plugins 与 dsh-plugin 读，统一引用防止字面量漂移） */
+export declare const OPENCODE_ENV: {
+    readonly CONFIG_DIR: "OPENCODE_CONFIG_DIR";
+    readonly CONTEXT_API_URL: "OPENCODE_CONTEXT_API_URL";
+    readonly VITE_LOGS_API_URL: "OPENCODE_VITE_LOGS_API_URL";
+    readonly LOG_FILES_JSON: "OPENCODE_LOG_FILES_JSON";
+    readonly VERBOSE: "OPENCODE_VERBOSE";
+    readonly ENABLE_LINT: "OPENCODE_ENABLE_LINT";
+    readonly VUE_DEVTOOLS_API_URL: "OPENCODE_VUE_DEVTOOLS_API_URL";
+    readonly WORKSPACE: "OPENCODE_WORKSPACE";
+};
+/** ==================== SSE 事件流消息类型 ==================== */
+/** 服务端 → 客户端 SSE 信封 type 字段（vite endpoints 写、client useServerSSE 读） */
+export declare const SSE_EVENT_TYPES: {
+    readonly CONNECTED: "CONNECTED";
+    readonly STATUS_SYNC: "STATUS_SYNC";
+    readonly TASK_UPDATE: "TASK_UPDATE";
+    readonly SESSION_EVENT: "SESSION_EVENT";
+    readonly CLEAR_ELEMENTS: "CLEAR_ELEMENTS";
+};
+export type SSEEventType = (typeof SSE_EVENT_TYPES)[keyof typeof SSE_EVENT_TYPES];

package/es/common/constants.mjs

@@ -66,17 +66,13 @@ const WARMUP_API_PATH = "/__aipanel_warmup__";
 const BRIDGE_SCRIPT_PATH = "/__aipanel_bridge__.js";
 const LOGS_API_PATH = "/__aipanel_process_logs__";
 const WIDGET_STYLE_PATH = "/__aipanel_widget__.css";
+const VUE_DEVTOOLS_API_PATH = "/__aipanel_vue_devtools__";
 const MAX_TEXT_LENGTH = 100;
 const CONTEXT_MARKER = "[\u5143\u7D20\u4E0A\u4E0B\u6587]";
 const PAGE_CONTEXT_MARKER = "__AIPANEL_CONTEXT__";
 const PAGE_CONTEXT_MAX_TEXT_LENGTH = 1e4;
 const SEVERITY_ERROR = 1;
 const SEVERITY_WARN = 2;
-const VSCODE_EXTENSION_PORT = 51939;
-const VSCODE_ROUTE_HEALTH = "/health";
-const VSCODE_ROUTE_FORMAT = "/format";
-const ENV_VSCODE_MODE = "AIPANEL_VSCODE_MODE";
-const ENV_VSCODE_PORT = "AIPANEL_VSCODE_PORT";
 const VUE_DEVTOOLS_ACTIONS = {
   GET_COMPONENT_TREE: "getComponentTree",
   GET_COMPONENT_STATE: "getComponentState",
@@ -85,6 +81,25 @@ const VUE_DEVTOOLS_ACTIONS = {
   TOGGLE_APP: "toggleApp",
   GET_ROUTER_INFO: "getRouterInfo"
 };
+const MUTATING_TOOLS = /* @__PURE__ */ new Set(["write", "edit", "apply_patch"]);
+const WIDGET_THEME_MODES = ["auto", "light", "dark"];
+const OPENCODE_ENV = {
+  CONFIG_DIR: "OPENCODE_CONFIG_DIR",
+  CONTEXT_API_URL: "OPENCODE_CONTEXT_API_URL",
+  VITE_LOGS_API_URL: "OPENCODE_VITE_LOGS_API_URL",
+  LOG_FILES_JSON: "OPENCODE_LOG_FILES_JSON",
+  VERBOSE: "OPENCODE_VERBOSE",
+  ENABLE_LINT: "OPENCODE_ENABLE_LINT",
+  VUE_DEVTOOLS_API_URL: "OPENCODE_VUE_DEVTOOLS_API_URL",
+  WORKSPACE: "OPENCODE_WORKSPACE"
+};
+const SSE_EVENT_TYPES = {
+  CONNECTED: "CONNECTED",
+  STATUS_SYNC: "STATUS_SYNC",
+  TASK_UPDATE: "TASK_UPDATE",
+  SESSION_EVENT: "SESSION_EVENT",
+  CLEAR_ELEMENTS: "CLEAR_ELEMENTS"
+};
 export {
   AIPANEL_CACHE_DIR,
   AUTO_OPEN_DELAY,
@@ -99,8 +114,6 @@ export {
   DEFAULT_PROXY_PORT,
   DEFAULT_RETRIES,
   DEFAULT_WEB_PORT,
-  ENV_VSCODE_MODE,
-  ENV_VSCODE_PORT,
   EXT_BROADCAST,
   EXT_MSG,
   HOST_EVENTS_API_PATH,
@@ -111,7 +124,9 @@ export {
   MAX_PORT_TRIES,
   MAX_TEXT_LENGTH,
   MCP_API_PATH,
+  MUTATING_TOOLS,
   NOTIFICATION_DURATION,
+  OPENCODE_ENV,
   PAGE_CONTEXT_MARKER,
   PAGE_CONTEXT_MAX_TEXT_LENGTH,
   RETRY_DELAY,
@@ -124,13 +139,13 @@ export {
   SEVERITY_ERROR,
   SEVERITY_WARN,
   SSE_EVENTS_PATH,
+  SSE_EVENT_TYPES,
   START_API_PATH,
-  VSCODE_EXTENSION_PORT,
-  VSCODE_ROUTE_FORMAT,
-  VSCODE_ROUTE_HEALTH,
   VUE_DEVTOOLS_ACTIONS,
+  VUE_DEVTOOLS_API_PATH,
   WARMUP_API_PATH,
   WIDGET_MSG,
   WIDGET_SCRIPT_PATH,
-  WIDGET_STYLE_PATH
+  WIDGET_STYLE_PATH,
+  WIDGET_THEME_MODES
 };

package/es/common/options.d.ts

@@ -16,6 +16,30 @@ export interface ChromeMcpOptions {
     args?: string[];
     /** 透传给 chrome-devtools-mcp 进程的额外环境变量（合并到 process.env 之上） */
     env?: Record<string, string>;
+    /** 项目边界策略（默认缺失 = 现状行为） */
+    project?: ChromeProjectOptions;
+}
+/**
+ * 项目边界策略（chrome-devtools-mcp 工具层的“本项目内操作”可配选项，默认均为现状）。
+ * 所有项只会收窄/放宽我们的边界判定，不改变白名单的权威性。
+ */
+export interface ChromeProjectOptions {
+    /**
+     * 白名单条目：除自动项目页外，可开启/可见/可操作的额外页面。每条三种写法：
+     * - 精确 origin："https://example.com"（前缀匹配该 origin 下任意路径）
+     * - glob 通配符："https://*.example.com/**"（picomatch，* 不跨 /，放开路径需 /**）
+     * - 正则字面量："/^https:\\/\\/app\\.example\\.com\\//"（以 / 起止、可带 flags，对完整 URL 匹配）
+     */
+    allowOrigins?: string[];
+    /** 是否允许扩展页（chrome-extension://）纳入可操作页面；启用时自动注入 --experimental-include-all-pages */
+    includeExtensionPages?: boolean;
+    /** 工具面选择：在默认白名单上按名字调整 */
+    tools?: {
+        /** 从默认白名单隐藏（如 ["upload_file"]） */
+        deny?: string[];
+        /** 仅可开启官方二级目录中的工具（如 click_at）；非目录名将被忽略并告警 */
+        extra?: string[];
+    };
 }
 /**
  * 插件配置选项

package/es/common/types.d.ts

@@ -2,6 +2,7 @@
  * 通用类型（Provider 无关）
  * Provider 专属类型已下沉至 @aipanel/provider-opencode。
  */
+import type { SessionStatus } from "./provider";
 /**
  * 展示模式类型
  */
@@ -123,9 +124,9 @@ export type AIPanelWidgetTheme = "light" | "dark" | "auto";
  */
 export type ServiceStatus = "idle" | "starting" | "ready" | "partial" | "failed";
 /**
- * Session 状态类型
+ * Session 状态类型（别名：以 ./provider 的 SessionStatus 为单一来源）
  */
-export type AIPanelSessionStatusType = "idle" | "running" | "streaming" | "completed";
+export type AIPanelSessionStatusType = SessionStatus;
 /**
  * Session 思考状态
  */
@@ -146,19 +147,9 @@ export interface AIPanelWidgetSession {
     url?: string;
 }
 /**
- * 挂件选中的元素
+ * 挂件选中的元素（别名：与 host 端 SelectedElement 同构，单一来源为本文件上方的 SelectedElement）
  */
-export interface AIPanelSelectedElement {
-    /** 节点唯一 id（与 SelectedElement.id 同源，`@节点[n<id>]` 标记与上下文注入共用） */
-    id?: string;
-    filePath: string | null;
-    line: number | null;
-    column: number | null;
-    innerText: string;
-    description?: string;
-    /** 用户选中节点时的页面 URL（AIPanel 附加；host 端上下文注入用） */
-    previewPageUrl?: string;
-}
+export type AIPanelSelectedElement = SelectedElement;
 /**
  * 单条代码诊断（1-based 行列坐标）——AIPanel 诊断工具（run_diagnostics 等）的
  * canonical 持久化/展示共用协议：宿主插件写 tool/result.meta，client 插件据此渲染卡片。

package/es/common/utils.d.ts

@@ -1,6 +1,3 @@
-/**
- * @fileoverview 通用工具函数
- */
 /**
  * 取（或生成）元素的节点唯一 id：优先复用已赋值的 id，否则生成随机 id 并写回元素。
  * 同一引用在会话标记（`@节点[n<id>]`）与上下文注入里使用同一个 id；
@@ -42,3 +39,29 @@ export declare function base64Decode(base64: string): string;
  * 支持多种常见响应格式
  */
 export declare function extractTextFromResponse(data: unknown): string | null;
+/**
+ * 生成节点提及标记 `@节点[n<id>]`（与 ensureNodeId 分配的 n<hex> id 体系一致）
+ */
+export declare function toNodeMention(id: string): string;
+/**
+ * 从文本中提取全部节点提及 id（去重、保序）
+ */
+export declare function parseNodeMentions(text: string): string[];
+/**
+ * 构造 iframe postMessage 信封：{ type, ...data }（AIPanel 挂件与 dsh-client 共用同一形状）
+ */
+export declare function widgetEnvelope(type: string, data?: Record<string, unknown>): Record<string, unknown>;
+/** 重试配置 */
+export interface RetryOptions {
+    /** 总尝试次数（默认 core DEFAULT_RETRIES） */
+    attempts?: number;
+    /** 失败后连续尝试间隔毫秒（默认 core RETRY_DELAY） */
+    delayMs?: number;
+    /** 每次失败、重试前回调（attempt 为 1-based） */
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+/**
+ * 带线性重试的执行包裹：执行 fn 直到成功或尝试完毕；最后一次失败原样抛出。
+ * 环境无关（仅使用 setTimeout），放于 common 供浏览器与 node 共用。
+ */
+export declare function withRetries<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;

package/es/common/utils.mjs

@@ -1,3 +1,4 @@
+import { DEFAULT_RETRIES, RETRY_DELAY } from "./constants.mjs";
 function ensureNodeId(element) {
   if (element.id) return element.id;
   const random = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID().replace(/-/g, "").slice(0, 8) : Math.random().toString(36).slice(2, 10);
@@ -50,11 +51,51 @@ function extractTextFromResponse(data) {
   }
   return null;
 }
+const NODE_MENTION_RE = /@节点\[(n[0-9a-z]+)\]/g;
+function toNodeMention(id) {
+  return `@\u8282\u70B9[${id}]`;
+}
+function parseNodeMentions(text) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(NODE_MENTION_RE)) {
+    const id = m[1];
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push(id);
+    }
+  }
+  return out;
+}
+function widgetEnvelope(type, data) {
+  return { type, ...data };
+}
+async function withRetries(fn, options = {}) {
+  const attempts = options.attempts ?? DEFAULT_RETRIES;
+  const delayMs = options.delayMs ?? RETRY_DELAY;
+  let lastError;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn(i);
+    } catch (e) {
+      lastError = e;
+      if (i < attempts - 1) {
+        options.onRetry?.(i + 1, e);
+        if (delayMs > 0) await sleep(delayMs);
+      }
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
 export {
   base64Decode,
   base64Encode,
   ensureNodeId,
   extractTextFromResponse,
+  parseNodeMentions,
   sleep,
-  truncate
+  toNodeMention,
+  truncate,
+  widgetEnvelope,
+  withRetries
 };

package/es/node/diagnostics.d.ts

@@ -1,5 +1,10 @@
 /** 是否为可诊断的源码文件（供宿主钩子过滤 edit/write 目标） */
 export declare function isJsFile(filePath: string): boolean;
+/**
+ * run_diagnostics 工具描述（单一来源，供 opencode / dsh 两侧插件引用）：
+ * 只声明能力与支持的文件类型，不涉及内部使用的检查工具。
+ */
+export declare const DIAGNOSTICS_TOOL_DESCRIPTION: string;
 /** LSP 风格诊断项（供宿主写入 metadata.diagnostics 等结构化输出） */
 export interface DiagnosticItem {
     /** 所属文件路径（相对/绝对，按来源解析）；跨文件诊断（全量模式）时必有 */

package/es/node/diagnostics.mjs

@@ -19,6 +19,19 @@ const JS_EXTENSIONS = /* @__PURE__ */ new Set([
 function isJsFile(filePath) {
   return JS_EXTENSIONS.has(path.extname(filePath));
 }
+const DIAGNOSTICS_TOOL_DESCRIPTION = [
+  "\u8FD0\u884C ESLint \u4E0E TypeScript \u7C7B\u578B\u8BCA\u65AD\uFF0C\u8FD4\u56DE\u8BCA\u65AD\u7ED3\u679C\u3002",
+  "",
+  "**\u652F\u6301\u7684\u6587\u4EF6\u7C7B\u578B**\uFF1A",
+  `- ESLint\uFF1AJavaScript / TypeScript / Vue \u6E90\u7801\uFF08${[...JS_EXTENSIONS].map((e) => `*${e}`).join(" ")}\uFF09`,
+  "- TypeScript \u7C7B\u578B\u68C0\u67E5\uFF1A*.ts *.tsx *.vue",
+  "",
+  "**\u4F55\u65F6\u4F7F\u7528\u6B64\u5DE5\u5177**\uFF1A",
+  "- \u521A\u5B8C\u6210\u4EE3\u7801\u4FEE\u6539\uFF0C\u60F3\u9A8C\u8BC1\u662F\u5426\u6709 ESLint \u9519\u8BEF\u6216\u7C7B\u578B\u9519\u8BEF",
+  "- \u5728\u63D0\u4EA4\u4EE3\u7801\u524D\u8FDB\u884C\u8D28\u91CF\u68C0\u67E5",
+  "- \u6392\u67E5\u7F16\u8F91\u5668\u672A\u663E\u793A\u4F46\u5B9E\u9645\u5B58\u5728\u7684\u7C7B\u578B\u95EE\u9898",
+  "- \u4E0D\u4F20\u53C2\u6570\u53EF\u5168\u91CF\u8BCA\u65AD\u6574\u4E2A\u9879\u76EE"
+].join("\n");
 let ESLintClass;
 function loadESLint(workspace) {
   if (ESLintClass) return;
@@ -34,7 +47,12 @@ function loadESLint(workspace) {
 }
 async function lintFiles(pattern, cwd, warnLimit = 5) {
   loadESLint(cwd);
-  if (!ESLintClass) return {};
+  if (!ESLintClass) {
+    return {
+      text: `[ESLint] \u672A\u8FD0\u884C\uFF1A\u65E0\u6CD5\u5728 workspace "${cwd}" \u89E3\u6790\u5230 eslint\uFF08\u4EC5\u663E\u793A TypeScript \u8BCA\u65AD\uFF09`,
+      diagnostics: []
+    };
+  }
   try {
     const eslint = new ESLintClass({ cwd });
     const results = await eslint.lintFiles(pattern);
@@ -82,7 +100,10 @@ async function lintFiles(pattern, cwd, warnLimit = 5) {
     return { text: lines.length > 0 ? lines.join("\n") : void 0, diagnostics };
   } catch (err) {
     log.warn("ESLint failed", { pattern, error: err.message });
-    return {};
+    return {
+      text: `[ESLint] \u8FD0\u884C\u5931\u8D25\uFF1A${err.message}\uFF08\u4EC5\u663E\u793A TypeScript \u8BCA\u65AD\uFF09`,
+      diagnostics: []
+    };
   }
 }
 let _vueTscBin;
@@ -255,6 +276,7 @@ function formatDiagnosticsSections(title, eslintOutput, tscOutput) {
 ` + parts.join("\n\n");
 }
 export {
+  DIAGNOSTICS_TOOL_DESCRIPTION,
   findAllTsconfigDirs,
   findTsconfigDir,
   formatDiagnosticsSections,

package/es/node/node-logger.mjs

@@ -3,8 +3,10 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 import { LOG_PREFIX } from "../common/constants.mjs";
 import {
+  LEVEL_NAMES,
   LogLevel,
   getConfig,
+  getTimestamp,
   formatContext,
   formatValue,
   generateTraceId as _generateTraceId
@@ -28,21 +30,6 @@ const LEVEL_COLORS = {
   [LogLevel.ERROR]: COLORS.red,
   [LogLevel.NONE]: COLORS.reset
 };
-const LEVEL_NAMES = {
-  [LogLevel.DEBUG]: "DEBUG",
-  [LogLevel.INFO]: "INFO",
-  [LogLevel.WARN]: "WARN",
-  [LogLevel.ERROR]: "ERROR",
-  [LogLevel.NONE]: "NONE"
-};
-function getTimestamp() {
-  const now = /* @__PURE__ */ new Date();
-  const hours = String(now.getHours()).padStart(2, "0");
-  const minutes = String(now.getMinutes()).padStart(2, "0");
-  const seconds = String(now.getSeconds()).padStart(2, "0");
-  const ms = String(now.getMilliseconds()).padStart(3, "0");
-  return `${hours}:${minutes}:${seconds}.${ms}`;
-}
 function getCallerInfo(depth = 3) {
   const stack = new Error().stack;
   if (!stack) return "";

package/es/node/node-utils.d.ts

@@ -26,3 +26,44 @@ export declare function isPortAvailable(port: number, hostname?: string): Promis
  * 从 startPort 开始寻找可用端口
  */
 export declare function findAvailablePort(startPort: number, hostname?: string, maxTries?: number): Promise<number>;
+/**
+ * 可等待的进程接口（ResultPromise 等匹配就够）
+ */
+export interface WaitableProcess {
+    exitCode: number | null | undefined;
+}
+/**
+ * 轮询等待服务准备就绪（HTTP 状态码 < 500 即当作 ready）；超时或进程退出时 reject
+ * @param url - 检查的服务 URL
+ * @param timeout - 超时毫秒数
+ * @param proc - 可选进程，提前退出时直接失败
+ */
+export declare function waitForServer(url: string, timeout?: number, proc?: WaitableProcess): Promise<void>;
+/**
+ * 从指定目录往上查找 .git 根目录（找不到时返回起始目录）
+ */
+export declare function findGitRoot(startDir: string, maxDepth?: number): string;
+/**
+ * 检查某 CLI 是否安装（运行 <bin> --version，退出码 0 即存在）
+ */
+export declare function checkCliInstalled(bin: string): Promise<boolean>;
+/**
+ * 获取某 CLI 版本号（<bin> --version 的第一行，败路返回 null）
+ */
+export declare function getCliVersion(bin: string): Promise<string | null>;
+/** 孤儿进程清理配置（提供商的 check/kill 统一实现） */
+export interface KillOrphanCliOptions {
+    /** 进程命令行/参数中需匹配的子串（如 opencode / dsh） */
+    match: string;
+    /** Windows wmic 按名称查询的进程名（如 opencode.exe / node.exe） */
+    winName: string;
+    /** 超时毫秒（默认 5000） */
+    timeout?: number;
+    /** 运行名（仅用于日志，默认等于 match） */
+    label?: string;
+}
+/**
+ * 清理被 reparent 到 init（PPID=1）的孤儿进程（win: wmic+taskkill；unix: ps+kill）
+ * @returns 被成功结束的进程数
+ */
+export declare function killOrphanCliProcesses(bin: string, options: KillOrphanCliOptions): Promise<number>;