@bbyx0011/ghostcode 0.1.0

package/bin/ghostcode-mcp

@@ -0,0 +1,11 @@
+#!/bin/sh
+# ghostcode-mcp 平台检测启动器
+# 自动选择当前平台对应的 MCP Server 二进制并执行
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLATFORM="$(uname -s)-$(uname -m)"
+case "$PLATFORM" in
+  Darwin-arm64)  exec "$SCRIPT_DIR/ghostcode-mcp-darwin-arm64" "$@" ;;
+  Darwin-x86_64) exec "$SCRIPT_DIR/ghostcode-mcp-darwin-x64" "$@" ;;
+  Linux-x86_64)  exec "$SCRIPT_DIR/ghostcode-mcp-linux-x64" "$@" ;;
+  *) echo "[GhostCode] 不支持的平台: $PLATFORM" >&2; exit 1 ;;
+esac

package/bin/ghostcode-wrapper

@@ -0,0 +1,11 @@
+#!/bin/sh
+# ghostcode-wrapper 平台检测启动器
+# 自动选择当前平台对应的 Wrapper 二进制并执行
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLATFORM="$(uname -s)-$(uname -m)"
+case "$PLATFORM" in
+  Darwin-arm64)  exec "$SCRIPT_DIR/ghostcode-wrapper-darwin-arm64" "$@" ;;
+  Darwin-x86_64) exec "$SCRIPT_DIR/ghostcode-wrapper-darwin-x64" "$@" ;;
+  Linux-x86_64)  exec "$SCRIPT_DIR/ghostcode-wrapper-linux-x64" "$@" ;;
+  *) echo "[GhostCode] 不支持的平台: $PLATFORM" >&2; exit 1 ;;
+esac

package/dist/cli.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file cli.ts
+ * @description GhostCode CLI 入口
+ *   CLI 命令分发：init / 其他子命令
+ *   通过 process.argv 手动解析参数，不引入额外 CLI 框架依赖
+ * @author Atlas.oi
+ * @date 2026-03-04
+ */
+/**
+ * CLI 主入口函数
+ *
+ * 业务逻辑：
+ * 1. 解析 argv 获取子命令名称
+ * 2. 根据命令名分发到对应处理函数
+ * 3. 未知命令时输出帮助信息并以非零退出码退出
+ *
+ * @param argv 命令行参数（默认为 process.argv）
+ */
+declare function main(argv?: string[]): Promise<void>;
+
+export { main };

package/dist/cli.js

@@ -0,0 +1,97 @@
+import { runInitCommand } from "./cli/init.js";
+import { runDoctor, formatDoctorReport } from "./cli/doctor.js";
+const VERSION = "0.1.0";
+function printHelp() {
+  console.log(`ghostcode v${VERSION}
+
+\u7528\u6CD5\uFF1A
+  ghostcode <\u547D\u4EE4> [\u9009\u9879]
+
+\u547D\u4EE4\uFF1A
+  init      \u521D\u59CB\u5316 GhostCode \u8FD0\u884C\u73AF\u5883\uFF08\u76EE\u5F55\u3001\u4E8C\u8FDB\u5236\u3001MCP \u914D\u7F6E\uFF09
+  doctor    \u8BCA\u65AD GhostCode \u8FD0\u884C\u73AF\u5883\u5065\u5EB7\u72B6\u6001
+  help      \u663E\u793A\u6B64\u5E2E\u52A9\u4FE1\u606F
+  version   \u663E\u793A\u7248\u672C\u4FE1\u606F
+
+\u793A\u4F8B\uFF1A
+  ghostcode init              # \u521D\u59CB\u5316\u73AF\u5883
+  ghostcode init --dry-run    # \u6A21\u62DF\u8FD0\u884C\uFF0C\u4E0D\u5B9E\u9645\u4FEE\u6539\u6587\u4EF6
+  ghostcode doctor            # \u8FD0\u884C\u73AF\u5883\u8BCA\u65AD
+`);
+}
+async function handleInit(args) {
+  const dryRun = args.includes("--dry-run");
+  let mcpJsonPath;
+  const mcpJsonIdx = args.indexOf("--mcp-json");
+  if (mcpJsonIdx >= 0) {
+    mcpJsonPath = args[mcpJsonIdx + 1];
+  }
+  console.log("[GhostCode] \u5F00\u59CB\u521D\u59CB\u5316...");
+  if (dryRun) {
+    console.log("[GhostCode] \u6A21\u62DF\u8FD0\u884C\u6A21\u5F0F\uFF08--dry-run\uFF09\uFF0C\u4E0D\u4F1A\u4FEE\u6539\u6587\u4EF6");
+  }
+  const result = await runInitCommand({
+    dryRun,
+    ...mcpJsonPath !== void 0 ? { mcpJsonPath } : {}
+  });
+  if (!result.success) {
+    console.error(`[GhostCode] \u521D\u59CB\u5316\u5931\u8D25\uFF1A${result.error ?? "\u672A\u77E5\u9519\u8BEF"}`);
+    process.exit(1);
+  }
+  if (result.dirsCreated) {
+    console.log("[GhostCode] \u76EE\u5F55\u7ED3\u6784\u5DF2\u521B\u5EFA\uFF1A~/.ghostcode/ \u548C ~/.ghostcode/bin/");
+  } else {
+    console.log("[GhostCode] \u76EE\u5F55\u7ED3\u6784\u5DF2\u5B58\u5728\uFF0C\u8DF3\u8FC7\u521B\u5EFA");
+  }
+  if (result.binInstalled) {
+    console.log("[GhostCode] \u4E8C\u8FDB\u5236\u6587\u4EF6\u5B89\u88C5\u5B8C\u6210");
+  } else {
+    console.log("[GhostCode] \u4E8C\u8FDB\u5236\u6587\u4EF6\u5DF2\u5B58\u5728\uFF0C\u8DF3\u8FC7\u5B89\u88C5");
+  }
+  if (result.mcpJsonWritten) {
+    console.log("[GhostCode] .mcp.json \u914D\u7F6E\u5DF2\u66F4\u65B0");
+  }
+  console.log("[GhostCode] \u521D\u59CB\u5316\u5B8C\u6210\uFF01");
+}
+async function handleDoctor() {
+  const report = await runDoctor();
+  console.log(formatDoctorReport(report));
+  if (report.overallStatus === "FAIL") {
+    process.exit(1);
+  }
+}
+async function main(argv = process.argv) {
+  const args = argv.slice(2);
+  const command = args[0];
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log(`ghostcode v${VERSION}`);
+    return;
+  }
+  if (command === "init") {
+    await handleInit(args.slice(1));
+    return;
+  }
+  if (command === "doctor") {
+    await handleDoctor();
+    return;
+  }
+  console.error(`[GhostCode] \u672A\u77E5\u547D\u4EE4\uFF1A${command}`);
+  printHelp();
+  process.exit(1);
+}
+const isMainModule = process.argv[1] !== void 0 && (process.argv[1].endsWith("cli.js") || process.argv[1].endsWith("cli.ts"));
+if (isMainModule) {
+  main().catch((err) => {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    console.error(`[GhostCode] CLI \u53D1\u751F\u672A\u9884\u671F\u9519\u8BEF\uFF1A${errMsg}`);
+    process.exit(1);
+  });
+}
+export {
+  main
+};
+//# sourceMappingURL=cli.js.map

package/dist/daemon.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @file Daemon 生命周期管理
+ * @description 管理 GhostCode Rust Daemon 进程的启动、停止、健康检查和心跳监控。
+ *              负责读取 ~/.ghostcode/daemon/ghostcoded.addr.json 获取 Daemon 连接信息，
+ *              在 Daemon 未运行时自动 spawn 新进程，并通过心跳维持连接存活。
+ *
+ *              核心流程：
+ *              1. 读取 addr.json -> 检测 Daemon 是否在运行
+ *              2. 不存在或 ping 失败 -> spawn ghostcoded 二进制
+ *              3. 等待 addr.json 出现（最多 5s）-> ping 确认
+ *              4. 心跳每 10s 一次，连续失败 3 次触发重启
+ *
+ *              参考: crates/ghostcode-types/src/addr.rs - AddrDescriptor 数据结构
+ *              参考: crates/ghostcode-types/src/ipc.rs - IPC 协议格式
+ *              参考: crates/ghostcode-daemon/src/paths.rs - addr.json 文件路径
+ *              参考: oh-my-claudecode/src/features/rate-limit-wait/daemon.ts - spawn 模式
+ * @author Atlas.oi
+ * @date 2026-03-01
+ */
+/**
+ * 端点描述符
+ *
+ * Daemon 启动后写入 ghostcoded.addr.json 的连接信息
+ * 参考: crates/ghostcode-types/src/addr.rs:25-53
+ */
+interface AddrDescriptor {
+    /** 协议版本号，固定为 1 */
+    v: number;
+    /** 传输协议，固定为 "unix" */
+    transport: string;
+    /** Unix socket 文件路径 */
+    path: string;
+    /** Daemon 进程 ID */
+    pid: number;
+    /** GhostCode 版本号 */
+    version: string;
+    /** 启动时间 ISO 8601 UTC */
+    ts: string;
+}
+/**
+ * 确保 Daemon 在运行，返回连接地址描述符
+ *
+ * 并发安全：多个调用者同时调用时，只会 spawn 一次 Daemon。
+ * 成功缓存：Daemon 启动成功后缓存 addr，后续调用直接复用（检查进程存活）。
+ *
+ * @returns Daemon 连接地址描述符
+ * @throws 如果 Daemon 启动失败或超时
+ */
+declare function ensureDaemon(): Promise<AddrDescriptor>;
+/**
+ * 停止 GhostCode Daemon
+ *
+ * 通过 IPC 发送 shutdown 操作。如果 Daemon 未运行，静默返回（幂等）。
+ */
+declare function stopDaemon(): Promise<void>;
+/**
+ * 启动心跳监控
+ *
+ * 每 10s 向 Daemon 发送 ping，连续失败 3 次触发重启。
+ *
+ * @param addr - 当前 Daemon 连接地址
+ * @returns 停止心跳的函数
+ */
+declare function startHeartbeat(addr: AddrDescriptor): () => void;
+/**
+ * 获取 Daemon 二进制文件路径
+ *
+ * @returns Daemon 二进制文件的绝对路径
+ */
+declare function getDaemonBinaryPath(): string;
+
+export { type AddrDescriptor, ensureDaemon, getDaemonBinaryPath, startHeartbeat, stopDaemon };

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export { AddrDescriptor, ensureDaemon, getDaemonBinaryPath, startHeartbeat, stopDaemon } from './daemon.js';
+export { DaemonError, DaemonRequest, DaemonResponse, IpcConnectionError, IpcProtocolError, IpcTimeoutError, callDaemon, createConnection, resetClient } from './ipc.js';
+export { HookEventType, HookHandler, clearHooks, getHooks, registerHook } from './hooks/registry.js';
+export { initializeHooks, preToolUseHandler, stopHandler } from './hooks/handlers.js';
+import 'node:net';
+import './router/streaming.js';
+
+/**
+ * @file GhostCode Plugin 主入口
+ * @description GhostCode Claude Code Plugin 的公开 API 导出入口。
+ *              作为 TypeScript 薄壳，本文件聚合三个核心模块的导出：
+ *              - daemon: Daemon 进程管理（T17 实现）
+ *              - ipc: IPC 通信层（T18 实现）
+ *              - hooks: Claude Code Hook 注册（后续任务实现）
+ *
+ *              Plugin 架构设计：
+ *              Claude Code 宿主 → Plugin (index.ts) → IPC → Rust Daemon
+ *
+ *              启动顺序：
+ *              1. installGhostcode()：平台检测 + 二进制部署到 ~/.ghostcode/bin/ghostcoded
+ *              2. MCP server 初始化（由宿主调用）
+ * @author Atlas.oi
+ * @date 2026-03-01
+ */
+
+/** GhostCode Plugin 版本号 */
+declare const VERSION = "0.1.0";
+/** GhostCode Plugin 名称 */
+declare const PLUGIN_NAME = "ghostcode";
+
+export { PLUGIN_NAME, VERSION };

package/dist/index.js

@@ -0,0 +1,35 @@
+import { installGhostcode } from "./install.js";
+await installGhostcode();
+import { ensureDaemon, stopDaemon, startHeartbeat, getDaemonBinaryPath } from "./daemon.js";
+import {
+  callDaemon,
+  createConnection,
+  resetClient,
+  IpcTimeoutError,
+  IpcConnectionError,
+  IpcProtocolError
+} from "./ipc.js";
+import { registerHook, getHooks, clearHooks, initializeHooks, preToolUseHandler, stopHandler } from "./hooks/index.js";
+const VERSION = "0.1.0";
+const PLUGIN_NAME = "ghostcode";
+export {
+  IpcConnectionError,
+  IpcProtocolError,
+  IpcTimeoutError,
+  PLUGIN_NAME,
+  VERSION,
+  callDaemon,
+  clearHooks,
+  createConnection,
+  ensureDaemon,
+  getDaemonBinaryPath,
+  getHooks,
+  initializeHooks,
+  preToolUseHandler,
+  registerHook,
+  resetClient,
+  startHeartbeat,
+  stopDaemon,
+  stopHandler
+};
+//# sourceMappingURL=index.js.map

package/dist/install.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file install.ts
+ * @description GhostCode Plugin 首次运行安装逻辑
+ *   支持两种安装模式：
+ *   1. 本地复制模式：从 Plugin 包内的 bin/ 目录复制预编译二进制（离线/快速路径）
+ *   2. Release 下载模式：从 GitHub Release 下载平台 bundle，验证 checksum 后解压安装
+ *   通过 ~/.ghostcode/.installed 标记文件避免重复安装
+ * @author Atlas.oi
+ * @date 2026-03-04
+ */
+/**
+ * 根据版本和平台信息生成 GitHub Release 资产的下载 URL
+ *
+ * URL 格式：
+ * https://github.com/{repo}/releases/download/v{version}/ghostcode-{platform}.tar.gz
+ *
+ * @param version 版本号（不含 v 前缀，如 "0.2.0"）
+ * @param platform Node.js process.platform 值（"darwin" | "linux"）
+ * @param arch Node.js process.arch 值（"arm64" | "x64"）
+ * @returns 完整的 tar.gz 下载 URL
+ * @throws Error 不支持的平台组合
+ */
+declare function buildReleaseAssetUrl(version: string, platform: string, arch: string): string;
+/**
+ * 从 GitHub Release 下载并安装 GhostCode 二进制
+ *
+ * 业务逻辑：
+ * 1. 检查是否已安装且版本匹配（快速路径，跳过下载）
+ * 2. 生成 bundle 下载 URL 和 SHA256SUMS URL
+ * 3. 下载 bundle tar.gz 到临时目录
+ * 4. 下载 SHA256SUMS 文件
+ * 5. 解析 SHA256SUMS，获取对应 bundle 的期望 checksum
+ * 6. 验证下载文件 checksum（不匹配则中止，不降级！）
+ * 7. 解压 bundle 到目标目录
+ * 8. 验证 ghostcoded 和 ghostcode-mcp 均已安装
+ * 9. 写入安装标记文件
+ *
+ * @param version 要安装的版本号（不含 v 前缀，如 "0.2.0"）
+ * @param platform Node.js process.platform 值（"darwin" | "linux"）
+ * @param arch Node.js process.arch 值（"arm64" | "x64"）
+ * @param targetDir 安装目标目录（默认为 ~/.ghostcode/bin）
+ * @throws Error checksum 不匹配、下载失败或解压失败时（禁止静默降级）
+ */
+declare function installFromRelease(version: string, platform: string, arch: string, targetDir?: string): Promise<void>;
+/**
+ * 执行 GhostCode Plugin 安装（本地复制模式）
+ *
+ * 业务逻辑：
+ * 1. 读取当前 Plugin 版本
+ * 2. 检查 bin/ 目录是否已安装且版本匹配（快速路径，跳过安装）
+ * 3. 检测当前平台
+ * 4. 定位 Plugin 包内对应平台的 ghostcoded 和 ghostcode-mcp 二进制文件
+ * 5. 创建目标目录（~/.ghostcode/bin/）
+ * 6. 复制双二进制并设置可执行权限
+ * 7. 写入安装标记文件到 bin/ 目录（与 installFromRelease 统一路径）
+ *
+ * @throws Error 当平台不受支持或二进制文件不存在时
+ */
+declare function installGhostcode(): Promise<void>;
+
+export { buildReleaseAssetUrl, installFromRelease, installGhostcode };

package/dist/ipc.d.ts

@@ -0,0 +1,121 @@
+import * as net from 'node:net';
+import { StreamEvent, StreamCallbacks } from './router/streaming.js';
+
+/**
+ * @file IPC 桥接层
+ * @description GhostCode Plugin 与 Rust Daemon 之间的 Unix socket IPC 通信层。
+ *              协议：换行符分隔的 JSON（newline-delimited JSON），每条消息为一行 JSON + \n。
+ *              连接策略：维护 1 个持久连接，断开后懒重连（下次请求时自动重连）。
+ *              超时：单次请求 10s，重连最多 3 次，指数退避（100ms / 200ms / 400ms）。
+ *
+ *              类型设计与 Rust 侧 DaemonRequest/DaemonResponse 完全对齐：
+ *              参考: crates/ghostcode-types/src/ipc.rs
+ *              参考: schemas/daemon-request.json, schemas/daemon-response.json
+ * @author Atlas.oi
+ * @date 2026-03-02
+ */
+
+/** Daemon 请求结构 - 与 DaemonRequest Rust struct 字段一一对应 */
+interface DaemonRequest {
+    /** 协议版本，固定为整数 1（与 Rust v: u8 = 1 对应） */
+    v: 1;
+    /** 操作名称，如 "ping"、"actor.add" */
+    op: string;
+    /** 操作参数，任意 JSON 对象（空参数时传 {}，不传 null） */
+    args: Record<string, unknown>;
+}
+/** Daemon 错误结构 - 与 DaemonError Rust struct 字段一一对应 */
+interface DaemonError {
+    /** 错误码，如 "NOT_FOUND"、"INVALID_ARGS" */
+    code: string;
+    /** 可读的错误描述 */
+    message: string;
+}
+/** Daemon 响应结构 - 与 DaemonResponse Rust struct 字段一一对应 */
+interface DaemonResponse {
+    /** 协议版本，固定为整数 1 */
+    v: 1;
+    /** 操作是否成功 */
+    ok: boolean;
+    /** 成功时的返回值（对应 Rust serde_json::Value，可为任意 JSON） */
+    result: unknown;
+    /** 失败时的错误信息 */
+    error?: DaemonError;
+}
+/** IPC 请求超时（单次请求超过 10s 未收到响应） */
+declare class IpcTimeoutError extends Error {
+    constructor(op: string, timeoutMs: number);
+}
+/** IPC 连接失败（无法建立或恢复 Unix socket 连接） */
+declare class IpcConnectionError extends Error {
+    constructor(socketPath: string, cause?: Error);
+}
+/** IPC 协议错误（收到无效 JSON 或响应结构不符合 Schema） */
+declare class IpcProtocolError extends Error {
+    constructor(detail: string);
+}
+/**
+ * 创建到 Daemon Unix socket 的原始连接
+ *
+ * 参考: cccc/src/cccc/daemon/client_ops.py:40-55 - AF_UNIX connect 逻辑
+ *
+ * @param socketPath - Unix socket 文件路径
+ * @returns 已建立连接的 net.Socket 实例
+ * @throws {IpcConnectionError} 无法连接时抛出
+ */
+declare function createConnection(socketPath: string): Promise<net.Socket>;
+/**
+ * 流式请求的聚合响应
+ * 收集流结束时所有已到达的事件和锁定的 sessionId
+ */
+interface StreamResponse {
+    /** 流过程中收到的所有事件，按到达顺序排列 */
+    events: StreamEvent[];
+    /** 从首个携带 session_id 的事件中锁定的会话 ID，若流中无 session_id 则为 null */
+    sessionId: string | null;
+}
+/**
+ * 解析 Socket 路径（三级回退策略）
+ *
+ * 优先级规则：
+ * 1. 显式参数 - 调用方直接传入的路径，优先级最高
+ * 2. 环境变量 GHOSTCODE_SOCKET_PATH - Daemon 启动后由 preToolUseHandler 注入
+ * 3. addr.json 文件 - 从 ~/.ghostcode/daemon/ghostcoded.addr.json 读取 path 字段
+ * 4. 全部失败 - 返回 null，由调用方决定如何处理
+ *
+ * @param explicit - 显式指定的 socket 路径（可选）
+ * @returns 解析到的 socket 路径，若三级均无法找到则返回 null
+ */
+declare function resolveSocketPath(explicit?: string): string | null;
+/**
+ * 向 Daemon 发起一次 RPC 调用（公共 API）
+ *
+ * 参考: cccc/src/cccc/daemon/server.py:968-988 - call_daemon() 函数设计
+ *
+ * @param op - 操作名称
+ * @param args - 操作参数（默认为 {}）
+ * @param socketPath - Unix socket 路径（可选，未传入时通过 resolveSocketPath 自动发现）
+ * @returns Daemon 响应
+ * @throws {IpcConnectionError} 无法解析 Socket 路径时抛出
+ */
+declare function callDaemon(op: string, args?: Record<string, unknown>, socketPath?: string): Promise<DaemonResponse>;
+/**
+ * 重置模块级单例（主要用于测试场景）
+ */
+declare function resetClient(): Promise<void>;
+/**
+ * 向 Daemon 发起流式 RPC 调用（公共 API）
+ *
+ * 在 callDaemon() 的基础上增加多行 JSON 流式支持。
+ * 已有的 callDaemon() 接口不受影响，完全向后兼容。
+ *
+ * @param op - 操作名称，如 "task.route"
+ * @param args - 操作参数（默认为 {}）
+ * @param callbacks - 流式事件回调集合
+ * @param socketPath - Unix socket 路径（可选，未传入时通过 resolveSocketPath 自动发现）
+ * @returns 流结束后的 StreamResponse（含所有事件和 sessionId）
+ * @throws {IpcConnectionError} 无法解析 Socket 路径时抛出
+ */
+declare function callDaemonStream(op: string, args: Record<string, unknown> | undefined, callbacks: StreamCallbacks, socketPath?: string): Promise<StreamResponse>;
+
+export { type DaemonError, type DaemonRequest, type DaemonResponse, IpcConnectionError, IpcProtocolError, IpcTimeoutError, StreamCallbacks, StreamEvent, type StreamResponse, callDaemon, callDaemonStream, createConnection, resetClient, resolveSocketPath };

package/dist/postinstall.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file postinstall.ts
+ * @description npm/pnpm install 后自动触发的二进制安装脚本
+ *              支持 CI 环境检测、GitHub Release 网络下载
+ *
+ * 业务流程：
+ * 1. 检测 CI 环境 -> 跳过所有下载操作，仅输出提示
+ * 2. 尝试 installFromRelease 下载最新版本
+ * 3. 下载失败 -> 输出明确错误信息、失败原因和修复建议
+ * 4. 权限错误 -> 输出 chmod/sudo 相关提示
+ *
+ * @author Atlas.oi
+ * @date 2026-03-04
+ */
+/**
+ * 检测是否为 CI 环境
+ *
+ * 业务逻辑：
+ * 检查常见 CI 平台的环境变量标识
+ * - CI: GitHub Actions, CircleCI, Travis CI 等通用标识
+ * - GITHUB_ACTIONS: GitHub Actions 专用
+ * - JENKINS_URL: Jenkins CI
+ * - GITLAB_CI: GitLab CI
+ *
+ * @returns true 表示当前运行在 CI 环境中
+ */
+declare function isCIEnvironment(): boolean;
+/**
+ * postinstall 主入口函数
+ *
+ * 在 npm/pnpm install 完成后自动执行。
+ * 输出保持简洁，不干扰包管理器的主控制台输出。
+ *
+ * 业务逻辑：
+ * 1. CI 环境检测 -> 跳过下载
+ * 2. installFromRelease 下载最新 bundle
+ * 3. 下载失败 -> 直接报错，输出失败原因和修复建议（禁止降级回退）
+ * 4. 权限错误 -> 输出 chmod/sudo 建议
+ */
+declare function runPostinstall(): Promise<void>;
+
+export { isCIEnvironment, runPostinstall };

package/dist/session-lease.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @file Session Lease 引用计数管理器
+ * @description 管理多会话共享单 Daemon 时的引用计数。
+ *              每个会话 acquire 一个 lease，只有最后一个会话 release 时才真正关闭 Daemon。
+ *              Lease 信息存储在文件中，支持跨进程安全读写（mkdir 互斥锁 + atomic write）。
+ *
+ * 文件格式（sessions.json）：
+ * {
+ *   "sessions": [
+ *     { "leaseId": "uuid-1", "pid": 12345, "acquiredAt": "ISO-timestamp" },
+ *     { "leaseId": "uuid-2", "pid": 12346, "acquiredAt": "ISO-timestamp" }
+ *   ]
+ * }
+ *
+ * @author Atlas.oi
+ * @date 2026-03-04
+ */
+/**
+ * Lease 获取结果
+ */
+interface LeaseInfo {
+    /** 唯一的 Lease 标识符（UUID v4 格式） */
+    leaseId: string;
+    /** 当前总引用计数（包含本次 acquire） */
+    refcount: number;
+}
+/**
+ * Lease 释放结果
+ */
+interface ReleaseResult {
+    /** 释放后的剩余引用计数 */
+    refcount: number;
+    /** 是否为最后一个 lease（true 表示可以关闭 Daemon） */
+    isLast: boolean;
+}
+/**
+ * Session Lease 引用计数管理器
+ *
+ * 使用文件存储实现跨进程安全的引用计数：
+ * 1. 每次 acquire/release 操作都包裹在 withFileLock 跨进程互斥锁中
+ * 2. 锁内执行 read-modify-write：读文件 → 修改内存 → atomic write 回文件
+ * 3. atomic write = 写临时文件 + rename，确保其他进程看到的始终是完整 JSON
+ * 4. 如果文件不存在，视为 0 个 session
+ */
+declare class SessionLeaseManager {
+    /** sessions.json 文件的绝对路径 */
+    private readonly filePath;
+    /** 互斥锁目录路径（与 sessions.json 同目录下的 .sessions.lock/） */
+    private readonly lockPath;
+    /**
+     * 创建 SessionLeaseManager 实例
+     *
+     * @param sessionsFilePath - sessions.json 文件路径（便于测试时使用临时路径）
+     */
+    constructor(sessionsFilePath: string);
+    /**
+     * 获取一个 session lease（引用计数 +1）
+     *
+     * 业务逻辑：
+     * 1. 读取当前 sessions.json 文件（不存在则视为空列表）
+     * 2. 生成新 UUID 作为 leaseId
+     * 3. 将新 session 追加到列表
+     * 4. Atomic write 回文件
+     * 5. 返回新 leaseId 和最新 refcount
+     *
+     * @returns LeaseInfo - 包含 leaseId 和当前 refcount
+     */
+    acquireLease(): LeaseInfo;
+    /**
+     * 释放一个 session lease（引用计数 -1）
+     *
+     * 业务逻辑：
+     * 1. 读取当前 sessions.json 文件
+     * 2. 从列表中移除对应 leaseId 的条目（找不到则安全跳过）
+     * 3. Atomic write 回文件
+     * 4. 返回剩余 refcount 和 isLast 标志
+     *
+     * @param leaseId - 要释放的 lease 标识符
+     * @returns ReleaseResult - 包含剩余 refcount 和 isLast 标志
+     */
+    releaseLease(leaseId: string): ReleaseResult;
+    /**
+     * 获取当前引用计数
+     *
+     * 直接从文件读取，反映最新的跨进程状态。
+     *
+     * @returns 当前 session 数量（引用计数）
+     */
+    getRefcount(): number;
+    /**
+     * 读取 sessions.json 文件
+     *
+     * 文件不存在或解析失败时返回空的 sessions 列表，而不是抛出异常。
+     *
+     * @returns SessionsFile - 解析后的文件内容
+     */
+    private readFile;
+    /**
+     * Atomic write sessions.json 文件
+     *
+     * 使用"写临时文件 + rename"策略确保跨进程安全：
+     * - 直接写目标文件可能导致其他进程读到中间状态（半写入的 JSON）
+     * - rename 是原子操作，确保其他进程看到的始终是完整的 JSON
+     *
+     * @param data - 要写入的文件内容
+     */
+    private writeFile;
+}
+
+export { type LeaseInfo, type ReleaseResult, SessionLeaseManager };