@wwkit/shared 1.0.26 → 1.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwkit/shared",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "author": "bluesliu <langcai163@163.com>",
   "description": "Shared utilities for @wwkit packages — config loader, platform detection",
   "type": "module",
@@ -33,8 +33,10 @@
     "jest": "^29.7.0"
   },
   "scripts": {
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache tests/unit",
-    "test:all": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache tests/unit",
+    "ut": "node ../../scripts/run-tests.js unit",
+    "it": "node ../../scripts/run-tests.js integration",
+    "e2e": "node ../../scripts/run-tests.js e2e",
+    "test": "pnpm run ut",
     "release": "node bin/release-pkg.js"
   }
 }

package/src/release.js

@@ -2,48 +2,35 @@ import { execSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
-// ── helpers ──────────────────────────────────────────────────
-
-export function bumpPatch(version) {
-  const parts = version.split('.').map(Number)
-  parts[2]++
-  return parts.join('.')
-}
-
-function runQuiet(cmd, opts = {}) {
-  return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], ...opts }).trim()
-}
-
-function run(cmd, { dryRun = false, ...execOpts } = {}) {
-  if (dryRun) { console.log(`    $ ${cmd}`); return }
-  execSync(cmd, { stdio: 'inherit', ...execOpts })
-}
-
-export function readPackage(pkgDir) {
-  const pkgPath = resolve(pkgDir, 'package.json')
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
-  return { pkg, pkgPath, name: pkg.name, version: pkg.version }
+// ════════════════════════════ 核心 API ════════════════════════════
+
+// 发布过程错误。stage 标记失败阶段（validate|bump|publish|git）；
+// published=true 表示新版本已上 npm——此时调用方【不得】rollbackVersion，
+// 而应保留版本号并按 repair 命令手动补齐 git 记录（否则下次发布会撞 E403 重复版本）。
+export class ReleaseError extends Error {
+  constructor(message, { stage, published = false, version = null, repair = [] } = {}) {
+    super(message)
+    this.name = 'ReleaseError'
+    this.stage = stage
+    this.published = published
+    this.version = version
+    this.repair = repair
+  }
 }
 
-// ── preflight ────────────────────────────────────────────────
-
-// 解析实际发布用的 registry：优先 package.json 的 publishConfig.registry，
-// 否则用该目录下 npm 配置的 registry。.npmrc 可能指向镜像，但发布走 publishConfig。
-function resolvePublishRegistry(pkgDir) {
-  try {
-    const { pkg } = readPackage(pkgDir)
-    if (pkg.publishConfig?.registry) return pkg.publishConfig.registry
-  } catch {}
-  try {
-    return runQuiet('npm config get registry', { cwd: pkgDir })
-  } catch {
-    return null
+// patch bump，仅支持稳定版 x.y.z；预发布/异常格式直接抛错（fail-fast）。
+export function bumpPatch(version) {
+  if (!/^\d+\.\d+\.\d+$/.test(String(version))) {
+    throw new Error(`版本号格式不支持自动 bump（需 x.y.z）: ${version}`)
   }
+  const [major, minor, patch] = version.split('.').map(Number)
+  return `${major}.${minor}.${patch + 1}`
 }
 
 // 发布前检查: git 工作区干净（不干净仅告警）+ npm 已登录（未登录抛出 Error）。
-// pkgDir 给定时，针对该包 publishConfig.registry 检查登录（而非 .npmrc 里可能指向镜像的 registry）。
-export function preflight({ dryRun = false, pkgDir = null } = {}) {
+// pkgDirs 给定时，按各包 publishConfig.registry【去重】逐一检查登录——
+// 发布实际走 publishConfig（如 npmjs.org），而非 .npmrc 里可能指向镜像的默认 registry。
+export function preflight({ pkgDirs = [] } = {}) {
   const gitStatus = runQuiet('git status --porcelain')
   if (gitStatus) {
     console.warn('⚠ Git 工作区不干净（仅告警，继续发布）')
@@ -51,62 +38,112 @@ export function preflight({ dryRun = false, pkgDir = null } = {}) {
   } else {
     console.log('  ✓ Git 工作区干净')
   }
-  const registry = pkgDir ? resolvePublishRegistry(pkgDir) : null
-  const whoamiCmd = registry ? `npm whoami --registry=${registry}` : 'npm whoami'
-  try {
-    const who = runQuiet(whoamiCmd)
-    console.log(`  ✓ npm 已登录: ${who}${registry ? ` (${registry})` : ''}`)
-  } catch {
-    console.error('✗ 未登录 npm，请先执行 npm login')
-    if (registry) console.error(`  (检查的 registry: ${registry})`)
-    throw new Error('npm-not-logged-in')
+  const registries = [...new Set(pkgDirs.map(resolvePublishRegistry).filter(Boolean))]
+  const targets = registries.length > 0 ? registries : [null]
+  for (const registry of targets) {
+    const whoamiCmd = registry ? `npm whoami --registry=${registry}` : 'npm whoami'
+    try {
+      const who = runQuiet(whoamiCmd)
+      console.log(`  ✓ npm 已登录: ${who}${registry ? ` (${registry})` : ''}`)
+    } catch {
+      console.error('✗ 未登录 npm，请先执行 npm login')
+      if (registry) console.error(`  (检查的 registry: ${registry})`)
+      throw new Error('npm-not-logged-in')
+    }
   }
 }
 
-// ── single-package release ───────────────────────────────────
+// 发布门禁: 依次在各包目录跑其标准入口 `pnpm run ut`，任一失败返回 false（调用方须中止发布）。
+// dryRun 只打印计划命令，不执行。
+export function runUnitTests(pkgDirs, { dryRun = false } = {}) {
+  console.log('\n━━━ 单元测试（发布门禁） ━━━')
+  for (const pkgDir of pkgDirs) {
+    const { name } = readPackage(pkgDir)
+    if (dryRun) {
+      console.log(`    $ pnpm run ut   # ${name}`)
+      continue
+    }
+    console.log(`▶ ${name}: pnpm run ut`)
+    try {
+      execSync('pnpm run ut', { cwd: pkgDir, stdio: 'inherit' })
+    } catch {
+      console.error(`\n✗ ${name} 单元测试未通过，发布已阻止（修复测试后重试）`)
+      return false
+    }
+  }
+  if (!dryRun) console.log('  ✓ 全部包单元测试通过')
+  return true
+}
 
 // 单包发布: bump patch → publish → commit + scoped tag（不推送）。
-// 成功返回 { name, oldVersion, version, tag }；失败抛出（调用方可 rollbackVersion）。
+// 成功返回 { name, oldVersion, version, tag }；失败抛出 ReleaseError（含阶段与 published 标记）。
 export function releasePackage({ pkgDir, dryRun = false } = {}) {
   const { pkgPath, name, version: oldVer } = readPackage(pkgDir)
-  const newVer = bumpPatch(oldVer)
-  if (!name || !oldVer) throw new Error(`无法从 ${pkgPath} 读取 name/version`)
+  if (!name) throw new ReleaseError(`无法从 ${pkgPath} 读取 name`, { stage: 'validate' })
+  let newVer
+  try {
+    newVer = bumpPatch(oldVer)
+  } catch (e) {
+    throw new ReleaseError(e.message, { stage: 'validate' })
+  }
 
   console.log(`━━━ 发布 ${name}@${newVer}（原 ${oldVer}）━━━`)
 
   // 1. bump version (no git tag — scoped tag created manually below)
-  run('pnpm version patch --no-git-tag-version --no-git-checks', { cwd: pkgDir, dryRun })
+  try {
+    run('pnpm version patch --no-git-tag-version --no-git-checks', { cwd: pkgDir, dryRun })
+  } catch {
+    throw new ReleaseError(`${name} 版本号 bump 失败`, { stage: 'bump' })
+  }
+  // 以 bump 后 package.json 的【实际版本】为准（dry-run 未实际 bump，用预测值）
+  const actualVer = dryRun ? newVer : readPackage(pkgDir).version
+  const tag = `${name}@${actualVer}`
 
   // 2. publish (prepublishOnly hook runs tests automatically)
-  run('pnpm publish --no-git-checks', { cwd: pkgDir, dryRun })
+  try {
+    run('pnpm publish --no-git-checks', { cwd: pkgDir, dryRun })
+  } catch {
+    throw new ReleaseError(`${name}@${actualVer} 发布失败`, { stage: 'publish', version: actualVer })
+  }
 
-  // 3. commit + scoped tag
-  if (!dryRun) {
-    execSync(`git add "${pkgPath}"`, { stdio: 'inherit' })
-    execSync(`git commit -m "release ${name}@${newVer}"`, { stdio: 'inherit' })
-    execSync(`git tag ${name}@${newVer}`, { stdio: 'inherit' })
-  } else {
-    console.log(`    $ git add + commit "release ${name}@${newVer}" + tag ${name}@${newVer}`)
+  // 3. commit + scoped tag —— 自此版本已在 npm 上，失败时不得再回滚版本号。
+  //    --only 仅提交该 package.json，避免把用户预先 staged 的无关改动裹进 release commit。
+  const repair = [
+    `git commit --only -m "release ${tag}" -- "${pkgPath}"`,
+    `git tag ${tag}`,
+  ]
+  try {
+    if (!dryRun) {
+      execSync(`git commit --only -m "release ${tag}" -- "${pkgPath}"`, { stdio: 'inherit' })
+      execSync(`git tag ${tag}`, { stdio: 'inherit' })
+    } else {
+      console.log(`    $ ${repair.join(' && ')}`)
+    }
+  } catch {
+    throw new ReleaseError(`${name}@${actualVer} 已发布但 git 记录失败`, {
+      stage: 'git', published: true, version: actualVer, repair,
+    })
   }
 
-  return { name, oldVersion: oldVer, version: newVer, tag: `${name}@${newVer}` }
+  return { name, oldVersion: oldVer, version: actualVer, tag }
 }
 
-// 回滚 package.json 版本号
+// 回滚 package.json 版本号。仅适用于【未发布】的失败包；
+// 已发布（ReleaseError.published）的包调用本函数会造成 npm 与仓库版本撕裂。
 export function rollbackVersion(pkgDir, { dryRun = false } = {}) {
   if (dryRun) return
   try {
     execSync('git checkout -- package.json', { cwd: pkgDir, stdio: 'pipe' })
     console.log('  已回滚版本号')
   } catch {
-    // version already committed? unlikely in this flow
+    console.warn('  ⚠ 版本号回滚失败，请手动检查该包 package.json')
   }
 }
 
-// ── push ─────────────────────────────────────────────────────
-
-// 推送到远端同名分支 + 指定 tag(s)。返回 true 成功，false 跳过（需手动推）。
-export function pushToRemote(tags, { dryRun = false } = {}) {
+// 推送到远端同名分支 + 指定 tag(s)，并追加同步到 alsoBranches（如 develop，HEAD:<branch>）。
+// 返回 true 成功/已打印计划，false 失败或跳过（需手动推）。
+// 推送异常被捕获并打印手动命令，不向上抛裸栈。
+export function pushToRemote(tags, { dryRun = false, alsoBranches = [] } = {}) {
   console.log('\n━━━ 推送到远端 ━━━')
 
   let remote
@@ -129,10 +166,50 @@ export function pushToRemote(tags, { dryRun = false } = {}) {
     return false
   }
 
-  run(`git push ${remote} ${branch}`, { dryRun })
-  if (tags.length > 0) {
-    run(`git push ${remote} ${tags.join(' ')}`, { dryRun })
+  const cmds = [`git push ${remote} ${branch}`]
+  if (tags.length > 0) cmds.push(`git push ${remote} ${tags.join(' ')}`)
+  // 额外分支同步（如 develop）：推当前 HEAD 到远端目标分支，跳过与当前分支同名的
+  for (const b of alsoBranches) {
+    if (b && b !== branch) cmds.push(`git push ${remote} HEAD:${b}`)
+  }
+  try {
+    for (const cmd of cmds) run(cmd, { dryRun })
+  } catch {
+    console.error('  ✗ 推送失败，请手动执行:')
+    for (const cmd of cmds) console.error(`    ${cmd}`)
+    return false
   }
   if (!dryRun) console.log('  ✓ 推送完成')
   return true
-}
+}
+
+// ════════════════════════════ 辅助方法 ════════════════════════════
+
+export function readPackage(pkgDir) {
+  const pkgPath = resolve(pkgDir, 'package.json')
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+  return { pkg, pkgPath, name: pkg.name, version: pkg.version }
+}
+
+function runQuiet(cmd, opts = {}) {
+  return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], ...opts }).trim()
+}
+
+function run(cmd, { dryRun = false, ...execOpts } = {}) {
+  if (dryRun) { console.log(`    $ ${cmd}`); return }
+  execSync(cmd, { stdio: 'inherit', ...execOpts })
+}
+
+// 解析实际发布用的 registry：优先 package.json 的 publishConfig.registry，
+// 否则用该目录下 npm 配置的 registry。.npmrc 可能指向镜像，但发布走 publishConfig。
+function resolvePublishRegistry(pkgDir) {
+  try {
+    const { pkg } = readPackage(pkgDir)
+    if (pkg.publishConfig?.registry) return pkg.publishConfig.registry
+  } catch {}
+  try {
+    return runQuiet('npm config get registry', { cwd: pkgDir })
+  } catch {
+    return null
+  }
+}

package/src/shell.js

@@ -48,7 +48,9 @@ export class Shell {
    * 解析可用的 bash 路径
    *
    * Unix: 优先 /bin/bash（原行为），回退 /usr/bin/bash，再回退 PATH 中的 bash
-   * Windows: 在 PATH 中查找 bash（Git Bash / WSL 提供）；找不到则抛错
+   * Windows: 优先 Git Bash（常见安装路径 + 由 `where git` 推导 Git 根），
+   *          再回退 PATH 中的 bash（排除 WSL 转发器 System32\bash.exe / WindowsApps\bash.exe）；
+   *          找不到则抛错
    *
    * @returns {string} bash 可执行文件路径
    * @throws {Error} 找不到 bash 时抛出（含平台相关提示）
@@ -63,10 +65,26 @@ export class Shell {
       }
     }
 
+    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) return out.split(/\r?\n/)[0]
+      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(
@@ -75,6 +93,43 @@ export class Shell {
     )
   }
 
+  /**
+   * 在 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 选项
    *
@@ -189,6 +244,17 @@ export class Shell {
     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'] })
+  }
+
   /**
    * 持久化设置系统环境变量（跨平台）
    *
@@ -204,10 +270,7 @@ export class Shell {
   setEnvVar(name, value) {
     if (this.isWindows) {
       try {
-        const result = spawnSync('setx', [name, String(value)], {
-          encoding: 'utf8',
-          stdio: ['pipe', 'pipe', 'pipe'],
-        })
+        const result = this._spawnSync('setx', [name, String(value)])
         return result.status === 0
       } catch {
         return false
@@ -302,6 +365,176 @@ const marker = `# >>> wwkit ${name} >>>`
     }).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>
@@ -312,7 +545,7 @@ const marker = `# >>> wwkit ${name} >>>`
   isCommandAvailable(cmd) {
     const checker = this.isWindows ? 'where' : 'which'
     try {
-      const result = spawnSync(checker, [cmd], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
+      const result = this._spawnSync(checker, [cmd])
       return result.status === 0
     } catch {
       return false