tmuxclihook 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mark liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# tmux-ai-status 安装器
+
+`tmuxclihook` 是 tmux-ai-hooks-status 的交互式 TUI，负责环境侦测/修复、AI CLI 侦测、hooks 装卸修、TPM 软链校验/创建，以及完整卸载编排。启动 TUI 本身需要 Node.js 18+；它不能在 Node.js 缺失时自举运行。
+
+## 运行
+
+```bash
+# 完整功能：从仓库副本运行
+cd installer
+npm install
+npm start
+
+# 插件已经载入 tmux 后
+prefix + I
+
+# npm 入口（环境与 AI CLI 检查）
+npx tmuxclihook
+```
+
+hooks 和 tmux 软链操作依赖仓库根目录中的 `scripts/` 与插件入口文件。npm 包当前适合独立运行环境/CLI 检查；完整安装操作应从仓库副本或 `prefix + I` 启动。
+
+## 功能
+
+| 菜单项 | 说明 |
+|--------|------|
+| 环境检查 | 侦测 tmux(≥3.1) / jq / bash(任意版本) / node(≥18)，显示 `✓ ready`、`✗ missing`、`⚠ outdated`，并在确认后安全修复 |
+| 侦测 AI CLI | 扫描 Claude Code / Codex / opencode，显示版本、最低版本和 hooks 状态；不自动安装或升级 AI CLI |
+| 安装 hooks | 选工具（claude/codex/opencode/全部）→ 调 `scripts/install-<tool>-hooks.sh` |
+| 卸载 hooks | 对称卸载本插件 hooks，保留其他工具注册的 hook |
+| 修复 hooks | 完整性检查 → 缺失则重装 |
+| tmux 软链 | 校验 `~/.tmux/plugins/` 是否有指向本仓库的软链（含旧名），缺失可创建；创建后若 `~/.tmux.conf` 未声明插件，可选追加 `@plugin` 并 `tmux source-file` 重载 |
+| 完整卸载插件 | 停止 Codex monitor、清除聚合状态 `@ai_all_status`、删除插件软链（含旧名，不删仓库）；`.tmux.conf` 删声明与 `tmux kill-server` 因破坏性仅打印手动指引 |
+
+## 环境自动修复规则
+
+Doctor 只通过 Homebrew 执行明确且可验证的操作：
+
+- 缺失依赖：可选择 `brew install <formula>`；
+- 版本过旧且 formula 已由 Homebrew 管理：可选择 `brew upgrade <formula>`；
+- 版本过旧但不是 Homebrew 管理：只显示手动升级建议；
+- 未检测到 Homebrew：只显示手动建议，不自动安装 Homebrew；
+- bash 已存在即视为满足要求，不主动升级 macOS 自带 bash；
+- Claude Code / Codex CLI 始终只检测，不自动安装或升级；
+- 单项修复失败不会阻止后续项目，执行后自动重新检查全部环境依赖。
+
+## 架构
+
+TUI 不重实现 bash hooks 逻辑——hooks 装/卸经 `execa` 调用薄 wrapper `scripts/install-<tool>-hooks.sh`（内部走 `scripts/adapters/<tool>.sh`）。工具元数据（bin/minVersion/hooksFile）在 `src/adapters-meta.js`，与 bash adapter 一一对应。
+
+环境职责分离：
+
+- `src/detect.js`：只探测并分类 `ready` / `missing` / `outdated`；
+- `src/env.js`：检查 Homebrew 所有权、生成 install/upgrade/manual 计划并执行白名单动作；
+- `bin/cli.js`：确认选择、逐项执行、报告失败并复检。
+
+新增 AI CLI：在 `src/adapters-meta.js` 加一条元数据，并增加对应 bash adapter/wrapper。
+
+## 开发与测试
+
+```bash
+npm run check
+npm test
+```
+
+测试通过依赖注入模拟 Homebrew，不会真的执行安装、升级或网络操作。
+
+## 发布（npm）
+
+由 GitHub Actions 自动发布：push 到 `main` 且 `installer/package.json` 的 `version` 比 npm 上已发布版本新时，`.github/workflows/publish-installer.yml` 自动执行 `npm publish --provenance --access public`、打 `installer-v<version>` tag 并创建 Release。
+
+发布前置：仓库 Settings → Secrets 配置 `NPM_TOKEN`（npm automation token）。手动发布版本：修改 `package.json` 的 `version` 后提交并 push 到 main。

package/bin/cli.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// cli.js — tmux-ai-status 交互式安装 TUI（@clack/prompts）
+//
+// 主菜单：环境检查 / 侦测 CLI / 安装 / 卸载 / 修复 hooks / tmux 软链。
+// 实际 hooks 逻辑委托 bash wrapper（scripts/install-<tool>-hooks.sh）。
+
+import * as p from '@clack/prompts';
+import { checkEnv, detectClis, interactiveShell } from '../src/detect.js';
+import { planBrewRemediation, runBrewAction } from '../src/env.js';
+import { installHooks, uninstallHooks, repairHooks } from '../src/hooks.js';
+import { checkSymlink, createSymlink, checkTmuxConf } from '../src/symlink.js';
+import { appendPluginDeclaration, reloadTmux } from '../src/tmuxconf.js';
+import { stopMonitor, clearAggregateStatus, removeSymlinks } from '../src/purge.js';
+import { TOOLS, repoExists, REPO_ROOT } from '../src/adapters-meta.js';
+import { note, padDisplay } from '../src/tui.js';
+
+const OK = '✓';
+const NO = '✗';
+
+function renderEnvResults(results, title = '环境依赖') {
+  const lines = results.map((result) => {
+    const mark = result.status === 'ready' ? OK : result.status === 'outdated' ? '⚠' : NO;
+    return `  ${mark} ${padDisplay(result.name, 6)} ${padDisplay(result.detail, 16)} (要求 ${result.min})`;
+  });
+  note(lines.join('\n'), title);
+}
+
+async function doctor() {
+  const s = p.spinner();
+  s.start('检查环境依赖');
+  const results = await checkEnv();
+  s.stop('环境检查完成');
+
+  renderEnvResults(results);
+
+  // 交互 shell 说明：消除「我用 zsh 但 Doctor 检查 bash」的困惑
+  const sh = interactiveShell();
+  note(
+    `  当前交互 shell：${sh.name}（${sh.path}）\n` +
+    `  说明：hook 脚本 shebang 为 #!/bin/bash，由 AI CLI 触发时以 bash 执行，\n` +
+    `        与你的交互 shell（${sh.name}）无关。macOS 自带 bash 3.2 即可，无需升级。`,
+    'shell 说明',
+  );
+
+  const failed = results.filter((result) => result.status !== 'ready');
+  if (failed.length === 0) {
+    p.log.success('所有依赖就绪');
+    return;
+  }
+
+  const plan = await planBrewRemediation(results);
+  const manual = plan.filter((entry) => entry.action === 'manual');
+  const actionable = plan.filter((entry) => entry.action !== 'manual');
+
+  if (manual.length > 0) {
+    p.log.warn('以下依赖不会自动修改：');
+    manual.forEach((entry) => {
+      p.log.message(`  ${entry.name}：${entry.reason}`);
+    });
+  }
+
+  if (actionable.length === 0) {
+    p.log.info('当前没有可由 Homebrew 自动修复的依赖');
+    return;
+  }
+
+  const entryByKey = new Map(actionable.map((entry) => [
+    `${entry.action}:${entry.pkg}`,
+    entry,
+  ]));
+  const pick = await p.multiselect({
+    message: '选择要自动修复的环境依赖',
+    options: actionable.map((entry) => ({
+      value: `${entry.action}:${entry.pkg}`,
+      label: `${entry.name} — ${entry.command}`,
+    })),
+    required: false,
+  });
+  if (p.isCancel(pick) || !pick || pick.length === 0) {
+    p.log.info('跳过自动修复。可手动执行：');
+    actionable.forEach((entry) => p.log.message(`  ${entry.command}`));
+    return;
+  }
+
+  for (const key of pick) {
+    const entry = entryByKey.get(key);
+    if (!entry) continue;
+
+    const s2 = p.spinner();
+    s2.start(entry.command);
+    const result = await runBrewAction(entry.action, entry.pkg);
+    if (result.ok) s2.stop(`${OK} ${entry.name} 修复命令执行完成`);
+    else s2.stop(`${NO} ${entry.name} 修复失败: ${result.output}`);
+  }
+
+  const verifySpinner = p.spinner();
+  verifySpinner.start('重新检查环境依赖');
+  const finalResults = await checkEnv();
+  verifySpinner.stop('环境复检完成');
+  renderEnvResults(finalResults, '修复后环境');
+
+  if (finalResults.every((result) => result.status === 'ready')) {
+    p.log.success('所有依赖就绪');
+  } else {
+    p.log.warn('仍有依赖需要处理，请查看上方复检结果');
+  }
+}
+
+async function detectCliMenu() {
+  const s = p.spinner();
+  s.start('侦测已安装的 AI CLI');
+  const rows = await detectClis();
+  s.stop('侦测完成');
+
+  const lines = rows.map((r) => {
+    if (!r.installed) return `  ${NO} ${padDisplay(r.label, 14)} 未安装`;
+    const verMark = r.meetsMin ? OK : '⚠';
+    const minNote = r.minVersion && !r.meetsMin ? ` (需 ≥ ${r.minVersion})` : '';
+    const hookNote = r.hooksInstalled ? '已装 hooks' : '未装 hooks';
+    return `  ${verMark} ${padDisplay(r.label, 14)} v${r.version}${minNote}  ${hookNote}`;
+  });
+  note(lines.join('\n'), 'AI CLI');
+}
+
+async function pickTool(message) {
+  const rows = await detectClis();
+  const opts = TOOLS.map((t) => {
+    const row = rows.find((r) => r.id === t.id);
+    const hint = !row?.installed ? '未安装' : row.hooksInstalled ? '已装 hooks' : '未装 hooks';
+    return { value: t.id, label: t.label, hint };
+  });
+  opts.push({ value: '__all__', label: '全部', hint: TOOLS.map((t) => t.id).join(' + ') });
+  opts.push({ value: '__back__', label: '← 返回主菜单' });
+  const sel = await p.select({ message, options: opts });
+  return p.isCancel(sel) || sel === '__back__' ? null : sel;
+}
+
+async function runHookAction(action, verb) {
+  const sel = await pickTool(`选择要${verb}的工具（Esc 返回）`);
+  if (!sel) { p.log.info('返回主菜单'); return; }
+  const ids = sel === '__all__' ? TOOLS.map((t) => t.id) : [sel];
+  for (const id of ids) {
+    const s = p.spinner();
+    s.start(`${verb} ${id} hooks`);
+    const r = await action(id);
+    if (r.ok) {
+      s.stop(`${OK} ${id} ${verb}完成`);
+      if (r.output) p.log.message(r.output.trim());
+    } else {
+      s.stop(`${NO} ${id} ${verb}失败`);
+      p.log.error(r.output || '未知错误');
+    }
+  }
+}
+
+async function symlinkMenu() {
+  const st = checkSymlink();
+  const conf = checkTmuxConf();
+  const lines = [
+    `  软链 ${PLUGIN_LINE(st)}`,
+    `  .tmux.conf: ${conf.exists ? (conf.referenced ? `${OK} 已引用插件` : `${NO} 未引用（需手动加 @plugin 或 run）`) : `${NO} 不存在`}`,
+  ];
+  note(lines.join('\n'), 'tmux 软链');
+
+  // 步骤 1：软链缺失/错误则询问创建
+  if (st.status !== 'ok') {
+    const go = await p.confirm({ message: `创建软链 ${PLUGIN_LINK_PATH()} → 仓库？` });
+    if (p.isCancel(go) || !go) return;
+    const r = createSymlink();
+    if (r.ok) p.log.success(`${OK} 软链已创建：${r.from} → ${r.to}`);
+    else { p.log.error(`${NO} 创建失败：${r.output}`); return; }
+  } else {
+    p.log.success('软链正常');
+  }
+
+  // 步骤 2：.tmux.conf 未引用插件则询问追加声明 + reload（闭合"软链建好但没加载"）
+  if (!conf.referenced) {
+    const decl = await p.confirm({
+      message: `.tmux.conf 未声明插件，追加 set -g @plugin 'tmux-ai-hooks-status' 并重载？`,
+    });
+    if (p.isCancel(decl) || !decl) return;
+    const a = appendPluginDeclaration();
+    if (!a.ok) { p.log.error(`${NO} 写入 .tmux.conf 失败：${a.output}`); return; }
+    if (a.appended) p.log.success(`${OK} 已追加插件声明到 ${a.path}`);
+    else p.log.info('已引用插件，跳过写入');
+    const rl = await reloadTmux();
+    if (rl.ok) p.log.success(`${OK} 已重载 tmux 配置`);
+    else p.log.warn(`重载失败（tmux 可能未运行）：${rl.output}\n请手动执行 tmux source-file ~/.tmux.conf`);
+  }
+}
+
+async function purgeMenu() {
+  p.log.warn('完整卸载：停止 monitor、清聚合状态、删软链。hooks 请先在「卸载 hooks」菜单移除。');
+  const go = await p.confirm({ message: '继续完整卸载插件运行态？（不删仓库、不改 .tmux.conf、不 kill-server）' });
+  if (p.isCancel(go) || !go) { p.log.info('已取消'); return; }
+
+  const mon = await stopMonitor();
+  if (mon.ok) p.log.success(`${OK} 已停止 Codex monitor`);
+  else p.log.warn(`monitor stop 失败（可能未运行）：${mon.output}`);
+
+  const clr = await clearAggregateStatus();
+  if (clr.ok) p.log.success(`${OK} 已清除 @ai_all_status`);
+  else p.log.warn(`清除聚合状态失败（tmux 可能未运行）：${clr.output}`);
+
+  const rm = removeSymlinks();
+  if (rm.removed.length > 0) p.log.success(`${OK} 已删除软链：${rm.removed.join(', ')}`);
+  else p.log.info('无软链可删除');
+
+  note(
+    "  以下破坏性步骤请手动执行：\n" +
+    "  1. 从 ~/.tmux.conf 删除：set -g @plugin 'tmux-ai-hooks-status'\n" +
+    "  2. 重启 tmux server 使状态行/hooks/按键完全卸载：tmux kill-server\n" +
+    "     （kill-server 会关闭当前所有 session，请先保存工作）",
+    '手动收尾',
+  );
+}
+
+function PLUGIN_LINE(st) {
+  if (st.status === 'ok') return `${OK} ${st.note || '指向本仓库'}`;
+  if (st.status === 'missing') return `${NO} 不存在`;
+  return `${NO} 错误（${st.reason || '指向其他位置'}）`;
+}
+function PLUGIN_LINK_PATH() {
+  return '~/.tmux/plugins/tmux-ai-hooks-status';
+}
+
+async function main() {
+  p.intro('tmux-ai-status 安装器');
+
+  if (!repoExists) {
+    p.log.warn(`未定位到仓库 scripts/（期望 ${REPO_ROOT}）。若通过 npx 运行，请在仓库内或已装插件目录下运行。`);
+  }
+
+  while (true) {
+    const choice = await p.select({
+      message: '选择操作（Esc 在子菜单返回主页面）',
+      options: [
+        { value: 'doctor', label: '环境检查', hint: 'tmux / jq / bash / node' },
+        { value: 'detect', label: '侦测 AI CLI', hint: '版本 + hooks 状态' },
+        { value: 'install', label: '安装 hooks' },
+        { value: 'uninstall', label: '卸载 hooks' },
+        { value: 'repair', label: '修复 hooks', hint: '完整性检查 + 缺失重装' },
+        { value: 'symlink', label: 'tmux 软链校验' },
+        { value: 'purge', label: '完整卸载插件', hint: 'monitor stop + 清状态 + 删软链' },
+        { value: 'exit', label: '退出' },
+      ],
+    });
+    // 主菜单是顶层：Esc（isCancel）不退出程序，留在主菜单；退出仅走「退出」项。
+    if (p.isCancel(choice)) {
+      p.log.info('已在主菜单（退出请选「退出」项）');
+      continue;
+    }
+    if (choice === 'exit') break;
+
+    try {
+      if (choice === 'doctor') await doctor();
+      else if (choice === 'detect') await detectCliMenu();
+      else if (choice === 'install') await runHookAction(installHooks, '安装');
+      else if (choice === 'uninstall') await runHookAction(uninstallHooks, '卸载');
+      else if (choice === 'repair') await runHookAction(repairHooks, '修复');
+      else if (choice === 'symlink') await symlinkMenu();
+      else if (choice === 'purge') await purgeMenu();
+    } catch (err) {
+      p.log.error(String(err));
+    }
+  }
+
+  p.outro('完成');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "tmuxclihook",
+  "version": "0.1.0",
+  "description": "交互式 TUI 安装器：环境侦测、AI CLI 侦测、tmux-ai-status hooks 装/卸/修、TPM 软链校验",
+  "type": "module",
+  "bin": {
+    "tmuxclihook": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "for f in bin/cli.js src/*.js; do node --check \"$f\"; done && echo 'all js syntax OK'",
+    "start": "node bin/cli.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "execa": "^9.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "keywords": [
+    "tmux",
+    "claude-code",
+    "codex",
+    "opencode",
+    "hooks",
+    "installer",
+    "tui"
+  ],
+  "author": "liu ziyuan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/liuziyuan/tmux-claude-hooks-status",
+    "directory": "installer"
+  },
+  "homepage": "https://github.com/liuziyuan/tmux-claude-hooks-status/tree/main/installer#readme",
+  "bugs": {
+    "url": "https://github.com/liuziyuan/tmux-claude-hooks-status/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/adapters-meta.js

@@ -0,0 +1,82 @@
+// adapters-meta.js — AI CLI 工具元数据 + 仓库路径定位
+//
+// TUI 侧的工具清单（对应 scripts/adapters/*.sh）。新增 CLI 时在此加一条 + 加 bash adapter。
+// bin/minVersion/hooksFile 用于侦测；installer 指向瘦 wrapper（真实逻辑在 bash adapter）。
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// installer/ 的上一级即仓库根
+export const REPO_ROOT = resolve(__dirname, '..', '..');
+export const SCRIPTS_DIR = join(REPO_ROOT, 'scripts');
+
+const HOME = homedir();
+
+// 工具元数据表。version 解析用正则从 `<bin> --version` 输出提取。
+export const TOOLS = [
+  {
+    id: 'claude',
+    label: 'Claude Code',
+    bin: 'claude',
+    versionArgs: ['--version'],
+    versionRe: /(\d+\.\d+\.\d+)/,          // "2.1.210 (Claude Code)"
+    minVersion: null,                        // 无硬性最低要求
+    hooksFile: join(process.env.CLAUDE_CONFIG_DIR || join(HOME, '.claude'), 'settings.json'),
+    installer: join(SCRIPTS_DIR, 'install-claude-hooks.sh'),
+    hookMarker: 'tmux-ai-status',
+    minHookCount: 10,
+  },
+  {
+    id: 'codex',
+    label: 'Codex CLI',
+    bin: 'codex',
+    versionArgs: ['--version'],
+    versionRe: /(\d+\.\d+\.\d+)/,          // "codex-cli 0.144.4"
+    minVersion: '0.144.0',                   // hooks.json + trust 起于 0.144
+    hooksFile: join(process.env.CODEX_HOME || join(HOME, '.codex'), 'hooks.json'),
+    installer: join(SCRIPTS_DIR, 'install-codex-hooks.sh'),
+    hookMarker: 'tmux-ai-status codex',
+    minHookCount: 6,
+  },
+  {
+    id: 'opencode',
+    label: 'opencode',
+    bin: 'opencode',
+    versionArgs: ['--version'],
+    versionRe: /(\d+\.\d+\.\d+)/,
+    minVersion: null,                        // plugin 系统本地文件跳过版本兼容检查
+    // hooksFile 实为 JS/TS plugin 文件（非 JSON hooks 配置），install/uninstall 整文件写入/删除
+    hooksFile: join(
+      process.env.OPENCODE_CONFIG_DIR || join(process.env.XDG_CONFIG_HOME || join(HOME, '.config'), 'opencode'),
+      'plugins',
+      'tmux-ai-status.ts'
+    ),
+    installer: join(SCRIPTS_DIR, 'install-opencode-hooks.sh'),
+    hookMarker: 'tmux-ai-status (managed by tmux-ai-hooks-status)',
+    minHookCount: 1,
+  },
+];
+
+export function toolById(id) {
+  return TOOLS.find((t) => t.id === id);
+}
+
+// 语义版本比较：a >= b ? 返回 true。仅比较 x.y.z 三段。
+export function versionGte(a, b) {
+  if (!a || !b) return true;
+  const pa = a.split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = b.split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return true;
+    if ((pa[i] || 0) < (pb[i] || 0)) return false;
+  }
+  return true;
+}
+
+// TPM 软链路径（仓库目录名）
+export const PLUGIN_LINK = join(HOME, '.tmux', 'plugins', 'tmux-ai-hooks-status');
+export const repoExists = existsSync(SCRIPTS_DIR);

package/src/detect.js

@@ -0,0 +1,124 @@
+// detect.js — 环境依赖侦测 + AI CLI 侦测
+import { execa } from 'execa';
+import { existsSync, readFileSync } from 'node:fs';
+import { TOOLS, versionGte } from './adapters-meta.js';
+
+// 探测某命令是否存在 + 版本
+async function probe(bin, args, re) {
+  try {
+    const { stdout } = await execa(bin, args, { reject: false, timeout: 8000 });
+    const m = re ? String(stdout).match(re) : null;
+    return { found: true, version: m ? m[1] : null, raw: String(stdout).trim() };
+  } catch {
+    return { found: false, version: null, raw: null };
+  }
+}
+
+function envResult({ name, found, meetsMinimum, detail, min, fixCmd, pkg }) {
+  const status = !found ? 'missing' : meetsMinimum ? 'ready' : 'outdated';
+  return {
+    name,
+    status,
+    ok: status === 'ready',
+    detail,
+    min,
+    fixCmd,
+    pkg,
+  };
+}
+
+// 环境依赖检查（Doctor）。返回逐项结果。
+export async function checkEnv({ probeCommand = probe } = {}) {
+  const results = [];
+
+  // tmux ≥ 3.1
+  const tmux = await probeCommand('tmux', ['-V'], /(\d+\.\d+)/);
+  results.push(envResult({
+    name: 'tmux',
+    found: tmux.found,
+    meetsMinimum: versionGte((tmux.version || '0') + '.0', '3.1.0'),
+    detail: tmux.found ? `v${tmux.version}` : '未安装',
+    min: '≥ 3.1',
+    fixCmd: 'brew install tmux',
+    pkg: 'tmux',
+  }));
+
+  // jq（唯一硬依赖）
+  const jq = await probeCommand('jq', ['--version'], /(\d+\.\d+)/);
+  results.push(envResult({
+    name: 'jq',
+    found: jq.found,
+    meetsMinimum: jq.found,
+    detail: jq.found ? (jq.raw || '已安装') : '未安装',
+    min: '任意版本',
+    fixCmd: 'brew install jq',
+    pkg: 'jq',
+  }));
+
+  // bash：脚本 shebang 为 #!/bin/bash，实测零 bash4 专属特性，macOS 自带 3.2 即可运行。
+  // 只要存在可执行 bash 即通过（不校验版本）。
+  const bash = await probeCommand('bash', ['--version'], /version (\d+\.\d+)/);
+  results.push(envResult({
+    name: 'bash',
+    found: bash.found,
+    meetsMinimum: bash.found,
+    detail: bash.found ? `v${bash.version}` : '未安装',
+    min: '任意版本',
+    fixCmd: 'brew install bash',
+    pkg: 'bash',
+  }));
+
+  // node（TUI 自身运行环境，必在）
+  const node = await probeCommand('node', ['-v'], /v?(\d+\.\d+\.\d+)/);
+  results.push(envResult({
+    name: 'node',
+    found: node.found,
+    meetsMinimum: versionGte(node.version || '0.0.0', '18.0.0'),
+    detail: node.found ? `v${node.version}` : '未安装',
+    min: '≥ 18',
+    fixCmd: 'brew install node',
+    pkg: 'node',
+  }));
+
+  return results;
+}
+
+// 当前交互 shell（用于 Doctor 说明：hook 用 bash 执行，与交互 shell 无关）。
+export function interactiveShell() {
+  const sh = process.env.SHELL || '';
+  const name = sh.split('/').pop() || '未知';
+  return { path: sh || '未知', name };
+}
+
+// 侦测某工具是否已装本插件 hooks
+function hooksInstalled(tool) {
+  try {
+    if (!existsSync(tool.hooksFile)) return false;
+    const raw = readFileSync(tool.hooksFile, 'utf8');
+    const count = (raw.match(new RegExp(tool.hookMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g')) || []).length;
+    return count >= tool.minHookCount;
+  } catch {
+    return false;
+  }
+}
+
+// 侦测所有已装 AI CLI
+export async function detectClis() {
+  const rows = [];
+  for (const tool of TOOLS) {
+    const p = await probe(tool.bin, tool.versionArgs, tool.versionRe);
+    const meetsMin = p.found ? versionGte(p.version || '0.0.0', tool.minVersion || '0.0.0') : false;
+    rows.push({
+      id: tool.id,
+      label: tool.label,
+      installed: p.found,
+      version: p.version,
+      meetsMin,
+      minVersion: tool.minVersion,
+      hooksInstalled: p.found ? hooksInstalled(tool) : false,
+    });
+  }
+  return rows;
+}
+
+export { hooksInstalled };

package/src/env.js

@@ -0,0 +1,112 @@
+// env.js — 环境依赖修复（仅限 Homebrew 安全安装/升级）
+import { execa } from 'execa';
+
+const BREW_ACTIONS = new Set(['install', 'upgrade']);
+
+// brew 是否可用。命令存在但退出非 0 也视为不可用。
+export async function hasBrew({ runner = execa } = {}) {
+  try {
+    const result = await runner('brew', ['--version'], { reject: false, timeout: 5000 });
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+// formula 是否由当前 Homebrew 安装并管理。
+export async function brewManages(pkg, { runner = execa } = {}) {
+  try {
+    const result = await runner('brew', ['list', '--versions', pkg], {
+      reject: false,
+      timeout: 8000,
+    });
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+// 将 Doctor 结果转换成 install / upgrade / manual 计划。
+export async function planBrewRemediation(
+  results,
+  { brewAvailable, manages = (pkg) => brewManages(pkg) } = {},
+) {
+  const available = brewAvailable ?? await hasBrew();
+  const plan = [];
+
+  for (const result of results) {
+    if (result.status === 'ready') continue;
+
+    if (!available) {
+      plan.push({
+        ...result,
+        action: 'manual',
+        command: null,
+        reason: '未检测到 Homebrew，请使用原安装方式手动处理',
+      });
+      continue;
+    }
+
+    if (result.status === 'missing') {
+      plan.push({
+        ...result,
+        action: 'install',
+        command: `brew install ${result.pkg}`,
+      });
+      continue;
+    }
+
+    if (result.status === 'outdated' && await manages(result.pkg)) {
+      plan.push({
+        ...result,
+        action: 'upgrade',
+        command: `brew upgrade ${result.pkg}`,
+      });
+      continue;
+    }
+
+    plan.push({
+      ...result,
+      action: 'manual',
+      command: null,
+      reason: `不是由 Homebrew 管理，请按原安装方式升级至 ${result.min}`,
+    });
+  }
+
+  return plan;
+}
+
+// 执行经过白名单校验的 brew install/upgrade。返回 {ok, output?}。
+export async function runBrewAction(
+  action,
+  pkg,
+  { onLine, runner = execa } = {},
+) {
+  if (!BREW_ACTIONS.has(action)) {
+    throw new Error(`Unsupported brew action: ${action}`);
+  }
+
+  try {
+    const subprocess = runner('brew', [action, pkg]);
+    if (onLine) {
+      subprocess.stdout?.on('data', (data) => onLine(String(data)));
+      subprocess.stderr?.on('data', (data) => onLine(String(data)));
+    }
+    const result = await subprocess;
+    if (result.exitCode != null && result.exitCode !== 0) {
+      return { ok: false, output: result.stderr || result.stdout || `brew ${action} exited ${result.exitCode}` };
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, output: err.shortMessage || String(err) };
+  }
+}
+
+// 兼容旧调用方。
+export async function brewInstall(pkg, onLine, options = {}) {
+  return runBrewAction('install', pkg, { ...options, onLine });
+}
+
+export async function brewUpgrade(pkg, onLine, options = {}) {
+  return runBrewAction('upgrade', pkg, { ...options, onLine });
+}

package/src/hooks.js

@@ -0,0 +1,42 @@
+// hooks.js — 调 bash wrapper 完成 hooks 装/卸/修
+import { execa } from 'execa';
+import { existsSync } from 'node:fs';
+import { toolById } from './adapters-meta.js';
+import { hooksInstalled } from './detect.js';
+
+// 安装某工具 hooks（调薄 wrapper install-<tool>-hooks.sh）
+export async function installHooks(id) {
+  const tool = toolById(id);
+  if (!tool) return { ok: false, output: `未知工具: ${id}` };
+  if (!existsSync(tool.installer)) return { ok: false, output: `找不到安装脚本: ${tool.installer}` };
+  try {
+    const { stdout } = await execa('bash', [tool.installer], { timeout: 30000 });
+    return { ok: true, output: stdout };
+  } catch (err) {
+    return { ok: false, output: err.stderr || err.shortMessage || String(err) };
+  }
+}
+
+// 卸载某工具 hooks
+export async function uninstallHooks(id) {
+  const tool = toolById(id);
+  if (!tool) return { ok: false, output: `未知工具: ${id}` };
+  if (!existsSync(tool.installer)) return { ok: false, output: `找不到安装脚本: ${tool.installer}` };
+  try {
+    const { stdout } = await execa('bash', [tool.installer, 'uninstall'], { timeout: 30000 });
+    return { ok: true, output: stdout };
+  } catch (err) {
+    return { ok: false, output: err.stderr || err.shortMessage || String(err) };
+  }
+}
+
+// 修复某工具 hooks：完整性检查（JS 侧 hooksInstalled）→ 缺失则重装
+export async function repairHooks(id) {
+  const tool = toolById(id);
+  if (!tool) return { ok: false, output: `未知工具: ${id}` };
+  if (hooksInstalled(tool)) {
+    return { ok: true, output: `${tool.label} hooks 完整，无需修复`, repaired: false };
+  }
+  const r = await installHooks(id);
+  return { ...r, repaired: r.ok };
+}

package/src/purge.js

@@ -0,0 +1,43 @@
+// purge.js — 完整卸载编排：monitor stop + 清聚合状态 + 删软链（不删仓库/不动 conf/不 kill-server）
+import { execa } from 'execa';
+import { rmSync, lstatSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { PLUGIN_LINK, SCRIPTS_DIR } from './adapters-meta.js';
+
+// 旧名软链（历史安装）
+const PLUGIN_LINK_LEGACY = join(dirname(PLUGIN_LINK), 'tmux-claude-hooks-status');
+
+// 停止 Codex lifecycle monitor
+export async function stopMonitor() {
+  try {
+    await execa('bash', [join(SCRIPTS_DIR, 'tmux-ai-monitor'), 'stop'], { timeout: 10000 });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, output: err.stderr || err.shortMessage || String(err) };
+  }
+}
+
+// 清除聚合状态选项 @ai_all_status
+export async function clearAggregateStatus() {
+  try {
+    await execa('tmux', ['set-option', '-gu', '@ai_all_status'], { timeout: 10000 });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, output: err.stderr || err.shortMessage || String(err) };
+  }
+}
+
+// 删除插件软链（canonical + 旧名）；不删真实仓库
+export function removeSymlinks() {
+  const removed = [];
+  for (const link of [PLUGIN_LINK, PLUGIN_LINK_LEGACY]) {
+    let present = false;
+    try { lstatSync(link); present = true; } catch { /* 不存在 */ }
+    if (!present) continue;
+    try {
+      rmSync(link, { force: true });
+      removed.push(link);
+    } catch { /* 忽略：权限等 */ }
+  }
+  return { ok: true, removed };
+}

package/src/symlink.js

@@ -0,0 +1,73 @@
+// symlink.js — TPM 软链校验/创建 + .tmux.conf 引用检查
+import { existsSync, lstatSync, readlinkSync, symlinkSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { PLUGIN_LINK, REPO_ROOT } from './adapters-meta.js';
+
+const PLUGINS_DIR = dirname(PLUGIN_LINK);
+
+// 扫 ~/.tmux/plugins/ 找任何指向本仓库的软链（含旧名 tmux-claude-hooks-status）。
+// 返回匹配的软链绝对路径，无则 null。
+function findRepoLink() {
+  try {
+    for (const name of readdirSync(PLUGINS_DIR)) {
+      const full = join(PLUGINS_DIR, name);
+      try {
+        const st = lstatSync(full);
+        if (st.isSymbolicLink() && readlinkSync(full) === REPO_ROOT) return full;
+        // 真实目录且含入口文件也算（非软链安装）
+        if (st.isDirectory() && full === REPO_ROOT) return full;
+      } catch { /* skip */ }
+    }
+  } catch { /* plugins dir 不存在 */ }
+  return null;
+}
+
+// 检查软链状态：missing | wrong | ok
+export function checkSymlink() {
+  // 先看是否已有任意指向本仓库的软链（含旧名）
+  const existing = findRepoLink();
+  if (existing) {
+    const note = existing === PLUGIN_LINK ? '指向本仓库' : `指向本仓库（软链名 ${existing.split('/').pop()}）`;
+    return { status: 'ok', target: REPO_ROOT, link: existing, note };
+  }
+
+  // 无匹配软链：检查 canonical 路径是否被占（悬空/指向他处）
+  try {
+    const st = lstatSync(PLUGIN_LINK);
+    if (st.isSymbolicLink()) {
+      let target = null;
+      try { target = readlinkSync(PLUGIN_LINK); } catch { /* dangling */ }
+      return { status: 'wrong', target, reason: target ? '指向其他位置' : '悬空软链' };
+    }
+    return { status: 'wrong', target: PLUGIN_LINK, reason: '同名目录（非软链）' };
+  } catch {
+    return { status: 'missing', target: null };
+  }
+}
+
+// 创建软链 PLUGIN_LINK → REPO_ROOT
+export function createSymlink() {
+  try {
+    mkdirSync(dirname(PLUGIN_LINK), { recursive: true });
+    // 已存在悬空软链先删
+    try { lstatSync(PLUGIN_LINK); } catch { /* not exist, ok */ }
+    symlinkSync(REPO_ROOT, PLUGIN_LINK, 'dir');
+    return { ok: true, from: PLUGIN_LINK, to: REPO_ROOT };
+  } catch (err) {
+    return { ok: false, output: err.code === 'EEXIST' ? '软链已存在' : String(err) };
+  }
+}
+
+// 检查 ~/.tmux.conf 是否引用本插件
+export function checkTmuxConf() {
+  const conf = join(homedir(), '.tmux.conf');
+  if (!existsSync(conf)) return { exists: false, referenced: false };
+  try {
+    const raw = readFileSync(conf, 'utf8');
+    const referenced = /tmux-ai-hooks-status|tmux-claude-hooks-status/.test(raw);
+    return { exists: true, referenced };
+  } catch {
+    return { exists: true, referenced: false };
+  }
+}

package/src/tmuxconf.js

@@ -0,0 +1,43 @@
+// tmuxconf.js — 写入 .tmux.conf 的 @plugin 声明 + reload tmux（symlink.js 保持只读职责）
+import { execa } from 'execa';
+import { existsSync, readFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { checkTmuxConf } from './symlink.js';
+
+const PLUGIN_DECL = "set -g @plugin 'tmux-ai-hooks-status'";
+
+function confPath() {
+  return join(homedir(), '.tmux.conf');
+}
+
+// 若 .tmux.conf 未引用本插件，追加 @plugin 声明。已引用则 no-op。
+export function appendPluginDeclaration() {
+  const path = confPath();
+  const { referenced } = checkTmuxConf();
+  if (referenced) return { ok: true, appended: false, path };
+  try {
+    // 保证与前文有换行分隔
+    let prefix = '';
+    if (existsSync(path)) {
+      const raw = readFileSync(path, 'utf8');
+      if (raw.length > 0 && !raw.endsWith('\n')) prefix = '\n';
+    }
+    appendFileSync(path, `${prefix}${PLUGIN_DECL}\n`);
+    return { ok: true, appended: true, path };
+  } catch (err) {
+    return { ok: false, appended: false, path, output: String(err) };
+  }
+}
+
+// 重载 tmux 配置（source-file 重跑插件加载；refresh-client 仅重绘不够）。
+// tmux 未运行时捕获错误返回提示，不抛。
+export async function reloadTmux() {
+  const path = confPath();
+  try {
+    await execa('tmux', ['source-file', path], { timeout: 10000 });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, output: err.stderr || err.shortMessage || String(err) };
+  }
+}

package/src/tui.js

@@ -0,0 +1,218 @@
+// tui.js — Unicode-safe terminal layout helpers.
+//
+// JavaScript string length counts UTF-16 code units, not terminal columns. CJK
+// characters and emoji commonly occupy two columns, while combining marks and
+// ANSI escape sequences occupy none. All box geometry must therefore use
+// displayWidth() rather than String#length or String#padEnd().
+
+import pc from 'picocolors';
+
+const ANSI_PATTERN = /[\u001B\u009B][[\]()#;?]*(?:(?:(?:;[-a-zA-Z\d/#&.:=?%@~_]+)*|[a-zA-Z\d]+(?:;[-a-zA-Z\d/#&.:=?%@~_]*)*)?\u0007|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
+const MARK = /^\p{Mark}+$/u;
+const EMOJI_PRESENTATION = /\p{Emoji_Presentation}|\p{Regional_Indicator}/u;
+const GRAPHEME_SEGMENTER = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+const WORD_SEGMENTER = new Intl.Segmenter(undefined, { granularity: 'word' });
+const TAB_SIZE = 4;
+
+function stripAnsi(value) {
+  return String(value).replace(ANSI_PATTERN, '');
+}
+
+function isZeroWidth(codePoint, character) {
+  return (
+    codePoint === 0x200d || // zero-width joiner
+    codePoint === 0x200c || // zero-width non-joiner
+    codePoint === 0xfe0e ||
+    codePoint === 0xfe0f || // variation selectors
+    (codePoint >= 0x1f3fb && codePoint <= 0x1f3ff) || // emoji modifiers
+    (codePoint >= 0xe0020 && codePoint <= 0xe007f) || // emoji tags
+    MARK.test(character)
+  );
+}
+
+// Adapted from the Unicode ranges used by is-fullwidth-code-point. Ambiguous
+// width characters intentionally remain one column, matching common terminals.
+function isFullWidthCodePoint(codePoint) {
+  return codePoint >= 0x1100 && (
+    codePoint <= 0x115f ||
+    codePoint === 0x2329 ||
+    codePoint === 0x232a ||
+    (codePoint >= 0x2e80 && codePoint <= 0x303e) ||
+    (codePoint >= 0x3040 && codePoint <= 0xa4cf) ||
+    (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+    (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+    (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+    (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+    (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+    (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+    (codePoint >= 0x1b000 && codePoint <= 0x1b2ff) ||
+    (codePoint >= 0x1f200 && codePoint <= 0x1f251) ||
+    (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+  );
+}
+
+function graphemeWidth(grapheme, currentColumn = 0) {
+  if (grapheme === '\t') return TAB_SIZE - (currentColumn % TAB_SIZE);
+  if (EMOJI_PRESENTATION.test(grapheme) || grapheme.includes('\ufe0f') || grapheme.includes('\u200d')) return 2;
+
+  let width = 0;
+  for (const character of grapheme) {
+    const codePoint = character.codePointAt(0);
+    if (
+      codePoint === 0 ||
+      codePoint < 0x20 ||
+      (codePoint >= 0x7f && codePoint < 0xa0) ||
+      isZeroWidth(codePoint, character)
+    ) continue;
+    width += isFullWidthCodePoint(codePoint) ? 2 : 1;
+  }
+  return width;
+}
+
+function graphemes(value) {
+  return [...GRAPHEME_SEGMENTER.segment(stripAnsi(value))].map(({ segment }) => segment);
+}
+
+export function displayWidth(value) {
+  let maximum = 0;
+  for (const line of stripAnsi(value).split('\n')) {
+    let width = 0;
+    for (const grapheme of graphemes(line)) {
+      width += graphemeWidth(grapheme, width);
+    }
+    maximum = Math.max(maximum, width);
+  }
+  return maximum;
+}
+
+export function padDisplay(value, targetWidth) {
+  const text = String(value);
+  return text + ' '.repeat(Math.max(0, targetWidth - displayWidth(text)));
+}
+
+function takeDisplay(value, maximumWidth) {
+  let result = '';
+  let width = 0;
+  for (const grapheme of graphemes(value)) {
+    const nextWidth = graphemeWidth(grapheme, width);
+    if (width + nextWidth > maximumWidth) break;
+    result += grapheme;
+    width += nextWidth;
+  }
+  return result;
+}
+
+export function wrapDisplay(value, maximumWidth, options = {}) {
+  if (!Number.isFinite(maximumWidth) || maximumWidth < 1) {
+    throw new RangeError('maximumWidth must be a positive number');
+  }
+
+  const continuationIndent = stripAnsi(options.continuationIndent || '');
+  const indent = takeDisplay(continuationIndent, Math.max(0, maximumWidth - 2));
+  const indentWidth = displayWidth(indent);
+  const wrapped = [];
+
+  for (const originalLine of stripAnsi(value).split('\n')) {
+    const sourceLine = continuationIndent && originalLine.startsWith(continuationIndent)
+      ? indent + originalLine.slice(continuationIndent.length)
+      : originalLine;
+    let line = '';
+    let width = 0;
+
+    const pushLine = () => {
+      wrapped.push(line.trimEnd());
+      line = indent;
+      width = indentWidth;
+    };
+
+    const appendHardWrapped = (token) => {
+      for (const grapheme of graphemes(token)) {
+        const nextWidth = graphemeWidth(grapheme, width);
+        if (width > indentWidth && width + nextWidth > maximumWidth) pushLine();
+        line += grapheme;
+        width += graphemeWidth(grapheme, width);
+      }
+    };
+
+    for (const { segment: token } of WORD_SEGMENTER.segment(sourceLine)) {
+      const tokenWidth = displayWidth(token);
+      if (width + tokenWidth <= maximumWidth) {
+        line += token;
+        width += tokenWidth;
+        continue;
+      }
+
+      if (line.trim().length > 0) pushLine();
+      if (/^\s+$/u.test(token)) continue;
+
+      if (width + tokenWidth <= maximumWidth) {
+        line += token;
+        width += tokenWidth;
+      } else {
+        appendHardWrapped(token);
+      }
+    }
+    wrapped.push(line.trimEnd());
+  }
+  return wrapped;
+}
+
+function truncateDisplay(value, maximumWidth) {
+  if (displayWidth(value) <= maximumWidth) return String(value);
+  if (maximumWidth <= 1) return '…'.slice(0, maximumWidth);
+
+  let result = '';
+  let width = 0;
+  for (const grapheme of graphemes(value)) {
+    const nextWidth = graphemeWidth(grapheme, width);
+    if (width + nextWidth > maximumWidth - 1) break;
+    result += grapheme;
+    width += nextWidth;
+  }
+  return `${result}…`;
+}
+
+export function renderNote(message = '', title = '', options = {}) {
+  const requestedColumns = Number(options.columns);
+  const columns = Number.isFinite(requestedColumns) && requestedColumns > 0
+    ? Math.max(10, Math.floor(requestedColumns))
+    : 80;
+  const color = options.color !== false;
+  const style = color
+    ? { gray: pc.gray, green: pc.green, dim: pc.dim, reset: pc.reset }
+    : { gray: String, green: String, dim: String, reset: String };
+
+  const rawLines = String(message).split('\n');
+  const naturalWidth = Math.max(
+    displayWidth(title),
+    ...rawLines.map(displayWidth),
+  );
+  const boxWidth = Math.min(columns, Math.max(10, naturalWidth + 6));
+  const contentWidth = boxWidth - 4;
+  const visibleTitle = truncateDisplay(title, Math.max(1, contentWidth - 2));
+  const titleWidth = displayWidth(visibleTitle);
+  const horizontal = '─'.repeat(Math.max(contentWidth - titleWidth - 1, 1));
+  const bodyLines = rawLines.flatMap((line) => {
+    const continuationIndent = line.match(/^ */u)?.[0] || '';
+    return wrapDisplay(line, contentWidth, { continuationIndent });
+  });
+  const framedLines = ['', ...bodyLines, ''].map((line) =>
+    `${style.gray('│')}  ${style.dim(padDisplay(line, contentWidth))}${style.gray('│')}`,
+  );
+
+  return [
+    style.gray('│'),
+    `${style.green('◇')}  ${style.reset(visibleTitle)} ${style.gray(`${horizontal}╮`)}`,
+    ...framedLines,
+    style.gray(`├${'─'.repeat(contentWidth + 2)}╯`),
+    '',
+  ].join('\n');
+}
+
+export function note(message = '', title = '', options = {}) {
+  const stream = options.stream || process.stdout;
+  stream.write(renderNote(message, title, {
+    columns: options.columns ?? stream.columns,
+    color: options.color,
+  }));
+}