tmuxclihook 0.1.1 → 0.2.0

package/README.md

@@ -1,23 +1,32 @@
 # tmux-ai-status 安装器
 
-`tmuxclihook` 是 tmux-ai-hooks-status 的交互式 TUI，负责环境侦测/修复、AI CLI 侦测、hooks 装卸修、TPM 软链校验/创建，以及完整卸载编排。启动 TUI 本身需要 Node.js 18+；它不能在 Node.js 缺失时自举运行。
+`tmuxclihook` 是 tmux-ai-hooks-status 的交互式 TUI，负责环境侦测/修复、AI CLI 侦测、hooks 装卸修、tmux 集成（`.tmux.conf` 的 `run-shell` 声明校验/修复）、source 管理（生产默认 / 本地开发路径切换），以及完整卸载编排。启动 TUI 本身需要 Node.js 18+；它不能在 Node.js 缺失时自举运行。
 
 ## 运行
 
 ```bash
-# 完整功能：从仓库副本运行
-cd installer
-npm install
-npm start
+# 生产：npm 全局安装，装完即完整可用（scripts/ 与 tmux 入口已打包进包内）
+npm install -g tmuxclihook
+tmuxclihook
+
+# 检查 npm registry 并将全局安装更新到最新版
+tmuxclihook update
 
 # 插件已经载入 tmux 后
 prefix + I
 
-# npm 入口（环境与 AI CLI 检查）
+# npm 入口（仅环境与 AI CLI 检查，临时缓存目录不适合持久化的 hooks/tmux 写入）
 npx tmuxclihook
+
+# 本地开发：从仓库副本运行
+cd installer
+npm install
+npm start
 ```
 
-hooks 和 tmux 软链操作依赖仓库根目录中的 `scripts/` 与插件入口文件。npm 包当前适合独立运行环境/CLI 检查；完整安装操作应从仓库副本或 `prefix + I` 启动。
+hooks 安装、tmux 集成写入的路径由「source」决定：环境变量 `TMUXCLIHOOK_SOURCE` > 持久化配置 `~/.config/tmuxclihook/config.json`（TUI「source 管理」菜单写入）> 包内自带 scripts/（生产默认）> 仓库根 scripts/（`cd installer && npm start` 时的开发回落）。见下方「source 管理」一节。
+
+`tmuxclihook update` 会显示当前版本，通过 `npm view tmuxclihook version` 查询最新版；版本不同时直接执行 `npm install -g tmuxclihook@latest`，版本相同则不做修改。网络查询或安装失败时命令以非零状态退出。
 
 ## 功能
 
@@ -25,11 +34,30 @@ hooks 和 tmux 软链操作依赖仓库根目录中的 `scripts/` 与插件入
 |--------|------|
 | 环境检查 | 侦测 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 | 选工具（claude/codex/opencode/全部）→ 调 `scripts/install-<tool>-hooks.sh`（路径随当前 source 解析） |
 | 卸载 hooks | 对称卸载本插件 hooks，保留其他工具注册的 hook |
 | 修复 hooks | 完整性检查 → 缺失则重装 |
-| tmux 软链 | 校验 `~/.tmux/plugins/` 是否有指向本仓库的软链（含旧名），缺失可创建；创建后若 `~/.tmux.conf` 未声明插件，可选追加 `@plugin` 并 `tmux source-file` 重载 |
-| 完整卸载插件 | 停止 Codex monitor、清除聚合状态 `@ai_all_status`、删除插件软链（含旧名，不删仓库）；`.tmux.conf` 删声明与 `tmux kill-server` 因破坏性仅打印手动指引 |
+| tmux 集成 | 校验 `~/.tmux.conf` 是否已有指向当前 source 的 `run-shell` 声明；缺失则追加，路径过期（例如切换过 source）则原地替换，随后 `tmux source-file` 重载；不依赖 TPM 软链（历史遗留软链仅作提示，清理走「完整卸载插件」） |
+| source 管理 | 查看当前生效 source（来源 + 失效警告）；设置本地仓库路径用于开发调试；清除持久化配置恢复默认 |
+| 完整卸载插件 | 停止 Codex monitor、清除聚合状态 `@ai_all_status`、清理历史遗留软链（不删仓库）；`.tmux.conf` 删声明与 `tmux kill-server` 因破坏性仅打印手动指引 |
+
+## Source 管理（生产默认 / 本地调试切换）
+
+`npm i -g` 装完后，hooks 安装与 tmux 集成默认使用包内自带的 `scripts/`（由 `npm publish` 前的 `prepack` 步骤从仓库根复制打包进来，见「架构」一节），开箱即用，无需仓库 checkout。
+
+调试本仓库的新功能时，无需重新 `npm publish`，把 source 指向本地 checkout 即可让改动立即生效：
+
+```bash
+# 一次性：环境变量优先级最高
+TMUXCLIHOOK_SOURCE=~/work/home/tmux-claude-hooks-status tmuxclihook
+
+# 持久化：写入 ~/.config/tmuxclihook/config.json，之后每次运行 tmuxclihook 都生效
+# （TUI 内「source 管理 → 设置本地开发路径」，或直接编辑该文件）
+```
+
+指向的路径必须包含 `scripts/` 子目录才会被采纳，否则该级解析会被跳过并给出警告，回落到下一级（配置文件 → 包内自带 → 仓库根）。
+
+**切换 source 不会自动重写已经写入的 hooks 配置或 `.tmux.conf`**——两者记录的是绝对路径快照，切换后需要重新执行一次「安装 hooks」与「tmux 集成」，新路径才会生效。在 TUI「source 管理」菜单选择"清除并恢复默认"可删除持久化配置，回到包内自带/仓库回落，同样需要重新执行安装动作才会生效。
 
 ## 环境自动修复规则
 
@@ -47,6 +75,12 @@ Doctor 只通过 Homebrew 执行明确且可验证的操作：
 
 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/adapters-meta.js` 的 `REPO_ROOT`/`SCRIPTS_DIR`/`TMUX_ENTRY` 不再是写死的相对路径，而是委托 `src/source.js` 的三级解析（`resolveSource()`）。这些导出是 ES module 的 live binding：`refreshSource()` 重新赋值后，所有下游 `import { REPO_ROOT } ...` 的调用方自动看到新值，无需重启进程——这是 TUI 内「source 管理」切换路径后立即生效的机制。
+
+npm 打包时（`npm publish` / `npm pack`），`package.json` 的 `prepack` 钩子（`tools/prepack-bundle.js`）把仓库根的 `scripts/` 与 `tmux-ai-hooks-status.tmux` 复制进 `installer/`（保留可执行位，排除隐藏文件），使发布的包自包含；`postpack` 钩子（`tools/prepack-clean.js`）随后清理这些复制产物，保持仓库工作区干净（复制产物已在根 `.gitignore` 中忽略，不会误入 git）。
+
+tmux 集成不再依赖 TPM 软链创建：`src/tmuxconf.js` 的 `ensureTmuxIntegration()` 直接在 `~/.tmux.conf` 写入/替换一行 `run-shell '<TMUX_ENTRY>'`；`src/symlink.js` 仅保留软链**检测**（`checkSymlink()`，用于提示历史遗留安装可清理）与 `.tmux.conf` 集成状态检测（`checkTmuxConf()`）。
+
 环境职责分离：
 
 - `src/detect.js`：只探测并分类 `ready` / `missing` / `outdated`；
@@ -62,10 +96,10 @@ npm run check
 npm test
 ```
 
-测试通过依赖注入模拟 Homebrew，不会真的执行安装、升级或网络操作。
+测试通过依赖注入模拟 Homebrew、文件系统路径（`source.js`/`tmuxconf.js` 均支持注入 `configFile`/`path` 等参数），不会真的执行安装、升级或网络操作，也不会触碰真实的 `~/.tmux.conf` / `~/.config/tmuxclihook/`。
 
 ## 发布（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。
+由 GitHub Actions 自动发布：push 到 `main` 且 `installer/package.json` 的 `version` 比 npm 上已发布版本新时（改动涉及 `installer/**`、`scripts/**` 或根 `tmux-ai-hooks-status.tmux` 均会触发工作流），`.github/workflows/publish-installer.yml` 自动执行 `npm publish --provenance --access public`（`prepack`/`postpack` 自动打包/清理仓库根脚本）、打 `installer-v<version>` tag 并创建 Release。
 
 发布前置：仓库 Settings → Secrets 配置 `NPM_TOKEN`（npm automation token）。手动发布版本：修改 `package.json` 的 `version` 后提交并 push 到 main。

package/bin/cli.js

@@ -1,18 +1,33 @@
 #!/usr/bin/env node
 // cli.js — tmux-ai-status 交互式安装 TUI（@clack/prompts）
 //
-// 主菜单：环境检查 / 侦测 CLI / 安装 / 卸载 / 修复 hooks / tmux 软链。
+// 主菜单：环境检查 / 侦测 CLI / 安装 / 卸载 / 修复 hooks / tmux 集成 / source 管理。
 // 实际 hooks 逻辑委托 bash wrapper（scripts/install-<tool>-hooks.sh）。
+//
+// "source" 决定 scripts/ 与 tmux 入口来自哪里：环境变量 TMUXCLIHOOK_SOURCE >
+// 持久化配置 ~/.config/tmuxclihook/config.json > 包内自带（生产默认）> 仓库根
+// （开发回落）。见 src/source.js 与 docs/2026-07-15-npm-global-install-plan.md。
 
+import { homedir } from 'node:os';
 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 { checkSymlink, checkTmuxConf } from '../src/symlink.js';
+import { ensureTmuxIntegration, reloadTmux } from '../src/tmuxconf.js';
 import { stopMonitor, clearAggregateStatus, removeSymlinks } from '../src/purge.js';
-import { TOOLS, repoExists, REPO_ROOT } from '../src/adapters-meta.js';
+import {
+  TOOLS,
+  repoExists,
+  REPO_ROOT,
+  TMUX_ENTRY,
+  SOURCE_ORIGIN,
+  SOURCE_WARNINGS,
+  refreshSource,
+} from '../src/adapters-meta.js';
+import { setSource, clearSource, getPersistedSource, originLabel } from '../src/source.js';
 import { note, padDisplay } from '../src/tui.js';
+import { updatePackage } from '../src/update.js';
 
 const OK = '✓';
 const NO = '✗';
@@ -153,44 +168,128 @@ async function runHookAction(action, verb) {
   }
 }
 
-async function symlinkMenu() {
-  const st = checkSymlink();
+// tmux 集成：不再依赖 TPM 软链，直接检查/修复 .tmux.conf 里指向当前 source
+// 的 run-shell 声明。历史遗留的 ~/.tmux/plugins/ 软链仅作提示，清理走「完整卸载插件」。
+// 确认 + 应用「确保 tmux 集成」，被「tmux 集成」菜单与启动时的主动检测共用。
+async function confirmAndApplyTmuxIntegration(conf) {
+  const go = await p.confirm({
+    message: conf.referenced
+      ? '.tmux.conf 中的声明指向过期路径（例如切换了 source），更新为当前路径并重载？'
+      : '.tmux.conf 未集成本插件，追加 run-shell 声明并重载？',
+  });
+  if (p.isCancel(go) || !go) return false;
+
+  const r = ensureTmuxIntegration();
+  if (!r.ok) { p.log.error(`${NO} 写入 .tmux.conf 失败：${r.output}`); return false; }
+  if (r.action === 'created') p.log.success(`${OK} 已创建 ${r.path} 并写入声明`);
+  else if (r.action === 'appended') p.log.success(`${OK} 已追加声明到 ${r.path}`);
+  else if (r.action === 'replaced') p.log.success(`${OK} 已更新 ${r.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`);
+  return true;
+}
+
+async function tmuxIntegrationMenu() {
+  const symlinkSt = checkSymlink();
   const conf = checkTmuxConf();
   const lines = [
-    `  软链 ${PLUGIN_LINE(st)}`,
-    `  .tmux.conf: ${conf.exists ? (conf.referenced ? `${OK} 已引用插件` : `${NO} 未引用（需手动加 @plugin 或 run）`) : `${NO} 不存在`}`,
+    `  加载方式：run-shell '${TMUX_ENTRY}'`,
+    `  .tmux.conf：${confStatusLine(conf)}`,
   ];
-  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('软链正常');
+  if (symlinkSt.status === 'ok') {
+    lines.push(`  历史遗留软链：检测到 ${symlinkSt.link}（新加载方式不再需要，可在「完整卸载插件」中一并清理）`);
   }
+  note(lines.join('\n'), 'tmux 集成');
+
+  if (conf.pointsToCurrent) {
+    p.log.success('已正确集成，无需操作');
+    return;
+  }
+
+  await confirmAndApplyTmuxIntegration(conf);
+}
+
+// 启动时主动检测：未集成 / 路径过期时主动提示，而非只在「tmux 集成」子菜单里被动
+// 等用户发现。尤其覆盖"全新 .tmux.conf"场景——`npm i -g` 装完不会自动写入任何东西
+// （没有 postinstall 钩子），必须经这一步或手动进「tmux 集成」菜单确认后才会写入。
+async function maybeOfferTmuxIntegration() {
+  const conf = checkTmuxConf();
+  if (conf.pointsToCurrent) return;
+
+  p.log.warn(
+    conf.exists
+      ? '.tmux.conf 尚未集成本插件（或路径已过期），状态栏与 hooks 不会自动生效。'
+      : '未找到 ~/.tmux.conf，可创建一个新文件并写入本插件的加载声明。',
+  );
+  await confirmAndApplyTmuxIntegration(conf);
+}
+
+function confStatusLine(conf) {
+  if (!conf.exists) return `${NO} 不存在`;
+  if (conf.pointsToCurrent) return `${OK} 已指向当前安装`;
+  if (conf.referenced) return `${NO} 已引用，但路径过期或为旧式声明`;
+  return `${NO} 未集成`;
+}
 
-  // 步骤 2：.tmux.conf 未引用插件则询问追加声明 + reload（闭合"软链建好但没加载"）
-  if (!conf.referenced) {
-    const decl = await p.confirm({
-      message: `.tmux.conf 未声明插件，追加 set -g @plugin 'tmux-ai-hooks-status' 并重载？`,
+// source 管理：查看当前生效 source（含来源与失效警告），设置本地开发路径，
+// 或清除持久化配置恢复默认。切换后仅影响"接下来"的 hooks 安装 / tmux 集成写入，
+// 已写入的旧路径需要重新执行对应操作才会更新（见 docs 计划的残留风险第 4 条）。
+function currentSourceLines() {
+  const lines = [
+    `  当前 source：${REPO_ROOT}`,
+    `  来源：${originLabel(SOURCE_ORIGIN)}`,
+  ];
+  for (const w of SOURCE_WARNINGS) lines.push(`  ⚠ ${w}`);
+  return lines;
+}
+
+async function sourceMenu() {
+  note(currentSourceLines().join('\n'), 'source 状态');
+
+  const persisted = getPersistedSource();
+  const choice = await p.select({
+    message: '选择操作（Esc 返回主菜单）',
+    options: [
+      { value: 'set', label: '设置本地开发路径', hint: '指向本地仓库，改代码即时生效' },
+      {
+        value: 'clear',
+        label: '清除并恢复默认',
+        hint: persisted ? `当前已保存：${persisted}` : '未设置持久化路径',
+      },
+      { value: '__back__', label: '← 返回主菜单' },
+    ],
+  });
+  if (p.isCancel(choice) || choice === '__back__') return;
+
+  if (choice === 'set') {
+    const dir = await p.text({
+      message: '输入本地仓库路径（需含 scripts/ 目录）',
+      placeholder: '~/work/home/tmux-claude-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`);
+    if (p.isCancel(dir) || !dir) { p.log.info('已取消'); return; }
+    const expanded = dir.startsWith('~') ? dir.replace(/^~/, homedir()) : dir;
+    const r = setSource(expanded);
+    if (!r.ok) { p.log.error(`${NO} ${r.output}`); return; }
+    refreshSource();
+    p.log.success(`${OK} source 已切换到 ${r.source}`);
+    p.log.warn('需重新执行「安装 hooks」与「tmux 集成」，新路径才会写入 hooks 配置 / .tmux.conf');
+    return;
+  }
+
+  if (choice === 'clear') {
+    const r = clearSource();
+    if (!r.ok) { p.log.error(`${NO} ${r.output}`); return; }
+    refreshSource();
+    p.log.success(`${OK} 已清除，恢复默认（${originLabel(SOURCE_ORIGIN)}）`);
+    p.log.warn('需重新执行「安装 hooks」与「tmux 集成」，默认路径才会写回 hooks 配置 / .tmux.conf');
   }
 }
 
 async function purgeMenu() {
-  p.log.warn('完整卸载：停止 monitor、清聚合状态、删软链。hooks 请先在「卸载 hooks」菜单移除。');
+  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; }
 
@@ -203,32 +302,28 @@ async function purgeMenu() {
   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('无软链可删除');
+  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" +
+    `  1. 从 ~/.tmux.conf 删除本插件的 run-shell 声明（形如 run-shell '.../tmux-ai-hooks-status.tmux'，\n` +
+    "     或历史遗留的 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 安装器');
 
+  note(currentSourceLines().join('\n'), 'source 状态');
+
   if (!repoExists) {
-    p.log.warn(`未定位到仓库 scripts/（期望 ${REPO_ROOT}）。若通过 npx 运行，请在仓库内或已装插件目录下运行。`);
+    p.log.warn(`当前 source（${REPO_ROOT}）下未找到 scripts/ 目录，hooks 安装与 tmux 集成将失败。请用「source 管理」指向一个有效仓库路径。`);
+  } else {
+    await maybeOfferTmuxIntegration();
   }
 
   while (true) {
@@ -240,8 +335,9 @@ async function main() {
         { value: 'install', label: '安装 hooks' },
         { value: 'uninstall', label: '卸载 hooks' },
         { value: 'repair', label: '修复 hooks', hint: '完整性检查 + 缺失重装' },
-        { value: 'symlink', label: 'tmux 软链校验' },
-        { value: 'purge', label: '完整卸载插件', hint: 'monitor stop + 清状态 + 删软链' },
+        { value: 'tmux', label: 'tmux 集成', hint: '校验/修复 .tmux.conf 的加载声明' },
+        { value: 'source', label: 'source 管理', hint: '生产默认 / 切换本地调试路径' },
+        { value: 'purge', label: '完整卸载插件', hint: 'monitor stop + 清状态 + 清历史软链' },
         { value: 'exit', label: '退出' },
       ],
     });
@@ -258,7 +354,8 @@ async function main() {
       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 === 'tmux') await tmuxIntegrationMenu();
+      else if (choice === 'source') await sourceMenu();
       else if (choice === 'purge') await purgeMenu();
     } catch (err) {
       p.log.error(String(err));
@@ -268,7 +365,16 @@ async function main() {
   p.outro('完成');
 }
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+if (process.argv[2] === 'update') {
+  updatePackage().then((ok) => {
+    if (!ok) process.exitCode = 1;
+  }).catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+  });
+} else {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmuxclihook",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "交互式 TUI 安装器：环境侦测、AI CLI 侦测、tmux-ai-status hooks 装/卸/修、TPM 软链校验",
   "type": "module",
   "bin": {
@@ -9,12 +9,16 @@
   "files": [
     "bin",
     "src",
+    "scripts",
+    "tmux-ai-hooks-status.tmux",
     "README.md"
   ],
   "scripts": {
-    "check": "for f in bin/cli.js src/*.js; do node --check \"$f\"; done && echo 'all js syntax OK'",
+    "check": "for f in bin/cli.js src/*.js tools/*.js; do node --check \"$f\"; done && echo 'all js syntax OK'",
     "start": "node bin/cli.js",
-    "test": "node --test"
+    "test": "node --test",
+    "prepack": "node tools/prepack-bundle.js",
+    "postpack": "node tools/prepack-clean.js"
   },
   "engines": {
     "node": ">=18"

package/scripts/adapters/claude.sh

@@ -0,0 +1,127 @@
+#!/bin/bash
+# adapters/claude.sh — Claude Code 工具适配器
+#
+# 由 lib-tmux-ai-status.sh 在确定 TOOL_ID=claude 后 source。声明 Claude Code 与其他
+# AI CLI 的差异；核心引擎读本文件暴露的变量/函数分派，不再写 case "$TOOL_ID"。
+#
+# 契约（每个 adapter 必须定义）：
+#   ADAPTER_EVENTS            该工具触发的事件集合（空格分隔）
+#   ADAPTER_PROCESS_NAMES     进程名（basename）集合，供 _pane_has_ai_process 识别
+#   ADAPTER_HOOKS_FILE        hooks 配置文件绝对路径
+#   ADAPTER_HAS_SESSION_END   "true"|"false" 是否有 SessionEnd 事件
+#   ADAPTER_SESSION_START_TIMING  "immediate"|"deferred" SessionStart 时机
+#   ADAPTER_HOLD_UNMATCHED_PERMISSION "true"|"false" 无请求 ID 时是否保守保持审批态
+#   ADAPTER_INSTALLER         install 脚本绝对路径（供自修复/TUI 调用）
+#   adapter_check_integrity() hooks 是否完整注册本插件（返回 0=完整）
+#   adapter_install_hooks()   安装 hooks（合并式，保留他人 hook）
+#   adapter_uninstall_hooks() 卸载本插件 hooks
+#
+# install/uninstall 依赖 lib-install-hooks.sh 的 _install_require_jq/_install_atomic_write，
+# 仅在被 install wrapper source 时可用；事件路径 source 本文件只定义函数不调用，零开销。
+
+# Claude Code 注册 10 个事件，全部 async（PermissionRequest 例外 sync）。
+ADAPTER_EVENTS="SessionStart SessionEnd UserPromptSubmit PreToolUse PostToolUse PostToolUseFailure PermissionRequest Notification Stop StopFailure"
+
+# 前台进程名（BFS pane 进程树匹配 basename）
+ADAPTER_PROCESS_NAMES="claude"
+
+# hooks 配置：~/.claude/settings.json（CLAUDE_CONFIG_DIR 可覆盖）
+ADAPTER_HOOKS_FILE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"
+
+# Claude Code 有 SessionEnd 事件，退出即发 hook → 状态可主动清。
+ADAPTER_HAS_SESSION_END="true"
+# SessionStart 在 CLI 启动时立即触发（对比 codex 延迟到首个 turn）。
+ADAPTER_SESSION_START_TIMING="immediate"
+# Claude 当前串行执行工具，完成事件可解除无 ID 的审批态。
+ADAPTER_HOLD_UNMATCHED_PERMISSION="false"
+
+# 自修复/TUI 调用的安装脚本
+ADAPTER_INSTALLER="${_LIB_DIR}/install-claude-hooks.sh"
+
+# 完整性检查：settings.json 的 10 个事件是否都注册了本插件 hook。
+# 缺失（外部应用覆盖配置）→ 返回 1。
+adapter_check_integrity() {
+    [ -f "$ADAPTER_HOOKS_FILE" ] || return 1
+    local registered
+    registered=$(jq '
+        .hooks as $h |
+        ["SessionStart","SessionEnd","UserPromptSubmit","PreToolUse","PostToolUse",
+         "PostToolUseFailure","PermissionRequest","Notification","Stop","StopFailure"]
+        | map(select([$h[.][]?.hooks[]?.command // empty] | any(contains("tmux-ai-status"))))
+        | length
+    ' "$ADAPTER_HOOKS_FILE" 2>/dev/null)
+    [ "${registered:-0}" -ge 10 ]
+}
+
+# Claude 事件集合（含同步事件 PermissionRequest）。install/uninstall 用。
+_CLAUDE_EVENTS="SessionStart SessionEnd UserPromptSubmit PreToolUse PostToolUse PostToolUseFailure PermissionRequest Notification Stop StopFailure"
+
+# 安装：合并式更新 settings.json，保留他人（masko 等）注册的 hook。
+# 清理 legacy 名（tmux-claude-status / tmux-powerline-claude-status）+ 指向其他路径的
+# stale tmux-ai-status 条目，$TOOL_CMD 未注册则追加。PermissionRequest 为 sync（async=false）。
+adapter_install_hooks() {
+    _install_require_jq
+    [ -f "$ADAPTER_HOOKS_FILE" ] || _install_atomic_write '{}' "$ADAPTER_HOOKS_FILE"
+    local hook_script="${_LIB_DIR}/tmux-ai-status"
+    local tool_cmd="${hook_script} claude"
+    local updated
+    updated=$(jq --arg dev_script "$hook_script" --arg tool_cmd "$tool_cmd" '
+        ["SessionStart","SessionEnd","UserPromptSubmit","PreToolUse","PostToolUse",
+         "PostToolUseFailure","PermissionRequest","Notification","Stop","StopFailure"] as $events |
+        ["PermissionRequest"] as $sync_events |
+        reduce $events[] as $event (
+            .;
+            ($tool_cmd + " " + $event) as $hook_cmd |
+            .hooks //= {} |
+            .hooks[$event] //= [] |
+            .hooks[$event] |= (
+                map(
+                    .hooks = [
+                        .hooks[]
+                        | select(.command | contains("tmux-powerline-claude-status") | not)
+                        | select(.command | contains("tmux-claude-status") | not)
+                        | select(
+                            (.command | contains("tmux-ai-status") | not)
+                            or (.command | startswith($dev_script))
+                        )
+                    ]
+                    | select(.hooks | length > 0)
+                )
+            ) |
+            if ([.hooks[$event][]?.hooks[]?.command] | index($hook_cmd)) == null then
+                .hooks[$event] += [{
+                    "hooks": [{
+                        "async": (($event | IN($sync_events[])) | not),
+                        "command": $hook_cmd,
+                        "type": "command"
+                    }],
+                    "matcher": ""
+                }]
+            else . end
+        )
+    ' "$ADAPTER_HOOKS_FILE")
+    _install_atomic_write "$updated" "$ADAPTER_HOOKS_FILE"
+    echo "Claude hooks installed to $ADAPTER_HOOKS_FILE"
+    echo "Events: $_CLAUDE_EVENTS"
+}
+
+# 卸载：单次 jq pipeline 移除所有指向本插件的 hooks，保留他人条目。
+adapter_uninstall_hooks() {
+    _install_require_jq
+    [ -f "$ADAPTER_HOOKS_FILE" ] || { echo "Claude hooks: nothing to uninstall"; return 0; }
+    local hook_script="${_LIB_DIR}/tmux-ai-status"
+    local updated
+    updated=$(jq --arg hook_script "$hook_script" '
+        .hooks |= if . then
+            [. | to_entries[] |
+                .value |= [
+                    .[] | .hooks = [.hooks[] | select(.command | startswith($hook_script) | not)]
+                    | select(.hooks | length > 0)
+                ]
+                | select(.value | length > 0)
+            ] | from_entries
+        else . end
+    ' "$ADAPTER_HOOKS_FILE")
+    _install_atomic_write "$updated" "$ADAPTER_HOOKS_FILE"
+    echo "Claude hooks uninstalled from $ADAPTER_HOOKS_FILE"
+}

package/scripts/adapters/codex.sh

@@ -0,0 +1,114 @@
+#!/bin/bash
+# adapters/codex.sh — Codex CLI 工具适配器（需 codex ≥ 0.144）
+#
+# 由 lib-tmux-ai-status.sh 在确定 TOOL_ID=codex 后 source。契约见 adapters/claude.sh 头注释。
+#
+# ⚠️ Codex 0.144 与 Claude 的关键差异（本 adapter 声明的语义）：
+#   - 无 SessionEnd 事件：codex 退出无任何 hook，pane 内 shell 仍活时 pane-exited 也不触发。
+#     退出状态由 tmux-ai-monitor 跟踪已见 Codex 的 pane，进程消失后精确清除。
+#   - SessionStart 延迟：codex 的 SessionStart hook 延迟到首个 turn 才发（上游
+#     run_pending_session_start_hooks），空闲蹲提示符时无事件。空窗期靠 build_all_status
+#     用 pane_current_command 补 idle `-`。
+#   - hook trust 门禁：user 来源 hook 需 hooks.state.<key>.trusted_hash 匹配才运行；
+#     hash 无法在 bash 复现，靠用户首启 codex TUI 点 "Trust all and continue"。
+
+# Codex 只触发 6 个事件（无 SessionEnd/Notification/PostToolUseFailure/StopFailure）。
+ADAPTER_EVENTS="SessionStart UserPromptSubmit PreToolUse PermissionRequest PostToolUse Stop"
+
+# 前台进程名（macOS 上 codex 二进制常为 codex-aarch64-* 等，basename 前缀匹配见
+# _pane_has_ai_process 的 case codex*)）
+ADAPTER_PROCESS_NAMES="codex"
+
+# hooks 配置：~/.codex/hooks.json（CODEX_HOME 可覆盖）
+ADAPTER_HOOKS_FILE="${CODEX_HOME:-$HOME/.codex}/hooks.json"
+
+# Codex 无 SessionEnd → 退出由 tmux-ai-monitor 做进程检测
+ADAPTER_HAS_SESSION_END="false"
+# SessionStart 延迟到首个 turn
+ADAPTER_SESSION_START_TIMING="deferred"
+# PermissionRequest 不含 tool_use_id，而 Codex 支持并行工具。用 sentinel 保守保持 `!`，
+# 直到 Stop/UserPromptSubmit/SessionStart 清理，避免其他工具完成时漏报待审批。
+ADAPTER_HOLD_UNMATCHED_PERMISSION="true"
+
+# 自修复/TUI 调用的安装脚本
+ADAPTER_INSTALLER="${_LIB_DIR}/install-codex-hooks.sh"
+
+# 完整性检查：hooks.json 是否含 6 个本插件 command（0.144+）。
+adapter_check_integrity() {
+    [ -f "$ADAPTER_HOOKS_FILE" ] || return 1
+    local n
+    n=$(jq '[.hooks[]?[]?.hooks[]?.command // empty
+             | select(contains("tmux-ai-status codex"))] | length' \
+        "$ADAPTER_HOOKS_FILE" 2>/dev/null)
+    [ "${n:-0}" -ge 6 ]
+}
+
+# Codex 6 事件（全部同步——0.144 静默跳过 async=true 的 hook）
+_CODEX_EVENTS="SessionStart UserPromptSubmit PreToolUse PermissionRequest PostToolUse Stop"
+_CODEX_LEGACY_TOML="${CODEX_HOME:-$HOME/.codex}/hooks.toml"
+
+# 从每个事件数组剔除本插件 group（command 含 tmux-ai-status），事件/hooks 清空后删键。
+_codex_strip_managed() {
+    jq '
+      def clean_event:
+        map(select(
+          (.hooks // []) | any(.type == "command" and (.command // "" | contains("tmux-ai-status"))) | not
+        ));
+      if .hooks then
+        .hooks |= (with_entries(.value |= clean_event) | with_entries(select(.value | length > 0)))
+      else . end
+      | if (.hooks // {}) == {} then del(.hooks) else . end
+    '
+}
+
+_codex_read_existing() {
+    if [ -f "$ADAPTER_HOOKS_FILE" ] && jq empty "$ADAPTER_HOOKS_FILE" >/dev/null 2>&1; then
+        cat "$ADAPTER_HOOKS_FILE"
+    else
+        echo '{}'
+    fi
+}
+
+# 安装：改写 hooks.json（剥离旧 managed group 后为每事件追加本插件 group），保留他人 hook。
+# 清理旧 hooks.toml（0.144 不再读取）。trust 无法在 bash 复现，靠用户首启 codex TUI 授信。
+adapter_install_hooks() {
+    _install_require_jq
+    mkdir -p "$(dirname "$ADAPTER_HOOKS_FILE")" 2>/dev/null || true
+    [ -f "$_CODEX_LEGACY_TOML" ] && rm -f "$_CODEX_LEGACY_TOML" && echo "移除旧 hooks.toml（0.144 不再读取）"
+    local hook_script="${_LIB_DIR}/tmux-ai-status"
+    local new_json
+    new_json=$(_codex_read_existing | _codex_strip_managed | jq \
+        --arg script "$hook_script" \
+        --arg events "$_CODEX_EVENTS" '
+          .hooks //= {}
+          | reduce ($events | split(" ")[]) as $ev (.;
+              .hooks[$ev] = ((.hooks[$ev] // []) + [{
+                hooks: [{ type: "command", command: ($script + " codex " + $ev), timeout: 5 }]
+              }])
+            )
+        ')
+    _install_atomic_write "$new_json" "$ADAPTER_HOOKS_FILE"
+    echo "Codex hooks installed to $ADAPTER_HOOKS_FILE"
+    echo "Events: $_CODEX_EVENTS"
+    echo ""
+    echo "⚠️  下次启动 codex 时 TUI 会提示 \"Hooks need review\"，选择 \"Trust all and continue\" 授信一次即可永久生效。"
+}
+
+# 卸载：剥离本插件 group，剩空对象则删文件，否则写回。清理旧 toml。
+adapter_uninstall_hooks() {
+    _install_require_jq
+    [ -f "$_CODEX_LEGACY_TOML" ] && rm -f "$_CODEX_LEGACY_TOML" && echo "移除旧 hooks.toml"
+    if [ -f "$ADAPTER_HOOKS_FILE" ]; then
+        local stripped
+        stripped=$(_codex_read_existing | _codex_strip_managed)
+        if [ "$(printf '%s' "$stripped" | jq -c .)" = "{}" ]; then
+            rm -f "$ADAPTER_HOOKS_FILE"
+            echo "Codex hooks uninstalled (removed empty $ADAPTER_HOOKS_FILE)"
+        else
+            _install_atomic_write "$stripped" "$ADAPTER_HOOKS_FILE"
+            echo "Codex hooks uninstalled from $ADAPTER_HOOKS_FILE (preserved external content)"
+        fi
+    else
+        echo "Codex hooks: nothing to uninstall ($ADAPTER_HOOKS_FILE not found)"
+    fi
+}