@wwkit/shared 1.0.30 → 1.0.31

package/src/shell.js

@@ -1,570 +1,570 @@
-/**
- * 跨平台 shell / 系统环境处理
- *
- * 封装 Windows / macOS / Linux 的 shell 与系统环境差异，供 @wwkit 各包复用：
- *   - 平台检测（isWindows / isMac / isLinux）
- *   - bash 解析（nvm / phpenv 等 bash 工具需要；Windows 下找 Git Bash / WSL）
- *   - execSync / spawnSync 的 shell 选项选择
- *   - shell profile 文件路径检测与写入（.zshrc / .bashrc / .profile）
- *
- * 用法：
- *   import { Shell } from '@wwkit/shared'
- *   const shell = new Shell()
- *   execSync(cmd, { shell: shell.shellForExec(true) })
- *   shell.writeProfile('NVM_DIR', 'nvm', ['export NVM_DIR=...'])
- */
-
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { execSync, spawnSync } from 'node:child_process'
-
-export class Shell {
-  /**
-   * @param {{ platform?: string, env?: Record<string,string> }} [opts]
-   *        platform / env 注入用于测试；默认取 process.platform / process.env
-   */
-  constructor({ platform = process.platform, env = process.env } = {}) {
-    this.platform = platform
-    this.env = env
-  }
-
-  /** 是否为 Windows */
-  get isWindows() {
-    return this.platform === 'win32'
-  }
-
-  /** 是否为 macOS */
-  get isMac() {
-    return this.platform === 'darwin'
-  }
-
-  /** 是否为 Linux */
-  get isLinux() {
-    return this.platform === 'linux'
-  }
-
-  /**
-   * 解析可用的 bash 路径
-   *
-   * Unix: 优先 /bin/bash（原行为），回退 /usr/bin/bash，再回退 PATH 中的 bash
-   * Windows: 优先 Git Bash（常见安装路径 + 由 `where git` 推导 Git 根），
-   *          再回退 PATH 中的 bash（排除 WSL 转发器 System32\bash.exe / WindowsApps\bash.exe）；
-   *          找不到则抛错
-   *
-   * @returns {string} bash 可执行文件路径
-   * @throws {Error} 找不到 bash 时抛出（含平台相关提示）
-   */
-  resolveBash() {
-    if (!this.isWindows) {
-      for (const c of ['/bin/bash', '/usr/bin/bash']) {
-        try {
-          fs.accessSync(c, fs.constants.X_OK)
-          return c
-        } catch {}
-      }
-    }
-
-    if (this.isWindows) {
-      const gitBash = this._findGitBash()
-      if (gitBash) return gitBash
-    }
-
-    try {
-      const cmd = this.isWindows ? 'where bash' : 'command -v bash'
-      const out = execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
-      if (out) {
-        const lines = out.split(/\r?\n/)
-        if (this.isWindows) {
-          // 排除 WSL 转发器（System32\bash.exe / WindowsApps\bash.exe）——它们不是真实 bash
-          const real = lines.find((l) => {
-            const lower = l.toLowerCase()
-            return !lower.includes('system32\\bash') && !lower.includes('windowsapps\\bash')
-          })
-          if (real) return real
-        }
-        return lines[0]
-      }
-    } catch {}
-
-    throw new Error(
-      'bash not found: nvm/phpenv require bash. ' +
-      (this.isWindows ? 'Install Git Bash or run inside WSL.' : 'Install bash.')
-    )
-  }
-
-  /**
-   * 在 Windows 上定位 Git Bash（真实 bash，非 WSL 转发器）
-   *
-   * 依次尝试：常见 Git 安装路径（ProgramFiles / ProgramFiles(x86) / LOCALAPPDATA\Programs\Git）
-   * → 由 `where git` 定位 git.exe 推导 Git 根（<root>\cmd\git.exe → <root>\bin\bash.exe）。
-   * @returns {string} Git Bash 路径；未找到返回空串
-   * @private
-   */
-  _findGitBash() {
-    const candidates = []
-    const pf = this.env.ProgramFiles
-    const pf86 = this.env['ProgramFiles(x86)']
-    const la = this.env.LOCALAPPDATA
-    if (pf) candidates.push(path.join(pf, 'Git', 'bin', 'bash.exe'))
-    if (pf86) candidates.push(path.join(pf86, 'Git', 'bin', 'bash.exe'))
-    if (la) candidates.push(path.join(la, 'Programs', 'Git', 'bin', 'bash.exe'))
-    for (const c of candidates) {
-      try {
-        fs.accessSync(c, fs.constants.X_OK)
-        return c
-      } catch {}
-    }
-    try {
-      const out = execSync('where git', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
-      const gitExe = out.split(/\r?\n/)[0]
-      if (gitExe && /\\cmd\\git\.exe$/i.test(gitExe)) {
-        const root = path.dirname(path.dirname(gitExe))
-        const bash = path.join(root, 'bin', 'bash.exe')
-        try {
-          fs.accessSync(bash, fs.constants.X_OK)
-          return bash
-        } catch {}
-      }
-    } catch {}
-    return ''
-  }
-
-  /**
-   * 返回 execSync / spawnSync 的 shell 选项
-   *
-   * needsBash=true  → 解析并返回 bash 路径（nvm/phpenv 等 bash 工具）
-   * needsBash=false → 返回 true（使用系统默认 shell：Unix /bin/sh，Windows cmd.exe）
-   *
-   * @param {boolean} needsBash - 命令是否需要 bash
-   * @returns {string|boolean}
-   */
-  shellForExec(needsBash) {
-    return needsBash ? this.resolveBash() : true
-  }
-
-  /**
-   * 返回 execSync / spawnSync 在继承终端输出时的 stdio 选项
-   *
-   * Windows + bash 下 stdio: 'inherit' 会使 bash 继承终端 stdin，
-   * 命令完成后 bash 仍等待 stdin EOF 不退出，导致 execSync/spawnSync 永久挂起。
-   * 改用 ['ignore', 'inherit', 'inherit']：stdin → NUL，bash 立即收到 EOF 退出；
-   * stdout/stderr 仍继承终端，输出可见。
-   *
-   * @param {boolean} needsBash - 是否使用 bash 作为 shell
-   * @returns {'inherit'|string[]} stdio 选项
-   */
-  stdioForExec(needsBash) {
-    if (needsBash && this.isWindows) {
-      return ['ignore', 'inherit', 'inherit']
-    }
-    return 'inherit'
-  }
-
-  /**
-   * 检测当前 shell 的 profile 文件路径
-   *
-   * Unix: $SHELL 含 zsh → ~/.zshrc；含 bash → ~/.bashrc；否则 ~/.profile
-   * Windows: 无 $SHELL，默认 ~/.bashrc（Git Bash 约定）
-   *
-   * @returns {string}
-   */
-  getProfile() {
-    const shell = this.env.SHELL || ''
-    if (shell.includes('zsh')) {
-      return path.join(os.homedir(), '.zshrc')
-    }
-    if (shell.includes('bash')) {
-      return path.join(os.homedir(), '.bashrc')
-    }
-    if (this.isWindows) {
-      return path.join(os.homedir(), '.bashrc')
-    }
-    return path.join(os.homedir(), '.profile')
-  }
-
-  /**
-   * 检测当前用户所有需要写入的 shell profile 文件
-   *
-   * 返回数组以覆盖多种场景（login / non-login / 不同 shell）：
-   *   - zsh:  ~/.zshrc（交互式 zsh 总是读取）
-   *   - bash: ~/.bashrc（非登录交互式）+ ~/.bash_profile（登录式，仅当已存在）
-   *   - fish: ~/.config/fish/config.fish（fish 唯一配置文件）
-   *   - 未知: ~/.profile（POSIX 通用回退）
-   *
-   * 每项含 `path`（绝对路径）和 `syntax`（'export' | 'fish'），
-   * 调用方据此生成正确语法的变量设置行。
-   *
-   * @returns {{ path: string, syntax: 'export' | 'fish' }[]}
-   */
-  getProfiles() {
-    const home = os.homedir()
-    const shell = this.env.SHELL || ''
-    const profiles = []
-
-    if (shell.includes('fish')) {
-      profiles.push({
-        path: path.join(home, '.config', 'fish', 'config.fish'),
-        syntax: 'fish',
-      })
-    } else if (shell.includes('zsh')) {
-      profiles.push({ path: path.join(home, '.zshrc'), syntax: 'export' })
-    } else if (shell.includes('bash')) {
-      profiles.push({ path: path.join(home, '.bashrc'), syntax: 'export' })
-      const bp = path.join(home, '.bash_profile')
-      if (fs.existsSync(bp)) {
-        profiles.push({ path: bp, syntax: 'export' })
-      }
-    } else {
-      profiles.push({ path: path.join(home, '.profile'), syntax: 'export' })
-    }
-
-    return profiles
-  }
-
-  /**
-   * 将 shell 初始化行写入 profile（按 marker 去重）
-   *
-   * @param {string} marker - 若 profile 已含该标记则跳过
-   * @param {string} comment - 写入块注释
-   * @param {string[]} lines - 要追加的行
-   * @returns {boolean} 是否写入了新行
-   */
-  writeProfile(marker, comment, lines) {
-    const profilePath = this.getProfile()
-    let existing = ''
-    try {
-      existing = fs.readFileSync(profilePath, 'utf8')
-    } catch {}
-    if (existing.includes(marker)) {
-      return false
-    }
-    const append = `\n# ${comment}\n${lines.join('\n')}\n`
-    fs.appendFileSync(profilePath, append, 'utf8')
-    return true
-  }
-
-  /**
-   * 统一的 spawnSync 封装（供 Windows 注册表/setx 操作与命令检测使用）
-   * @param {string} cmd - 可执行文件
-   * @param {string[]} [args=[]] - 参数
-   * @returns {Object} spawnSync 结果对象
-   * @private
-   */
-  _spawnSync(cmd, args = []) {
-    return spawnSync(cmd, args, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
-  }
-
-  /**
-   * 持久化设置系统环境变量（跨平台）
-   *
-   * Unix: 将变量设置行写入所有相关 shell profile（getProfiles()），使用
-   *       begin/end 标记块管理区块，支持幂等（值相同则跳过）和值更新
-   *       （路径变化时自动替换）。覆盖 bash/zsh/fish 及 login/non-login 场景。
-   * Windows: 使用 `setx` 设置用户级环境变量（写入注册表，始终覆盖）。
-   *
-   * @param {string} name - 环境变量名
-   * @param {string} value - 环境变量值
-   * @returns {boolean} 是否写入/更新了至少一个目标（全部已存在且值相同则 false）
-   */
-  setEnvVar(name, value) {
-    if (this.isWindows) {
-      try {
-        const result = this._spawnSync('setx', [name, String(value)])
-        return result.status === 0
-      } catch {
-        return false
-      }
-    }
-
-    const escaped = String(value).replace(/[$`\\"]/g, '\\$&')
-    let wrote = false
-
-    for (const { path: profilePath, syntax } of this.getProfiles()) {
-      const line = syntax === 'fish'
-        ? `set -gx ${name} "${escaped}"`
-        : `export ${name}="${escaped}"`
-      if (this._writeEnvBlock(profilePath, name, line)) {
-        wrote = true
-      }
-    }
-
-    return wrote
-  }
-
-  /**
-   * 向指定 profile 文件写入/更新一个环境变量标记块
-   *
-   * 写入前先清理文件中所有同名的裸 export/set 行（非标记块内的），
-   * 避免裸行与标记块并存导致残留误导。
-   * 标记块用单行注释头（无尾标记），形如：
-   *   # >>> wwkit NAME >>>
-   *   export NAME="value"
-   *
-   * @param {string} profilePath - profile 文件绝对路径
-   * @param {string} name - 环境变量名（用于生成标记）
-   * @param {string} line - 变量设置行（含正确语法）
-   * @returns {boolean} 是否写入/更新了该文件
-   */
-  _writeEnvBlock(profilePath, name, line) {
-    let existing = ''
-    try {
-      existing = fs.readFileSync(profilePath, 'utf8')
-    } catch {}
-
-const marker = `# >>> wwkit ${name} >>>`
-    const oldEndMarker = `# <<< wwkit ${name} <<<`
-
-    // 清理同名裸 export/set 行（不在任何标记块内的）
-    existing = this._stripBareEnvLines(existing, name)
-
-    const beginIdx = existing.indexOf(marker)
-    if (beginIdx !== -1) {
-      const afterMarker = beginIdx + marker.length
-      // 块尾：优先找旧版 end marker，其次找下一个 wwkit marker，最后 EOF
-      const oldEndIdx = existing.indexOf(oldEndMarker, afterMarker)
-      const nextMarkerIdx = existing.indexOf('# >>> wwkit', afterMarker)
-      let blockEnd
-      if (oldEndIdx !== -1 && (nextMarkerIdx === -1 || oldEndIdx < nextMarkerIdx)) {
-        blockEnd = oldEndIdx + oldEndMarker.length
-      } else if (nextMarkerIdx !== -1) {
-        blockEnd = nextMarkerIdx
-      } else {
-        blockEnd = existing.length
-      }
-      const currentBlock = existing.slice(beginIdx, blockEnd)
-      const newBlock = `${marker}\n${line}\n`
-      if (currentBlock.trim() === newBlock.trim()) return false
-      existing = existing.slice(0, beginIdx) + newBlock + existing.slice(blockEnd)
-      fs.writeFileSync(profilePath, existing, 'utf8')
-      return true
-    }
-
-    const dir = path.dirname(profilePath)
-    fs.mkdirSync(dir, { recursive: true })
-    fs.appendFileSync(profilePath, `\n${marker}\n${line}\n`, 'utf8')
-    return true
-  }
-
-  /**
-   * 从 profile 内容中删除所有同名的裸 export/set 行（不在标记块内的）
-   * @param {string} content
-   * @param {string} name
-   * @returns {string}
-   * @private
-   */
-  _stripBareEnvLines(content, name) {
-    const lines = content.split('\n')
-    const barePattern = new RegExp(`^\\s*(export|set -gx)\\s+${name}\\b`)
-    let inBlock = false
-    return lines.filter((l) => {
-      if (l.startsWith('# >>> wwkit ')) { inBlock = true; return true }
-      if (l.startsWith('# <<< wwkit ')) { inBlock = false; return true }
-      if (inBlock) return true
-      return !barePattern.test(l)
-    }).join('\n')
-  }
-
-  /**
-   * 归一化路径用于 PATH 条目比较（大小写不敏感、统一分隔符、去尾斜杠）
-   * @param {string} p - 原始路径/条目
-   * @returns {string}
-   * @private
-   */
-  _absPathKey(p) {
-    return String(p).trim().replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()
-  }
-
-  /**
-   * 判断路径列表（分号/冒号分隔）是否包含指定目录
-   * @param {string} pathList - 分隔符连接的路径列表
-   * @param {string} dir - 要查找的目录
-   * @param {string} sep - 分隔符（Windows ';'，Unix ':'）
-   * @returns {boolean}
-   * @private
-   */
-  _pathListIncludes(pathList, dir, sep = ';') {
-    if (!pathList) return false
-    const needle = this._absPathKey(dir)
-    if (!needle) return false
-    return String(pathList)
-      .split(sep)
-      .some((p) => this._absPathKey(p) === needle)
-  }
-
-  /**
-   * 判断目录是否已包含在当前进程 PATH（或传入的用户 PATH 字符串）中
-   *
-   * 进程 PATH 按平台分隔（Windows ';'，Unix ':'）；持久化用户 PATH 字符串
-   * （Windows 注册表读取值）恒为分号分隔。
-   * @param {string} dir - 目录绝对路径
-   * @param {string} [userPath=''] - 可选：持久化用户 PATH 字符串（Windows 注册表读取值）
-   * @returns {boolean}
-   */
-  dirInPath(dir, userPath = '') {
-    const needle = this._absPathKey(dir)
-    if (!needle) return false
-    const procSep = this.isWindows ? ';' : ':'
-    if (this._pathListIncludes(this.env.PATH, dir, procSep)) return true
-    return this._pathListIncludes(userPath, dir, ';')
-  }
-
-  /**
-   * 读取持久化用户 PATH（Windows 注册表 HKCU\Environment\Path）
-   *
-   * Unix 无用户级 PATH 注册表，返回空串（PATH 由 shell profile 管理）。
-   * @returns {string}
-   */
-  getUserPath() {
-    if (!this.isWindows) return ''
-    try {
-      const result = this._spawnSync('reg', ['query', 'HKCU\\Environment', '/v', 'Path'])
-      if (result.status !== 0) return ''
-      const lines = result.stdout.split(/\r?\n/)
-      for (const line of lines) {
-        const m = line.match(/^\s*Path\s+REG_\w+\s+(.*)$/)
-        if (m) return m[1].trim()
-      }
-      return ''
-    } catch {
-      return ''
-    }
-  }
-
-  /**
-   * 写回持久化用户 PATH（Windows 注册表，保留 REG_EXPAND_SZ 类型）
-   *
-   * 不用 setx 的原因：setx 会把 REG_EXPAND_SZ 降级为 REG_SZ（%VAR% 字面量失去展开）
-   * 且值超过 1024 字符会被静默截断；reg add 可原样保留类型与完整值。
-   * @param {string} value - 完整 PATH 值（分号分隔）
-   * @returns {boolean} 是否写入成功
-   * @private
-   */
-  _setUserPath(value) {
-    try {
-      const result = this._spawnSync(
-        'reg', ['add', 'HKCU\\Environment', '/v', 'Path', '/t', 'REG_EXPAND_SZ', '/d', value, '/f']
-      )
-      return result.status === 0
-    } catch {
-      return false
-    }
-  }
-
-  /**
-   * 追加目录到持久化用户 PATH（Windows 注册表，保留 REG_EXPAND_SZ 类型）
-   * @param {string} dir - 要追加的目录绝对路径
-   * @returns {boolean} 是否写入成功
-   * @private
-   */
-  _appendUserPath(dir) {
-    const current = this.getUserPath()
-    const sep = current && !current.endsWith(';') ? ';' : ''
-    return this._setUserPath(current + sep + dir)
-  }
-
-  /**
-   * 确保目录已进入 Windows 持久化用户 PATH（幂等），并同步当前进程 PATH
-   *
-   * 解决场景：npm 全局安装（如 ww init 插件）装到 shell 会话专属前缀（如 nvm
-   * 的 bin/）时，该目录不在系统/用户 PATH，其他 shell 中命令不可用。此方法
-   * 把目录追加进 HKCU\Environment\Path（REG_EXPAND_SZ），重启终端后全局生效。
-   *
-   * Unix：不干预（PATH 由 nvm/profile 管理，npm 全局 bin 通常已在其中），返回 false。
-   *
-   * @param {string} dir - 目录绝对路径
-   * @returns {boolean} 是否新写入（已在则 false）
-   */
-  ensurePathEntry(dir) {
-    const needle = this._absPathKey(dir)
-    if (!needle || !this.isWindows) return false
-    if (this._pathListIncludes(this.getUserPath(), dir)) return false
-    const ok = this._appendUserPath(dir)
-    if (ok && !this._pathListIncludes(this.env.PATH, dir)) {
-      const sep = this.env.PATH && !this.env.PATH.endsWith(';') ? ';' : ''
-      this.env.PATH = (this.env.PATH || '') + sep + dir
-    }
-    return ok
-  }
-
-  /**
-   * 把目录前置到当前进程 PATH（process.env.PATH，幂等，不写注册表）
-   *
-   * 进程从旧 PATH 启动时不含注册表最新变更；需要让本进程后续的子进程立即用
-   * 新目录中的命令（如 mise shims 的 node）时调用。已在则移到最前（不重复）。
-   * @param {string|string[]} dirs - 目录（数组按序前置，最后一个在最前）
-   */
-  prependProcPath(dirs) {
-    const list = (Array.isArray(dirs) ? dirs : [dirs]).filter(Boolean)
-    if (!list.length) return
-    const sep = this.isWindows ? ';' : ':'
-    const key = (e) => this._absPathKey(e)
-    let entries = String(this.env.PATH || '').split(sep).filter(Boolean)
-    for (const d of list) {
-      const needle = key(d)
-      if (!needle) continue
-      entries = entries.filter((e) => key(e) !== needle)
-      entries.unshift(d)
-    }
-    this.env.PATH = entries.join(sep)
-  }
-
-  /**
-   * 确保目录已前置到 Windows 持久化用户 PATH 最前（幂等），并同步当前进程 PATH
-   *
-   * 用于需要**优先于系统 PATH** 的场景：如 mise shims 目录——系统 PATH 里可能已有
-   * 旧版 node（如 D:\library\nodejs），只有把 mise shims 前置才能让新 shell 优先用
-   * mise 管理的 node。若目录已在用户 PATH 任意位置，会移到最前（幂等更新）。
-   *
-   * Unix：不干预，返回 false。
-   *
-   * @param {string} dir - 目录绝对路径
-   * @returns {boolean} 是否新写入/更新（已在最前则 false）
-   */
-  prependPathEntry(dir) {
-    const needle = this._absPathKey(dir)
-    if (!needle || !this.isWindows) return false
-    const current = this.getUserPath()
-    const entries = String(current || '').split(';').map((e) => e.trim()).filter(Boolean)
-    const key = (e) => this._absPathKey(e)
-    const filtered = entries.filter((e) => key(e) !== needle)
-    const newValue = [dir, ...filtered].join(';')
-    if (newValue === current) return false
-    const ok = this._setUserPath(newValue)
-    if (ok) this.prependProcPath(dir)
-    return ok
-  }
-
-  /**
-   * 检测系统命令是否可用
-   * Windows: where <cmd>；Unix: which <cmd>
-   *
-   * @param {string} cmd - 命令名
-   * @returns {boolean}
-   */
-  isCommandAvailable(cmd) {
-    const checker = this.isWindows ? 'where' : 'which'
-    try {
-      const result = this._spawnSync(checker, [cmd])
-      return result.status === 0
-    } catch {
-      return false
-    }
-  }
-
-  /**
-   * 按优先级检测可用的网络探测工具
-   * 顺序: curl > wget > ping
-   *
-   * curl 优先：支持代理（-x）、输出 locale 无关（HTTP 状态码）、检查 HTTP 层可达性。
-   * ping 最后：ICMP 不支持代理、输出依赖系统语言（中文 Windows 乱码）、仅检查网络层。
-   *
-   * @returns {string|null} 'curl' | 'wget' | 'ping' | null
-   */
-  getNetProbeTool() {
-    for (const cmd of ['curl', 'wget', 'ping']) {
-      if (this.isCommandAvailable(cmd)) return cmd
-    }
-    return null
-  }
+/**
+ * 跨平台 shell / 系统环境处理
+ *
+ * 封装 Windows / macOS / Linux 的 shell 与系统环境差异，供 @wwkit 各包复用：
+ *   - 平台检测（isWindows / isMac / isLinux）
+ *   - bash 解析（nvm / phpenv 等 bash 工具需要；Windows 下找 Git Bash / WSL）
+ *   - execSync / spawnSync 的 shell 选项选择
+ *   - shell profile 文件路径检测与写入（.zshrc / .bashrc / .profile）
+ *
+ * 用法：
+ *   import { Shell } from '@wwkit/shared'
+ *   const shell = new Shell()
+ *   execSync(cmd, { shell: shell.shellForExec(true) })
+ *   shell.writeProfile('NVM_DIR', 'nvm', ['export NVM_DIR=...'])
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { execSync, spawnSync } from 'node:child_process'
+
+export class Shell {
+  /**
+   * @param {{ platform?: string, env?: Record<string,string> }} [opts]
+   *        platform / env 注入用于测试；默认取 process.platform / process.env
+   */
+  constructor({ platform = process.platform, env = process.env } = {}) {
+    this.platform = platform
+    this.env = env
+  }
+
+  /** 是否为 Windows */
+  get isWindows() {
+    return this.platform === 'win32'
+  }
+
+  /** 是否为 macOS */
+  get isMac() {
+    return this.platform === 'darwin'
+  }
+
+  /** 是否为 Linux */
+  get isLinux() {
+    return this.platform === 'linux'
+  }
+
+  /**
+   * 解析可用的 bash 路径
+   *
+   * Unix: 优先 /bin/bash（原行为），回退 /usr/bin/bash，再回退 PATH 中的 bash
+   * Windows: 优先 Git Bash（常见安装路径 + 由 `where git` 推导 Git 根），
+   *          再回退 PATH 中的 bash（排除 WSL 转发器 System32\bash.exe / WindowsApps\bash.exe）；
+   *          找不到则抛错
+   *
+   * @returns {string} bash 可执行文件路径
+   * @throws {Error} 找不到 bash 时抛出（含平台相关提示）
+   */
+  resolveBash() {
+    if (!this.isWindows) {
+      for (const c of ['/bin/bash', '/usr/bin/bash']) {
+        try {
+          fs.accessSync(c, fs.constants.X_OK)
+          return c
+        } catch {}
+      }
+    }
+
+    if (this.isWindows) {
+      const gitBash = this._findGitBash()
+      if (gitBash) return gitBash
+    }
+
+    try {
+      const cmd = this.isWindows ? 'where bash' : 'command -v bash'
+      const out = execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
+      if (out) {
+        const lines = out.split(/\r?\n/)
+        if (this.isWindows) {
+          // 排除 WSL 转发器（System32\bash.exe / WindowsApps\bash.exe）——它们不是真实 bash
+          const real = lines.find((l) => {
+            const lower = l.toLowerCase()
+            return !lower.includes('system32\\bash') && !lower.includes('windowsapps\\bash')
+          })
+          if (real) return real
+        }
+        return lines[0]
+      }
+    } catch {}
+
+    throw new Error(
+      'bash not found: nvm/phpenv require bash. ' +
+      (this.isWindows ? 'Install Git Bash or run inside WSL.' : 'Install bash.')
+    )
+  }
+
+  /**
+   * 在 Windows 上定位 Git Bash（真实 bash，非 WSL 转发器）
+   *
+   * 依次尝试：常见 Git 安装路径（ProgramFiles / ProgramFiles(x86) / LOCALAPPDATA\Programs\Git）
+   * → 由 `where git` 定位 git.exe 推导 Git 根（<root>\cmd\git.exe → <root>\bin\bash.exe）。
+   * @returns {string} Git Bash 路径；未找到返回空串
+   * @private
+   */
+  _findGitBash() {
+    const candidates = []
+    const pf = this.env.ProgramFiles
+    const pf86 = this.env['ProgramFiles(x86)']
+    const la = this.env.LOCALAPPDATA
+    if (pf) candidates.push(path.join(pf, 'Git', 'bin', 'bash.exe'))
+    if (pf86) candidates.push(path.join(pf86, 'Git', 'bin', 'bash.exe'))
+    if (la) candidates.push(path.join(la, 'Programs', 'Git', 'bin', 'bash.exe'))
+    for (const c of candidates) {
+      try {
+        fs.accessSync(c, fs.constants.X_OK)
+        return c
+      } catch {}
+    }
+    try {
+      const out = execSync('where git', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim()
+      const gitExe = out.split(/\r?\n/)[0]
+      if (gitExe && /\\cmd\\git\.exe$/i.test(gitExe)) {
+        const root = path.dirname(path.dirname(gitExe))
+        const bash = path.join(root, 'bin', 'bash.exe')
+        try {
+          fs.accessSync(bash, fs.constants.X_OK)
+          return bash
+        } catch {}
+      }
+    } catch {}
+    return ''
+  }
+
+  /**
+   * 返回 execSync / spawnSync 的 shell 选项
+   *
+   * needsBash=true  → 解析并返回 bash 路径（nvm/phpenv 等 bash 工具）
+   * needsBash=false → 返回 true（使用系统默认 shell：Unix /bin/sh，Windows cmd.exe）
+   *
+   * @param {boolean} needsBash - 命令是否需要 bash
+   * @returns {string|boolean}
+   */
+  shellForExec(needsBash) {
+    return needsBash ? this.resolveBash() : true
+  }
+
+  /**
+   * 返回 execSync / spawnSync 在继承终端输出时的 stdio 选项
+   *
+   * Windows + bash 下 stdio: 'inherit' 会使 bash 继承终端 stdin，
+   * 命令完成后 bash 仍等待 stdin EOF 不退出，导致 execSync/spawnSync 永久挂起。
+   * 改用 ['ignore', 'inherit', 'inherit']：stdin → NUL，bash 立即收到 EOF 退出；
+   * stdout/stderr 仍继承终端，输出可见。
+   *
+   * @param {boolean} needsBash - 是否使用 bash 作为 shell
+   * @returns {'inherit'|string[]} stdio 选项
+   */
+  stdioForExec(needsBash) {
+    if (needsBash && this.isWindows) {
+      return ['ignore', 'inherit', 'inherit']
+    }
+    return 'inherit'
+  }
+
+  /**
+   * 检测当前 shell 的 profile 文件路径
+   *
+   * Unix: $SHELL 含 zsh → ~/.zshrc；含 bash → ~/.bashrc；否则 ~/.profile
+   * Windows: 无 $SHELL，默认 ~/.bashrc（Git Bash 约定）
+   *
+   * @returns {string}
+   */
+  getProfile() {
+    const shell = this.env.SHELL || ''
+    if (shell.includes('zsh')) {
+      return path.join(os.homedir(), '.zshrc')
+    }
+    if (shell.includes('bash')) {
+      return path.join(os.homedir(), '.bashrc')
+    }
+    if (this.isWindows) {
+      return path.join(os.homedir(), '.bashrc')
+    }
+    return path.join(os.homedir(), '.profile')
+  }
+
+  /**
+   * 检测当前用户所有需要写入的 shell profile 文件
+   *
+   * 返回数组以覆盖多种场景（login / non-login / 不同 shell）：
+   *   - zsh:  ~/.zshrc（交互式 zsh 总是读取）
+   *   - bash: ~/.bashrc（非登录交互式）+ ~/.bash_profile（登录式，仅当已存在）
+   *   - fish: ~/.config/fish/config.fish（fish 唯一配置文件）
+   *   - 未知: ~/.profile（POSIX 通用回退）
+   *
+   * 每项含 `path`（绝对路径）和 `syntax`（'export' | 'fish'），
+   * 调用方据此生成正确语法的变量设置行。
+   *
+   * @returns {{ path: string, syntax: 'export' | 'fish' }[]}
+   */
+  getProfiles() {
+    const home = os.homedir()
+    const shell = this.env.SHELL || ''
+    const profiles = []
+
+    if (shell.includes('fish')) {
+      profiles.push({
+        path: path.join(home, '.config', 'fish', 'config.fish'),
+        syntax: 'fish',
+      })
+    } else if (shell.includes('zsh')) {
+      profiles.push({ path: path.join(home, '.zshrc'), syntax: 'export' })
+    } else if (shell.includes('bash')) {
+      profiles.push({ path: path.join(home, '.bashrc'), syntax: 'export' })
+      const bp = path.join(home, '.bash_profile')
+      if (fs.existsSync(bp)) {
+        profiles.push({ path: bp, syntax: 'export' })
+      }
+    } else {
+      profiles.push({ path: path.join(home, '.profile'), syntax: 'export' })
+    }
+
+    return profiles
+  }
+
+  /**
+   * 将 shell 初始化行写入 profile（按 marker 去重）
+   *
+   * @param {string} marker - 若 profile 已含该标记则跳过
+   * @param {string} comment - 写入块注释
+   * @param {string[]} lines - 要追加的行
+   * @returns {boolean} 是否写入了新行
+   */
+  writeProfile(marker, comment, lines) {
+    const profilePath = this.getProfile()
+    let existing = ''
+    try {
+      existing = fs.readFileSync(profilePath, 'utf8')
+    } catch {}
+    if (existing.includes(marker)) {
+      return false
+    }
+    const append = `\n# ${comment}\n${lines.join('\n')}\n`
+    fs.appendFileSync(profilePath, append, 'utf8')
+    return true
+  }
+
+  /**
+   * 统一的 spawnSync 封装（供 Windows 注册表/setx 操作与命令检测使用）
+   * @param {string} cmd - 可执行文件
+   * @param {string[]} [args=[]] - 参数
+   * @returns {Object} spawnSync 结果对象
+   * @private
+   */
+  _spawnSync(cmd, args = []) {
+    return spawnSync(cmd, args, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
+  }
+
+  /**
+   * 持久化设置系统环境变量（跨平台）
+   *
+   * Unix: 将变量设置行写入所有相关 shell profile（getProfiles()），使用
+   *       begin/end 标记块管理区块，支持幂等（值相同则跳过）和值更新
+   *       （路径变化时自动替换）。覆盖 bash/zsh/fish 及 login/non-login 场景。
+   * Windows: 使用 `setx` 设置用户级环境变量（写入注册表，始终覆盖）。
+   *
+   * @param {string} name - 环境变量名
+   * @param {string} value - 环境变量值
+   * @returns {boolean} 是否写入/更新了至少一个目标（全部已存在且值相同则 false）
+   */
+  setEnvVar(name, value) {
+    if (this.isWindows) {
+      try {
+        const result = this._spawnSync('setx', [name, String(value)])
+        return result.status === 0
+      } catch {
+        return false
+      }
+    }
+
+    const escaped = String(value).replace(/[$`\\"]/g, '\\$&')
+    let wrote = false
+
+    for (const { path: profilePath, syntax } of this.getProfiles()) {
+      const line = syntax === 'fish'
+        ? `set -gx ${name} "${escaped}"`
+        : `export ${name}="${escaped}"`
+      if (this._writeEnvBlock(profilePath, name, line)) {
+        wrote = true
+      }
+    }
+
+    return wrote
+  }
+
+  /**
+   * 向指定 profile 文件写入/更新一个环境变量标记块
+   *
+   * 写入前先清理文件中所有同名的裸 export/set 行（非标记块内的），
+   * 避免裸行与标记块并存导致残留误导。
+   * 标记块用单行注释头（无尾标记），形如：
+   *   # >>> wwkit NAME >>>
+   *   export NAME="value"
+   *
+   * @param {string} profilePath - profile 文件绝对路径
+   * @param {string} name - 环境变量名（用于生成标记）
+   * @param {string} line - 变量设置行（含正确语法）
+   * @returns {boolean} 是否写入/更新了该文件
+   */
+  _writeEnvBlock(profilePath, name, line) {
+    let existing = ''
+    try {
+      existing = fs.readFileSync(profilePath, 'utf8')
+    } catch {}
+
+const marker = `# >>> wwkit ${name} >>>`
+    const oldEndMarker = `# <<< wwkit ${name} <<<`
+
+    // 清理同名裸 export/set 行（不在任何标记块内的）
+    existing = this._stripBareEnvLines(existing, name)
+
+    const beginIdx = existing.indexOf(marker)
+    if (beginIdx !== -1) {
+      const afterMarker = beginIdx + marker.length
+      // 块尾：优先找旧版 end marker，其次找下一个 wwkit marker，最后 EOF
+      const oldEndIdx = existing.indexOf(oldEndMarker, afterMarker)
+      const nextMarkerIdx = existing.indexOf('# >>> wwkit', afterMarker)
+      let blockEnd
+      if (oldEndIdx !== -1 && (nextMarkerIdx === -1 || oldEndIdx < nextMarkerIdx)) {
+        blockEnd = oldEndIdx + oldEndMarker.length
+      } else if (nextMarkerIdx !== -1) {
+        blockEnd = nextMarkerIdx
+      } else {
+        blockEnd = existing.length
+      }
+      const currentBlock = existing.slice(beginIdx, blockEnd)
+      const newBlock = `${marker}\n${line}\n`
+      if (currentBlock.trim() === newBlock.trim()) return false
+      existing = existing.slice(0, beginIdx) + newBlock + existing.slice(blockEnd)
+      fs.writeFileSync(profilePath, existing, 'utf8')
+      return true
+    }
+
+    const dir = path.dirname(profilePath)
+    fs.mkdirSync(dir, { recursive: true })
+    fs.appendFileSync(profilePath, `\n${marker}\n${line}\n`, 'utf8')
+    return true
+  }
+
+  /**
+   * 从 profile 内容中删除所有同名的裸 export/set 行（不在标记块内的）
+   * @param {string} content
+   * @param {string} name
+   * @returns {string}
+   * @private
+   */
+  _stripBareEnvLines(content, name) {
+    const lines = content.split('\n')
+    const barePattern = new RegExp(`^\\s*(export|set -gx)\\s+${name}\\b`)
+    let inBlock = false
+    return lines.filter((l) => {
+      if (l.startsWith('# >>> wwkit ')) { inBlock = true; return true }
+      if (l.startsWith('# <<< wwkit ')) { inBlock = false; return true }
+      if (inBlock) return true
+      return !barePattern.test(l)
+    }).join('\n')
+  }
+
+  /**
+   * 归一化路径用于 PATH 条目比较（大小写不敏感、统一分隔符、去尾斜杠）
+   * @param {string} p - 原始路径/条目
+   * @returns {string}
+   * @private
+   */
+  _absPathKey(p) {
+    return String(p).trim().replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()
+  }
+
+  /**
+   * 判断路径列表（分号/冒号分隔）是否包含指定目录
+   * @param {string} pathList - 分隔符连接的路径列表
+   * @param {string} dir - 要查找的目录
+   * @param {string} sep - 分隔符（Windows ';'，Unix ':'）
+   * @returns {boolean}
+   * @private
+   */
+  _pathListIncludes(pathList, dir, sep = ';') {
+    if (!pathList) return false
+    const needle = this._absPathKey(dir)
+    if (!needle) return false
+    return String(pathList)
+      .split(sep)
+      .some((p) => this._absPathKey(p) === needle)
+  }
+
+  /**
+   * 判断目录是否已包含在当前进程 PATH（或传入的用户 PATH 字符串）中
+   *
+   * 进程 PATH 按平台分隔（Windows ';'，Unix ':'）；持久化用户 PATH 字符串
+   * （Windows 注册表读取值）恒为分号分隔。
+   * @param {string} dir - 目录绝对路径
+   * @param {string} [userPath=''] - 可选：持久化用户 PATH 字符串（Windows 注册表读取值）
+   * @returns {boolean}
+   */
+  dirInPath(dir, userPath = '') {
+    const needle = this._absPathKey(dir)
+    if (!needle) return false
+    const procSep = this.isWindows ? ';' : ':'
+    if (this._pathListIncludes(this.env.PATH, dir, procSep)) return true
+    return this._pathListIncludes(userPath, dir, ';')
+  }
+
+  /**
+   * 读取持久化用户 PATH（Windows 注册表 HKCU\Environment\Path）
+   *
+   * Unix 无用户级 PATH 注册表，返回空串（PATH 由 shell profile 管理）。
+   * @returns {string}
+   */
+  getUserPath() {
+    if (!this.isWindows) return ''
+    try {
+      const result = this._spawnSync('reg', ['query', 'HKCU\\Environment', '/v', 'Path'])
+      if (result.status !== 0) return ''
+      const lines = result.stdout.split(/\r?\n/)
+      for (const line of lines) {
+        const m = line.match(/^\s*Path\s+REG_\w+\s+(.*)$/)
+        if (m) return m[1].trim()
+      }
+      return ''
+    } catch {
+      return ''
+    }
+  }
+
+  /**
+   * 写回持久化用户 PATH（Windows 注册表，保留 REG_EXPAND_SZ 类型）
+   *
+   * 不用 setx 的原因：setx 会把 REG_EXPAND_SZ 降级为 REG_SZ（%VAR% 字面量失去展开）
+   * 且值超过 1024 字符会被静默截断；reg add 可原样保留类型与完整值。
+   * @param {string} value - 完整 PATH 值（分号分隔）
+   * @returns {boolean} 是否写入成功
+   * @private
+   */
+  _setUserPath(value) {
+    try {
+      const result = this._spawnSync(
+        'reg', ['add', 'HKCU\\Environment', '/v', 'Path', '/t', 'REG_EXPAND_SZ', '/d', value, '/f']
+      )
+      return result.status === 0
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * 追加目录到持久化用户 PATH（Windows 注册表，保留 REG_EXPAND_SZ 类型）
+   * @param {string} dir - 要追加的目录绝对路径
+   * @returns {boolean} 是否写入成功
+   * @private
+   */
+  _appendUserPath(dir) {
+    const current = this.getUserPath()
+    const sep = current && !current.endsWith(';') ? ';' : ''
+    return this._setUserPath(current + sep + dir)
+  }
+
+  /**
+   * 确保目录已进入 Windows 持久化用户 PATH（幂等），并同步当前进程 PATH
+   *
+   * 解决场景：npm 全局安装（如 ww init 插件）装到 shell 会话专属前缀（如 nvm
+   * 的 bin/）时，该目录不在系统/用户 PATH，其他 shell 中命令不可用。此方法
+   * 把目录追加进 HKCU\Environment\Path（REG_EXPAND_SZ），重启终端后全局生效。
+   *
+   * Unix：不干预（PATH 由 nvm/profile 管理，npm 全局 bin 通常已在其中），返回 false。
+   *
+   * @param {string} dir - 目录绝对路径
+   * @returns {boolean} 是否新写入（已在则 false）
+   */
+  ensurePathEntry(dir) {
+    const needle = this._absPathKey(dir)
+    if (!needle || !this.isWindows) return false
+    if (this._pathListIncludes(this.getUserPath(), dir)) return false
+    const ok = this._appendUserPath(dir)
+    if (ok && !this._pathListIncludes(this.env.PATH, dir)) {
+      const sep = this.env.PATH && !this.env.PATH.endsWith(';') ? ';' : ''
+      this.env.PATH = (this.env.PATH || '') + sep + dir
+    }
+    return ok
+  }
+
+  /**
+   * 把目录前置到当前进程 PATH（process.env.PATH，幂等，不写注册表）
+   *
+   * 进程从旧 PATH 启动时不含注册表最新变更；需要让本进程后续的子进程立即用
+   * 新目录中的命令（如 mise shims 的 node）时调用。已在则移到最前（不重复）。
+   * @param {string|string[]} dirs - 目录（数组按序前置，最后一个在最前）
+   */
+  prependProcPath(dirs) {
+    const list = (Array.isArray(dirs) ? dirs : [dirs]).filter(Boolean)
+    if (!list.length) return
+    const sep = this.isWindows ? ';' : ':'
+    const key = (e) => this._absPathKey(e)
+    let entries = String(this.env.PATH || '').split(sep).filter(Boolean)
+    for (const d of list) {
+      const needle = key(d)
+      if (!needle) continue
+      entries = entries.filter((e) => key(e) !== needle)
+      entries.unshift(d)
+    }
+    this.env.PATH = entries.join(sep)
+  }
+
+  /**
+   * 确保目录已前置到 Windows 持久化用户 PATH 最前（幂等），并同步当前进程 PATH
+   *
+   * 用于需要**优先于系统 PATH** 的场景：如 mise shims 目录——系统 PATH 里可能已有
+   * 旧版 node（如 D:\library\nodejs），只有把 mise shims 前置才能让新 shell 优先用
+   * mise 管理的 node。若目录已在用户 PATH 任意位置，会移到最前（幂等更新）。
+   *
+   * Unix：不干预，返回 false。
+   *
+   * @param {string} dir - 目录绝对路径
+   * @returns {boolean} 是否新写入/更新（已在最前则 false）
+   */
+  prependPathEntry(dir) {
+    const needle = this._absPathKey(dir)
+    if (!needle || !this.isWindows) return false
+    const current = this.getUserPath()
+    const entries = String(current || '').split(';').map((e) => e.trim()).filter(Boolean)
+    const key = (e) => this._absPathKey(e)
+    const filtered = entries.filter((e) => key(e) !== needle)
+    const newValue = [dir, ...filtered].join(';')
+    if (newValue === current) return false
+    const ok = this._setUserPath(newValue)
+    if (ok) this.prependProcPath(dir)
+    return ok
+  }
+
+  /**
+   * 检测系统命令是否可用
+   * Windows: where <cmd>；Unix: which <cmd>
+   *
+   * @param {string} cmd - 命令名
+   * @returns {boolean}
+   */
+  isCommandAvailable(cmd) {
+    const checker = this.isWindows ? 'where' : 'which'
+    try {
+      const result = this._spawnSync(checker, [cmd])
+      return result.status === 0
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * 按优先级检测可用的网络探测工具
+   * 顺序: curl > wget > ping
+   *
+   * curl 优先：支持代理（-x）、输出 locale 无关（HTTP 状态码）、检查 HTTP 层可达性。
+   * ping 最后：ICMP 不支持代理、输出依赖系统语言（中文 Windows 乱码）、仅检查网络层。
+   *
+   * @returns {string|null} 'curl' | 'wget' | 'ping' | null
+   */
+  getNetProbeTool() {
+    for (const cmd of ['curl', 'wget', 'ping']) {
+      if (this.isCommandAvailable(cmd)) return cmd
+    }
+    return null
+  }
 }