@noob-stupid/dsh-plugin-console 0.5.38 → 0.5.40

package/lib/server/domain/lock-importer.js

@@ -0,0 +1,411 @@
+// L1 · domain —— lock-importer.js（pnpm-lock.yaml importer 条目的**定点写入** + **只读**校验；0.5.39 加法）
+//
+// 为什么存在（用户 2026-10-04 定案，两处真缺陷）：
+//   ① `reconcileLockfile` 过去对 `link:` 漂移一律跑一次**完整** `pnpm add`（拉包、动 node_modules、
+//      重写整份 lock）—— 而 lock 里 link 依赖的持久化**只需要 importer 里那两行**
+//      （pnpm 对 link 依赖不写 packages/snapshots —— 本机 pnpm 11.21.0 实测）。所以非 registry 来源的
+//      lock 持久化 = 本模块的定点写入（**唯一实现**；persist.js 走的 reconcile 通路就是这一条），
+//      `pnpm add` **不再**充当持久化手段。
+//   ② 写出后必须用 **只读** 的 pnpm 校验确认 lock 仍可解析：`install --lockfile-only --dry-run
+//      --frozen-lockfile`（实测：成功与失败两种结局下 lock 都逐字节不变）；失败或无法确认 ⇒ 调用方
+//      报「未持久化」+ 一键钉住，**绝不报成功**。
+//
+// ★ 现场事实（2026-10-04 实测，pnpm 11.21.0，本机 desktop profile 的副本）：
+//   `pnpm install --lockfile-only`（**不加** `--dry-run`）会把**无关条目**的 peer 后缀剥掉 ——
+//   实测把 `@deepseek-ai/dsh-experimental-schedule-bundle` / `dsh-schedule` 的
+//   `(@deepseek-ai/dsh-brand@0.1.7-rc.2)` 去掉。⇒ 它**不是**"定点补一条"的无损工具，因此：
+//     · 本模块的写入是**纯文本外科手术**（只动目标条目的那几行，其余字节逐字保留，见 planLockImporterEntry）；
+//     · 校验只用 `--dry-run`（并且每次校验后核对 lock 字节，一旦发现被动过就**立即还原**并报未确认）。
+//
+// 分层：L1 domain —— 不认识 cordis ctx；IO 与 pnpm 执行都可注入（便于离线单测跑正控/负控）。
+import { readFileSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+import { buildPnpmEnv, runPnpmWithFallback } from '../infra/exec.js'
+import { queuedWrite } from '../infra/fsx.js'
+
+/** importers 段里 pnpm 认的三个依赖分区（与 lockfile-health.js#DEP_SECTIONS 同一形状）。 */
+const IMPORTER_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies']
+
+/**
+ * 能由 importer 条目**完整**表达的来源（唯一白名单）：`link:`。
+ * 为什么其余的不在这里（本机 pnpm 11.21.0 实测）：`file:` / `git+` / tarball URL 依赖除了 importer 那两行，
+ * pnpm 还要写 `packages:` / `snapshots:` 里的**解析记录**（file: 目录 = `resolution: {directory: …}`，
+ * file: tgz 与 URL = `integrity`），只留 importer 时 `pnpm install --lockfile-only` 会把 packages 段
+ * 重新补出来 ⇒ 本地无法凭空确定，**绝不伪造**（也不退回 `pnpm add`；由调用方如实报未持久化 + 一键钉住）。
+ */
+const IMPORTER_ONLY_RE = /^link:/u
+
+/** 该校验/写入用的 lock 文件名（唯一常量，别处不要再拼字面量）。 */
+const LOCKFILE_NAME = 'pnpm-lock.yaml'
+
+/** 只读校验的超时（`--dry-run --lockfile-only` 实测 0.5~1.5s；给足余量，失败即如实报）。 */
+const VERIFY_TIMEOUT_MS = 60000
+
+/** 该来源是否走「只写 lock importer 条目」的定点写入（唯一判据；调用方不许再各判一套）。 */
+function canWriteImporterEntry(spec) {
+  return typeof spec === 'string' && IMPORTER_ONLY_RE.test(spec.trim())
+}
+
+/**
+ * lock 里 importer 键行的判据（**唯一真源**）：`name:` / `'name':` / `"name":` 三种形态都认。
+ * 与 selfupdate.js#lockVersion 的键判据**逐字同一份**（真机证据：pnpm 对含 `/`、`@` 的包名加引号，
+ * 对未加 scope 的裸名不加 —— 0.5.38 修过一次"裸键读不出来"，两处各写一份必然再次分叉）。
+ */
+function lockEntryKeyMatches(line, name) {
+  const trimmed = String(line).trim()
+  const bare = trimmed.replace(/^'|':?$/gu, '').replace(/'$/u, '')
+  const bareKey = trimmed.replace(/'$/u, '').replace(/:$/u, '')
+  const unquoted = trimmed.replace(/^"|":?$/gu, '').replace(/"$/u, '')
+  return trimmed === `'${name}':` || trimmed === `"${name}":` || bare === name || bareKey === name || unquoted === name
+}
+
+/** YAML 明文标量安全吗（危险形态才加引号）。普通路径/URL/`link:…` 一律**明文** —— pnpm 自己就是
+ *  这么写的（真机 lock 证据：`specifier: link:C:/Users/花火/.dsh/plugin-src/…` 未加引号；
+ *  `@` 与 `:` 出现在**中间**是合法明文，只有出现在开头/结尾或后跟空格才是危险形态）。 */
+function yamlScalar(value) {
+  const text = String(value)
+  const needsQuote = text === ''
+    || /[\n\r\t]/u.test(text)
+    || /^\s|\s$/u.test(text)
+    || /:\s|:$/u.test(text)
+    || /#/u.test(text)
+    || /^[!&*?|>%@`"'[\]{},-]/u.test(text)
+  return needsQuote ? `'${text.replace(/'/gu, "''")}'` : text
+}
+
+/**
+ * `link:` 规格在 lock 里的 `version:` 形态（**pnpm 实际写出的形态**，真机 + 本机实测双重证据）：
+ *   · 同盘 → 相对 profile 目录的路径（`link:../../plugin-src/x`）；
+ *   · 跨盘（`path.relative` 只能给出绝对路径）→ 绝对路径（`link:D:/dsh-link/x`）；
+ *   · 一律**正斜杠**（清单里的反斜杠目标也归一成正斜杠 —— 真机 desktop profile 的
+ *     `link:D:\dsh-link\…` 在 lock 里就是 `link:D:/dsh-link/…`）。
+ * 非 link: 规格返回 null（不在本模块的白名单里）。
+ */
+function lockVersionText(profileDir, spec) {
+  if (!canWriteImporterEntry(spec)) return null
+  const raw = spec.trim().slice('link:'.length).replace(/\\/gu, '/')
+  if (raw === '') return null
+  const abs = isAbsolute(raw) ? raw : resolve(String(profileDir), raw)
+  let rel = ''
+  try {
+    rel = relative(String(profileDir), abs)
+  } catch {
+    rel = ''
+  }
+  const text = rel !== '' && !isAbsolute(rel) ? rel : abs
+  return `link:${String(text).replace(/\\/gu, '/')}`
+}
+
+/**
+ * 纯函数：把 lock 文本改成"该包在 importer 里有正确条目"的文本（**只动它自己那几行**）。
+ * 返回 `{ ok, changed, text, reason }`；`changed:false` 表示磁盘上的形态已经就是目标形态（零写盘）。
+ * 形态不认识的 lock（没有 importers 段 / 缩进不是 pnpm 的形状）→ `ok:false` + 原因，**绝不猜着改**。
+ */
+function planLockImporterEntry(lockText, { name, specifier, version, section = IMPORTER_SECTIONS[0] } = {}) {
+  const text = typeof lockText === 'string' ? lockText : String(lockText ?? '')
+  const eol = /\r\n/u.test(text) ? '\r\n' : '\n'
+  const trailing = /\r?\n$/u.test(text)
+  const lines = text.split(/\r?\n/u)
+  if (trailing && lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+  const rebuild = (next) => next.join(eol) + (trailing ? eol : '')
+  const fail = (reason) => ({ ok: false, changed: false, text, reason })
+
+  const start = lines.findIndex((l) => /^importers:\s*$/u.test(l))
+  if (start === -1) return fail('lock 里没有 importers 段（形态不认识），已跳过定点写入')
+  // 根 importer（profile 是单项目工程 → 键是 `.`；找不到就退回第一个 importer）
+  let importerAt = -1
+  let importerEnd = lines.length
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^[A-Za-z]/u.test(lines[i])) {
+      if (importerAt !== -1) importerEnd = i
+      break
+    }
+    const key = /^\s{2}(\S.*?):\s*$/u.exec(lines[i])
+    if (key !== null) {
+      if (importerAt === -1) importerAt = i
+      if (key[1] === '.') {
+        importerAt = i
+        // 该 importer 的结束位置：下一个缩进 ≤2 的非空行
+        for (let k = i + 1; k < lines.length; k += 1) {
+          if (lines[k].trim() !== '' && !/^\s{3,}/u.test(lines[k])) {
+            importerEnd = k
+            break
+          }
+        }
+        break
+      }
+    }
+  }
+  if (importerAt === -1) return fail('lock 里读不到 importer 键（形态不认识），已跳过定点写入')
+
+  const wanted = [yamlScalar(`specifier: ${specifier}`), yamlScalar(`version: ${version}`)]
+  // 扫该 importer：既找该包现有条目（就地改），也记录目标分区的插入点
+  let foundAt = -1
+  let foundSection = null
+  let foundBlockEnd = -1
+  let target = IMPORTER_SECTIONS.includes(section) ? section : IMPORTER_SECTIONS[0]
+  let currentSection = null
+  let insertAt = -1
+  for (let i = importerAt + 1; i < importerEnd; i += 1) {
+    const line = lines[i]
+    if (line.trim() === '') continue
+    const sec = /^\s{4}([A-Za-z]+):\s*$/u.exec(line)
+    if (sec !== null) {
+      currentSection = sec[1]
+      if (currentSection === target) {
+        // 目标分区的插入点：本分区最后一个条目之后（遇到缩进 ≤4 的非空行即本分区结束）
+        let last = i
+        for (let k = i + 1; k < importerEnd; k += 1) {
+          if (lines[k].trim() !== '' && !/^\s{5,}/u.test(lines[k])) break
+          last = k
+        }
+        insertAt = last + 1
+      }
+      continue
+    }
+    if (foundAt === -1 && /^\s{6}\S/u.test(line) && lockEntryKeyMatches(line, name)) {
+      foundAt = i
+      foundSection = currentSection
+      // 该条目的块范围（键行 + 缩进更深的字段行）
+      foundBlockEnd = i + 1
+      for (let k = i + 1; k < importerEnd; k += 1) {
+        if (lines[k].trim() !== '' && !/^\s{7,}/u.test(lines[k])) break
+        foundBlockEnd = k + 1
+      }
+    }
+  }
+
+  if (foundAt !== -1) {
+    // 就地改：只替换/补齐 specifier 与 version 两行，其它字段与所有无关行逐字保留
+    const keyIndent = /^\s*/u.exec(lines[foundAt])[0]
+    const fieldIndent = `${keyIndent}  `
+    const block = lines.slice(foundAt + 1, foundBlockEnd)
+    const next = [...block]
+    let sawSpecifier = false
+    let sawVersion = false
+    for (let k = 0; k < next.length; k += 1) {
+      const field = /^\s*(specifier|version):/u.exec(next[k])
+      if (field === null) continue
+      if (field[1] === 'specifier') {
+        sawSpecifier = true
+        next[k] = `${fieldIndent}specifier: ${yamlScalar(specifier)}`
+      } else {
+        sawVersion = true
+        next[k] = `${fieldIndent}version: ${yamlScalar(version)}`
+      }
+    }
+    if (!sawSpecifier) next.unshift(`${fieldIndent}specifier: ${yamlScalar(specifier)}`)
+    if (!sawVersion) next.push(`${fieldIndent}version: ${yamlScalar(version)}`)
+    if (next.join(eol) === block.join(eol)) {
+      return { ok: true, changed: false, text, reason: null, section: foundSection ?? target, version, specifier }
+    }
+    return {
+      ok: true,
+      changed: true,
+      text: rebuild([...lines.slice(0, foundAt + 1), ...next, ...lines.slice(foundBlockEnd)]),
+      reason: null,
+      section: foundSection ?? target,
+      version,
+      specifier,
+    }
+  }
+
+  // 没有该条目 → 在目标分区末尾插入一条（分区不存在时先补分区头）
+  const keyText = /[/@]/u.test(name) ? `'${name}':` : `${name}:`
+  const block = [`      ${keyText}`, `        specifier: ${yamlScalar(specifier)}`, `        version: ${yamlScalar(version)}`]
+  if (insertAt === -1) {
+    // 分区不存在：插到该 importer 现有分区之后（没有分区就紧跟 importer 键行）
+    let at = importerAt + 1
+    for (let i = importerAt + 1; i < importerEnd; i += 1) {
+      if (lines[i].trim() === '') continue
+      at = i + 1
+    }
+    return {
+      ok: true,
+      changed: true,
+      text: rebuild([...lines.slice(0, at), `    ${target}:`, ...block, ...lines.slice(at)]),
+      reason: null,
+      section: target,
+      version,
+      specifier,
+    }
+  }
+  return {
+    ok: true,
+    changed: true,
+    text: rebuild([...lines.slice(0, insertAt), ...block, ...lines.slice(insertAt)]),
+    reason: null,
+    section: target,
+    version,
+    specifier,
+  }
+}
+
+/**
+ * 写入（**唯一写入口**）：读 → 纯函数改造 → 写 → **读回核实**（既有规矩：写完必须读回，绝不凭返回值
+ * 报成功）。走 fsx 的写队列（与清单/补丁写入同一把锁，避免并发读改写互相覆盖）。
+ * 返回 `{ changed, unchanged, specifier, version, section, reason }`；任何一步不成 ⇒ `changed:false` + 原因。
+ */
+async function writeLockImporterEntry(profileDir, { name, spec, section = IMPORTER_SECTIONS[0], deps = {} } = {}) {
+  const readText = typeof deps.readText === 'function' ? deps.readText : (p) => readFileSync(p, 'utf8')
+  const writeText = typeof deps.writeText === 'function' ? deps.writeText : (p, text) => writeFileSync(p, text, 'utf8')
+  const file = join(String(profileDir), LOCKFILE_NAME)
+  const specifier = typeof spec === 'string' ? spec.trim() : ''
+  const version = lockVersionText(profileDir, specifier)
+  if (version === null) {
+    return { changed: false, unchanged: false, specifier, version: null, section, reason: '该来源的 lock 记录不止 importer 一行，本地无法确定 ⇒ 未写入（不用 pnpm add 当持久化手段）' }
+  }
+  return queuedWrite(async () => {
+    let text = null
+    try {
+      text = readText(file)
+    } catch (error) {
+      return { changed: false, unchanged: false, specifier, version, section, reason: `读不到 ${LOCKFILE_NAME}（${error instanceof Error ? error.message : String(error)}），未写入` }
+    }
+    const plan = planLockImporterEntry(text, { name, specifier, version, section })
+    if (plan.ok !== true) return { changed: false, unchanged: false, specifier, version, section, reason: plan.reason }
+    if (plan.changed !== true) return { changed: false, unchanged: true, specifier: plan.specifier, version: plan.version, section: plan.section, reason: null }
+    try {
+      writeText(file, plan.text)
+    } catch (error) {
+      return { changed: false, unchanged: false, specifier, version, section, reason: `写盘失败：${error instanceof Error ? error.message : String(error)}` }
+    }
+    let after = null
+    try {
+      after = readText(file)
+    } catch (error) {
+      return { changed: false, unchanged: false, specifier, version, section, reason: `写盘后读回失败：${error instanceof Error ? error.message : String(error)}` }
+    }
+    if (after !== plan.text) return { changed: false, unchanged: false, specifier, version, section, reason: '写盘后读回与预期不一致（未能核实），按未写入处理' }
+    return { changed: true, unchanged: false, specifier: plan.specifier, version: plan.version, section: plan.section, reason: null }
+  })
+}
+
+/**
+ * 从 lock 自己的 `settings:` 段取出 pnpm 配置，供**只读**校验按 lock 的形态复算
+ * （不镜像它时 pnpm 直接 `ERR_PNPM_LOCKFILE_CONFIG_MISMATCH`：本机实测 `autoInstallPeers`）。
+ * 只认单行标量；对象/数组等复杂设置一律不传（不猜）。
+ */
+function lockfileSettingsFlags(lockText) {
+  const lines = String(lockText ?? '').split(/\r?\n/u)
+  const start = lines.findIndex((l) => /^settings:\s*$/u.test(l))
+  if (start === -1) return []
+  const flags = []
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^[A-Za-z]/u.test(lines[i])) break
+    const m = /^\s{2}([A-Za-z][A-Za-z0-9]*):\s*(.+?)\s*$/u.exec(lines[i])
+    if (m === null) continue
+    const value = m[2].replace(/^'|'$/gu, '')
+    if (!/^[A-Za-z0-9._-]+$/u.test(value)) continue
+    flags.push(`--config.${m[1]}=${value}`)
+  }
+  return flags
+}
+
+/** 只读校验的 argv（**唯一产出点**，纯函数，便于单测断言"没有任何写盘开关"）。 */
+function verifyArgsFor({ registry = null, settings = [], relaxReleaseAge = false } = {}) {
+  const args = ['install', '--lockfile-only', '--dry-run', '--frozen-lockfile']
+  if (typeof registry === 'string' && registry.trim() !== '') args.push('--registry', registry.trim())
+  args.push(...settings)
+  // ★ 供应链年龄闸（pnpm 的 minimumReleaseAge，默认 24h）会在**解析之前**卡住整份 lock：
+  //   本机实测（刚发布的 @noob-stupid/dsh-plugin-console@0.5.37 在 24h 窗口内）不加它时任何
+  //   `--lockfile-only` 调用都只报 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION，看不出 lock 到底能不能解析。
+  //   它与"lock 可解析"是两件事，所以**只读重试**时才放宽；`--dry-run` + `--lockfile-only` 下不装任何东西
+  //   （实测 lock 逐字节不变）。**写盘路径永不出现这个开关**（修复 argv 由 lockfile-health#repairArgsFor
+  //   唯一产出，那一处一个字没动）。
+  if (relaxReleaseAge) args.push('--config.minimumReleaseAge=0')
+  return args
+}
+
+/** 错误文本尾部（面板要能看到 pnpm 的原始输出，不允许只报"失败了"）。 */
+function tailOf(error) {
+  const message = String(error?.message ?? error ?? '')
+  return message.split(/\r?\n/u).filter((l) => l.trim() !== '').slice(-3).join(' ⏎ ').slice(0, 400)
+}
+
+/**
+ * **只读**校验：这条 lock 现在还能被 pnpm 解析吗（`install --lockfile-only --dry-run --frozen-lockfile`）。
+ * 返回 `{ verified, via, reason, attempts, changed }`：
+ *   · `verified:true`  —— pnpm 退出码 0，且 lock 字节**逐字节未变**；
+ *   · `verified:false` —— pnpm 明确报错（lock 形态/配置有问题）；
+ *   · `verified:null`  —— pnpm 根本跑不起来（执行方式不可用）⇒ "无法确认"，调用方按未持久化处理。
+ * `changed:true` 表示校验过程**动过** lock（理论上不可能，`--dry-run` 的硬前提）——此时立即还原原字节
+ * 并把结论降为未确认：宁可报"没确认"，也绝不留下被校验命令改过的 lock。
+ */
+async function verifyLockReadOnly({ profileDir, registry = null, run = runPnpmWithFallback, deps = {}, execOpts = {} } = {}) {
+  const file = join(String(profileDir), LOCKFILE_NAME)
+  let before = null
+  try {
+    before = readFileSync(file, 'utf8')
+  } catch (error) {
+    return { verified: false, via: null, changed: false, attempts: [], reason: `读不到 ${LOCKFILE_NAME}（${error instanceof Error ? error.message : String(error)}），无法校验` }
+  }
+  const settings = lockfileSettingsFlags(before)
+  const attempts = []
+  const once = async (relax) => {
+    const args = verifyArgsFor({ registry, settings, relaxReleaseAge: relax })
+    try {
+      await run(args, { execOpts: { cwd: profileDir, timeout: VERIFY_TIMEOUT_MS, windowsHide: true, maxBuffer: 4 * 1024 * 1024, env: buildPnpmEnv(registry), ...execOpts } })
+      attempts.push({ args, ok: true, tail: null })
+      return { ok: true, tail: null }
+    } catch (error) {
+      const tail = tailOf(error)
+      attempts.push({ args, ok: false, tail })
+      return { ok: false, tail, error }
+    }
+  }
+  const guard = () => {
+    // 校验必须是无损的：核对字节，被动过就还原（并如实标注 changed）
+    let now = null
+    try {
+      now = readFileSync(file, 'utf8')
+    } catch {
+      return { changed: true, restored: false }
+    }
+    if (now === before) return { changed: false, restored: false }
+    try {
+      writeFileSync(file, before, 'utf8')
+      return { changed: true, restored: true }
+    } catch {
+      return { changed: true, restored: false }
+    }
+  }
+  let outcome = await once(false)
+  if (outcome.ok !== true && /MINIMUM_RELEASE_AGE|minimumReleaseAge/iu.test(String(outcome.tail))) outcome = await once(true)
+  const bytes = guard()
+  const via = attempts.filter((a) => a.ok).length > 0 ? 'pnpm install --lockfile-only --dry-run --frozen-lockfile' : null
+  if (bytes.changed) {
+    return {
+      verified: null,
+      via,
+      changed: true,
+      restored: bytes.restored,
+      attempts,
+      reason: `只读校验**改动了** ${LOCKFILE_NAME}（违反只读前提）——已${bytes.restored ? '还原' : '尝试还原失败'}，按未确认处理`,
+    }
+  }
+  if (outcome.ok === true) return { verified: true, via, changed: false, attempts, reason: null }
+  const unavailable = /ENOENT|Cannot find module|已尝试：/u.test(String(outcome.tail)) && !/ERR_PNPM_/u.test(String(outcome.tail))
+  return {
+    verified: unavailable ? null : false,
+    via,
+    changed: false,
+    attempts,
+    reason: `${unavailable ? 'pnpm 执行方式不可用（无法确认）' : 'pnpm 只读校验未通过'}：${outcome.tail ?? '（无输出）'}`,
+  }
+}
+
+export {
+  IMPORTER_SECTIONS,
+  IMPORTER_ONLY_RE,
+  LOCKFILE_NAME,
+  VERIFY_TIMEOUT_MS,
+  canWriteImporterEntry,
+  lockEntryKeyMatches,
+  lockVersionText,
+  lockfileSettingsFlags,
+  planLockImporterEntry,
+  verifyArgsFor,
+  verifyLockReadOnly,
+  writeLockImporterEntry,
+}

package/lib/server/domain/manifest.js

@@ -12,8 +12,10 @@
 
 import { readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { linkSpecFor, materializePackageForLink, probeFailureKind, probeRegistryPackage, suggestedPinAction } from './dep-source.js'
+import { linkSpecFor, materializePackageForLink, probeFailureKind, probeRegistryPackage, sameSourceSpec, suggestedPinAction } from './dep-source.js'
+import { ensureLinkSelfSufficiency, removeLinkSelfSufficiency } from './link-self-sufficiency.js'
 import { queuedWrite } from '../infra/fsx.js'
+import { runPnpmAdd } from '../infra/exec.js'
 import { resolvePackageJson } from '../infra/paths.js'
 import { reconcileLockfile } from './selfupdate.js'
 
@@ -108,10 +110,25 @@ async function specOf(profileDir, packageName) {
  *   · 本次没探到（网络/镜像不可达）      → 不敢替用户猜：仍按旧行为写版本号，但**如实记 note**
  *     并给出结构化「钉住」建议动作（面板可一键执行），绝不写成"已钉住"。
  * 返回 { form, spec, note, suggestion }；`spec` 为 null 表示"不要改清单"。
+ *
+ * 2026-10-06 加法 —— **来源型默认【真装】**（用户点名：「默认真装 + link 自足」）：
+ *   调用方**知道这个包的真实来源规格**时（tarball URL / `github:owner/repo` / 本地目录），
+ *   传 `sourceSpec` 进来，写回的就是**那个规格本身** —— 于是 `pnpm add <spec>` 由包管理器
+ *   保证依赖与 peer，与官方 `dsh plugin add` 同一条通道（`form: 'source'`）。
+ *   `link:` 退居**显式开发式安装**：仅在"拿不到真实来源规格"（或用户明确选择开发式）时使用，
+ *   由 `link-self-sufficiency.js` 补齐依赖与框架 peer 垫片根。
+ *   优先级刻意保持"registry 可解析 → 版本号"在最前：既有 registry 流程一字不改（不倒退）。
  */
-async function planDependencySpec({ profileDir, packageName, version, registries = [], probe = null, home = undefined, profile = null }) {
+async function planDependencySpec({ profileDir, packageName, version, registries = [], probe = null, home = undefined, profile = null, sourceSpec = null }) {
   const doProbe = typeof probe === 'function' ? probe : probeRegistryPackage
+  const realSpec = typeof sourceSpec === 'string' && sourceSpec.trim() !== '' ? sourceSpec.trim() : null
   const linkable = () => materializePackageForLink(profileDir, packageName, home === undefined ? {} : { home })
+  const asSource = () => ({
+    form: 'source',
+    spec: realSpec,
+    note: `${packageName}：按**真实来源规格**记录依赖（${realSpec}）—— 走 pnpm add <spec> 真装，依赖与 peer 由包管理器保证（与官方 dsh plugin add 同一通道）`,
+    suggestion: null,
+  })
   const asLink = (why) => {
     const dir = linkable()
     if (dir === null) {
@@ -137,6 +154,8 @@ async function planDependencySpec({ profileDir, packageName, version, registries
     result = { resolvable: false, hasVersion: false, tried: [error instanceof Error ? error.message : String(error)] }
   }
   if (result?.resolvable === true && result.hasVersion !== false) return { form: 'version', spec: version, note: null, suggestion: null }
+  // 来源型：调用方给了真实来源规格 ⇒ 默认真装（不写 link:）。拿不到真实规格才退回 link:。
+  if (probeFailureKind(result) === 'fetch-404' && realSpec !== null) return asSource()
   if (probeFailureKind(result) === 'fetch-404') {
     return asLink(result?.resolvable === true
       ? `registry 上没有 ${version} 这个版本（该包只在 GitHub release / 本地有）`
@@ -164,29 +183,66 @@ async function planDependencySpec({ profileDir, packageName, version, registries
  *             lockSynced: boolean, lockNote: string|null, depNote: string|null, suggested: object|null }}
  */
 async function declareProfileDependency(profileDir, packageName, version = null, options = {}) {
-  const { syncLock = true, registries = [], probe = null, home = undefined, profile = null } = options
-  const empty = { changed: false, version: null, spec: null, form: null, reason: null, lockSynced: false, lockNote: null, depNote: null, suggested: null }
+  const { syncLock = true, registries = [], probe = null, home = undefined, profile = null, sourceSpec = null, installSource = null } = options
+  const empty = { changed: false, version: null, spec: null, form: null, reason: null, lockSynced: false, lockNote: null, depNote: null, suggested: null, sourceInstall: null, selfSufficiency: null }
+  const realSpec = typeof sourceSpec === 'string' && sourceSpec.trim() !== '' ? sourceSpec.trim() : null
+  // ★ 来源型默认【真装】（2026-10-06 加法）：给了真实来源规格、而磁盘上还没有这个包时，
+  // **先真装**（pnpm add <spec>，依赖/peer 交给包管理器）；装失败也**不拒绝** ——
+  // 如实记 sourceInstall 后继续走既有判定（退回 link: 并由自足性补齐）。
+  let sourceInstall = null
+  if (realSpec !== null && await installedVersionOf(profileDir, packageName) === null) {
+    sourceInstall = await installSourceDependency({ profileDir, spec: realSpec, registries, install: installSource })
+  }
   const resolved = typeof version === 'string' && version !== '' ? version : await installedVersionOf(profileDir, packageName)
-  if (resolved === null) return { ...empty, reason: '读不到已安装版本' }
+  if (resolved === null) return { ...empty, sourceInstall, reason: '读不到已安装版本' }
   // 探测/物化放在写锁**之外**（网络探测最长 8 秒，占着清单写锁会堵住其它写）
-  const plan = await planDependencySpec({ profileDir, packageName, version: resolved, registries, probe, home, profile })
+  const plan = await planDependencySpec({ profileDir, packageName, version: resolved, registries, probe, home, profile, sourceSpec: realSpec })
   if (plan.spec === null) return { ...empty, version: resolved, form: plan.form, reason: plan.note, depNote: plan.note, suggested: plan.suggestion }
   const result = await queuedWrite(async () => {
     const manifest = await readManifest(profileDir)
     const deps = { ...(manifest.dependencies ?? {}) }
-    if (deps[packageName] === plan.spec) return { changed: false }
+    // 0.5.39 改错（Fix 2）：逐字比较会把「同一目标的另一种写法」当成漂移 —— 真机 desktop profile 的
+    // `link:D:\dsh-link\…`（反斜杠）会被这条路径无谓改写成正斜杠（用户没要求的漂移）。等价 ⇒ 零写盘。
+    if (sameSourceSpec(profileDir, deps[packageName], plan.spec)) return { changed: false }
     deps[packageName] = plan.spec
     manifest.dependencies = deps
     await writeManifest(profileDir, manifest)
     return { changed: true }
   })
-  const out = { ...empty, changed: result.changed, version: resolved, spec: plan.spec, form: plan.form, depNote: plan.note, suggested: plan.suggestion }
+  // ★ link: 自足性（2026-10-06 加法）：写成 link: 之后立刻补齐 —— 目标目录内装它的 dependencies
+  // + 建框架 peer 垫片根。幂等（自足 ⇒ 零写盘）、绝不覆盖它自带的 node_modules、
+  // 失败只如实报未就绪 + 给动作 —— 安装主路径**不新增拒绝分支**。
+  const selfSufficiency = plan.form === 'link'
+    ? await ensureLinkSelfSufficiency({ profileDir, packageName, spec: plan.spec, home })
+    : null
+  const out = { ...empty, changed: result.changed, version: resolved, spec: plan.spec, form: plan.form, depNote: plan.note, suggested: plan.suggestion, sourceInstall, selfSufficiency }
   if (syncLock !== true) return out
   // **写完清单必须把 lock 拉齐**（2026-09-24 CI 实测）：只写清单不写 lock → 清单/lock 不一致 →
   // 之后任何 pnpm 操作都会硬失败（ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS）。
   // 放在写队列**之外**执行（对账本身会跑 pnpm，不该占着清单写锁）；失败只记 note，不让安装失败。
   const synced = await syncLockFor(profileDir, [packageName], { registries, home, profile })
-  return { ...out, ...synced, depNote: joinNotes(plan.note, synced.depNote), suggested: synced.suggested ?? plan.suggestion }
+  return {
+    ...out,
+    ...synced,
+    depNote: joinNotes(plan.note, selfSufficiency === null ? null : selfSufficiency.note, synced.depNote),
+    suggested: synced.suggested ?? (selfSufficiency === null ? null : selfSufficiency.action) ?? plan.suggestion,
+  }
+}
+
+/**
+ * 来源型**真装**（2026-10-06 加法）：把真实来源规格交给包管理器 —— `pnpm add <spec>` 进 profile，
+ * 与官方 `dsh plugin add` 同一条通道（依赖与 peer 由 pnpm 保证，我们不手铺）。
+ * 返回 `{ ok, spec, error }`，**绝不抛**：安装主路径不得新增拒绝分支。
+ */
+async function installSourceDependency({ profileDir, spec, registries = [], install = null, timeout = 180000 } = {}) {
+  const runner = typeof install === 'function' ? install : runPnpmAdd
+  const registry = (Array.isArray(registries) ? registries : []).find((r) => typeof r === 'string' && r.trim() !== '') ?? 'https://registry.npmmirror.com'
+  try {
+    await runner({ profileDir, spec, registry, timeout })
+    return { ok: true, spec, error: null }
+  } catch (error) {
+    return { ok: false, spec, error: String(error instanceof Error ? error.message : error).slice(0, 600) }
+  }
 }
 
 /** 多段说明拼接（空段自动跳过）：文案只做拼接，不覆盖 —— 覆盖就是"谎报"的来源。 */
@@ -230,14 +286,19 @@ async function pinProfileDependency(profileDir, packageName, options = {}) {
   const changed = await queuedWrite(async () => {
     const manifest = await readManifest(profileDir)
     const deps = { ...(manifest.dependencies ?? {}) }
-    if (deps[packageName] === spec) return false
+    // 0.5.39 改错（Fix 2）：等价写法（正/反斜杠、相对↔绝对指向同一目录）**不再改写清单** ——
+    // 幂等零写盘；只有真漂移（目标不同/确实缺失）才写，且写的是 linkSpecFor 的**规范形**。
+    if (sameSourceSpec(profileDir, deps[packageName], spec)) return false
     deps[packageName] = spec
     manifest.dependencies = deps
     await writeManifest(profileDir, manifest)
     return true
   })
   const after = await specOf(profileDir, packageName)
-  return { ok: after === spec, spec, before, after, changed, dir }
+  // ★ link: 自足性（2026-10-06 加法）：钉住是"显式开发式安装"的入口，钉完立刻补齐
+  // （目标目录内装 dependencies + 框架 peer 垫片根）。幂等、绝不覆盖、失败只如实报。
+  const selfSufficiency = await ensureLinkSelfSufficiency({ profileDir, packageName, spec, home })
+  return { ok: sameSourceSpec(profileDir, after, spec), spec, before, after, changed, dir, selfSufficiency }
 }
 
 /**
@@ -252,7 +313,8 @@ async function setProfileDependency(profileDir, packageName, spec) {
   const changed = await queuedWrite(async () => {
     const manifest = await readManifest(profileDir)
     const deps = { ...(manifest.dependencies ?? {}) }
-    if (deps[packageName] === spec) return false
+    // 0.5.39 改错（Fix 2）：判等用同一把尺子（canonicalSourceSpec + realpath）—— 等价即零写盘
+    if (sameSourceSpec(profileDir, deps[packageName], spec)) return false
     deps[packageName] = spec
     manifest.dependencies = deps
     await writeManifest(profileDir, manifest)
@@ -261,9 +323,11 @@ async function setProfileDependency(profileDir, packageName, spec) {
   return { before, after: await specOf(profileDir, packageName), changed }
 }
 
-/** 卸载即撤销声明。 */
-async function undeclareProfileDependency(profileDir, packageName) {
-  return queuedWrite(async () => {
+/** 卸载即撤销声明（并清掉**我们造的** link 垫片 —— 卸载即净）。
+ *  `options.home` 必须与当初 `declareProfileDependency` 用的 home 一致（生产两边都不传 = `dshHome()`）；
+ *  只有隔离测试才会传私有 home —— 传错不会误删（记录读不到 ⇒ 无事发生），但也清不掉。 */
+async function undeclareProfileDependency(profileDir, packageName, options = {}) {
+  const result = await queuedWrite(async () => {
     const manifest = await readManifest(profileDir)
     const deps = { ...(manifest.dependencies ?? {}) }
     if (!(packageName in deps)) return { changed: false }
@@ -272,6 +336,10 @@ async function undeclareProfileDependency(profileDir, packageName) {
     await writeManifest(profileDir, manifest)
     return { changed: true }
   })
+  // 2026-10-06 加法：link 自足性造的垫片是我们加的，卸载时只清**我们造的**那些
+  // （记录里逐个核对"现在仍是指向当初目标的链接"，被人改过的一律不碰）。清不掉只如实报。
+  const shims = removeLinkSelfSufficiency({ packageName, home: options.home ?? null })
+  return { ...result, shimsRemoved: shims.removed, shimsKept: shims.kept, selfSufficiencyNote: shims.note }
 }
 
 /**
@@ -325,6 +393,6 @@ async function applyDependencyBackfill(profileDir, options = {}) {
 
 export {
   DEFAULT_BUNDLES, addBundleToManifest, applyDependencyBackfill, declareProfileDependency,
-  installedVersionOf, planDependencyBackfill, planDependencySpec, pinProfileDependency, removeBundleFromManifest,
+  installedVersionOf, installSourceDependency, planDependencyBackfill, planDependencySpec, pinProfileDependency, removeBundleFromManifest,
   setProfileDependency, specOf, syncLockFor, undeclareProfileDependency,
 }

package/lib/server/domain/persist.js

@@ -31,7 +31,7 @@
 // 分层：L1 domain —— 不认识 cordis ctx；IO 与四个写入器都可注入（便于离线单测跑正控/负控）。
 import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
-import { PLUGIN_SRC_DIR, linkSpecFor, profileNameOf, linkSpecIsIntact } from './dep-source.js'
+import { PLUGIN_SRC_DIR, linkSpecFor, profileNameOf, linkSpecIsIntact, sameSourceSpec } from './dep-source.js'
 import { isUnder } from '../infra/framework-root.js'
 import { addBundleToManifest, declareProfileDependency, pinProfileDependency, setProfileDependency } from './manifest.js'
 import { appendInsert, parseInsertNames } from './patch.js'
@@ -145,11 +145,15 @@ function lockPart({ profileDir, packageName, spec }) {
   const value = String(entry).trim()
   const s = typeof spec === 'string' ? spec.trim() : ''
   if (s.startsWith('link:')) {
-    if (value.startsWith('link:')) {
+    // 0.5.39 改错（Fix 2）：link 条目还必须**指向清单里的同一个目标** —— 只判"以 link: 开头"会把
+    // 「清单指 A、lock 指 B」当成就位，而 pnpm 下一次操作会按 lock 把链接还原到 B（真实漂移）。
+    if (value.startsWith('link:') && sameSourceSpec(profileDir, value, s)) {
       out.ok = true
       return out
     }
-    out.reason = `清单把该包钉在 ${s}，而 lock 里是 ${value}（对账后会被 pnpm 还原）`
+    out.reason = value.startsWith('link:')
+      ? `清单把该包钉在 ${s}，而 lock 里是 ${value}（**指向的目标不同**，对账后会被 pnpm 还原）`
+      : `清单把该包钉在 ${s}，而 lock 里是 ${value}（对账后会被 pnpm 还原）`
     return out
   }
   if (EXACT_VERSION_RE.test(s)) {
@@ -361,6 +365,18 @@ async function ensurePersisted({ profileDir, patchPath, packageName, mode = 'ins
     }
   }
   const after = persistReport({ profileDir, patchPath, packageName, entries })
+  // 0.5.39 加法（修 1 的收尾）：reconcile 写出 lock importer 条目后会用 pnpm 的**只读**用法确认 lock
+  // 仍可解析；「没通过 / 无法确认」时**不能**因为磁盘上有那两行就报成功 —— 按未持久化处理。
+  // 判据与文案都来自同一条通路（reconcile 的 lockVerified/lockNote），本模块只把结论并进来，不新判一套。
+  let lockVerdict = null
+  if (lock !== null && typeof lock === 'object' && (lock.lockVerified === false || lock.lockVerified === null) && lock.lockUpdated !== true) {
+    const reason = lock.lockNote ?? 'lock 已写入，但 pnpm 的只读校验未能确认它可解析'
+    after.parts.lock = { ...after.parts.lock, ok: false, reason }
+    after.missing = PERSIST_PARTS.filter((key) => after.parts[key].ok !== true)
+    after.persisted = after.missing.length === 0
+    after.note = after.persisted ? null : persistNote(after)
+    lockVerdict = { verified: lock.lockVerified, reason }
+  }
   const suggested = after.persisted ? null : suggestedPersistAction({ packageName, profileDir, missing: after.missing, reason: after.note })
   return {
     persisted: after.persisted,
@@ -370,6 +386,7 @@ async function ensurePersisted({ profileDir, patchPath, packageName, mode = 'ins
     parts: after.parts,
     declared,
     lock,
+    lockVerdict,
     bundled,
     rowId: after.parts.mount.rowId ?? rowId ?? null,
     notes,