@hyzyn/dsh-safe 0.3.0 → 0.3.2

package/README.en.md

@@ -16,13 +16,16 @@ Requires Node >= 20 and a local `dsh` command. Zero runtime dependencies.
 
 ## Quick Start
 
-Just replace `dsh` with `dsh-safe`:
+Just swap `dsh` for `dsh-safe` — `-u` (update-and-boot) is recommended: when dsh has a new version it upgrades and restores quarantined plugins first; when dsh is already latest it behaves exactly like a plain start:
 
 ```bash
-dsh-safe web          # same as dsh web, with auto-quarantine
+dsh-safe -u web       # recommended: update then boot (with auto-quarantine)
+dsh-safe web          # no update check, boot with auto-quarantine
 dsh-safe --profile tui --patch ./extra.yml
 ```
 
+`-u` adds one version check per boot (needs network; on check failure it just warns and boots anyway) — offline or scripted environments can use the second line.
+
 Sample output (shown with a zh locale: a broken plugin is quarantined, then startup retries):
 
 ```
@@ -32,20 +35,23 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 [dsh-safe] 重试启动…
 ```
 
-## Commands
+## Commands & Options
 
-```
-dsh-safe <dsh args…>              wrap and run dsh
-dsh-safe -u [dsh args…]           upgrade dsh first (skip if latest), then boot
-dsh-safe list [--profile <name>]  show quarantined plugins (defaults to all profiles)
-dsh-safe restore --profile <name> (--id <id> | --all) [--dry-run]
-                                  re-enable auto-disabled plugins (after a fixed plugin upgrade)
-dsh-safe update [-y] [--to <ver>] [--self] [--no-restore] [--pm npm|pnpm]
-                                  upgrade dsh and dsh-safe itself, auto-restore quarantined plugins
-dsh-safe help
-```
+### Subcommands
+
+| Command | Description |
+| --- | --- |
+| `dsh-safe <dsh args…>` | wrap and run dsh (swap `dsh` for `dsh-safe`) |
+| `dsh-safe -u [update options] [dsh args…]` | upgrade dsh and dsh-safe itself first (skip if latest), then boot in wrap mode; `--update` is an alias |
+| `dsh-safe update [options]` | upgrade only, no boot — options below |
+| `dsh-safe list [--profile <name>]` | show quarantined plugins (defaults to all profiles) |
+| `dsh-safe restore --profile <name> (--id <id> \| --all) [--dry-run]` | re-enable auto-disabled plugins (after a fixed plugin upgrade) |
+| `dsh-safe help` (`-h` / `--help`) | show help |
+| `dsh-safe --version` (`-V`) | show version |
 
-Wrapper-mode options (must come before the profile / subcommand):
+Every short flag has an equivalent long form (`-u` = `--update`, `-y` = `--yes`, `-h` = `--help`, `-V` = `--version`); single letters use `-`, words use `--`.
+
+### Wrapper-mode options (must come before the first positional argument)
 
 | Option | Description |
 | --- | --- |
@@ -53,13 +59,25 @@ Wrapper-mode options (must come before the profile / subcommand):
 | `--max-retries <n>` | Max startup retries after an auto-quarantine (default 2; `0` means pass through without quarantining) |
 | `--allow-first-party` | Allow auto-disabling first-party `@deepseek-ai/*` plugins (skipped by default; handle manually) |
 
-Upgrading dsh: `dsh-safe update` auto-detects the dsh package name and install method (npm / pnpm global installs), compares against the latest version and runs the upgrade for you, then automatically restores all quarantined plugins — any still incompatible under the new dsh will be auto-quarantined again on the next start. `--to <version>` pins a target version (also how you roll back), `--no-restore` skips the restore, `-y` skips the confirmation.
+### update / -u options (after `-u` or `update`; wrapper flags before the dsh args still apply)
 
-update / -u also checks dsh-safe's own version and upgrades whichever is outdated (single install command); `--self` updates dsh-safe only. Additionally, every wrapped boot checks for a new dsh-safe version at most once a day and prints a one-line notice (fully silent on check failure); disable with `DSH_SAFE_NO_UPDATE_CHECK=1`.
+| Option | Description |
+| --- | --- |
+| `-y` / `--yes` | Skip the upgrade confirmation (required in non-interactive terminals) |
+| `--to <version>` | Target dsh version, also how you roll back (explicit downgrades allowed); dsh-safe itself always upgrades to the latest |
+| `--self` | Update dsh-safe itself only; dsh and quarantine state untouched |
+| `--no-restore` | Do not auto-restore quarantined plugins after upgrading dsh |
+| `--pm <npm\|pnpm>` | Force the package manager (auto-detected by default) |
 
-For daily use, just make `dsh-safe -u web` your start command: boots immediately when dsh is already latest (one version check), upgrades + restores first when an update is available, and only warns (still boots) if the update check itself fails. `-u` accepts update options (e.g. `-u -y web`) and wrapper flags (e.g. `-u --max-retries 0 web`).
+### Environment variables
+
+| Variable | Description |
+| --- | --- |
+| `DSH_SAFE_LANG=zh\|en` | Force message language (defaults to `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE`) |
+| `DSH_SAFE_NO_UPDATE_CHECK=1` | Disable the at-most-daily dsh-safe new-version notice on boot |
+| `DSH_HOME` | dsh home directory (dsh's own variable; the quarantine ledger and patch paths follow it) |
 
-Messages follow `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE` (`zh*` → Chinese, otherwise English); force with `DSH_SAFE_LANG=zh|en`.
+How upgrading works: `dsh-safe update` auto-detects the dsh package name and install method (npm / pnpm global installs), compares against the latest version and runs the upgrade for you, then automatically restores all quarantined plugins — any still incompatible under the new dsh will be auto-quarantined again on the next start. For daily use, just make `dsh-safe -u web` your start command: boots immediately when dsh is already latest (one version check), upgrades + restores first when an update is available, and only warns (still boots) if the update check itself fails. `-u` accepts update options (e.g. `-u -y web`) and wrapper flags (e.g. `-u --max-retries 0 web`).
 
 ## How It Works
 
@@ -81,7 +99,7 @@ Messages follow `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE` (`zh*` → Chines
 - Rows inserted via `--patch` overlay layers are not part of the mapping (only the profile patch, the home patch and bundle patches are scanned).
 - To capture stderr, the wrapper pipes dsh's stderr (content is still echoed to the terminal in real time); stdout/stdin pass through unaffected.
 - Match patterns target the dsh 0.1.x error formats; a major dsh upgrade that changes them requires updating the parser.
-- Windows is best-effort: update / --self / list / restore are adapted (.cmd shim parsing, shelled npm/pnpm invocations), but the wrapped dsh boot's child-process spawn is unverified on Windows.
+- Windows is best-effort: update / --self / list / restore are adapted (.cmd shim parsing, shelled npm/pnpm invocations); the wrapped boot resolves the node entry embedded in dsh's .cmd/.ps1 shim on PATH and spawns `node <entry>` directly (.exe runs as-is, unparseable shims fall back to a shelled spawn), sidestepping Node's ban on spawning .cmd files. Not yet verified end-to-end on a real Windows machine — feedback welcome.
 
 ## Development
 

package/README.md

@@ -16,13 +16,16 @@ npm install -g @hyzyn/dsh-safe
 
 ## 快速开始
 
-把平时的 `dsh` 换成 `dsh-safe` 即可：
+把平时的 `dsh` 换成 `dsh-safe` 即可，推荐直接用 `-u`（更新并启动）：dsh 有新版本时先升级并恢复被隔离的插件再启动，已最新时和普通启动完全一样：
 
 ```bash
-dsh-safe web          # 等价于 dsh web，带自动隔离
+dsh-safe -u web       # 推荐：更新并启动（含自动隔离）
+dsh-safe web          # 不检查更新，直接带自动隔离启动
 dsh-safe --profile tui --patch ./extra.yml
 ```
 
+`-u` 每次启动多做一次版本检查（需要联网，检查失败只告警、照常启动）；离线或脚本环境用第二行即可。
+
 输出示例（坏插件被自动隔离后重试）：
 
 ```
@@ -32,20 +35,23 @@ Error: dsh: plugin tree failed to load: failed to apply loader entry smoke-broke
 [dsh-safe] 重试启动…
 ```
 
-## 命令
+## 命令与参数
 
-```
-dsh-safe <dsh 参数…>             包装运行 dsh
-dsh-safe -u [dsh 参数…]            先升级 dsh（已最新则跳过），再启动
-dsh-safe list [--profile <名>]    查看隔离名单（缺省列出全部 profile）
-dsh-safe restore --profile <名> (--id <id> | --all) [--dry-run]
-                                  恢复被自动禁用的插件（升级修复后使用）
-dsh-safe update [-y] [--to <版本>] [--self] [--no-restore] [--pm npm|pnpm]
-                                  升级 dsh 与 dsh-safe 自身，并自动恢复被隔离的插件
-dsh-safe help
-```
+### 子命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `dsh-safe <dsh 参数…>` | 包装运行 dsh（把平时的 `dsh` 换成 `dsh-safe`） |
+| `dsh-safe -u [update 选项] [dsh 参数…]` | 先升级 dsh 与 dsh-safe 自身（已最新则跳过），再按包装模式启动；`--update` 等价 |
+| `dsh-safe update [选项]` | 只升级不启动，选项见下 |
+| `dsh-safe list [--profile <名>]` | 查看隔离名单（缺省列出全部 profile） |
+| `dsh-safe restore --profile <名> (--id <id> \| --all) [--dry-run]` | 恢复被自动禁用的插件（升级修复后使用） |
+| `dsh-safe help`（`-h` / `--help`） | 显示帮助 |
+| `dsh-safe --version`（`-V`） | 显示版本 |
 
-包装模式选项（必须写在 profile / 子命令之前）：
+短选项都有等价的长形式（`-u` = `--update`、`-y` = `--yes`、`-h` = `--help`、`-V` = `--version`）；单字母用 `-`，多字母用 `--`。
+
+### 包装模式选项（必须写在第一个位置参数之前）
 
 | 选项 | 说明 |
 | --- | --- |
@@ -53,13 +59,25 @@ dsh-safe help
 | `--max-retries <n>` | 自动隔离后最多重试启动的次数（默认 2；`0` 表示不隔离只透传） |
 | `--allow-first-party` | 允许自动禁用 `@deepseek-ai/*` 第一方插件（默认跳过，需手动处理） |
 
-升级 dsh：`dsh-safe update` 自动探测 dsh 的包名与安装方式（npm / pnpm 全局安装）、对比最新版本后代跑升级，完成后自动恢复所有被隔离的插件——新 dsh 下仍不兼容的会在下次启动时再次被自动隔离。`--to <版本>` 指定目标版本（也是回滚方式），`--no-restore` 跳过恢复，`-y` 跳过确认。
+### update / -u 选项（写在 `-u` 或 `update` 之后；其前的包装旗标照常生效）
 
-update / -u 会同时检查 dsh-safe 自身的版本，谁旧升谁（一条安装命令）；`--self` 只更新 dsh-safe。另外每次包装启动时最多每天一次检查 dsh-safe 新版并提示一行（检查失败完全静默），`DSH_SAFE_NO_UPDATE_CHECK=1` 关闭。
+| 选项 | 说明 |
+| --- | --- |
+| `-y` / `--yes` | 跳过升级确认（非交互终端必须显式加 `-y`） |
+| `--to <版本>` | 指定 dsh 的目标版本，也是回滚方式（显式允许降级）；dsh-safe 自身始终升到最新 |
+| `--self` | 只更新 dsh-safe 自身，不动 dsh 与隔离状态 |
+| `--no-restore` | 升级 dsh 后不自动恢复被隔离的插件 |
+| `--pm <npm\|pnpm>` | 强制指定包管理器（缺省自动探测） |
 
-日常把 `dsh-safe -u web` 当启动命令即可：dsh 已是最新时直接启动（仅一次版本检查），有更新时先升级并恢复隔离再启动，更新检查失败只告警、照常启动。`-u` 后可接 update 的选项（如 `-u -y web`）与包装旗标（如 `-u --max-retries 0 web`）。
+### 环境变量
+
+| 变量 | 说明 |
+| --- | --- |
+| `DSH_SAFE_LANG=zh\|en` | 强制提示信息语言（缺省跟随 `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE`） |
+| `DSH_SAFE_NO_UPDATE_CHECK=1` | 关闭启动时每天最多一次的 dsh-safe 新版提示 |
+| `DSH_HOME` | dsh 的 home 目录（dsh 自己的环境变量；隔离台账与各 patch 路径随之） |
 
-提示信息语言跟随 `LC_ALL` / `LC_MESSAGES` / `LANG` / `LANGUAGE`（`zh*` 为中文，其余英文），也可用环境变量 `DSH_SAFE_LANG=zh|en` 强制指定。
+升级行为：`dsh-safe update` 自动探测 dsh 的包名与安装方式（npm / pnpm 全局安装）、对比最新版本后代跑升级，完成后自动恢复所有被隔离的插件——新 dsh 下仍不兼容的会在下次启动时再次被自动隔离。日常把 `dsh-safe -u web` 当启动命令即可：dsh 已是最新时直接启动（仅一次版本检查），有更新时先升级并恢复隔离再启动，更新检查失败只告警、照常启动。`-u` 后可接 update 的选项（如 `-u -y web`）与包装旗标（如 `-u --max-retries 0 web`）。
 
 ## 工作原理
 
@@ -81,12 +99,12 @@ update / -u 会同时检查 dsh-safe 自身的版本，谁旧升谁（一条安
 - `--patch` 覆盖层里插入的行不参与对照表（对照表只扫 profile patch、home patch 与 bundle patch）。
 - 为了捕获 stderr，包装器把 dsh 的 stderr 接到管道（内容仍实时回显到终端）；stdout/stdin 直通不受影响。
 - 本项目针对 dsh 0.1.x 的报错格式做匹配；dsh 大版本升级后格式变化时需要同步更新解析器。
-- Windows 为尽力支持：update / --self / list / restore 已适配（.cmd shim 解析、shell 方式调用 npm/pnpm），包装启动 dsh 的子进程方式未在 Windows 验证。
+- Windows 为尽力支持：update / --self / list / restore 已适配（.cmd shim 解析、shell 方式调用 npm/pnpm）；包装启动会把 PATH 上 dsh 的 .cmd/.ps1 shim 解析出内嵌的 node 入口、改为 `node <入口>` 直接启动（.exe 直接运行，shim 解析失败退回 shell 方式），绕开 Node 禁止 spawn .cmd 的限制。尚未在真实 Windows 上端到端验证，欢迎反馈。
 
 ## 开发
 
 ```bash
-npm test        # node:test 单元测试 + 假 dsh 集成测试
+npm test        # node:test 单元测试 + fake dsh 集成测试
 ```
 
 ## License

package/lib/dshpaths.js

@@ -6,7 +6,7 @@
  */
 import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { resolve, join } from 'node:path'
+import { dirname, resolve, join } from 'node:path'
 
 /** dsh home 目录：`DSH_HOME` 优先，默认 `~/.dsh`。 */
 export function dshHome() {
@@ -79,3 +79,75 @@ export function detectInvocation(args) {
   }
   return { mode: 'boot', profile: profile || null }
 }
+
+/**
+ * 解析把 dsh 跑起来的 spawn 目标（Windows 兼容的关键）。
+ *
+ * 非 Windows 的全局 bin 是 symlink / 带执行位脚本，`spawn('dsh')` 原样可用。
+ * Windows 的全局 bin 是 .cmd/.ps1 批处理：Node 出于安全禁止无 shell 地 spawn
+ * 它们（EINVAL），裸名也不参与 PATHEXT 解析（ENOENT）。因此按 PATH 目录顺序
+ * 找 `dsh.exe` / `dsh.cmd` / `dsh.ps1`：
+ *   - .exe → 直接 spawn；
+ *   - .cmd/.ps1 → 解析 shim 内嵌的 node_modules 入口脚本，改 spawn
+ *     `node <entry>`（无 shell、无参数转义问题，stderr 管道行为与 unix 一致）；
+ *   - shim 里解析不出入口 → 退回 shell 方式运行 shim 本身；
+ *   - PATH 上什么都没有 → 原样返回（报错行为与从前一致）。
+ *
+ * @param {string} command dsh 可执行名（默认 'dsh'）
+ * @param {{
+ *   platform?: string,
+ *   pathEnv?: string,
+ *   execPath?: string,
+ *   exists?: (path: string) => boolean,
+ *   readFile?: (path: string) => string | undefined,
+ * }} [inject] 测试注入
+ * @returns {{ file: string, prefix: string[], shell: boolean }}
+ *          spawn(file, [...prefix, ...args], { shell })
+ */
+export function resolveDshSpawnTarget(command, {
+  platform = process.platform,
+  pathEnv = process.env.PATH ?? '',
+  execPath = process.execPath,
+  exists = existsSync,
+  readFile = (p) => { try { return readFileSync(p, 'utf8') } catch { return undefined } },
+} = {}) {
+  if (platform !== 'win32') return { file: command, prefix: [], shell: false }
+  for (const dir of pathEnv.split(';')) {
+    if (!dir) continue
+    for (const ext of ['.exe', '.cmd', '.ps1']) { // 同目录内按 PATHEXT 惯例 .exe 优先
+      const p = join(dir, command + ext)
+      if (!exists(p)) continue
+      if (ext === '.exe') return { file: p, prefix: [], shell: false }
+      return resolveShimEntry(p, { execPath, exists, readFile })
+    }
+  }
+  return { file: command, prefix: [], shell: false }
+}
+
+/** 从 .cmd/.ps1 shim 解析内嵌入口；失败退回 shell 方式运行 shim（路径含空白时加引号）。 */
+function resolveShimEntry(shimPath, { execPath, exists, readFile }) {
+  const content = readFile(shimPath)
+  const entry = content ? findShimEntry(content, dirname(shimPath), exists) : null
+  if (entry) return { file: execPath, prefix: [entry], shell: false }
+  return { file: /\s/.test(shimPath) ? `"${shimPath}"` : shimPath, prefix: [], shell: true }
+}
+
+/**
+ * npm/pnpm 的 cmd/ps1 shim 内容里都内嵌 node_modules 下的入口脚本路径：
+ * cmd 形如 `"%~dp0\node_modules\@scope\pkg\bin\x.js"`（也可能先 SET 进变量再
+ * `node "%_prog%" %*`），ps1 形如 `$basedir/node_modules/...`。%~dp0 与
+ * $basedir 都展开为 shim 所在目录；取第一个真实存在的候选。
+ */
+function findShimEntry(content, shimDir, exists) {
+  const candidates = []
+  for (const m of content.matchAll(/"([^"\r\n]*node_modules[^"\r\n]*\.(?:js|cjs|mjs))"/gi)) candidates.push(m[1])
+  for (const m of content.matchAll(/[\w@.$%~\-\\\/]*node_modules[\w@.$%~\-\\\/]*\.(?:js|cjs|mjs)/gi)) candidates.push(m[0])
+  for (let raw of candidates) {
+    // `SET "_prog=%~dp0\..."` 会把变量名一起捕进来，切掉 `node_modules` 之前的 `xxx=`
+    const eq = raw.indexOf('=')
+    if (eq >= 0 && eq < raw.toLowerCase().indexOf('node_modules')) raw = raw.slice(eq + 1)
+    const p = resolve(raw.replace(/%~dp0|\$basedir/gi, `${shimDir}/`).replace(/\\/g, '/'))
+    if (exists(p)) return p
+  }
+  return null
+}

package/lib/wrap.js

@@ -6,11 +6,14 @@
  *   - 失败退出 → 从 stderr 解析坏插件，对照 patch 行后把对应行置为 disabled
  *     （写入托管区块 + 台账），然后重试；识别不出、超过重试上限、或命中
  *     第一方插件（@deepseek-ai/*，默认保护）时原样透传退出码。
+ *
+ * Windows 上经 resolveDshSpawnTarget 把 dsh 的 .cmd shim 解析成 `node <入口>`
+ * 再启动（见 dshpaths.js），其余平台原样 spawn。
  */
 import { spawn } from 'node:child_process'
 import { summarizeLine, parseFailureReport } from './failures.js'
 import { collectKnownRows, matchFailures } from './knownrows.js'
-import { detectInvocation } from './dshpaths.js'
+import { detectInvocation, resolveDshSpawnTarget } from './dshpaths.js'
 import { writeQuarantine } from './quarantine.js'
 import { t } from './i18n.js'
 
@@ -19,12 +22,17 @@ const FIRST_PARTY_PREFIX = '@deepseek-ai/'
 
 const isFirstParty = (name) => typeof name === 'string' && name.startsWith(FIRST_PARTY_PREFIX)
 
+/** shell 方式兜底时给含空白的参数补引号（正常路径不走 shell，不受影响）。 */
+const quoteShellArg = (a) => (/\s/.test(a) && !/^".*"$/.test(a) ? `"${a}"` : a)
+
 /** 运行 dsh：stdin/stdout 直通，stderr 回显并捕获（上限内）。 */
 export function spawnDsh(args, { command = 'dsh' } = {}) {
+  const target = resolveDshSpawnTarget(command)
   return new Promise((resolve) => {
-    const child = spawn(command, args, {
+    const child = spawn(target.file, [...target.prefix, ...(target.shell ? args.map(quoteShellArg) : args)], {
       stdio: ['inherit', 'inherit', 'pipe'],
       env: process.env,
+      shell: target.shell,
     })
     let captured = ''
     child.stderr?.on('data', (chunk) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyzyn/dsh-safe",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "dsh 启动保险丝：社区插件不兼容导致 dsh 启动失败时，自动禁用坏插件并重试",
   "type": "module",
   "license": "MIT",