@kira905/dsh-butler-install 0.2.0 → 0.3.0

package/lib/exec.mjs

@@ -9,7 +9,7 @@
  * 打印出来的命令行与真正执行的命令行是同一个函数生成的，报告里不会出现"说要跑 A、
  * 实际跑了 B"。
  */
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 
 const SAFE_ARG = /^[A-Za-z0-9@/._:+=,~^()-]+$/;
 
@@ -40,12 +40,66 @@ function killTree(pid) {
   }
 }
 
+/** 当前还活着的子进程 pid（只记我们自己 spawn 的；进程退出时要靠它把树杀干净） */
+const liveChildren = new Set();
+
+export function runningChildPids() {
+  return [...liveChildren];
+}
+
+/** 退出钩子专用：把还在跑的子进程树**同步**杀一遍，返回杀了几棵 */
+export function killAllRunningSync() {
+  let killed = 0;
+  for (const pid of liveChildren) {
+    if (killTreeSync(pid)) killed += 1;
+  }
+  liveChildren.clear();
+  return killed;
+}
+
+/**
+ * 同步版杀进程树 —— **只给退出钩子用**。
+ *
+ * 为什么非要有这一份：`killTree()` 走的是**异步** `spawn`，而 Node 的 `process.on('exit')`
+ * 里只能跑同步代码。于是"Ctrl+C 不留孤儿 npm"如果用异步版，会有两种假象之一：
+ * 要么钩子跑完异步 spawn 还没被执行（进程已经没了），要么子进程被杀了一半。
+ * 实测结论：退出钩子必须同步 —— 这里用 `spawnSync('taskkill', …)`。
+ *
+ * ⚠️ `/T` 在这里是对的：它只针对**我们自己起的**那棵子进程树。
+ * 与"杀 dsh 不能带 /T（会连坐守护鱼）"是两件不同的事，别把结论搬过去。
+ */
+export function killTreeSync(pid) {
+  if (!pid) return false;
+  try {
+    if (process.platform === 'win32') {
+      const res = spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+      return res && res.status === 0;
+    }
+    try { process.kill(-pid, 'SIGKILL'); } catch { process.kill(pid, 'SIGKILL'); }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 取消之后最多再等这么久就把它当成"已停"（子进程被杀但不发 close 的兜底） */
+const ABORT_SETTLE_MS = 3000;
+
 /**
- * @returns {Promise<{code:number|null, stdout:string, stderr:string, timedOut:boolean, cmdline:string, error?:string}>}
+ * @param {object} [options]
+ * @param {number} [options.timeoutMs] 单步超时（到点按超时处理，走 killTree）
+ * @param {AbortSignal} [options.signal] 外部取消。**不传 ⇒ 行为与加这个参数之前一模一样**
+ * @returns {Promise<{code:number|null, stdout:string, stderr:string, timedOut:boolean, aborted:boolean, cmdline:string, error?:string}>}
  */
 export function spawnCommand(file, args, options = {}) {
-  const { timeoutMs = 120000, env = {}, cwd, onLine, quiet = false } = options;
+  const { timeoutMs = 120000, env = {}, cwd, onLine, quiet = false, signal } = options;
   const cmdline = formatCommandLine(file, args);
+
+  // 已经取消过了就别起进程：起一个立刻杀一个既慢又会给用户看一个假的"正在装"
+  if (signal && signal.aborted) {
+    return Promise.resolve({ code: null, stdout: '', stderr: '', timedOut: false, aborted: true, cmdline, error: 'aborted-before-start' });
+  }
+
   return new Promise((resolve) => {
     let child;
     try {
@@ -56,20 +110,51 @@ export function spawnCommand(file, args, options = {}) {
         env: { ...process.env, ...env },
       });
     } catch (err) {
-      resolve({ code: null, stdout: '', stderr: '', timedOut: false, cmdline, error: String(err && err.message ? err.message : err) });
+      resolve({ code: null, stdout: '', stderr: '', timedOut: false, aborted: false, cmdline, error: String(err && err.message ? err.message : err) });
       return;
     }
 
     let stdout = '';
     let stderr = '';
     let timedOut = false;
+    let aborted = false;
     let settled = false;
+    let abortSettleTimer = null;
+    let timer = null;
+    // 登记在册：进程退出时（Ctrl+C / 关 .cmd 窗口）要靠这份名册把子进程树同步杀掉，
+    // 否则页面停了、npm 还在改 profile（方案 R2）
+    if (child.pid) liveChildren.add(child.pid);
 
-    const timer = setTimeout(() => {
+    const finish = (payload) => {
+      if (settled) return;
+      settled = true;
+      if (child.pid) liveChildren.delete(child.pid);
+      if (timer) clearTimeout(timer);
+      if (abortSettleTimer) clearTimeout(abortSettleTimer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve(payload);
+    };
+
+    timer = setTimeout(() => {
       timedOut = true;
       killTree(child.pid);
     }, timeoutMs);
 
+    // 取消与超时走**同一个** killTree 分支：都是"这条命令不能算成功"，只是原因不同
+    const onAbort = () => {
+      if (settled) return;
+      aborted = true;
+      killTree(child.pid);
+      // 子进程被杀之后 close 一般很快就来；万一来不了，也不能让"取消中…"永远挂着
+      abortSettleTimer = setTimeout(() => {
+        finish({ code: null, stdout, stderr, timedOut, aborted, cmdline });
+      }, ABORT_SETTLE_MS);
+    };
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener('abort', onAbort, { once: true });
+    }
+
     const pump = (stream, into) => {
       let buffer = '';
       stream.on('data', (chunk) => {
@@ -90,17 +175,11 @@ export function spawnCommand(file, args, options = {}) {
     if (child.stderr) pump(child.stderr, 'err');
 
     child.on('error', (err) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve({ code: null, stdout, stderr, timedOut, cmdline, error: String(err && err.message ? err.message : err) });
+      finish({ code: null, stdout, stderr, timedOut, aborted, cmdline, error: String(err && err.message ? err.message : err) });
     });
 
     child.on('close', (code) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve({ code, stdout, stderr, timedOut, cmdline });
+      finish({ code, stdout, stderr, timedOut, aborted, cmdline });
     });
   });
 }

package/lib/explain-failure.mjs

@@ -0,0 +1,117 @@
+/**
+ * 把「环境障碍」翻成人话 —— 只给展示用，**不参与任何判据**。
+ *
+ * 为什么要有这一层：真装验收里撞到过两类拦路虎，安装器原来只甩一段英文原文，
+ * 用户看不出"这到底是包坏了、网络坏了、还是我自己的机器拦了它"。
+ *
+ * 三条硬边界（改这个文件之前先读一遍）：
+ *  1. **纯函数**：不 spawn 子进程、不读盘、不发网络请求、不打日志。传什么进来看什么。
+ *  2. 认不出就返回 `null` —— 宁可不说，也不许瞎猜。猜错比不说更糟：
+ *     用户会照着错的"怎么办"去改机器。
+ *  3. 只做**追加**：调用方必须先原样打印原始 stderr，归因永远排在它后面。
+ *     本文件不认识退出码语义，也不允许谁拿 `kind` 当判据（0/2/3/4 一个不动）。
+ *
+ * 两类签名的真实出处（都来自真跑，不是编的）：
+ *  - `blocked-symlink`：Windows 上 360 / EDR 拦 pnpm 建符号链接，pnpm 栈里落在 registerProject
+ *  - `store-mismatch`：pnpm store 与已有 node_modules 不是同一处（不同盘 / 换过数据根）
+ */
+
+/** 认得出来的码：`ERR_PNPM_UNEXPECTED_STORE` 最精确，先认它 */
+const CODE_STORE_MISMATCH = 'ERR_PNPM_UNEXPECTED_STORE';
+/** pnpm 所有自己的错误码都是这个前缀（认得出"是 pnpm 的错"，但具体含义未必收录） */
+const ANY_PNPM_CODE = /\bERR_PNPM_[A-Z0-9_]+\b/;
+
+function splitLines(text) {
+  return String(text || '').split(/\r?\n/);
+}
+
+/**
+ * 解释一次 pnpm（或经 pnpm 的 `dsh plugin`）失败。
+ *
+ * @param {{stderr?: string, stdout?: string}} [input] 两个流任一命中都算
+ * @returns {{kind: string, code: string|null, title: string, why: string, fix: string}|null}
+ */
+export function explainPnpmFailure({ stderr, stdout } = {}) {
+  const errText = String(stderr || '');
+  const outText = String(stdout || '');
+  const text = `${errText}\n${outText}`;
+  if (!text.trim()) return null;
+  const lines = splitLines(text);
+
+  // ① store 与已有 node_modules 不是同一处：码是本工具最精确的指纹，先认它。
+  //    先于 blocked-symlink 判：两者万一同时出现，"要你用回原来那处 store"这句更可执行。
+  if (text.includes(CODE_STORE_MISMATCH)) {
+    return {
+      kind: 'store-mismatch',
+      code: CODE_STORE_MISMATCH,
+      title: '这个 profile 的 node_modules 是用另一处 pnpm store 装的，pnpm 现在想用新的那处，两边对不上。',
+      why: 'pnpm 在 node_modules 里记着"我是从哪个 store 链过来的"；发现要用的 store 不是同一条就停手，'
+        + '免得把已装依赖的链接链断掉。这条不是包坏了，也不是网络问题。',
+      fix: '① 让 pnpm 用回原来那处（pnpm config set store-dir <上面报的那个 store>）'
+        + '  ② 或者就在那个 profile 里重装依赖（pnpm install，让 pnpm 按新 store 重链一遍）'
+        + '  ③ 换一个干净的数据根（--home 指到一个空目录）',
+    };
+  }
+
+  // ② 安全软件拦符号链接。判据两条，任一命中：
+  //    a) 某一行里同时出现 EPERM 与 symlink（pnpm 的原样报错就长这样）
+  //    b) 栈里出现 registerProject（pnpm「给这个 project 登记 store 链接」那一步被拦）
+  const epermSymlink = lines.some((l) => /\bEPERM\b/.test(l) && /symlink/i.test(l));
+  const registerProject = /registerProject/.test(text);
+  if (epermSymlink || registerProject) {
+    return {
+      kind: 'blocked-symlink',
+      code: epermSymlink ? 'EPERM' : null,
+      title: '这不是包坏了：你的安全软件（360 / EDR）拦了 pnpm 往 store 里建符号链接。',
+      why: 'pnpm 靠"store 里存一份真文件、各 profile 只放符号链接"来省空间；建链接这一步会被安全软件当成可疑动作拦掉。'
+        + '这类拦截是间歇出现的 —— 同一条命令重试一次可能就过了。',
+      fix: '① 在安全软件里给 pnpm / node 放行（或暂时退出）'
+        + '  ② 换个不会被拦的位置做数据根（--home 指到别处）'
+        + '  ③ 直接重试一次（这类拦截是间歇的）',
+    };
+  }
+
+  // ③ 认得出是 pnpm 自己的错，但这条码没收录 ⇒ 给原码 + 让用户把原文带走。
+  //    注意：这里**不**猜原因 —— 只说"是 pnpm 这一层报的，怎么修得看这个码"。
+  const anyCode = text.match(ANY_PNPM_CODE);
+  if (anyCode) {
+    const code = anyCode[0];
+    return {
+      kind: 'unknown-pnpm',
+      code,
+      title: `pnpm 自己报的错（${code}），这条码本工具还没收录。`,
+      why: '能确定是 pnpm 这一层的错（不是本工具的判据失败，也不是网络偶发），但具体怎么修得看这个码的含义。',
+      fix: `把上面那段原始输出整段贴给维护者，或者去 pnpm 文档 / 搜索引擎里搜「${code}」。`,
+    };
+  }
+
+  // 认不出 —— 别硬编。
+  return null;
+}
+
+/**
+ * 退出码写人话：Windows 上子进程被信号/异常结束时，`res.code` 是**无符号**值，
+ * 日志里就出现过 `退出码 4294963248`（其实是 -4048 / 0xFFFFF030 那一类）。人读不出来。
+ *
+ * 规则：原始数值**一律保留**在最前面（可解析性不能丢），能解释成负数/十六进制时追加在括号里。
+ * 常规退码（0~65535）原样返回 —— 不减一个字。
+ *
+ * @param {number|string|null|undefined} code
+ * @returns {string}
+ */
+export function formatExitCode(code) {
+  if (code === null || code === undefined) return '未知';
+  const n = Number(code);
+  if (!Number.isFinite(n)) return String(code);
+  if (!Number.isInteger(n)) return String(code);
+  if (n === 0) return '0';
+
+  const hex = (v) => `0x${(v >>> 0).toString(16).toUpperCase().padStart(8, '0')}`;
+  // 负数：补码形态最能对上文档里的 0xFFFFF030 那种写法
+  if (n < 0) return `${n}（${hex(n)}）`;
+  // 2^31 以上：极可能是无符号包装过的负数（Windows 的 CRASH / 异常退出码都在这段）
+  if (n > 0x7fffffff) return `${n}（= ${n - 0x100000000}，${hex(n)}）`;
+  // 65535 以上但没溢出符号位：罕见的自定义码，给出十六进制方便对照
+  if (n > 0xffff) return `${n}（${hex(n)}）`;
+  return String(n);
+}

package/lib/item-status.mjs

@@ -0,0 +1,64 @@
+/**
+ * 安装状态的两套徽标 —— **全仓只有这一份实现**。
+ *
+ * 为什么单独抽出来（方案 §11.6 · S1）：
+ *  `ui-page.mjs` 里原来有两份 `statusOf()`：一份给服务端首屏渲染、一份塞在页面脚本里。
+ *  加"安装中 / 成功 / 失败"这三个运行态时，两份必然漂移 —— 首屏说"已装"、重查后说"未装"，
+ *  用户会以为安装器瞎报。
+ *
+ * 所以现在的规矩是：
+ *  - 服务端用 `statusOf()` 渲染首屏，**并且**把结果作为 `item.status` 一起下发（`decorateState`）；
+ *  - 页面脚本**不再自己算**，只读 `item.status` / `item.label` 这两个字段。
+ *  ⇒ 想改文案、想加状态，来这里改一处，两处自动一致。
+ *
+ * 两套徽标是不同的东西，别混：
+ *  - `statusOf(item)`   = 「这一项**现在装着没有**」（未装 / 已装 / 版本不在区间…）
+ *  - `runLabel(status)` = 「这一轮**跑到它时怎么样**」（待装 / 安装中 / 成功 / 跳过 / 失败 / 已取消）
+ */
+
+/** 运行态徽标（进度区与清单表共用） */
+export const RUN_LABELS = {
+  pending: { cls: 'badge-wait', text: '待装' },
+  running: { cls: 'badge-run', text: '安装中' },
+  ok: { cls: 'badge-ok', text: '成功' },
+  skip: { cls: 'badge-skip', text: '跳过' },
+  fail: { cls: 'badge-bad', text: '失败' },
+  cancelled: { cls: 'badge-warn', text: '已取消' },
+};
+
+export function runLabel(status) {
+  return RUN_LABELS[status] || RUN_LABELS.pending;
+}
+
+const RUN_HINTS = {
+  pending: '还没轮到它',
+  running: '正在跑这一步的命令',
+  ok: '当场判据过了（不是"命令退出码 0"）',
+  skip: '已经满足，这一轮不动它',
+  fail: '这一步没成（看下面那行 detail）',
+  cancelled: '取消时正跑到它',
+};
+
+/**
+ * 「现在装着没有」的徽标。
+ * `item.run` 存在时优先（同一行既可能"已装"、也可能"这一轮刚把它装成/装坏"）。
+ */
+export function statusOf(item) {
+  if (!item || typeof item !== 'object') return { cls: 'badge-bad', text: '未装', hint: '读数缺失' };
+  if (item.run && RUN_LABELS[item.run]) {
+    return { cls: RUN_LABELS[item.run].cls, text: RUN_LABELS[item.run].text, hint: RUN_HINTS[item.run] || '' };
+  }
+  if (!item.installed) return { cls: 'badge-bad', text: '未装', hint: '这一项可以装（点【开始安装】）' };
+  if (item.inRange === 'unknown') return { cls: 'badge-warn', text: '已装', hint: '版本带预发布后缀，区间不判' };
+  if (item.inRange !== 'yes') return { cls: 'badge-warn', text: '已装', hint: '版本不在期望区间内' };
+  return { cls: 'badge-ok', text: '已装', hint: item.action === 'skip' ? '这一轮会跳过' : '这一轮会重跑' };
+}
+
+/** 把 `statusOf` 的结果塞进 state 再下发 —— 页面脚本只读不算（这就是"同源"） */
+export function decorateState(state) {
+  if (!state || !Array.isArray(state.items)) return state;
+  return {
+    ...state,
+    items: state.items.map((item) => ({ ...item, status: statusOf(item) })),
+  };
+}

package/lib/run.mjs

@@ -22,6 +22,7 @@ import { runProbe } from './probe.mjs';
 import { analyzeDump, checkMounted, skippedBundlesFromStderr } from './dump.mjs';
 import { takeSnapshot, restoreSnapshot, verifySnapshotRestored, SNAPSHOT_WARNING } from './snapshot.mjs';
 import { spawnCommand, formatCommandLine } from './exec.mjs';
+import { explainPnpmFailure, formatExitCode } from './explain-failure.mjs';
 import { EXIT } from './cli-args.mjs';
 import {
   DEFAULT_MANIFEST,
@@ -41,6 +42,30 @@ function firstLine(text) {
   return String(text || '').trim().split(/\r?\n/)[0] || '';
 }
 
+/**
+ * 失败之后追加的「人话环境归因」—— **只展示，不参与判据**。
+ *
+ * 三条纪律（改这里之前先读一遍）：
+ *  1. 原始报错已经在上一行**原样**打过了（`❌ …：<stderr 首行>`），这里只**追加**，
+ *     绝不替换、绝不截断，也不改退出码语义（0/2/3/4 一个不动）。
+ *  2. 终端这三行缩进 4 格 = 与子命令原始输出同一层，不冒充摘要行（`--ui` 的进度事件
+ *     只收摘要行，见 runSuite 里 say 的注释）。
+ *  3. 但页面（`--ui` / exe）也得看得见 —— 所以另外发**一条** log 事件（标题 + 怎么办）。
+ *     页面 lines 只收摘要行，这一条不再缩进；两处各显示各自的一份，不重复也不丢。
+ * 认不出（`explainPnpmFailure` 返回 null）就一个字都不加 —— 宁可不说，不瞎猜。
+ */
+function printFailureHint(say, emit, res) {
+  if (!res || res.timedOut || res.aborted) return null; // 超时/取消不是"环境障碍"，别乱归因
+  const hint = explainPnpmFailure({ stderr: res.stderr, stdout: res.stdout });
+  if (!hint) return null;
+  say(`    💡 ${hint.title}`);
+  say(`       ${hint.why}`);
+  say(`       怎么办：${hint.fix}`);
+  // 页面 lines 用的那一份：一句话带上"怎么办"（页面是窄栏，别把三段都塞进去）
+  emit({ kind: 'log', detail: `💡 ${hint.title} ｜ 怎么办：${hint.fix}` });
+  return hint;
+}
+
 function stamp() {
   return new Date().toISOString().replace(/[-:]/g, '').replace(/\..*$/, '');
 }
@@ -140,7 +165,7 @@ export async function verifyItem(item, ctx) {
           label: '挂载',
           status: mounted.ok ? 'pass' : 'fail',
           detail: mounted.ok
-            ? `组合头 1 行 · 条目 1 条 · 该 id 计数 ${mounted.idCounts.join(',') || 'n/a'}`
+            ? `组合头 1 行 · 条目 ${mounted.entryCount} 条（${mounted.names.join(' | ')}） · 该 id 计数 ${mounted.idCounts.join(',') || 'n/a'}`
             : mounted.problems.join('；'),
         });
         if (!mounted.ok && dump.skipped.length) {
@@ -162,14 +187,54 @@ function printChecks(say, checks) {
 
 /**
  * 主入口。返回 {exitCode, summary}。
+ *
+ * 第二个参数 `hooks` 是**纯增量**（2026-10-31 为 --ui 的逐项进度加的）：
+ *  - `hooks.onEvent(event)`：进度回调，事件形如
+ *      { kind:'step-start'|'step-done'|'log'|'batch-done', index, total, item, ok, detail }
+ *  - `hooks.signal`（AbortSignal）：取消信号，直接透给 spawnCommand（页面上的【取消】靠它）
+ * 🔴 不传 hooks（或传了个空对象）⇒ 输出与行为**与加这个参数之前逐字节相同**；
+ *    回调自己抛错也不算安装失败（安装结果只认判据）。
+ * 🔴 进度事件只带**摘要行**：每行命令的原始输出在这里都缩进 4 格，那是 MB 级的 npm 输出，
+ *    不进内存进度对象、更不进页面。别改成 monkey-patch process.stdout.write —— 那会污染
+ *    整个向导页进程的输出（.cmd 窗口 + 多请求互相穿插）。
  */
-export async function runSuite(options) {
+export async function runSuite(options, hooks = {}) {
+  const hooksObj = hooks && typeof hooks === 'object' ? hooks : {};
+  const signal = hooksObj.signal;
+  const emit = (event) => {
+    if (typeof hooksObj.onEvent !== 'function') return;
+    try {
+      hooksObj.onEvent(event);
+    } catch {
+      /* 进度回调炸了不能带崩安装：安装结果只认判据，不认回调 */
+    }
+  };
+
   const lines = [];
+  let failure = null;
   const say = (text = '') => {
     lines.push(text);
     const stream = options.json ? process.stderr : process.stdout;
     stream.write(`${text}\n`);
+    // 摘要行 = 没缩进 4 格的那些；缩进 4 格的是子命令的原始输出（见下面 onLine: (l) => say(`    ${l}`)）
+    if (typeof hooksObj.onEvent === 'function' && !text.startsWith('    ')) {
+      emit({ kind: 'log', detail: text.length > 500 ? `${text.slice(0, 500)}…` : text });
+    }
+  };
+  const finish = (result) => {
+    const installed = Array.isArray(result.summary && result.summary.installedThisRun) ? result.summary.installedThisRun : [];
+    emit({
+      kind: 'batch-done',
+      ok: result.exitCode === EXIT.OK,
+      exitCode: result.exitCode,
+      installed: installed.slice(),
+      failed: failure && failure.entry ? failure.entry.item.name : null,
+      detail: result.exitCode === EXIT.OK ? '全绿' : `退出码 ${result.exitCode}`,
+    });
+    return result;
   };
+  // 所有出口都过这一层：/install/progress 靠 batch-done 判"这一批结束了没有"
+  const ret = (exitCode) => finish({ exitCode, summary, text: lines.join('\n') });
   // 清单 → 选中 → 现状 → 每项要跑的命令：全部在 lib/plan.mjs 里算一次。
   // 这里只负责"印人话"；`--ui` 的 GET /state 是同一份数据的另一种渲染 —— 两处必然一致。
   const built = await buildSuiteState(options);
@@ -183,7 +248,7 @@ export async function runSuite(options) {
 
   if (!built.ok) {
     summary.exitCode = built.exitCode;
-    return { exitCode: built.exitCode, summary, text: lines.join('\n') };
+    return ret(built.exitCode);
   }
 
   const { plan, preflight } = built;
@@ -217,33 +282,38 @@ export async function runSuite(options) {
     if (preflight.length) {
       for (const p of preflight) warn(`前置条件不满足：${p}`);
       summary.exitCode = EXIT.USAGE;
-      return { exitCode: EXIT.USAGE, summary, text: lines.join('\n') };
+      return ret(EXIT.USAGE);
     }
     summary.exitCode = EXIT.OK;
-    return { exitCode: EXIT.OK, summary, text: lines.join('\n') };
+    return ret(EXIT.OK);
   }
 
   if (preflight.length) {
     for (const p of preflight) say(`✖ ${p}`);
     summary.exitCode = EXIT.USAGE;
-    return { exitCode: EXIT.USAGE, summary, text: lines.join('\n') };
+    return ret(EXIT.USAGE);
   }
 
   // ── 5b. 卸载 ──────────────────────────────────────────────
   if (options.uninstall) {
     let failed = 0;
-    for (const entry of plan) {
+    for (const [index, entry] of plan.entries()) {
       const step = uninstallStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix });
       say(`\n[${entry.item.group}] ${entry.item.name}`);
       say(`  $ ${formatCommandLine(step.file, step.args)}`);
+      emit({ kind: 'step-start', index: index + 1, total: plan.length, item: entry.item.name, action: 'uninstall' });
       const res = await spawnCommand(step.file, step.args, {
         timeoutMs: options.timeoutMs,
         env: execEnv(ctx, step.env),
         onLine: (l) => say(`    ${l}`),
+        signal,
       });
       if (res.timedOut || res.code !== 0) {
-        say(`  ❌ 卸载命令退出码 ${res.timedOut ? '超时' : res.code}`);
+        say(`  ❌ 卸载命令退出码 ${res.timedOut ? '超时' : formatExitCode(res.code)}`);
+        const hint = printFailureHint(say, emit, res);
+        const detail = `卸载命令${res.timedOut ? '超时' : `退出码 ${formatExitCode(res.code)}`}`;
         failed += 1;
+        emit({ kind: 'step-done', index: index + 1, total: plan.length, item: entry.item.name, ok: false, detail: hint ? `${detail}｜${hint.title}` : detail });
         continue;
       }
       invalidateDump();
@@ -251,11 +321,12 @@ export async function runSuite(options) {
       const gone = after.version === null;
       say(`  ${gone ? '✅' : '❌'} 卸载核对：${gone ? '实体已不在' : `实体仍在（${after.version}）`}`);
       if (!gone) failed += 1;
+      emit({ kind: 'step-done', index: index + 1, total: plan.length, item: entry.item.name, ok: gone, detail: gone ? '实体已不在' : `实体仍在（${after.version}）` });
     }
     summary.exitCode = failed ? EXIT.ROLLED_BACK : EXIT.OK;
     say(`\n卸载结束：${plan.length - failed} 项已卸、${failed} 项没卸干净。`);
     if (failed) say('（卸载没有"回滚"这一说：它看的是现在装着什么，不是这一轮做了什么。）');
-    return { exitCode: summary.exitCode, summary, text: lines.join('\n') };
+    return ret(summary.exitCode);
   }
 
   // ── 6. 快照（真跑前唯一一次写盘，且只写快照目录）────────────────
@@ -269,7 +340,7 @@ export async function runSuite(options) {
   } catch (err) {
     say(`✖ 快照写不出来，按规矩停手（不带着"回滚不了"的批次往下跑）：${err.message}`);
     summary.exitCode = EXIT.UNCLEAN;
-    return { exitCode: EXIT.UNCLEAN, summary, text: lines.join('\n') };
+    return ret(EXIT.UNCLEAN);
   }
   say(`快照：${snapshotRoot}（开跑前一份 pre-run，之后每装成功一步再拍一份）`);
   say(`  ${SNAPSHOT_WARNING}`);
@@ -278,17 +349,20 @@ export async function runSuite(options) {
   // ── 7. 逐步执行 ────────────────────────────────────────────
   const runStart = Date.now();
   const installedThisRun = [];
-  let failure = null;
+  // （failure 在函数顶部声明：batch-done 事件要读它，早退的出口也得能读）
 
   for (let i = 0; i < plan.length; i += 1) {
     const entry = plan[i];
     entry.stepIndex = i;
+    emit({ kind: 'step-start', index: i + 1, total: plan.length, item: entry.item.name, action: entry.action });
     if (entry.action === 'skip') {
       say(`[${i + 1}/${plan.length}] ⏭ ${entry.item.name} 已满足（${entry.version}），跳过`);
+      emit({ kind: 'step-done', index: i + 1, total: plan.length, item: entry.item.name, ok: true, detail: `已满足（${entry.version}），跳过` });
       continue;
     }
     if (Date.now() - runStart > options.budgetMs) {
       failure = { reason: 'budget', entry, message: `整批已跑 ${Math.round((Date.now() - runStart) / 1000)}s，超过墙钟上限 ${Math.round(options.budgetMs / 1000)}s` };
+      emit({ kind: 'step-done', index: i + 1, total: plan.length, item: entry.item.name, ok: false, detail: '没开始：整批墙钟超时' });
       break;
     }
     const step = installStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix });
@@ -298,6 +372,7 @@ export async function runSuite(options) {
       timeoutMs: options.timeoutMs,
       env: execEnv(ctx, step.env),
       onLine: (l) => say(`    ${l}`),
+      signal,
     });
     entry.command = formatCommandLine(step.file, step.args);
     entry.rc = res.code;
@@ -305,10 +380,23 @@ export async function runSuite(options) {
       failure = {
         reason: 'cmd',
         entry,
-        message: `安装命令${res.timedOut ? '超时' : `退出码 ${res.code}`}：${firstLine(res.stderr) || '（无输出）'}`,
+        message: res.aborted
+          ? '这条命令被取消了（前端点了【取消】⇒ AbortSignal ⇒ 进程树被杀）；这一步可能只装了半截'
+          : `安装命令${res.timedOut ? '超时' : `退出码 ${formatExitCode(res.code)}`}：${firstLine(res.stderr) || '（无输出）'}`,
         attempted: true,
+        aborted: Boolean(res.aborted),
+        hint: null, // 纯展示用的环境归因（见 printFailureHint），**不是判据**
       };
       say(`  ❌ ${failure.message}`);
+      failure.hint = printFailureHint(say, emit, res);
+      emit({
+        kind: 'step-done',
+        index: i + 1,
+        total: plan.length,
+        item: entry.item.name,
+        ok: false,
+        detail: failure.hint ? `${failure.message}｜${failure.hint.title}` : failure.message,
+      });
       break;
     }
     invalidateDump();
@@ -317,6 +405,7 @@ export async function runSuite(options) {
     printChecks(say, verdict.checks);
     if (!verdict.ok) {
       failure = { reason: 'criteria', entry, message: '命令成功了，但判据没过（这类"装完不生效"正是本工具要抓的）', attempted: true };
+      emit({ kind: 'step-done', index: i + 1, total: plan.length, item: entry.item.name, ok: false, detail: failure.message });
       break;
     }
     // 记下装完之后的真实版本（汇总里要显示"实际装成了什么"，不是"装之前是什么"）
@@ -324,6 +413,7 @@ export async function runSuite(options) {
       ? profileInstalledVersion(home, options.profile, entry.item.name)
       : globalInstalledVersion(npm.prefix, entry.item.name);
     installedThisRun.push(entry);
+    emit({ kind: 'step-done', index: i + 1, total: plan.length, item: entry.item.name, ok: true, detail: `装好：实体 ${entry.version || 'n/a'}` });
     // 每成功一步拍一份：步级回滚要回到"失败那一步之前"，而不是回到整批开跑之前
     const afterDir = path.join(snapshotRoot, `after-${String(i + 1).padStart(2, '0')}`);
     try {
@@ -367,7 +457,7 @@ export async function runSuite(options) {
   if (!failure) {
     summary.exitCode = EXIT.OK;
     printSummary(say, plan, null);
-    return { exitCode: EXIT.OK, summary, text: lines.join('\n') };
+    return ret(EXIT.OK);
   }
 
   // ── 9. 回滚 ───────────────────────────────────────────────
@@ -402,13 +492,15 @@ export async function runSuite(options) {
     }
     const step = uninstallStepFor(entry.item, { profile: options.profile, npmPrefix: npm.prefix });
     say(`  $ ${formatCommandLine(step.file, step.args)}`);
+    // 回滚里的卸载同样要能被取消打断：用户点了【取消】之后不该继续干 2 分钟的活
     const res = await spawnCommand(step.file, step.args, {
       timeoutMs: options.timeoutMs,
       env: execEnv(ctx, step.env),
       onLine: (l) => say(`    ${l}`),
+      signal,
     });
     actions.push({ name: entry.item.name, command: formatCommandLine(step.file, step.args), rc: res.code, timedOut: res.timedOut });
-    if (res.timedOut || res.code !== 0) say(`    ❌ 卸不掉（${res.timedOut ? '超时' : `rc=${res.code}`}）—— 这一项留下了残留`);
+    if (res.timedOut || res.code !== 0) say(`    ❌ 卸不掉（${res.timedOut ? '超时' : `rc=${formatExitCode(res.code)}`}）—— 这一项留下了残留`);
   }
   if (!undo.length) say('  （没有跑过任何安装命令，无需卸载）');
 
@@ -454,7 +546,7 @@ export async function runSuite(options) {
   summary.rollback = { mode, clean, snapshotDirUsed: rollbackDir, actions, verify, stillDeclared, residue };
   summary.exitCode = clean ? EXIT.ROLLED_BACK : EXIT.UNCLEAN;
   printSummary(say, plan, failure);
-  return { exitCode: summary.exitCode, summary, text: lines.join('\n') };
+  return ret(summary.exitCode);
 }
 
 function printSummary(say, plan, failure) {