tmuxclihook 0.5.1 → 0.5.2

package/README.md

@@ -12,7 +12,7 @@ tmuxclihook
 # 按当前安装方式（npm/volta）检查并更新到最新版
 tmuxclihook update
 
-# 升级并直接删除不生效的另一份安装（默认会交互确认）
+# 删除不生效的另一份安装；已是最新时也会执行清理（默认交互确认）
 tmuxclihook update --prune
 
 # hooks 健康明细（非交互）：每个 CLI 的完整性、判定真源、注册路径、漂移警告
@@ -37,11 +37,11 @@ npm start
 
 hooks 安装、tmux 集成写入的路径由「source」决定：环境变量 `TMUXCLIHOOK_SOURCE` > 持久化配置 `~/.config/tmuxclihook/config.json`（TUI「source 管理」菜单写入）> 包内自带 scripts/（生产默认）> 仓库根 scripts/（`cd installer && npm start` 时的开发回落）。见下方「source 管理」一节。
 
-`tmuxclihook update` 会显示当前版本，通过 `npm view tmuxclihook version` 查询最新版；版本相同则不做修改。需要升级时，它按 PATH 上第一个可执行的 `tmuxclihook` 判断当前生效的安装方式：入口位于 `$VOLTA_HOME/bin/`（默认 `~/.volta/bin/`）或 volta 的 packages 镜像内时，只执行 `volta install tmuxclihook@latest`；其余入口（npm 全局、nvm/fnm 等 node 工具链目录）只执行 `npm install -g tmuxclihook@latest`。不会同时写入两套安装。网络查询或安装失败时命令以非零状态退出。
+`tmuxclihook update` 会显示当前版本，通过 `npm view tmuxclihook version` 查询最新版；版本相同则不做任何安装（若显式传入 `--prune`，仍会执行一次非生效副本检测与清理）。需要升级时，它按 PATH 上第一个可执行的 `tmuxclihook` 判断当前生效的安装方式：入口位于 `$VOLTA_HOME/bin/`（默认 `~/.volta/bin/`）或 volta 的 packages 镜像内时，只执行 `volta install tmuxclihook@latest`；其余入口（npm 全局、nvm/fnm 等 node 工具链目录）只执行 `npm install -g tmuxclihook@latest`。不会同时写入两套安装。网络查询或安装失败时命令以非零状态退出。
 
 安装完成后会按 PATH 自检实际生效版本。若生效入口不是 volta、自检仍未反映新版，且本机可执行 volta，则补执行一次 `volta install tmuxclihook@latest` 作为兜底并复检；仍不一致时打印警告（不影响退出码）。
 
-升级确认成功后，update 会检查另一套安装（volta packages 镜像或当前 npm 全局 prefix）是否还留有副本。发现副本时：TTY 下询问是否删除（默认不删）；非交互环境只打印警告；`--prune` 跳过询问直接删除。删除前会校验该副本未被任何 hooks 与 `~/.tmux.conf` 引用——任一检查无法确认就保留并提示先重装 hooks。**生效入口永远不删**，清理失败不影响升级结果。也可以手动收敛：卸载不再使用的那份（`npm uninstall -g tmuxclihook` 或 `volta uninstall tmuxclihook`），再从生效入口重新安装 hooks。
+升级成功，或版本已是最新且显式传入 `--prune` 时，update 会检查另一套安装（volta packages 镜像或当前 npm 全局 prefix）是否还留有副本。发现副本时：TTY 下询问是否删除（默认不删）；非交互环境只打印警告；`--prune` 跳过询问直接删除。删除前会校验该副本未被任何 hooks 与 `~/.tmux.conf` 引用——任一检查无法确认就保留并提示先重装 hooks。**生效入口永远不删**，清理失败不影响升级结果。也可以手动收敛：卸载不再使用的那份（`npm uninstall -g tmuxclihook` 或 `volta uninstall tmuxclihook`），再从生效入口重新安装 hooks。
 
 ## 功能
 

package/bin/cli.js

@@ -31,6 +31,7 @@ import { setSource, clearSource, getPersistedSource, originLabel } from '../src/
 import { enableEscapeCancel, setSpinnerActive } from '../src/esc.js';
 import { note, padDisplay } from '../src/tui.js';
 import { updatePackage, CURRENT_VERSION } from '../src/update.js';
+import { HELP_TEXT } from '../src/help.js';
 
 const OK = '✓';
 const NO = '✗';
@@ -505,17 +506,7 @@ if (arg === 'update') {
 } else if (arg === '--version' || arg === '-v' || arg === 'version') {
   console.log(`tmuxclihook v${CURRENT_VERSION}`);
 } else if (arg === '--help' || arg === '-h' || arg === 'help') {
-  console.log(
-    'tmuxclihook — tmux-ai-status 交互式安装器\n' +
-    '\n' +
-    '用法：\n' +
-    '  tmuxclihook              打开交互式 TUI 安装器\n' +
-    '  tmuxclihook check        hooks 健康明细（可跟 claude|codex|opencode；exit 1 = 有缺失或漂移）\n' +
-    '  tmuxclihook update       按当前安装方式（npm/volta）检查并更新到最新版本\n' +
-    '  tmuxclihook update --prune  升级后直接删除不生效的另一份安装（默认交互确认）\n' +
-    '  tmuxclihook version      显示版本（--version / -v 等价）\n' +
-    '  tmuxclihook help         显示本帮助（--help / -h 等价）',
-  );
+  console.log(HELP_TEXT);
 } else {
   main().catch((err) => {
     console.error(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmuxclihook",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "交互式 TUI 安装器：环境侦测、AI CLI 侦测、tmux-ai-status hooks 装/卸/修、TPM 软链校验",
   "type": "module",
   "bin": {

package/src/help.js

@@ -0,0 +1,31 @@
+// `tmuxclihook help` 的静态文案。独立成模块是为了让测试可以直接 import，
+// 而不必加载 bin/cli.js（入口文件顶层会执行参数分支，未知参数会启动 TUI）。
+const COMMAND_WIDTH = 26;
+
+function line(command, description) {
+  return `  ${command.padEnd(COMMAND_WIDTH)}  ${description}`;
+}
+
+export const HELP_TEXT = [
+  'tmuxclihook — tmux-ai-status 交互式安装器',
+  '',
+  '命令行：',
+  line('tmuxclihook', '打开交互式 TUI 安装器'),
+  line('tmuxclihook check', 'hooks 健康明细（可跟 claude|codex|opencode；exit 1 = 有缺失或漂移）'),
+  line('tmuxclihook update', '按当前安装方式（npm/volta）检查并更新到最新版本'),
+  line('tmuxclihook update --prune', '更新后删除不生效的另一份安装；已是最新时也会执行清理'),
+  line('tmuxclihook version', '显示版本（--version / -v 等价）'),
+  line('tmuxclihook help', '显示本帮助（--help / -h 等价）'),
+  '',
+  'tmux 快捷键（插件加载后生效）：',
+  line('prefix + I', '打开交互式 TUI 安装器'),
+  line('prefix + C-h', '安装 Claude Code hooks'),
+  line('prefix + C-u', '卸载 Claude Code hooks'),
+  line('prefix + M-h', '安装 Codex hooks'),
+  line('prefix + M-u', '卸载 Codex hooks'),
+  line('prefix + C-p', '安装 opencode plugin'),
+  line('prefix + M-p', '卸载 opencode plugin'),
+  line('prefix + r', '重载配置（含本插件初始化）'),
+  '',
+  'prefix 默认是 Ctrl+b；若你在 tmux 配置中改过 prefix，以你的配置为准。',
+].join('\n');

package/src/update.js

@@ -290,6 +290,26 @@ function warnNotEffective(log, result) {
   log.error(`If you use volta, run: volta install ${PACKAGE_NAME}@latest`);
 }
 
+// 清理非生效副本，并在实际删除过副本后复检生效入口。升级成功路径与
+// 「已是最新 + --prune」路径共用，避免两处逻辑漂移。清理失败只记录日志，
+// 不影响 update 的返回值。
+async function reconcileStaleCopies({
+  source, env, run, log, prune, isTTY, confirm,
+  checkHooks, checkTmuxConf, detectStale, verify, expectedVersion,
+}) {
+  try {
+    const removed = await cleanupStale({
+      source, env, run, log, prune, isTTY, confirm, checkHooks, checkTmuxConf, detectStale,
+    });
+    if (removed && verify) {
+      const after = await verify(expectedVersion, env);
+      if (after.status !== 'ok') warnNotEffective(log, after);
+    }
+  } catch (err) {
+    log.error(`Cleanup skipped: ${err}`);
+  }
+}
+
 // volta 安装路径：当 PATH 上的生效入口来自 volta（shim 或 packages 镜像）
 // 时，升级只能走 `volta install`——`npm install -g` 只写 node 工具链目录，
 // 不会更新 volta 的 packages 镜像。此函数现在是 volta 分支的唯一升级动作，
@@ -346,6 +366,20 @@ export async function updatePackage(options = {}) {
 
   if (currentVersion === latestVersion) {
     log.log('Already up to date.');
+
+    // 版本已最新：绝不安装；仅显式 --prune 时收敛非生效副本。
+    // 未传 --prune 时保持历史行为：不探测来源、不清理、直接返回。
+    if (cleanup && prune) {
+      const effectiveSource = typeof detectSource === 'function'
+        ? detectSource(env)
+        : 'unknown';
+      await reconcileStaleCopies({
+        source: effectiveSource, env, run, log, prune, isTTY, confirm,
+        checkHooks, checkTmuxConf, detectStale, verify,
+        expectedVersion: latestVersion,
+      });
+    }
+
     return true;
   }
 
@@ -394,18 +428,11 @@ export async function updatePackage(options = {}) {
 
   // 升级已确认成功后再收敛历史副本；清理失败不影响升级结果，也不改变退出码。
   if (cleanup && result.status === 'ok') {
-    try {
-      const removed = await cleanupStale({
-        source, env, run, log, prune, isTTY, confirm, checkHooks, checkTmuxConf, detectStale,
-      });
-      // 删过东西就再确认一次生效入口，避免误删导致命令不可用。
-      if (removed && verify) {
-        const after = await verify(latestVersion, env);
-        if (after.status !== 'ok') warnNotEffective(log, after);
-      }
-    } catch (err) {
-      log.error(`Cleanup skipped: ${err}`);
-    }
+    await reconcileStaleCopies({
+      source, env, run, log, prune, isTTY, confirm,
+      checkHooks, checkTmuxConf, detectStale, verify,
+      expectedVersion: latestVersion,
+    });
   }
 
   return true;