@noob-stupid/dsh-plugin-console 0.5.101 → 0.5.103

package/lib/server/domain/selfupdate-copy.js

@@ -0,0 +1,393 @@
+// L1 · domain —— selfupdate-copy.js（自更新的**手铺兜底**：先备好 tarball → 只覆盖文件、不清空目录 → 补 lock）
+//
+// ── 现场（真机 2026-11-04 实测采样，用户提供的原始时间线）─────────────────────────────────
+//   0.5.102 的自更新是「包管理器优先」：`pnpm update` → `pnpm add` → 才轮到手铺（见 domain/selfupdate.js 顶部）。
+//   pnpm 一启动就**先清空目标目录**再重算整棵依赖树；这一步在 profile 里要跑几分钟
+//   （`14:45:46 pkg=True files=160` → `14:45:56 pkg=False files=1`），于是：
+//     · 撞 90s/180s 超时被杀 → 目录停在"空了"的状态，跑了一整夜都没轮到第三步；
+//     · 就算第三步轮到了，既有 curl 通道也是"先 rmSync 整目录再 copyTree"（见 install.js#curlManualInstall），
+//       宿主正读着这些文件时更容易被 Windows 拒绝。
+//   ⇒ 用户要的：pnpm 卡住/失败时**立刻**手铺、并把 lock 一起补上（否则又会"更新成功、下次 pnpm 操作被还原"）。
+//
+// ── 本模块只做三件事（都不改既有通道的触发条件）──────────────────────────────────
+//   ① prepareSelfUpdateTarball：走 pnpm **之前**先用既有 curl/元数据链路把目标版本 tarball 备到手
+//      （失败**不影响**后续，只把原因记下来 —— 后面照样跑 pnpm 与既有 curl 通道）；
+//   ② overlaySelfUpdateTarball：用备好的 tarball **只覆盖文件、绝不清空目录**（copyTree 的语义，
+//      见 infra/fsx.js —— 它只 copyFileSync，不删任何东西），随后**读回** package.json 的版本与期望值比对；
+//   ③ patchSelfUpdateLock：把 `pnpm-lock.yaml` 里该包的版本/完整性更新到目标版本（**唯一**写入口仍是
+//      domain/lock-importer.js#writeLockRegistryVersion，本模块不另写一套 lock 解析），
+//      再用既有 `verifyLockReadOnly`（pnpm 只读用法）复核；复核明确不通过 ⇒ **把 lock 还原成改动前的字节**
+//      并如实上报（宁可报"没补上"，也绝不留下 pnpm 会拒绝的 lock）。
+//
+// ── 与既有实现的关系（复用，不另造一套）──────────────────────────────────────────
+//   · 盒子校验 `verifyPackageBox`（install-box.js）、覆盖复制 `copyTree`（fsx.js）、
+//     lock 写入/只读校验（lock-importer.js）、失败兜底与自愈（self-update-guard.js）全部是既有件；
+//   · 本模块**不判断"更新成功与否"**：那由 selfupdate.js 的回读核实 + 自更新守卫说了算。
+//
+// ── 边界（别越线）──────────────────────────────────────────────────────────────
+//   ① 只对**自更新**生效：由 selfupdate.js 在 `/self-update` 那条路里调用；装别的插件的通道一个字节都不经过这里。
+//   ② 拿不到 tarball / 没有该版本的完整性摘要 ⇒ 什么都不做（返回 reason），调用方回落到 0.5.102 的既有行为。
+//   ③ 覆盖失败（EPERM/EBUSY 等）⇒ 如实返回 reason，**不重试、不删目录、不谎报**。
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { verifyLockReadOnly, writeLockRegistryVersion } from './lock-importer.js'
+import { verifyPackageBox } from './install-box.js'
+import { execFileAsync } from '../infra/exec.js'
+import { copyTree, removeDirVerified } from '../infra/fsx.js'
+import { fetchJsonUrl } from '../infra/http.js'
+
+/** registry 元数据的超时（与既有 curl 通道同量级；拿不到就是拿不到，不许拖住自更新）。 */
+const META_TIMEOUT_MS = 15000
+/** tarball 下载超时（既有 curl 通道是 70s；这里 60s 封顶）。 */
+const DOWNLOAD_TIMEOUT_MS = 60000
+/** 解包超时（既有 curl 通道 30s）。 */
+const EXTRACT_TIMEOUT_MS = 30000
+/** 补完 lock 之后那次 pnpm **只读**校验的超时。刻意比 lock-importer 的 60s 短：
+ *  自更新这条路上 pnpm 本来就是"可能很慢"的那一环，不能为了复核再让用户多等一分钟；
+ *  超时按"**无法确认**"处理（verified=null），**不**回滚 —— 只有 pnpm 真的报错才回滚。 */
+const LOCK_VERIFY_TIMEOUT_MS = 20000
+/** 工作目录前缀（临时目录，跑完即删；名字里带随机段避免并发互撞）。 */
+const WORK_PREFIX = 'dsh-selfupdate-'
+
+/** registry 包名 → URL 段（与 install.js#curlManualInstall **同一口径**：scope 的 `/` 编成 `%2f`）。 */
+function encodePackageName(packageName) {
+  const name = String(packageName ?? '')
+  if (!name.startsWith('@')) return encodeURIComponent(name)
+  return `@${encodeURIComponent(name.slice(1).split('/')[0])}%2f${encodeURIComponent(name.split('/').slice(1).join('/'))}`
+}
+
+/** curl 可执行名（与既有通道一致：Windows 上是 curl.exe —— 有些环境里 PATH 上只有它）。 */
+function curlBin() {
+  return process.platform === 'win32' ? 'curl.exe' : 'curl'
+}
+
+/** 离线/测试模式：CI 里 `DSH_TEST_SKIP_NETWORK=1`（见 .github/workflows/test.yml），照着跳过网络。 */
+function networkBlocked(deps = {}) {
+  const env = typeof deps.env === 'object' && deps.env !== null ? deps.env : process.env
+  return String(env?.DSH_TEST_SKIP_NETWORK ?? '') === '1'
+}
+
+/** 建一个本次自更新专用的临时工作目录。 */
+function makeWorkDir(deps = {}) {
+  const base = typeof deps.tmpDir === 'function' ? deps.tmpDir() : tmpdir()
+  const dir = join(base, `${WORK_PREFIX}${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+/** 删掉一个工作目录并**核实**（infra/fsx.js#removeDirVerified：本机实测 `%TEMP%` 下 rmSync 会
+ *  **静默落空** —— 不抛错、目录仍在；临时目录里装着下载下来的 tarball，不能"以为删了"就算了）。
+ *  返回 `{ removed, note }`；没删掉时 note 里带绝对路径（用户可自己清）。 */
+function cleanWorkDir(dir) {
+  const target = typeof dir === 'string' ? dir : ''
+  if (target === '') return { removed: false, note: null }
+  const verdict = removeDirVerified(target)
+  if (verdict.ok === true) return { removed: true, note: null }
+  return { removed: false, note: `临时目录没删掉（${target}）：${verdict.error ?? '原因未知'}（可自行删除）` }
+}
+
+/** `curl -sL -m <秒> -o <tgz> <url>`（与 install.js#curlManualInstall 同一形态）。 */
+async function downloadToFile(url, tgz, { timeout = DOWNLOAD_TIMEOUT_MS, deps = {} } = {}) {
+  const run = typeof deps.exec === 'function' ? deps.exec : execFileAsync
+  await run(curlBin(), ['-s', '-L', '-m', String(Math.max(5, Math.ceil(timeout / 1000))), '-o', tgz, url], { timeout: timeout + 10000, windowsHide: true })
+}
+
+/** `tar -xzf <tgz> -C <dir>`（与既有通道同一形态）。 */
+async function extractTarball(tgz, dir, { deps = {} } = {}) {
+  const run = typeof deps.exec === 'function' ? deps.exec : execFileAsync
+  await run('tar', ['-xzf', tgz, '-C', dir], { timeout: EXTRACT_TIMEOUT_MS, windowsHide: true })
+}
+
+/** 解压目录里含 package.json 的那一层（npm tarball 恒为 `package/`，但别假设）。 */
+function findPackageDir(dir) {
+  const direct = join(dir, 'package')
+  if (existsSync(join(direct, 'package.json'))) return direct
+  let entries = []
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return null
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const candidate = join(dir, entry.name)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+  }
+  return null
+}
+
+/** 目录里的文件相对路径集合（用于如实报"铺了几个文件、原地保留了几个"）。只读、失败返回空集。 */
+function filesUnder(dir) {
+  const out = new Set()
+  const walk = (current, prefix) => {
+    let entries = []
+    try {
+      entries = readdirSync(current, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`
+      if (entry.isDirectory()) walk(join(current, entry.name), rel)
+      else if (entry.isFile()) out.add(rel)
+    }
+  }
+  if (existsSync(dir)) walk(dir, '')
+  return out
+}
+
+/**
+ * ① 预先备好目标版本的 tarball（**pnpm 之前**跑；失败只记原因，不阻断后续）。
+ * 走的是既有链路：registry 元数据（`fetchJsonUrl`，可注入）→ `meta.versions[版本].dist.tarball` → curl 下载。
+ * 返回 `{ ok, version, tgzPath, workDir, integrity, tarball, registry, reason, ms }`。
+ * `integrity` 来自元数据 `dist.integrity`（pnpm 自己写进 lock 的就是这个值）——
+ * 拿不到就为 null，调用方据此**不**改 lock 的 packages 段（绝不用旧版本的摘要顶替）。
+ */
+async function prepareSelfUpdateTarball({ packageName, version, registries = [], deps = {} } = {}) {
+  const startedAt = Date.now()
+  const out = { ok: false, version: typeof version === 'string' ? version : null, tgzPath: null, workDir: null, integrity: null, tarball: null, registry: null, reason: null, ms: 0 }
+  const label = (error) => (error instanceof Error ? error.message : String(error))
+  const fetchJson = typeof deps.fetchJson === 'function' ? deps.fetchJson : fetchJsonUrl
+  if (typeof version !== 'string' || version.trim() === '') {
+    out.reason = '没有目标版本，未预先下载 tarball'
+    return out
+  }
+  if (networkBlocked(deps)) {
+    out.reason = '已跳过网络（DSH_TEST_SKIP_NETWORK=1）—— 未预先下载 tarball'
+    return out
+  }
+  const regs = Array.isArray(registries) ? registries.filter((r) => typeof r === 'string' && r !== '') : []
+  if (regs.length === 0) {
+    out.reason = '没有可用的软件源，未预先下载 tarball'
+    return out
+  }
+  let dist = null
+  const metaErrors = []
+  for (const registry of regs) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const meta = await fetchJson(`${registry}/${encodePackageName(packageName)}`, META_TIMEOUT_MS)
+      const record = meta?.versions?.[version]
+      if (record === undefined || record === null) {
+        metaErrors.push(`${registry}：元数据里没有 ${version} 这个版本`)
+        continue
+      }
+      const tarball = typeof record.dist?.tarball === 'string' ? record.dist.tarball : null
+      if (tarball === null) {
+        metaErrors.push(`${registry}：${version} 没有 dist.tarball`)
+        continue
+      }
+      dist = { registry, tarball, integrity: typeof record.dist?.integrity === 'string' && record.dist.integrity !== '' ? record.dist.integrity : null }
+      break
+    } catch (error) {
+      metaErrors.push(`${registry}：${label(error)}`)
+    }
+  }
+  if (dist === null) {
+    out.reason = `拿不到 ${version} 的 registry 元数据（${metaErrors.join('；') || '原因未知'}）`
+    out.ms = Date.now() - startedAt
+    return out
+  }
+  let workDir = null
+  try {
+    workDir = makeWorkDir(deps)
+    const tgzPath = join(workDir, 'pkg.tgz')
+    const download = typeof deps.download === 'function' ? deps.download : downloadToFile
+    await download(dist.tarball, tgzPath, { timeout: deps.downloadTimeoutMs ?? DOWNLOAD_TIMEOUT_MS, deps })
+    const size = existsSync(tgzPath) ? statSync(tgzPath).size : 0
+    if (size <= 0) throw new Error(`下载下来的 tarball 是空文件（${tgzPath}）`)
+    out.ok = true
+    out.version = version
+    out.tgzPath = tgzPath
+    out.workDir = workDir
+    out.integrity = dist.integrity
+    out.tarball = dist.tarball
+    out.registry = dist.registry
+    return out
+  } catch (error) {
+    out.reason = `下载 ${version} 的 tarball 失败：${label(error)}`
+    if (workDir !== null) {
+      cleanWorkDir(workDir)
+    }
+    return out
+  } finally {
+    out.ms = Date.now() - startedAt
+  }
+}
+
+/**
+ * ② 用备好的 tarball **只覆盖文件、不清空目录**地铺进 `node_modules/<包名>`，随后**读回**版本核实。
+ * 与既有 curl 通道的区别只有一条、但正是这条要命：**不先 rmSync 整目录**
+ * （宿主正读着这些文件时，删目录比覆盖文件更容易被 Windows 拒绝；而且删完再失败就只剩空目录）。
+ * 返回 `{ ok, version, files, preserved, boxNote, reason }`：`preserved` = 目录里原有的、**不在 tarball 里**的文件数
+ * （copyTree 一个都不删，这个数是给"没清空目录"作证的）。
+ */
+async function overlaySelfUpdateTarball({ prepared = null, profileDir, packageName, expectedVersion = null, deps = {} } = {}) {
+  const out = { ok: false, version: null, files: 0, preserved: 0, boxNote: null, reason: null }
+  const label = (error) => (error instanceof Error ? error.message : String(error))
+  if (prepared === null || prepared === undefined || prepared.ok !== true || typeof prepared.tgzPath !== 'string') {
+    out.reason = `没有可用的预下载 tarball${prepared?.reason ? `（${prepared.reason}）` : ''}`
+    return out
+  }
+  const target = join(String(profileDir), 'node_modules', ...String(packageName).split('/'))
+  let extractDir = null
+  try {
+    extractDir = makeWorkDir(deps)
+    const extract = typeof deps.extract === 'function' ? deps.extract : extractTarball
+    await extract(prepared.tgzPath, extractDir, { deps })
+    const pkgDir = findPackageDir(extractDir)
+    if (pkgDir === null) throw new Error('解包后未找到含 package.json 的目录')
+    // 盒子校验（既有件）：包名不符 / 入口文件缺失 / bundle 引用缺失 —— 覆盖旧版本**之前**拦住
+    const box = verifyPackageBox(pkgDir, profileDir, packageName)
+    out.boxNote = box?.note ?? null
+    const tarballFiles = filesUnder(pkgDir)
+    const existing = filesUnder(target)
+    let preserved = 0
+    for (const rel of existing) if (!tarballFiles.has(rel)) preserved += 1
+    // ★ 只覆盖：copyTree 只 copyFileSync（不删任何东西），目录缺就建目录 —— 见 infra/fsx.js
+    copyTree(pkgDir, target)
+    try {
+      writeFileSync(join(target, '.dsh-installed-at'), String(Date.now()), 'utf8')
+    } catch {}
+    const installed = readVersionOf(target)
+    out.version = installed
+    out.files = tarballFiles.size
+    out.preserved = preserved
+    const want = typeof expectedVersion === 'string' && expectedVersion !== '' ? expectedVersion : null
+    if (want !== null && installed !== want) {
+      out.reason = `铺完之后读回的版本是 ${installed ?? '（读不出来）'}，不是目标版本 ${want}`
+      return out
+    }
+    out.ok = true
+    return out
+  } catch (error) {
+    out.reason = `覆盖文件失败：${label(error)}`
+    return out
+  } finally {
+    if (extractDir !== null) {
+      cleanWorkDir(extractDir)
+    }
+  }
+}
+
+/** 读一份包目录里清单的版本（读不到返回 null）。 */
+function readVersionOf(dir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(String(dir), 'package.json'), 'utf8'))
+    return typeof pkg?.version === 'string' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+/** 该包在清单里属于哪个依赖分区 —— **不在这里再写一份**：由调用方（selfupdate.js#manifestSectionOf，
+ *  复用 lockfile-health.js 的既有解析器）传进来，两处各写一份必然分叉。 */
+
+/**
+ * ③ 手铺成功之后**必须**把 lock 补到目标版本（不补就重演"下次 pnpm 操作把版本还原"的老毛病）。
+ * 写入走 domain/lock-importer.js#writeLockRegistryVersion（唯一写入口，内部再复用 importer 规划器）；
+ * 复核走既有 `verifyLockReadOnly`（`pnpm install --lockfile-only --dry-run --frozen-lockfile`）。
+ * 复核**明确不通过**（verified === false）⇒ 把 lock 还原成改动前的字节，并按未补上如实上报：
+ * 宁可回到"会被还原"的老状态 + 一条可复制的命令，也绝不留下 pnpm 会拒绝的 lock。
+ * 返回 `{ attempted, changed, unchanged, version, integrityWritten, renamed, verified, verifyNote, rolledBack, reason, note }`。
+ */
+async function patchSelfUpdateLock({ profileDir, packageName, targetVersion, spec = null, integrity = null, section = 'dependencies', deps = {} } = {}) {
+  const out = { attempted: false, changed: false, unchanged: false, version: null, integrityWritten: false, renamed: { packages: false, snapshots: false }, verified: null, verifyNote: null, rolledBack: false, reason: null, note: null }
+  const label = (error) => (error instanceof Error ? error.message : String(error))
+  const specText = typeof spec === 'string' ? spec.trim() : ''
+  const rangeLike = specText === '' || /^[\^~]?\d/u.test(specText) || /^(>=|>|=)\s*\d/u.test(specText)
+  if (rangeLike !== true) {
+    // 来源型 spec（git/file/link/URL）：既有约定是**原样保留**清单声明，lock 的 importer 条目也因此不改
+    // （改成版本号就会与清单对不上，pnpm 下一次操作会把链接/来源丢掉）。
+    out.reason = `清单 spec 是来源型（${specText}）—— 按既有约定保留来源，importer 条目不改写，lock 未补`
+    return out
+  }
+  const lockFile = join(String(profileDir), 'pnpm-lock.yaml')
+  let before = null
+  try {
+    before = readFileSync(lockFile, 'utf8')
+  } catch (error) {
+    out.reason = `读不到 pnpm-lock.yaml（${label(error)}）—— lock 未补`
+    return out
+  }
+  out.attempted = true
+  const write = typeof deps.writeLock === 'function' ? deps.writeLock : writeLockRegistryVersion
+  let written = null
+  try {
+    written = await write(String(profileDir), {
+      name: packageName,
+      // 清单会被收尾段同步成裸版本号（见 self-update-guard.js#finishSelfUpdate），lock 的 specifier 跟它一致
+      spec: targetVersion,
+      version: targetVersion,
+      integrity,
+      section,
+      deps: deps.writeDeps ?? {},
+    })
+  } catch (error) {
+    out.reason = `写 lock 失败：${label(error)}`
+    return out
+  }
+  out.changed = written?.changed === true
+  out.unchanged = written?.unchanged === true
+  out.version = written?.version ?? null
+  out.integrityWritten = written?.integrityWritten === true
+  out.renamed = written?.renamed ?? out.renamed
+  // 写入器"改成了、但有话要说"（例如没有该版本的完整性摘要 ⇒ packages/snapshots 段按规则不动）：
+  // 这句是**说明**不是失败，放 note 里如实下发（reason 只留给真正的失败）。
+  out.note = typeof written?.reason === 'string' && written.reason !== '' ? written.reason : null
+  if (out.changed !== true && out.unchanged !== true) {
+    out.reason = written?.reason ?? 'lock 未写入（原因未给出）'
+    return out
+  }
+  const verify = typeof deps.verifyLock === 'function' ? deps.verifyLock : verifyLockReadOnly
+  try {
+    const verdict = await verify({ profileDir, registry: deps.registry ?? null, execOpts: { timeout: LOCK_VERIFY_TIMEOUT_MS }, ...(deps.verifyArgs ?? {}) })
+    out.verified = verdict?.verified ?? null
+    out.verifyNote = verdict?.reason ?? null
+  } catch (error) {
+    out.verified = null
+    out.verifyNote = `只读校验执行失败：${label(error)}`
+  }
+  // 只读校验**没跑完**（超时/被杀/执行方式不可用）不算"明确不通过" ⇒ 按无法确认处理，不回滚：
+  // 这类失败说明的是"这台机器上 pnpm 跑不动"，而不是"写进去的 lock 有问题"。
+  if (out.verified === false && /超时|timed out|timeout|已终止整棵进程树|killed|ENOENT|Cannot find module|不可用/iu.test(String(out.verifyNote ?? ''))) {
+    out.verified = null
+    out.verifyNote = `pnpm 只读校验没跑完（按无法确认处理，未回滚）：${out.verifyNote ?? '原因未知'}`
+  }
+  if (out.verified === false) {
+    // 明确不通过：还原成改动前的字节（宁可报没补上，也绝不留下 pnpm 会拒绝的 lock）
+    try {
+      writeFileSync(lockFile, before, 'utf8')
+      out.rolledBack = true
+      out.changed = false
+      out.reason = `pnpm 的只读校验未通过（${out.verifyNote ?? '原因未知'}）—— 已把 pnpm-lock.yaml 还原成改动前的内容，按未补上处理`
+    } catch (error) {
+      out.reason = `pnpm 的只读校验未通过（${out.verifyNote ?? '原因未知'}），且还原 pnpm-lock.yaml 失败：${label(error)}`
+    }
+  }
+  return out
+}
+
+/** 收尾：删掉本次临时工作目录（不抛、不阻塞、绝不影响返回结构）。 */
+function disposeSelfUpdateTarball(prepared) {
+  return cleanWorkDir(typeof prepared?.workDir === 'string' ? prepared.workDir : '')
+}
+
+export {
+  DOWNLOAD_TIMEOUT_MS,
+  EXTRACT_TIMEOUT_MS,
+  LOCK_VERIFY_TIMEOUT_MS,
+  META_TIMEOUT_MS,
+  WORK_PREFIX,
+  disposeSelfUpdateTarball,
+  downloadToFile,
+  encodePackageName,
+  extractTarball,
+  filesUnder,
+  findPackageDir,
+  overlaySelfUpdateTarball,
+  patchSelfUpdateLock,
+  prepareSelfUpdateTarball,
+  readVersionOf,
+}

package/lib/server/domain/selfupdate-read.js

@@ -0,0 +1,95 @@
+// L1 · domain —— selfupdate-read.js（自更新/对账共用的**只读**读数：spec 判定、已装版本、lock 里被钉住的版本）
+//
+// 为什么单独一个模块（2026-11-04 加法）：domain/selfupdate.js 贴着 600 行架构棘轮
+// （tests/test-architecture-guard.mjs），而本轮要给"pnpm 卡住/失败后立刻手铺 + 补 lock"腾出空间。
+// 这几个函数本来就是自洽的一族"只读、纯函数式、不认识 cordis"的读数，搬出来只换绑定来源：
+//   · 名字与语义**一个字节都没改**；selfupdate.js 继续 import 它们并**原样 re-export**
+//     （外部 persist.js / plugin-actions.js / unpin-dev-dir.js / install-version.js 与 6 个测试套件
+//      都还从 selfupdate.js 取这几个名字，导出面一个字不能少）；
+//   · 真值只有一份：lock 的键判据仍然只来自 lock-importer.js#lockEntryKeyMatches
+//     （见下面 lockVersion 的长注释 —— 两处各写一份必然再次分叉，0.5.38 就是那个现场）。
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { lockEntryKeyMatches } from './lock-importer.js'
+
+/** spec 是否是 registry 版本范围（`^1.2.3` / `~1.2.3` / `1.2.3` / `>=1` / `=1`）。
+ * 只有这种才能用 `pnpm update` 在**不改写 spec**的前提下把 lock 提到范围内最新；
+ * git / file / link / workspace 来源没有"范围"可言，只能走 `pnpm add <pkg>@<版本>`。 */
+function isRegistryRange(spec) {
+  if (typeof spec !== 'string') return false
+  const s = spec.trim()
+  if (/^[\^~]?\d/u.test(s)) return true
+  return /^(>=|>|=)\s*\d/u.test(s)
+}
+
+/** profile 里该包的依赖声明（spec）。读不到返回 null。 */
+function profileSpec(profileDir, name) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'))
+    const spec = pkg?.dependencies?.[name]
+    return typeof spec === 'string' ? spec : null
+  } catch {
+    return null
+  }
+}
+
+/** 已安装版本（直接读 node_modules 里那份 package.json）。 */
+function readInstalledVersion(profileDir, name) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(profileDir, 'node_modules', ...name.split('/'), 'package.json'), 'utf8'))
+    return typeof pkg?.version === 'string' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 从 pnpm-lock.yaml 读出该包被**钉住**的版本。解析策略（lock 格式五花八门，只认两种确定性位置，避免子串误命中）：
+ *   ① importers 段：行内容恰为 `'<name>':`（可带缩进），随后几行内的 `version: X`；
+ *   ② packages 段：行首（可带缩进/引号）`<name>@<版本或 git+...>:` 的键名。
+ * 读不到返回 null（调用方据此判定"没能核实"，不谎报成功）。
+ *
+ * ★ 2026-09-22 修复（缺陷②连带）：旧版 ① 在遇到 `specifier: …` 行时**直接 break**，而 importers 段
+ *   恒为 `specifier:` 在前、`version:` 在后 → ① 从来没生效过，全靠 ② 兜底；而 ② 的正则用 `[^':\s]+`
+ *   取值，遇到 `name@https://…tgz` / `link:…` 会在第一个冒号处截断（读出 `http`）或读不到（link 依赖
+ *   在 lock 里没有 packages 条目 → 返回 null）。后果：来源钉住的包永远被判为「漂移」→ 每次安装都白跑
+ *   一次 pnpm add，并给用户一条假的「没写进 lock」警告。现在 ① 跳过 specifier 行、② 取到行尾。
+ */
+function lockVersion(profileDir, name) {
+  const file = join(profileDir, 'pnpm-lock.yaml')
+  if (!existsSync(file)) return null
+  let lines = []
+  try {
+    lines = readFileSync(file, 'utf8').split(/\r?\n/u)
+  } catch {
+    return null
+  }
+  for (let i = 0; i < lines.length; i += 1) {
+    // 键形态三种都认（0.5.38 改错）：`name`、`'name':`（pnpm 对**含 `/`/`@`** 的包名加引号）、
+    // `name:`（pnpm 对**未加 scope** 的包名不加引号）。旧判据漏了第三种 ⇒ 未加 scope 的 `link:`
+    // 依赖在 importers 里明明有条目却读不出来（真机 desktop profile 的 `dshmarket` 就是：
+    // lock 的 35-37 行写着 `dshmarket: / specifier: link:… / version: link:../../plugin-src/dshmarket`，
+    // 而 `lockVersion()` 返回 null）——后果是面板永远报"没写进 pnpm-lock.yaml"、pin 永远 partial、
+    // 每次对账都白跑一次 `pnpm add`。真值一律从下面这一处读，别在调用方再补一套。
+    // 0.5.39：键判据搬进 lock-importer.js#lockEntryKeyMatches —— 定点**写**入也要认同一批键形态，
+    // 两处各写一份必然再次分叉（写进去的键、读的时候认不出，就是 0.5.38 那个现场）。
+    if (lockEntryKeyMatches(lines[i], name)) {
+      for (let k = i + 1; k < Math.min(i + 8, lines.length); k += 1) {
+        const m = /^\s*version:\s*(\S+)\s*$/u.exec(lines[k])
+        if (m) return m[1]
+        // 只在新包的键行（`'<name>':` 形态）处停止；`specifier: X` 有值，不是键行，必须继续往下看
+        if (/^\s*'?[^\s:]+'?:\s*$/u.test(lines[k])) break
+      }
+    }
+  }
+  const escaped = name.replace(/[/\\^$*+?.()|[\]{}]/gu, '\\$&')
+  // 取到行尾再剥尾部的引号/冒号：`'name@https://…tgz':` / `name@git+https://…#sha:` / `name@1.2.3:`
+  const keyRe = new RegExp(`^\\s*'?${escaped}@(.+?)'?:\\s*$`, 'u')
+  for (const line of lines) {
+    const m = keyRe.exec(line)
+    if (m) return m[1]
+  }
+  return null
+}
+
+export { isRegistryRange, lockVersion, profileSpec, readInstalledVersion }