@bbyx0011/ghostcode 0.1.0

package/scripts/hook-pre-tool-use.mjs

@@ -0,0 +1,225 @@
+/**
+ * @file scripts/hook-pre-tool-use.mjs
+ * @description PreToolUse Hook 脚本
+ *              在每次工具调用前确保 GhostCode Daemon 已启动并获取 Session Lease。
+ *
+ *              与原 handlers.ts 的关键区别：
+ *              - 每次调用是独立进程，使用文件状态替代内存变量
+ *              - 不启动心跳（进程执行完即退出，心跳无意义）
+ *              - 通过状态文件实现跨调用的幂等性
+ *
+ *              参考: src/plugin/src/hooks/handlers.ts - preToolUseHandler
+ * @author Atlas.oi
+ * @date 2026-03-05
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+// ============================================
+// 常量：路径配置
+// ============================================
+
+// GhostCode 主目录，优先使用环境变量覆盖
+const GHOSTCODE_HOME = process.env.GHOSTCODE_HOME || join(homedir(), ".ghostcode");
+
+// Hook 状态文件：记录 Daemon 启动状态和 Lease 信息
+// 所有 Hook 脚本共享此文件，实现跨进程状态传递
+const STATE_FILE = join(GHOSTCODE_HOME, "state", "hook-state.json");
+
+// Plugin 根目录（由 run.mjs 注入或从脚本路径推导）
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || join(dirname(new URL(import.meta.url).pathname), "..");
+
+// ============================================
+// 状态文件读写工具函数
+// ============================================
+
+/**
+ * 读取 Hook 状态文件
+ *
+ * 业务逻辑：
+ * 1. 检查文件是否存在
+ * 2. 解析 JSON 内容
+ * 3. 文件不存在或解析失败时返回默认空状态
+ *
+ * @returns {{ daemonStarted: boolean, socketPath: string|null, leaseId: string|null }}
+ */
+function readState() {
+  try {
+    if (existsSync(STATE_FILE)) {
+      return JSON.parse(readFileSync(STATE_FILE, "utf-8"));
+    }
+  } catch {
+    // 状态文件解析失败时，返回默认状态重新初始化
+  }
+  return { daemonStarted: false, socketPath: null, leaseId: null, webStarted: false };
+}
+
+/**
+ * 写入 Hook 状态文件
+ *
+ * 业务逻辑：
+ * 1. 确保父目录存在（首次运行时创建）
+ * 2. 将状态序列化为 JSON 写入文件
+ *
+ * @param {{ daemonStarted: boolean, socketPath: string|null, leaseId: string|null }} state - 要持久化的状态
+ */
+function writeState(state) {
+  // 确保状态目录存在，首次运行时自动创建
+  const dir = dirname(STATE_FILE);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), "utf-8");
+}
+
+/**
+ * 检测指定 PID 的进程是否存活
+ *
+ * 使用 kill -0 信号探测进程，不发送实际信号
+ *
+ * @param {number} pid - 目标进程 PID
+ * @returns {boolean} 进程存活返回 true，否则返回 false
+ */
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    // 进程不存在或无权限访问，均视为不存活
+    return false;
+  }
+}
+
+// ============================================
+// 主逻辑
+// ============================================
+
+/**
+ * PreToolUse Hook 主函数
+ *
+ * 业务逻辑说明：
+ * 1. 读取当前状态文件，获取 Daemon 启动状态
+ * 2. 如果 Daemon 已启动，验证进程是否仍在运行（幂等保护）
+ * 3. 如果 Daemon 不存在或进程已退出，重新启动 Daemon
+ * 4. 获取 Session Lease（如果尚未持有）
+ * 5. 将最新状态写回状态文件
+ */
+async function main() {
+  // ============================================
+  // 第一步：读取当前状态
+  // ============================================
+  const state = readState();
+
+  // ============================================
+  // 第二步：检查 Daemon 是否已启动（幂等保护）
+  // 如果状态文件记录 Daemon 已启动，通过 addr.json 验证进程是否仍然存活
+  // ============================================
+  if (state.daemonStarted && state.socketPath) {
+    // 读取 addr.json 获取 Daemon 进程信息
+    const addrPath = join(GHOSTCODE_HOME, "daemon", "ghostcoded.addr.json");
+    let daemonAlive = false;
+    try {
+      if (existsSync(addrPath)) {
+        const addr = JSON.parse(readFileSync(addrPath, "utf-8"));
+        if (addr.pid && isProcessAlive(addr.pid)) {
+          daemonAlive = true;
+        }
+      }
+    } catch {
+      // addr.json 读取失败，说明 Daemon 状态异常，需要重新启动
+    }
+
+    if (daemonAlive) {
+      // Daemon 仍在运行，但仍需确保 Web Dashboard 也在运行
+      // Bug 修复：之前直接 return 导致 ensureWeb 永远不会被调用
+      if (!state.webStarted) {
+        try {
+          const { ensureWeb } = await import(join(PLUGIN_ROOT, "dist", "web.js"));
+          await ensureWeb();
+          state.webStarted = true;
+          writeState(state);
+        } catch (err) {
+          // Dashboard 启动失败不阻断工具调用
+          console.error("[GhostCode] Dashboard 自动启动失败:", err);
+        }
+      }
+      return;
+    }
+
+    // Daemon 进程不再存活，重置状态准备重新启动
+    state.daemonStarted = false;
+    state.socketPath = null;
+    state.leaseId = null;
+    state.webStarted = false;
+  }
+
+  // ============================================
+  // 第三步：启动 Daemon
+  // 动态导入编译产物，支持 CLAUDE_PLUGIN_ROOT 环境变量覆盖
+  // ============================================
+  try {
+    const { ensureDaemon } = await import(join(PLUGIN_ROOT, "dist", "daemon.js"));
+    const addr = await ensureDaemon();
+
+    // Daemon 启动成功，更新状态
+    state.daemonStarted = true;
+    state.socketPath = addr.path;
+
+    // ============================================
+    // 第四步：获取 Session Lease（如果尚未持有）
+    // Lease 标识当前 Claude Code 会话，用于多 Agent 协作管理
+    // ============================================
+    if (!state.leaseId) {
+      try {
+        const { SessionLeaseManager } = await import(join(PLUGIN_ROOT, "dist", "session-lease.js"));
+        // sessions.json 记录所有活跃会话的 Lease 信息
+        const sessionsPath = join(GHOSTCODE_HOME, "daemon", "sessions.json");
+        const leaseManager = new SessionLeaseManager(sessionsPath);
+        const lease = leaseManager.acquireLease();
+        state.leaseId = lease.leaseId;
+      } catch (err) {
+        // Lease 获取失败不阻断流程，仅记录错误
+        // 没有 Lease 仍可正常使用，只是部分协作功能受限
+        console.error("[GhostCode] Session lease 获取失败:", err);
+      }
+    }
+
+    // ============================================
+    // 第五步：启动 Dashboard Web 服务（单实例保证）
+    // ensureWeb() 内部检查 ghostcode-web 是否已运行，
+    // 已运行则跳过，未运行则自动启动并等待健康检查通过
+    // ============================================
+    try {
+      const { ensureWeb } = await import(join(PLUGIN_ROOT, "dist", "web.js"));
+      await ensureWeb();
+      state.webStarted = true;
+    } catch (err) {
+      // Dashboard 启动失败不阻断工具调用
+      // 用户仍可通过 /gc-web 命令手动启动
+      console.error("[GhostCode] Dashboard 自动启动失败:", err);
+    }
+
+    // ============================================
+    // 第六步：将最新状态写回文件
+    // 下次 Hook 调用时可从此文件读取状态，实现跨进程幂等性
+    // ============================================
+    writeState(state);
+  } catch (err) {
+    // Daemon 启动失败，记录错误但不阻断工具调用
+    // 遵循 exit 0 策略：GhostCode 的问题不应影响用户正常使用 Claude Code
+    console.error("[GhostCode] Daemon 启动失败，工具调用将继续但无协作功能:", err);
+
+    // 重置状态文件，下次 Hook 调用时会重试启动
+    writeState({ daemonStarted: false, socketPath: null, leaseId: null, webStarted: false });
+  }
+}
+
+// ============================================
+// 入口：执行主逻辑
+// 任何未捕获的异常都 exit 0，绝不阻断 Claude Code 的工具调用
+// ============================================
+main().catch((err) => {
+  console.error("[GhostCode] hook-pre-tool-use 异常:", err);
+  // exit 0 策略：即使 Hook 完全失败，也不影响工具调用继续执行
+  process.exit(0);
+});

package/scripts/hook-session-end.mjs

@@ -0,0 +1,108 @@
+/**
+ * @file scripts/hook-session-end.mjs
+ * @description SessionEnd Hook 脚本
+ *              在 Claude Code 会话正常结束时执行清理操作：
+ *              1. 触发最终 Skill Learning 汇总（调用 learner 模块的 onSessionEnd）
+ *              2. 清理 ~/.ghostcode/state/ 下的状态文件（重置会话状态）
+ *
+ *              与 Stop Hook 的分工：
+ *              - Stop: 在 Claude Code 输出停止时触发，负责释放 Lease + 关闭 Daemon
+ *              - SessionEnd: 在整个会话结束时触发，负责最终汇总 + 状态清理
+ *
+ *              注意：失败时 exit 0，不阻断 Claude Code 会话正常关闭
+ * @author Atlas.oi
+ * @date 2026-03-05
+ */
+
+import { existsSync, readdirSync, unlinkSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+// ============================================
+// 常量配置
+// ============================================
+
+// GhostCode 主目录，支持环境变量覆盖（主要用于测试隔离）
+const GHOSTCODE_HOME = process.env.GHOSTCODE_HOME || join(homedir(), ".ghostcode");
+
+// 状态目录路径
+const STATE_DIR = join(GHOSTCODE_HOME, "state");
+
+// Plugin 根目录（用于动态 import learner 模块）
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || join(dirname(new URL(import.meta.url).pathname), "..");
+
+// ============================================
+// 状态清理工具函数
+// ============================================
+
+/**
+ * 清理 state 目录下的所有状态文件
+ *
+ * 业务逻辑说明：
+ * 1. 检查 state 目录是否存在
+ * 2. 遍历目录下所有 .json 文件并删除
+ * 3. 失败时静默处理，不阻断主流程
+ */
+function clearStateFiles() {
+  try {
+    if (!existsSync(STATE_DIR)) {
+      return;
+    }
+    const files = readdirSync(STATE_DIR);
+    for (const file of files) {
+      if (file.endsWith(".json")) {
+        try {
+          unlinkSync(join(STATE_DIR, file));
+        } catch {
+          // 单个文件删除失败不影响其他文件
+        }
+      }
+    }
+  } catch {
+    // state 目录读取失败，静默处理
+  }
+}
+
+// ============================================
+// 主逻辑
+// ============================================
+
+/**
+ * SessionEnd Hook 主函数
+ *
+ * 业务逻辑说明：
+ * 1. 触发 Skill Learning 最终汇总（onSessionEnd）
+ *    - 调用成功：输出汇总日志
+ *    - 调用失败：静默处理，继续执行清理
+ * 2. 清理 state 目录下的所有状态文件
+ */
+async function main() {
+  // ============================================
+  // 第一步：触发 Skill Learning 最终汇总
+  // 确保会话结束时所有学习内容被持久化
+  // ============================================
+  try {
+    const { onSessionEnd } = await import(join(PLUGIN_ROOT, "dist", "learner", "index.js"));
+    await onSessionEnd();
+    console.log("[GhostCode] SessionEnd: Skill Learning 汇总完成");
+  } catch {
+    // learner 模块可能未构建（开发环境），静默处理
+  }
+
+  // ============================================
+  // 第二步：清理状态文件
+  // 会话已完全结束，重置所有 Hook 状态
+  // ============================================
+  clearStateFiles();
+  console.log("[GhostCode] SessionEnd: 状态文件清理完成");
+}
+
+// ============================================
+// 入口：执行主逻辑
+// exit 0 策略：SessionEnd 失败不应阻断 Claude Code 会话关闭
+// ============================================
+main().catch((err) => {
+  console.error("[GhostCode] hook-session-end 异常:", err);
+  clearStateFiles();
+  process.exit(0);
+});

package/scripts/hook-session-start.mjs

@@ -0,0 +1,243 @@
+/**
+ * @file scripts/hook-session-start.mjs
+ * @description SessionStart Hook 脚本
+ *              在 Claude Code 会话启动时执行初始化操作：
+ *              1. 确保状态目录存在（首次运行时自动创建）
+ *              2. 幂等性：如果状态文件已存在（其他 Hook 已初始化），跳过状态文件写入
+ *              3. 自动安装 wrapper + prompts（从 Plugin 包 symlink 到 ~/.ghostcode/）
+ *              4. 输出 GhostCode Plugin 启动信息（版本 + skill 数量 + Daemon 状态）
+ *
+ *              与 PreToolUse 的分工：
+ *              - SessionStart: 输出欢迎信息，创建目录，标记会话开始
+ *              - PreToolUse: 启动 Daemon，获取 Session Lease
+ *
+ *              幂等保证：
+ *              - 每次 SessionStart 都输出初始化消息（用于用户感知）
+ *              - 状态文件已存在时跳过写入，避免覆盖 PreToolUse 写入的 Daemon 状态
+ * @author Atlas.oi
+ * @date 2026-03-05
+ */
+
+import { existsSync, mkdirSync, writeFileSync, symlinkSync, readlinkSync, unlinkSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+// ============================================
+// 常量配置
+// ============================================
+
+// GhostCode 主目录，支持环境变量覆盖（主要用于测试隔离）
+const GHOSTCODE_HOME = process.env.GHOSTCODE_HOME || join(homedir(), ".ghostcode");
+
+// Plugin 版本号（与 package.json 保持一致）
+const PLUGIN_VERSION = "0.1.0";
+
+// Hook 状态文件路径（与 hook-pre-tool-use.mjs 和 hook-stop.mjs 共享同一路径）
+const STATE_FILE = join(GHOSTCODE_HOME, "state", "hook-state.json");
+
+// ============================================
+// Skill 列表：用于计算 skill 数量
+// 与 hooks.json 中原 echo 命令的 skill 列表保持一致
+// ============================================
+const SKILLS = [
+  "/gc:team-research",
+  "/gc:team-plan",
+  "/gc:team-exec",
+  "/gc:team-review",
+  "/gc:spec-research",
+  "/gc:spec-plan",
+  "/gc:spec-impl",
+];
+
+// ============================================
+// 主逻辑
+// ============================================
+
+/**
+ * SessionStart Hook 主函数
+ *
+ * 业务逻辑说明：
+ * 1. 确保 GhostCode 状态目录存在（首次安装时创建）
+ * 2. 如果状态文件不存在，创建初始空状态（daemonStarted: false）
+ *    - 如果状态文件已存在，说明 PreToolUse 已写入 Daemon 状态，跳过写入（幂等保护）
+ * 3. 输出初始化消息：版本号 + skill 数量 + Daemon 状态
+ */
+function main() {
+  // ============================================
+  // 第一步：确保状态目录存在
+  // 首次运行时自动创建 ~/.ghostcode/state/ 目录
+  // ============================================
+  const stateDir = join(GHOSTCODE_HOME, "state");
+  mkdirSync(stateDir, { recursive: true });
+
+  // ============================================
+  // 第二步：幂等性检查 + 初始状态文件创建
+  // 仅在状态文件不存在时写入初始状态
+  // 避免覆盖 PreToolUse 已写入的 Daemon 启动状态
+  // ============================================
+  if (!existsSync(STATE_FILE)) {
+    // 状态文件不存在，创建初始空状态
+    // daemonStarted: false 表示 Daemon 尚未启动（由 PreToolUse 负责启动）
+    const initialState = {
+      daemonStarted: false,
+      socketPath: null,
+      leaseId: null,
+    };
+    writeFileSync(STATE_FILE, JSON.stringify(initialState, null, 2), "utf-8");
+  }
+
+  // ============================================
+  // 第三步：自动安装 wrapper + prompts
+  // 从 Plugin 包 symlink 到 ~/.ghostcode/，Plugin 更新时自动生效
+  // ============================================
+  setupWrapperAndPrompts();
+
+  // ============================================
+  // 第四步：输出初始化消息
+  // 每次 SessionStart 都输出，让用户感知 GhostCode 已加载
+  // 格式：[GhostCode] Plugin vX.Y.Z | N skills loaded | Daemon: pending
+  // ============================================
+  const skillCount = SKILLS.length;
+  // Daemon 状态固定显示 pending：实际启动由 PreToolUse 负责，此时尚未启动
+  const daemonStatus = "pending";
+  console.log(`[GhostCode] Plugin v${PLUGIN_VERSION} | ${skillCount} skills loaded | Daemon: ${daemonStatus}`);
+}
+
+// ============================================
+// setupWrapperAndPrompts 函数
+// 从 Plugin 包自动 symlink wrapper 和 prompts 到 ~/.ghostcode/
+//
+// 业务逻辑：
+// 1. 通过 CLAUDE_PLUGIN_ROOT 或脚本路径推算 Plugin 包根目录
+// 2. 将 bin/ghostcode-wrapper 启动器 symlink 到 ~/.ghostcode/bin/
+// 3. 将 prompts/*.md 角色提示词 symlink 到 ~/.ghostcode/prompts/
+// 4. 幂等设计：已存在且指向正确目标的 symlink 不重复创建
+// 5. 失败时仅 console.error，不阻断会话建立
+// ============================================
+
+/**
+ * 创建或更新 symlink（幂等）
+ *
+ * 业务逻辑说明：
+ * 1. 如果 link 已存在且指向正确目标，跳过
+ * 2. 如果 link 已存在但指向旧目标，删除后重建
+ * 3. 如果 link 不存在，创建新 symlink
+ *
+ * @param {string} target - symlink 指向的实际文件路径
+ * @param {string} linkPath - symlink 文件路径
+ * @returns {boolean} 是否成功
+ */
+function ensureSymlink(target, linkPath) {
+  try {
+    if (existsSync(linkPath)) {
+      // 检查现有 symlink 是否指向正确目标
+      try {
+        const currentTarget = readlinkSync(linkPath);
+        if (currentTarget === target) {
+          // 已存在且指向正确目标，跳过（幂等）
+          return true;
+        }
+      } catch {
+        // readlinkSync 失败说明不是 symlink（可能是普通文件），删除后重建
+      }
+      // 删除旧的 symlink 或文件
+      unlinkSync(linkPath);
+    }
+    // 创建新 symlink
+    symlinkSync(target, linkPath);
+    return true;
+  } catch (err) {
+    console.error(`[GhostCode] symlink 创建失败: ${linkPath} -> ${target}:`, err.message);
+    return false;
+  }
+}
+
+/**
+ * 自动安装 wrapper 和 prompts
+ *
+ * 两种环境的查找策略：
+ * - 分发环境：Plugin 包中有 bin/ghostcode-wrapper 启动器 → 直接 symlink
+ * - 开发环境：Plugin 包中无预编译二进制 → 查找 cargo 编译产物 target/release/ghostcode-wrapper
+ *             prompts 从 src/plugin/prompts/ 直接 symlink
+ *
+ * @returns {void}
+ */
+function setupWrapperAndPrompts() {
+  try {
+    // ============================================
+    // 推算 Plugin 包根目录
+    // 优先使用 CLAUDE_PLUGIN_ROOT 环境变量（Claude Code 注入）
+    // 回退方案：通过当前脚本路径向上推导（scripts/ -> 根目录）
+    // ============================================
+    let pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+    if (!pluginRoot) {
+      // 回退：当前脚本在 scripts/ 目录下，向上一级即为 Plugin 根目录
+      const currentFile = fileURLToPath(import.meta.url);
+      pluginRoot = join(dirname(currentFile), "..");
+    }
+
+    // ============================================
+    // 确保目标目录存在
+    // ============================================
+    const binDir = join(GHOSTCODE_HOME, "bin");
+    const promptsDir = join(GHOSTCODE_HOME, "prompts");
+    mkdirSync(binDir, { recursive: true });
+    mkdirSync(promptsDir, { recursive: true });
+
+    // ============================================
+    // 查找 wrapper 二进制
+    // 策略 1：分发环境 — Plugin 包中的平台检测启动器
+    // 策略 2：开发环境 — cargo build 产物 target/release/ghostcode-wrapper
+    // ============================================
+    let wrapperSrc = join(pluginRoot, "bin", "ghostcode-wrapper");
+    if (!existsSync(wrapperSrc)) {
+      // 开发环境：从 src/plugin 向上推算项目根目录（../../），查找 cargo 编译产物
+      const projectRoot = join(pluginRoot, "..", "..");
+      const cargoBinary = join(projectRoot, "target", "release", "ghostcode-wrapper");
+      if (existsSync(cargoBinary)) {
+        wrapperSrc = cargoBinary;
+      } else {
+        // 两种路径都找不到 wrapper 二进制，跳过
+        // 开发环境需先执行 cargo build --release -p ghostcode-wrapper
+        return;
+      }
+    }
+
+    // symlink wrapper
+    // ~/.ghostcode/bin/ghostcode-wrapper -> wrapper 实际路径
+    const wrapperLink = join(binDir, "ghostcode-wrapper");
+    ensureSymlink(wrapperSrc, wrapperLink);
+
+    // ============================================
+    // 查找并 symlink prompts
+    // 策略 1：分发环境 — Plugin 包中的 prompts/ 目录
+    // 策略 2：开发环境 — src/plugin/prompts/ 目录（pluginRoot 即为 src/plugin）
+    // 两种环境下 prompts 都在 ${pluginRoot}/prompts/，逻辑统一
+    // ============================================
+    const promptsSrcDir = join(pluginRoot, "prompts");
+    if (existsSync(promptsSrcDir)) {
+      const promptFiles = readdirSync(promptsSrcDir).filter(f => f.endsWith(".md"));
+      for (const promptFile of promptFiles) {
+        const promptSrc = join(promptsSrcDir, promptFile);
+        const promptLink = join(promptsDir, promptFile);
+        ensureSymlink(promptSrc, promptLink);
+      }
+    }
+  } catch (err) {
+    // 安装失败不阻断会话建立，仅输出错误信息
+    console.error("[GhostCode] wrapper/prompts 自动安装失败:", err.message);
+  }
+}
+
+// ============================================
+// 入口：执行主逻辑
+// exit 0 策略：SessionStart 失败不应阻断 Claude Code 会话建立
+// ============================================
+try {
+  main();
+} catch (err) {
+  console.error("[GhostCode] hook-session-start 初始化失败:", err);
+  // exit 0：初始化失败不阻断 Claude Code 正常使用
+  process.exit(0);
+}