@kira905/dsh-butler-install 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kira905
+
+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

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# dsh-butler-install
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+大管家全家桶的**薄壳安装器**：一条命令按清单装齐插件与命令行工具，装完**立刻告诉你成了没**，红了能整批回滚。
+
+> 卖点不是"一键"，是"一键之后的可验证性"。
+> 一个包"装完 rc=0 但其实没生效"是这套生态里真实存在过的坑（宿主只会吐一行
+> `declares no dsh.bundle` 警告，然后把它装成普通依赖）。本工具逐包核对**包实体在不在、
+> 版本落不落在期望区间、插件到底有没有进组合列表**，任一条不过就判这一步失败。
+
+## 30 秒上手
+
+```powershell
+# ① 先看它会做什么（默认就是演练档：一条命令都不跑，零写入）
+npx @kira905/dsh-butler-install --profile web
+
+# ② 真装
+npx @kira905/dsh-butler-install --profile web --apply
+
+# ③ 只装一部分（组名 / 包名 / 别名都认）
+npx @kira905/dsh-butler-install --profile web --apply --only 面板,看板
+```
+
+装完/以后任何时候的自检，是 `dsh-butler-core` 仓里那条装后自检：
+
+```powershell
+node <dsh-butler-core 仓根>/selfcheck-replica.mjs --manifest suite-manifest.json
+```
+
+> ⚠️ **这条自检命令的现状**：它目前在 `dsh-butler-core` 仓里，**还没有接清单**
+> （只跑它内置的那几项判据）。本仓的 `suite-manifest.json` 的字段是**为它将来接清单准备的**
+> —— 字段含义见下文「清单字段」一节。别把它当成"已经能按清单跑了"。
+
+## 它只做两件事，且只用两个原语
+
+| 原语 | 用来装什么 |
+|---|---|
+| `dsh plugin --profile <p> add <包>@<期望区间>` / `remove <包>` | 插件类（要进 profile 的组合列表） |
+| `npm i -g <包>@<期望区间>` / `npm rm -g <包>` | 命令行类（不参与挂载） |
+
+明确**不做**（这是设计红线，不是懒）：
+
+- **不写** `dsh.profile.bundles` —— 那是宿主的活；本工具只调 `dsh plugin add`，让宿主自己登记。
+- **不写** `cordis.patch.yml` —— 需要手工 insert 的包，本工具只告诉你"它要手工挂"，不代劳。
+- **不碰** `node_modules` —— 不自己下载、不解包、不建链接。代码里没有第二条装包路径。
+- **不重启**你的 DSH，不改别的仓，不帮你决定要不要装。
+
+删掉本工具，一切照旧：它没有留下任何自己的运行时状态（只有回滚快照，见下）。
+
+## 为什么安装命令要带 `<包>@<期望区间>`
+
+因为注册表的 `latest` 标签和"最高版本号"不是一回事。实测踩过：某个包的 `latest`
+指着一个旧版本，而更新的版本确实已发布、却没被 `latest` 指着 —— 不带区间装上来的是
+**旧的那一版**，于是"期望 ^0.1.1、实体 0.1.0"，装完看着成功、实际装错了版本。
+
+带上区间之后，解析器只能落在期望区间里：落不进去就报错停下（而不是装个别的版本还报成功）。
+
+## 退出码
+
+| 码 | 含义 |
+|---|---|
+| `0` | 全绿（含"本来就已满足、这次全跳过"） |
+| `2` | 用法 / 清单 / 前置条件错误 —— **什么都没改** |
+| `3` | 有步骤失败，但**已回滚干净** |
+| `4` | 有步骤失败，且**回滚不干净**（要人看：报告里会指出哪份文件对不上、快照在哪） |
+
+## 回滚：两级，别只做一级
+
+失败时默认**只退失败那一步**（前面已装好的几步保留，不用全重来）：
+
+| 参数 | 干什么 |
+|---|---|
+| `--rollback` / `--rollback=step`（默认） | 回到**失败那一步之前**：先卸掉这一步装进去的包，再回放那一步之前拍的快照 |
+| `--rollback=batch` | 回到**本轮开跑之前**：逐包卸掉本轮装过的，再回放开跑前的快照 |
+| `--uninstall` | **不是回滚**：把选中的包从 profile / 全局前缀卸掉（"我不想装这套了"） |
+
+一句话分清：**回滚看的是"这一轮做了什么"，卸载看的是"现在装着什么"。**
+
+快照拍的是**声明层文件**：`package.json`、`pnpm-lock.yaml`、`cordis.patch.yml`，
+外加包管理器自己会写的 `pnpm-workspace.yaml`（实测会出现，不拍就漏一份）。开跑前一份，
+之后每成功一步再拍一份 —— 这样"退到上一步之前"才有落点。
+
+🔴 **诚实边界**：`node_modules` 里的实体文件**不在快照内**。`remove` 能摘掉依赖链接，
+但清不干净包管理器的缓存与虚拟store，所以回滚后可能还留着实体文件 —— 报告会明写这一句，
+不会假装"回滚 = 什么都没变"。
+
+## 清单（`suite-manifest.json`）= 单一真相
+
+安装器读它；将来 `dsh-butler-core` 的装后自检也读**同一份**。任何一方想加判据，只能改这份清单
+—— 两处真相必然漂移。
+
+字段：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `name` | ✅ | 包名（`@scope/name` 或裸名） |
+| `versionRange` | ✅ | **期望区间**，写法只接受 `^x.y.z` / `~x.y.z` / `x.y.z`。不支持 `>=1.2`、`1.x`、`||` 组合 —— 与其两处语义各猜一半，不如让写法收敛 |
+| `type` | ✅ | `plugin`（要进组合列表）/ `cli`（不参与挂载） |
+| `group` | ✅ | 组名，`--only` 按组选 |
+| `mount` | 插件可选 | `auto`（默认，装完应自动挂）/ `manual`（按设计不进组合列表，挂载由它自带的部署命令完成）/ `none` |
+| `probe` | ✅ | 见下「探针」 |
+| `aliases` | 可选 | `--only` 用的别名（如 `面板`、`看板`），不许与包名重复 |
+| `note` | 可选 | 一句人话：这个包是什么、有什么坑 |
+| `excluded[]` | 顶层可选 | **不可安装项**：不是包的目录（如历史聚合仓）。演练档会跳过它并打印原因 |
+
+**期望版本一律写区间，不钉精确版本**：宿主落进 profile 的本来就是区间，
+钉精确版本只会造出"清单与实体永远不一致"的假红。
+
+## 探针（`probe.kind`）
+
+| 值 | 干什么 | 什么时候能用 |
+|---|---|---|
+| `existence`（**默认**） | 只看文件在不在：插件看 `node_modules/<包>/package.json`，命令行看 `.bin` 或全局前缀下的命令文件。**一条命令都不执行** | 任何命令都能用 |
+| `help` | 先**静态核**该命令源码里确有 `--help` 分支，再跑 `<命令> --help` | **仅当这条命令确实实现了 `--help`**。核不到就**拒绝执行**并判失败 |
+| `cmd` | 跑清单指定的一个**只读**命令 | 清单里必须写 `readonlyBecause`：凭什么认定它只读 |
+
+🔴 **为什么 `help` 要加硬闸**：这批命令行工具里有相当一部分没有参数解析，未知参数被忽略后
+**直接执行真动作**（导出快照、归档、改状态）。拿 `--help` 当"只看一眼"是错的。
+所以 `help` 探针在**执行之前**先读源码，找不到 `--help` 分支就拒跑 —— 宁可判红，不赌它是只读的。
+
+要取证"哪些命令真的实现了 `--help`"，用随包附带的只读扫描器（一个命令都不跑）：
+
+```powershell
+npx -p @kira905/dsh-butler-install dsh-butler-install-probe-scan <某仓根或父目录>
+```
+
+只有它标 ✅ 的命令，才允许在清单里写 `probe.kind: "help"`。
+
+## 常用参数
+
+| 参数 | 说明 |
+|---|---|
+| `--profile <name>` | 必填。宿主会定位 `<数据根>/profiles/<name>` |
+| `--apply` | 真装（不加就是演练档） |
+| `--only` / `--skip` | 逗号分隔，认组名 / 包名 / 包名末段 / 别名 |
+| `--upgrade` | 已满足的项也重跑一遍安装（"装过但坏了"的情形） |
+| `--rollback[=step\|batch]` | 失败后怎么回滚，默认 `step` |
+| `--uninstall` | 卸掉选中的包（不是回滚） |
+| `--npm-prefix <dir>` | 全局包落点（默认取 npm 自己的全局前缀）。**隔离演练时用它**：装到临时目录，不碰你真正的全局包 |
+| `--home <dir>` | DSH 数据根（默认 `$DSH_HOME`，再默认 `~/.dsh`） |
+| `--timeout` / `--budget` | 单步超时（默认 120s）/ 整批墙钟上限（默认 300s，超了就停下并回滚本批） |
+| `--snapshot-dir <dir>` | 快照目录，默认 `<数据根>/butler-install/snapshots/<时间戳>` |
+| `--json` | 只输出一份 JSON 汇总（人读的输出改走 stderr） |
+
+## 它在 Windows 上怎么跑子进程
+
+`dsh` / `npm` 在这台机器上是 `.cmd` 壳：不带 shell 的 spawn 直接 `ENOENT`，
+显式写 `.cmd` 又会 `EINVAL`。所以本工具在 Windows 上过 shell 执行，并且参数做了最小必要引号化
+（只有含空格等特殊字符的参数才加引号）——打印出来的命令行与真正执行的命令行由同一个函数生成，
+报告里不会出现"说要跑 A、实际跑了 B"。
+
+## 已知限制（别当 bug）
+
+- 回滚**不覆盖** `node_modules` 里的实体文件与包管理器缓存（见上文诚实边界）。
+- 用 `--upgrade` 重装一个**之前就装着**的包、然后失败回滚时，声明层会回到快照值，
+  但实体层可能变成"声明在、实体更新过"的中间态 —— 再跑一次安装即可对齐。
+- `mount: "manual"` 的包（按设计不进组合列表、靠自带部署命令挂载）本工具只装不挂，
+  挂载判据记"跳过"。
+- 不判"运行时会不会崩"：`--dump-config` 只证明组合树里有这一行。真要验运行时，得自己起一次服务看日志。
+- 不替你决定"要不要装某一件"，也不做"装完自动起服务"。
+
+## 夹具
+
+```powershell
+npm test
+```
+
+夹具全部落在自己的临时目录里（假 `dsh`、假 `npm`、假 profile、假全局前缀），
+不读也不写真实数据根。覆盖：清单校验（每条错误都带文件名 + 行号）· 版本区间三态 ·
+探针三分支（含"标了 `help` 但该命令没实现 ⇒ 拒执行且不产生任何执行"）· 组合树三条计数判据
+（各自独立可触发）· 快照回放与核对 · 演练档零副作用（目录指纹必须一模一样）· 退出码 0/3/4 ·
+步级与整批回滚的差别 · 卸载。
+
+## 许可
+
+MIT

package/bin/dsh-butler-install.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * 入口：解析参数 → 交给 runSuite。
+ * 这里只做三件事：--help / --version 的早退、参数错误转 rc 2、--json 的输出整形。
+ * 真正的编排一律在 lib/run.mjs，别把逻辑塞回入口。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs, HELP_TEXT, EXIT } from '../lib/cli-args.mjs';
+import { runSuite } from '../lib/run.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    const json = JSON.parse(fs.readFileSync(path.join(here, '..', 'package.json'), 'utf8'));
+    return json.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+const { options, errors } = parseArgs(process.argv.slice(2));
+
+if (options.help) {
+  process.stdout.write(HELP_TEXT);
+  process.exitCode = EXIT.OK;
+} else if (options.version) {
+  process.stdout.write(`${pkgVersion()}\n`);
+  process.exitCode = EXIT.OK;
+} else if (errors.length) {
+  for (const e of errors) process.stderr.write(`✖ ${e}\n`);
+  process.stderr.write('用 --help 看可用参数。\n');
+  process.exitCode = EXIT.USAGE;
+} else {
+  const { exitCode, summary } = await runSuite(options);
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ exitCode, ...summary }, null, 2)}\n`);
+  } else {
+    process.stdout.write(`\n退出码 ${exitCode}：${exitCode === 0 ? '全绿' : exitCode === 3 ? '有步骤失败，已回滚干净' : exitCode === 4 ? '有步骤失败，回滚不干净（要人看）' : '用法/前置条件错误，什么都没改'}\n`);
+  }
+  process.exitCode = exitCode;
+}

package/bin/probe-scan.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * 探针取证工具：扫一批包的 `bin` 源文件，逐个命令回答"它到底有没有实现 --help"。
+ *
+ * 为什么单独做成一条命令：清单里把某一项升级成 `probeKind: "help"` 之前，必须先
+ * **按命令**核过。这个判断很容易想当然（"同一个仓里别的命令都有，这个也一定有"），
+ * 而错了的后果是探针把 `--help` 当普通参数丢给脚本，脚本照常导出/归档/改状态 ——
+ * 那不是"看一眼"，是真干活。所以取证动作要能一条命令重跑、结论能贴进清单。
+ *
+ * **零执行**：只读文件、只做字符串判断，一个 bin 都不跑。
+ *
+ * 用法：
+ *   dsh-butler-install-probe-scan <目录> [--json] [--depth N]
+ *   目录可以是某个包根，也可以是装着多个包根的父目录。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { hasHelpBranch } from '../lib/probe.mjs';
+
+const argv = process.argv.slice(2);
+if (argv.includes('-h') || argv.includes('--help') || argv.length === 0) {
+  process.stdout.write(`dsh-butler-install-probe-scan —— 只读核对哪些命令真的实现了 --help
+
+用法：
+  dsh-butler-install-probe-scan <目录> [--json] [--depth N]
+
+  <目录>      某个包的根目录，或装着多个包根的父目录
+  --json      输出一份 JSON（贴进清单/报告用）
+  --depth N   往下找 package.json 的层数，默认 3
+`);
+  process.exitCode = argv.length === 0 ? 2 : 0;
+} else {
+  const json = argv.includes('--json');
+  const depthIndex = argv.indexOf('--depth');
+  const maxDepth = depthIndex >= 0 ? Number(argv[depthIndex + 1]) || 3 : 3;
+  const root = argv.find((a) => !a.startsWith('--') && a !== String(maxDepth) && a !== argv[depthIndex + 1]);
+
+  if (!root) {
+    process.stderr.write('✖ 缺目录参数\n');
+    process.exitCode = 2;
+  } else {
+    const results = scan(path.resolve(root), maxDepth);
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ root: path.resolve(root), results }, null, 2)}\n`);
+    } else {
+      process.stdout.write(`扫描根：${path.resolve(root)}\n`);
+      process.stdout.write('（只读：一个命令都没执行；结论来自源码静态判断）\n\n');
+      for (const r of results) {
+        process.stdout.write(`${r.helpBranch ? '✅' : '❌'} ${r.pkg}  ${r.cmd}  →  ${r.file}\n`);
+      }
+      const yes = results.filter((r) => r.helpBranch).length;
+      process.stdout.write(`\n共 ${results.length} 个命令：有 --help 分支 ${yes} 个、没有 ${results.length - yes} 个。\n`);
+      process.stdout.write('只有 ✅ 那些才允许在清单里标 probeKind=help；其余一律用 existence（只查文件在不在，零执行）。\n');
+    }
+    process.exitCode = 0;
+  }
+}
+
+function scan(dir, maxDepth) {
+  const out = [];
+  for (const pkgDir of findPackageDirs(dir, maxDepth, 0)) {
+    const pkgJson = path.join(pkgDir, 'package.json');
+    let json;
+    try {
+      json = JSON.parse(fs.readFileSync(pkgJson, 'utf8'));
+    } catch {
+      continue;
+    }
+    const bin = json.bin;
+    if (!bin) continue;
+    const pairs = typeof bin === 'string' ? [[json.name || path.basename(pkgDir), bin]] : Object.entries(bin);
+    for (const [cmd, rel] of pairs) {
+      const file = path.resolve(pkgDir, rel);
+      let source = '';
+      try {
+        source = fs.readFileSync(file, 'utf8');
+      } catch {
+        out.push({ pkg: json.name, cmd, file, helpBranch: false, reason: '读不到源文件' });
+        continue;
+      }
+      out.push({ pkg: json.name, cmd, file, helpBranch: hasHelpBranch(source) });
+    }
+  }
+  return out;
+}
+
+function findPackageDirs(dir, maxDepth, depth) {
+  if (depth > maxDepth) return [];
+  const out = [];
+  if (fs.existsSync(path.join(dir, 'package.json'))) out.push(dir);
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+    out.push(...findPackageDirs(path.join(dir, entry.name), maxDepth, depth + 1));
+  }
+  return out;
+}

package/lib/cli-args.mjs

@@ -0,0 +1,167 @@
+/**
+ * 命令行参数解析。
+ *
+ * 纪律：**未知参数一律报错退出**。这批命令行工具里有不少"未知参数被忽略、然后照常干活"
+ * 的先例 —— 安装器自己绝不能成为同一类东西（写错一个字母就静默跑成别的事，比报错坏得多）。
+ */
+
+export const EXIT = {
+  OK: 0,
+  USAGE: 2,
+  ROLLED_BACK: 3,
+  UNCLEAN: 4,
+};
+
+export const HELP_TEXT = `dsh-butler-install —— 大管家全家桶薄壳安装器
+
+用法：
+  dsh-butler-install --profile <profile> [选项]
+
+  --profile <name>        要操作的 profile（必填）。宿主会用它定位 <数据根>/profiles/<name>
+  --manifest <path>       清单文件，默认用包内自带的 suite-manifest.json
+  --apply                 真装。**不加就是演练档**：只打印将要执行的命令与每步判据，一条命令都不跑
+  --only <列表>           只装这些：组名 / 包名 / 别名，逗号分隔，可重复给
+  --skip <列表>           跳过这些（同 --only 的写法）
+  --upgrade               已满足的项也重跑一遍安装（用于"装过但坏了"的情形）
+  --rollback[=step|batch] 失败后怎么回滚：默认 step（只回滚失败那一步），batch 退整批
+  --uninstall             把选中的包卸掉（**不是回滚**：卸载看"现在装着什么"，回滚看"这轮做了什么"）
+  --npm-prefix <dir>      全局包的落点（默认取 npm 自己的全局前缀；隔离演练时用它）
+  --home <dir>            DSH 数据根（默认 $DSH_HOME，再默认 ~/.dsh）
+  --timeout <秒>          单步超时，默认 120
+  --budget <秒>           整批墙钟上限，默认 300；超了停下并回滚本批
+  --snapshot-dir <dir>    快照目录，默认 <数据根>/butler-install/snapshots/<时间戳>
+  --json                  只输出一份 JSON 汇总（人读的输出改走 stderr）
+  --dry-run               显式写"演练"（与默认行为相同，便于脚本表达意图）
+  -h, --help              看这份说明
+  -V, --version           看版本号
+
+退出码：
+  0  全绿
+  2  用法/清单/前置条件错误（什么都没改）
+  3  有步骤失败，但已回滚干净
+  4  有步骤失败，且回滚不干净（要人看：报告里会指出哪份文件对不上）
+
+只用两个原语：\`dsh plugin --profile <p> add|remove …\` 与 \`npm i -g|npm rm -g …\`。
+本工具**不写** dsh.profile.bundles、**不写** cordis.patch.yml、**不碰** node_modules —— 那些是宿主的事。
+`;
+
+const VALUE_FLAGS = new Set([
+  '--profile',
+  '--manifest',
+  '--only',
+  '--skip',
+  '--npm-prefix',
+  '--home',
+  '--timeout',
+  '--budget',
+  '--snapshot-dir',
+]);
+
+const BOOL_FLAGS = new Set(['--apply', '--upgrade', '--uninstall', '--json', '--dry-run', '--help', '-h', '--version', '-V', '--rollback']);
+
+export function parseArgs(argv) {
+  const options = {
+    profile: null,
+    manifest: null,
+    apply: false,
+    only: [],
+    skip: [],
+    upgrade: false,
+    rollbackMode: 'step',
+    uninstall: false,
+    npmPrefix: null,
+    home: null,
+    timeoutMs: 120000,
+    budgetMs: 300000,
+    snapshotDir: null,
+    json: false,
+    help: false,
+    version: false,
+  };
+  const errors = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--rollback') {
+      const next = argv[i + 1];
+      if (next === 'step' || next === 'batch') {
+        options.rollbackMode = next;
+        i += 1;
+      }
+      continue;
+    }
+    if (token.startsWith('--rollback=')) {
+      const value = token.slice('--rollback='.length);
+      if (value !== 'step' && value !== 'batch') errors.push(`--rollback 只接受 step 或 batch（现在读到 ${JSON.stringify(value)}）`);
+      else options.rollbackMode = value;
+      continue;
+    }
+    if (token.startsWith('--')) {
+      const eq = token.indexOf('=');
+      const flag = eq >= 0 ? token.slice(0, eq) : token;
+      const inlineValue = eq >= 0 ? token.slice(eq + 1) : null;
+      if (VALUE_FLAGS.has(flag)) {
+        const value = inlineValue !== null ? inlineValue : argv[i + 1];
+        if (value === undefined || value.startsWith('--')) {
+          errors.push(`${flag} 需要一个值`);
+          continue;
+        }
+        if (inlineValue === null) i += 1;
+        applyValue(options, flag, value, errors);
+        continue;
+      }
+      if (BOOL_FLAGS.has(flag)) {
+        if (inlineValue !== null) errors.push(`${flag} 是开关，不接受值`);
+        if (flag === '--apply') options.apply = true;
+        if (flag === '--upgrade') options.upgrade = true;
+        if (flag === '--uninstall') options.uninstall = true;
+        if (flag === '--json') options.json = true;
+        if (flag === '--help' || flag === '-h') options.help = true;
+        if (flag === '--version' || flag === '-V') options.version = true;
+        continue;
+      }
+      errors.push(`未知参数：${token}（用 --help 看可用参数）`);
+      continue;
+    }
+    if (token === '-h') { options.help = true; continue; }
+    if (token === '-V') { options.version = true; continue; }
+    errors.push(`多余的位置参数：${token}`);
+  }
+
+  if (!options.help && !options.version && !options.profile) errors.push('缺 --profile；用法：dsh-butler-install --profile <name> [--apply]');
+  return { options, errors };
+}
+
+function applyValue(options, flag, value, errors) {
+  if (flag === '--profile') {
+    if (!/^[A-Za-z0-9._-]+$/.test(value)) errors.push(`--profile 只接受字母数字与 . _ -（现在读到 ${JSON.stringify(value)}）`);
+    options.profile = value;
+  } else if (flag === '--manifest') {
+    options.manifest = value;
+  } else if (flag === '--only') {
+    options.only.push(...splitList(value));
+  } else if (flag === '--skip') {
+    options.skip.push(...splitList(value));
+  } else if (flag === '--npm-prefix') {
+    options.npmPrefix = value;
+  } else if (flag === '--home') {
+    options.home = value;
+  } else if (flag === '--snapshot-dir') {
+    options.snapshotDir = value;
+  } else if (flag === '--timeout') {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) errors.push(`--timeout 要正数秒（现在读到 ${JSON.stringify(value)}）`);
+    else options.timeoutMs = Math.round(n * 1000);
+  } else if (flag === '--budget') {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) errors.push(`--budget 要正数秒（现在读到 ${JSON.stringify(value)}）`);
+    else options.budgetMs = Math.round(n * 1000);
+  }
+}
+
+function splitList(value) {
+  return String(value)
+    .split(/[,，]/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}

package/lib/dump.mjs

@@ -0,0 +1,73 @@
+/**
+ * 解析 `dsh --profile <p> --dump-config` 的输出。
+ *
+ * 为什么非要数次数、不满足于"抓到那一行就不管了"：组合树里同一份实现被挂两次时，
+ * 宿主**不报错**、只是多打一行 —— 用户装完一路绿灯，实际用的是哪一份实现谁也说不清。
+ * 所以判据是"出现恰好 1 次"，不是"出现过"。
+ *
+ * 输出形态（实测）：
+ *   # == <bundle 名>                     ← 组合（bundle）级
+ *   # == <bundle 名>, patched by <包名>   ← 被 patch 的 bundle，别把这行算成"包里出现了"
+ *   - id: <entry id>
+ *     name: '<包名 或 内部模块名>'
+ */
+export function analyzeDump(text) {
+  const bundles = [];
+  const entries = [];
+  const idCounts = new Map();
+  const nameCounts = new Map();
+  let current = null;
+
+  for (const rawLine of String(text || '').split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+$/, '');
+    const head = /^# == (.+)$/.exec(line);
+    if (head) {
+      const first = head[1].split(',')[0].trim();
+      if (first) bundles.push(first);
+      current = null;
+      continue;
+    }
+    const idLine = /^- id:\s*(.+)$/.exec(line);
+    if (idLine) {
+      const id = idLine[1].trim();
+      current = { id, name: null };
+      entries.push(current);
+      idCounts.set(id, (idCounts.get(id) || 0) + 1);
+      continue;
+    }
+    const nameLine = /^ {2}name:\s*(.+)$/.exec(line);
+    if (nameLine && current && current.name === null) {
+      const name = nameLine[1].trim().replace(/^['"]|['"]$/g, '');
+      current.name = name;
+      nameCounts.set(name, (nameCounts.get(name) || 0) + 1);
+      continue;
+    }
+    // 别的顶级/子级行不改变"当前 entry"，但 `- id:` 之外的新 entry 起点已经处理
+  }
+
+  return { bundles, entries, idCounts, nameCounts };
+}
+
+/** 某个包在组合树里的三条计数判据 */
+export function checkMounted(analysis, pkgName) {
+  const bundleLines = analysis.bundles.filter((b) => b === pkgName).length;
+  const matching = analysis.entries.filter((e) => e.name === pkgName);
+  const ids = matching.map((e) => e.id);
+  const idCounts = ids.map((id) => analysis.idCounts.get(id) || 0);
+  const problems = [];
+  if (bundleLines !== 1) problems.push(`组合头 "# == ${pkgName}" 出现 ${bundleLines} 次（应为 1）（packages: ${analysis.bundles.filter((b)=>b.includes(pkgName)).join(' | ') || '无'}）`);
+  if (matching.length !== 1) problems.push(`条目 name=${pkgName} 出现 ${matching.length} 次（应为 1）`);
+  for (let i = 0; i < ids.length; i += 1) {
+    if (idCounts[i] !== 1) problems.push(`条目 id=${ids[i]} 在整棵树里出现 ${idCounts[i]} 次（应为 1）—— 撞 id 时宿主不报错，只静默保留一份`);
+  }
+  return { ok: problems.length === 0, bundleLines, nameCount: matching.length, ids, idCounts, problems };
+}
+
+/** dump 的 stderr 里"某个 bundle 被跳过"的行（能归因时为安装器所用） */
+export function skippedBundlesFromStderr(stderr) {
+  const out = [];
+  for (const line of String(stderr || '').split(/\r?\n/)) {
+    if (/skipping profile bundle|declares no dsh\.bundle/.test(line)) out.push(line.trim());
+  }
+  return out;
+}