@mzzsfy/dsh-maintain 0.5.2

package/test/core.test.mjs

@@ -0,0 +1,176 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  parseSemver,
+  gtSemver,
+  judgeVersion,
+  buildUpgradeCommand,
+  isValidChannelName,
+  isValidRegistryBase,
+  shouldReloadAfterRestart,
+  VERDICT_OUTDATED,
+  VERDICT_UP_TO_DATE,
+  VERDICT_UNKNOWN,
+} from '../src/core.mjs'
+
+const CURRENT = '0.1.1-rc.2'
+
+test('semver 解析:标准版本含 prerelease 与 build', () => {
+  const parsed = parseSemver('1.2.3-rc.2+build.7')
+  assert.deepEqual(
+    { major: parsed.major, minor: parsed.minor, patch: parsed.patch, prerelease: parsed.prerelease },
+    { major: 1, minor: 2, patch: 3, prerelease: ['rc', 2] },
+  )
+})
+
+test('semver 解析:非 semver 字符串返回 null', () => {
+  assert.equal(parseSemver('latest'), null)
+  assert.equal(parseSemver(''), null)
+  assert.equal(parseSemver(null), null)
+  assert.equal(parseSemver('1.2'), null)
+  assert.equal(parseSemver('01.2.3'), null)
+})
+
+test('semver 比较:prerelease 数值序 rc.2 低于 rc.10', () => {
+  assert.equal(gtSemver('0.1.1-rc.10', '0.1.1-rc.2'), true)
+  assert.equal(gtSemver('0.1.1-rc.2', '0.1.1-rc.10'), false)
+})
+
+test('semver 比较:无 prerelease 高于有 prerelease', () => {
+  assert.equal(gtSemver('0.1.1', '0.1.1-rc.2'), true)
+  assert.equal(gtSemver('0.1.1-rc.2', '0.1.1'), false)
+})
+
+test('semver 比较:spec 官方示例链严格升序', () => {
+  const chain = ['1.0.0-alpha', '1.0.0-alpha.1', '1.0.0-alpha.beta', '1.0.0-beta', '1.0.0-beta.2', '1.0.0-beta.11', '1.0.0-rc.1', '1.0.0']
+  for (let i = 1; i < chain.length; i++) {
+    assert.equal(gtSemver(chain[i], chain[i - 1]), true, chain[i] + ' 应高于 ' + chain[i - 1])
+    assert.equal(gtSemver(chain[i - 1], chain[i]), false, chain[i - 1] + ' 不应高于 ' + chain[i])
+  }
+})
+
+test('semver 比较:build 元数据不参与比较', () => {
+  assert.equal(gtSemver('1.0.0+build.1', '1.0.0+build.2'), false)
+  assert.equal(gtSemver('1.0.0', '1.0.0+build.2'), false)
+})
+
+test('semver 比较:含非法版本返回 false', () => {
+  assert.equal(gtSemver('not-a-version', '1.0.0'), false)
+  assert.equal(gtSemver('1.0.0', null), false)
+})
+
+test('场景:通道落后判定', () => {
+  const result = judgeVersion({ currentVersion: CURRENT, tags: { latest: '0.1.2-alpha.3', next: CURRENT }, channel: 'latest' })
+  assert.equal(result.verdict, VERDICT_OUTDATED)
+  assert.equal(result.channelLatest, '0.1.2-alpha.3')
+  assert.equal(result.reason, null)
+})
+
+test('场景:通道切换后判定跟随', () => {
+  const tags = { latest: '0.1.2-alpha.3', next: CURRENT, alpha: '0.1.2-alpha.3' }
+  assert.equal(judgeVersion({ currentVersion: CURRENT, tags, channel: 'alpha' }).verdict, VERDICT_OUTDATED)
+  assert.equal(judgeVersion({ currentVersion: CURRENT, tags, channel: 'next' }).verdict, VERDICT_UP_TO_DATE)
+})
+
+test('场景:已是最新判定', () => {
+  const result = judgeVersion({ currentVersion: CURRENT, tags: { latest: CURRENT }, channel: 'latest' })
+  assert.equal(result.verdict, VERDICT_UP_TO_DATE)
+})
+
+test('场景:通道不在 dist-tags 判未知', () => {
+  const result = judgeVersion({ currentVersion: CURRENT, tags: { latest: CURRENT }, channel: 'beta' })
+  assert.equal(result.verdict, VERDICT_UNKNOWN)
+  assert.equal(result.channelLatest, null)
+  assert.match(result.reason, /beta/)
+})
+
+test('场景:当前版本或 tags 缺失判未知', () => {
+  assert.equal(judgeVersion({ currentVersion: null, tags: { latest: '1.0.0' }, channel: 'latest' }).verdict, VERDICT_UNKNOWN)
+  assert.equal(judgeVersion({ currentVersion: CURRENT, tags: null, channel: 'latest' }).verdict, VERDICT_UNKNOWN)
+})
+
+test('场景:版本字符串非法判未知', () => {
+  const result = judgeVersion({ currentVersion: 'dev-main', tags: { latest: '1.0.0' }, channel: 'latest' })
+  assert.equal(result.verdict, VERDICT_UNKNOWN)
+  assert.match(result.reason, /dev-main/)
+})
+
+test('场景:升级命令占位符替换', () => {
+  const command = buildUpgradeCommand({ template: 'npm install -g @deepseek-ai/dsh@{tag}', tag: 'next' })
+  assert.equal(command, 'npm install -g @deepseek-ai/dsh@next')
+})
+
+test('场景:升级命令模板可整体自改为无占位符命令', () => {
+  const command = buildUpgradeCommand({ template: 'pnpm add -g @deepseek-ai/dsh', tag: 'alpha' })
+  assert.equal(command, 'pnpm add -g @deepseek-ai/dsh')
+})
+
+test('场景:升级命令占位符多次出现全部替换', () => {
+  const command = buildUpgradeCommand({ template: 'echo {tag} {tag}', tag: 'latest' })
+  assert.equal(command, 'echo latest latest')
+})
+
+test('场景:升级命令模板为空拒绝执行', () => {
+  assert.throws(() => buildUpgradeCommand({ template: '   ', tag: 'latest' }), /模板/)
+  assert.throws(() => buildUpgradeCommand({ template: null, tag: 'latest' }), /模板/)
+})
+
+test('场景:tag 含 shell 元字符拒绝执行(远端数据回流成命令的拦截点)', () => {
+  for (const tag of ['latest; rm -rf /', 'x && calc', 'a|b', '$(whoami)', '`id`', 'a b', '']) {
+    assert.throws(() => buildUpgradeCommand({ template: 'npm install -g pkg@{tag}', tag }), /非法字符/, tag)
+  }
+  for (const tag of ['latest', 'next', 'beta-1.2', 'canary_ignored', 'v1.0.0-rc.1']) {
+    assert.doesNotThrow(() => buildUpgradeCommand({ template: 'npm install -g pkg@{tag}', tag }), tag)
+  }
+})
+
+test('场景:tag 白名单形态对齐 npm dist-tag 规则(首尾字母数字,上限 214)', () => {
+  assert.equal(isValidChannelName('..'), false)
+  assert.equal(isValidChannelName('.a'), false)
+  assert.equal(isValidChannelName('a.'), false)
+  assert.equal(isValidChannelName('-a'), false)
+  assert.equal(isValidChannelName('a'), true)
+  assert.equal(isValidChannelName('a' + 'b'.repeat(213)), true, '恰 214 字符放行')
+  assert.equal(isValidChannelName('a' + 'b'.repeat(214)), false, '超 214 拒绝')
+})
+
+test('场景:registry 基地址合法判定', () => {
+  assert.equal(isValidRegistryBase('https://registry.npmmirror.com'), true)
+  assert.equal(isValidRegistryBase('http://127.0.0.1:4873'), true)
+  assert.equal(isValidRegistryBase('  https://example.com  '), true)
+  assert.equal(isValidRegistryBase('HTTPS://example.com'), true)
+})
+
+test('场景:registry 基地址非法判定', () => {
+  assert.equal(isValidRegistryBase('registry.npmmirror.com'), false)
+  assert.equal(isValidRegistryBase('ftp://example.com'), false)
+  assert.equal(isValidRegistryBase(''), false)
+  assert.equal(isValidRegistryBase('   '), false)
+  assert.equal(isValidRegistryBase(null), false)
+  assert.equal(isValidRegistryBase(undefined), false)
+})
+
+test('场景:重启失联后恢复触发刷新', () => {
+  assert.equal(shouldReloadAfterRestart({ lost: true, pid: 100, bootAt: 1 }, { lost: false, pid: 100, bootAt: 1 }), true)
+  assert.equal(shouldReloadAfterRestart({ lost: true, pid: null, bootAt: null }, { lost: false, pid: null, bootAt: null }), true)
+})
+
+test('场景:快速重启零失联凭 pid 变化触发刷新', () => {
+  assert.equal(shouldReloadAfterRestart({ lost: false, pid: 100, bootAt: 1 }, { lost: false, pid: 200, bootAt: 2 }), true)
+})
+
+test('场景:容器 pid 恒 1 零失联凭 bootAt 变化触发刷新', () => {
+  // Docker entrypoint 常驻 pid 1 + 停机时长小于轮询间隔:pid 信号结构性失效,
+  // bootAt(宿主进程启动时刻)变化是唯一可靠代际信号
+  assert.equal(shouldReloadAfterRestart({ lost: false, pid: 1, bootAt: 100 }, { lost: false, pid: 1, bootAt: 200 }), true)
+})
+
+test('场景:未失联且实例标识未变不刷新', () => {
+  assert.equal(shouldReloadAfterRestart({ lost: false, pid: 100, bootAt: 1 }, { lost: false, pid: 100, bootAt: 1 }), false)
+  // 单侧缺失退化为 pid 比对;pid/bootAt 双双缺失不构成重启证据
+  assert.equal(shouldReloadAfterRestart({ lost: false, pid: null, bootAt: null }, { lost: false, pid: 200, bootAt: 2 }), false)
+  assert.equal(shouldReloadAfterRestart({ lost: false, pid: 100, bootAt: 1 }, { lost: false, pid: undefined, bootAt: undefined }), false)
+  // bootAt 单侧出现不构成证据(防旧宿主快照缺字段误判)
+  assert.equal(shouldReloadAfterRestart({ lost: false, pid: 100, bootAt: null }, { lost: false, pid: 100, bootAt: 200 }), false)
+})

package/test/dist-tags.test.mjs

@@ -0,0 +1,220 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { fetchDistTags, resolveHostVersion, hostPackageCandidates, TARGET_PACKAGE } from '../src/core.mjs'
+
+const REGISTRY = 'https://registry.npmmirror.com'
+
+// fetchDistTags 走 response.body.getReader() 流式读取;mock 按单块提供全部字节
+function streamBody(text) {
+  const chunks = [new TextEncoder().encode(text)]
+  return {
+    getReader: () => ({
+      read: async () => (chunks.length ? { done: false, value: chunks.shift() } : { done: true, value: undefined }),
+      cancel: async () => {},
+    }),
+  }
+}
+
+function fakeFetch(body, { ok = true, status = 200 } = {}) {
+  return async (url, options) => {
+    const text = typeof body === 'function' ? body(url) : typeof body === 'string' ? body : JSON.stringify(body)
+    return { ok, status, body: streamBody(text) }
+  }
+}
+
+test('场景:dist-tags 拉取走轻量端点且透传 redirect/signal 选项', async () => {
+  let requestedUrl = null
+  let capturedOptions = null
+  const tags = await fetchDistTags({
+    registryBase: REGISTRY,
+    fetchImpl: async (url, options) => {
+      requestedUrl = url
+      capturedOptions = options
+      return { ok: true, status: 200, body: streamBody(JSON.stringify({ latest: '0.1.1-rc.2' })) }
+    },
+    timeoutMs: 1000,
+  })
+  assert.deepEqual(tags, { latest: '0.1.1-rc.2' })
+  assert.equal(requestedUrl, REGISTRY + '/-/package/' + encodeURIComponent(TARGET_PACKAGE) + '/dist-tags')
+  // 选项透传断言:redirect:'error' 的实际拒跟行为由平台 fetch 保证,mock 只验证参数到达
+  assert.equal(capturedOptions.redirect, 'error')
+  assert.ok(capturedOptions.signal instanceof AbortSignal)
+})
+
+test('场景:registry 基地址尾部斜杠容忍', async () => {
+  const tags = await fetchDistTags({
+    registryBase: REGISTRY + '/',
+    fetchImpl: fakeFetch({ latest: '1.0.0' }),
+    timeoutMs: 1000,
+  })
+  assert.deepEqual(tags, { latest: '1.0.0' })
+})
+
+test('场景:registry 地址非法拒绝', async () => {
+  await assert.rejects(
+    () => fetchDistTags({ registryBase: 'ftp://x', fetchImpl: fakeFetch({}), timeoutMs: 1000 }),
+    /registry/,
+  )
+})
+
+test('场景:registry 不可达时抛错由调用方保留上次结果', async () => {
+  await assert.rejects(
+    () => fetchDistTags({ registryBase: REGISTRY, fetchImpl: async () => { throw new Error('ECONNREFUSED') }, timeoutMs: 1000 }),
+    /ECONNREFUSED/,
+  )
+})
+
+test('场景:HTTP 非 2xx 抛错', async () => {
+  await assert.rejects(
+    () => fetchDistTags({ registryBase: REGISTRY, fetchImpl: fakeFetch({}, { ok: false, status: 502 }), timeoutMs: 1000 }),
+    /502/,
+  )
+})
+
+test('场景:响应不是对象抛错', async () => {
+  await assert.rejects(
+    () => fetchDistTags({ registryBase: REGISTRY, fetchImpl: fakeFetch('not-json'), timeoutMs: 1000 }),
+    /JSON/,
+  )
+  await assert.rejects(
+    () => fetchDistTags({ registryBase: REGISTRY, fetchImpl: fakeFetch([]), timeoutMs: 1000 }),
+    /dist-tags/,
+  )
+})
+
+test('场景:响应体超限时流式读取中途断开', async () => {
+  const huge = JSON.stringify({ latest: '1.0.0', pad: 'x'.repeat(80 * 1024) })
+  let cancelled = false
+  const bytes = new TextEncoder().encode(huge)
+  await assert.rejects(
+    () => fetchDistTags({
+      registryBase: REGISTRY,
+      fetchImpl: async () => ({
+        ok: true,
+        status: 200,
+        body: {
+          getReader() {
+            let sent = 0
+            return {
+              read: async () => {
+                if (sent >= bytes.byteLength) return { done: true, value: undefined }
+                const chunk = bytes.subarray(sent, sent + 8 * 1024)
+                sent += chunk.byteLength
+                return { done: false, value: chunk }
+              },
+              cancel: async () => {
+                cancelled = true
+              },
+            }
+          },
+        },
+      }),
+      timeoutMs: 1000,
+    }),
+    /超过上限/,
+  )
+  assert.equal(cancelled, true, '超限后必须 cancel 断开上游,不得读完全量')
+})
+
+test('场景:timeoutMs 缺省快速失败不发起请求', async () => {
+  let called = false
+  await assert.rejects(
+    () => fetchDistTags({
+      registryBase: REGISTRY,
+      fetchImpl: async () => { called = true; return { ok: true, text: async () => '{}' } },
+    }),
+    /timeoutMs/,
+  )
+  assert.equal(called, false)
+})
+
+test('场景:非字符串值被过滤,空表抛错', async () => {
+  await assert.rejects(
+    () => fetchDistTags({ registryBase: REGISTRY, fetchImpl: fakeFetch({ latest: 3 }), timeoutMs: 1000 }),
+    /dist-tags/,
+  )
+})
+
+test('场景:宿主版本定位 win32 全局布局', async () => {
+  const files = {
+    'C:\\nvm\\v24.14.1\\node_modules\\@deepseek-ai\\dsh\\package.json': JSON.stringify({ version: '0.1.1-rc.2' }),
+  }
+  const version = await resolveHostVersion({
+    execPath: 'C:\\nvm\\v24.14.1\\node.exe',
+    platform: 'win32',
+    readFileImpl: async (path) => {
+      if (!Object.prototype.hasOwnProperty.call(files, path)) throw new Error('ENOENT')
+      return files[path]
+    },
+    resolveImpl: () => { throw new Error('MODULE_NOT_FOUND') },
+  })
+  assert.equal(version, '0.1.1-rc.2')
+})
+
+test('场景:宿主版本定位 posix 全局布局', async () => {
+  const files = {
+    '/home/u/.nvm/versions/node/v24/lib/node_modules/@deepseek-ai/dsh/package.json': JSON.stringify({ version: '1.2.3' }),
+  }
+  const version = await resolveHostVersion({
+    execPath: '/home/u/.nvm/versions/node/v24/bin/node',
+    platform: 'linux',
+    readFileImpl: async (path) => {
+      if (!Object.prototype.hasOwnProperty.call(files, path)) throw new Error('ENOENT')
+      return files[path]
+    },
+    resolveImpl: () => { throw new Error('MODULE_NOT_FOUND') },
+  })
+  assert.equal(version, '1.2.3')
+})
+
+test('场景:候选布局失败时走 require 解析兜底', async () => {
+  const version = await resolveHostVersion({
+    execPath: '/usr/bin/node',
+    platform: 'linux',
+    readFileImpl: async (path) => {
+      if (path === '/opt/dsh/package.json') return JSON.stringify({ version: '2.0.0' })
+      throw new Error('ENOENT')
+    },
+    resolveImpl: () => '/opt/dsh/package.json',
+  })
+  assert.equal(version, '2.0.0')
+})
+
+test('场景:全部途径失败返回 null 不抛错', async () => {
+  const version = await resolveHostVersion({
+    execPath: '/usr/bin/node',
+    platform: 'linux',
+    readFileImpl: async () => { throw new Error('ENOENT') },
+    resolveImpl: () => { throw new Error('MODULE_NOT_FOUND') },
+  })
+  assert.equal(version, null)
+})
+
+test('场景:候选文件可读但 version 非法时静默换下一候选', async () => {
+  const files = {
+    '/prefix/lib/node_modules/@deepseek-ai/dsh/package.json': JSON.stringify({ name: 'x' }),
+    '/opt/dsh/package.json': JSON.stringify({ version: '2.0.0' }),
+  }
+  const version = await resolveHostVersion({
+    execPath: '/prefix/bin/node',
+    platform: 'linux',
+    readFileImpl: async (path) => {
+      if (!Object.prototype.hasOwnProperty.call(files, path)) throw new Error('ENOENT')
+      return files[path]
+    },
+    resolveImpl: () => '/opt/dsh/package.json',
+  })
+  assert.equal(version, '2.0.0')
+})
+
+test('候选路径推导:win32 与 posix 布局', () => {
+  assert.deepEqual(
+    hostPackageCandidates({ execPath: 'C:\\nvm\\v24\\node.exe', platform: 'win32' }),
+    ['C:\\nvm\\v24\\node_modules\\@deepseek-ai\\dsh\\package.json'],
+  )
+  assert.deepEqual(
+    hostPackageCandidates({ execPath: '/prefix/bin/node', platform: 'linux' }),
+    ['/prefix/lib/node_modules/@deepseek-ai/dsh/package.json'],
+  )
+})

package/test/logic-extract.mjs

@@ -0,0 +1,21 @@
+// 测试内部共享的 LOGIC 段提取器:从 client.js 源码提取
+// // LOGIC-BEGIN <name> ... // LOGIC-END <name> 标记段并工厂化,
+// deps 为段内自由变量。单份实现防多份提取器漂移(此前 restart-ready 与 parity 各持一份)。
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const CLIENT_SOURCE = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+
+export function clientSource() {
+  return CLIENT_SOURCE
+}
+
+export function extractLogic(name, deps = {}) {
+  const pattern = new RegExp('// LOGIC-BEGIN ' + name + '\\n([\\s\\S]*?)\\n\\s*// LOGIC-END ' + name)
+  const match = CLIENT_SOURCE.match(pattern)
+  if (!match) throw new Error('client.js 缺少 LOGIC 段: ' + name)
+  const keys = Object.keys(deps)
+  return new Function(...keys, 'return (' + match[1].trim() + ')')(...keys.map((key) => deps[key]))
+}

package/test/parity.test.mjs

@@ -0,0 +1,149 @@
+// parity 测试:client.js 的 LOGIC 标记段与 core.mjs 同源函数对拍,
+// 数据镜像常量(默认值/VERDICT/API 路径/超时窗口)与 host 侧组合值对照。
+// client 半区无法 import ESM,按 LOGIC 标记提取源码文本后工厂化执行。
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  shouldReloadAfterRestart as coreShouldReload,
+  isValidRegistryBase as coreIsValidRegistryBase,
+  VERDICT_OUTDATED,
+  VERDICT_UP_TO_DATE,
+  VERDICT_UNKNOWN,
+  TARGET_PACKAGE,
+} from '../src/core.mjs'
+import { clientSource, extractLogic } from './logic-extract.mjs'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const CLIENT_SOURCE = clientSource()
+
+function extractConst(name) {
+  // 行首锚定 + 全局扫描唯一性:防注释/示例代码中的同名字样静默错抓
+  const pattern = new RegExp('^const ' + name + " = '([^']*)'", 'm')
+  const all = CLIENT_SOURCE.match(new RegExp(pattern.source, 'gm'))
+  assert.ok(all && all.length >= 1, 'client.js 缺少常量: ' + name)
+  assert.equal(all.length, 1, 'client.js 常量声明不唯一: ' + name)
+  return all[0].match(pattern)[1]
+}
+
+function extractNumberConst(name) {
+  const pattern = new RegExp('^const ' + name + ' = ([0-9 *]+)$', 'm')
+  const all = CLIENT_SOURCE.match(new RegExp(pattern.source, 'gm'))
+  assert.ok(all && all.length >= 1, 'client.js 缺少常量: ' + name)
+  assert.equal(all.length, 1, 'client.js 常量声明不唯一: ' + name)
+  return eval(all[0].match(pattern)[1])
+}
+
+const clientShouldReload = extractLogic('shouldReloadAfterRestart')
+const clientIsValidRegistryBase = extractLogic('isValidRegistryBase')
+
+// prev/next 为 {lost,pid,bootAt} 快照;lost 强信号优先;bootAt 双侧齐备时以其为唯一
+// 实例证据(自洽数据:不同进程 bootAt 必不同),pid 比对是 bootAt 缺失时的退化路径
+const RELOAD_CASES = [
+  { prev: { lost: true, pid: 1, bootAt: 1 }, next: { lost: false, pid: 1, bootAt: 1 }, expected: true },
+  { prev: { lost: false, pid: 7, bootAt: 100 }, next: { lost: false, pid: 8, bootAt: 200 }, expected: true },
+  { prev: { lost: false, pid: 7, bootAt: 100 }, next: { lost: false, pid: 7, bootAt: 100 }, expected: false },
+  { prev: { lost: false, pid: 1, bootAt: 100 }, next: { lost: false, pid: 1, bootAt: 200 }, expected: true, note: '容器 pid 恒 1 靠 bootAt' },
+  { prev: { lost: false, pid: 7, bootAt: null }, next: { lost: false, pid: 8, bootAt: 200 }, expected: true, note: 'bootAt 缺失退化 pid 比对' },
+  { prev: { lost: false, pid: 7, bootAt: null }, next: { lost: false, pid: 7, bootAt: 200 }, expected: false, note: 'bootAt 单侧缺失且 pid 未变' },
+  { prev: { lost: false, pid: null, bootAt: null }, next: { lost: false, pid: 8, bootAt: 200 }, expected: false },
+  { prev: { lost: false, pid: 7, bootAt: 100 }, next: { lost: false, pid: null, bootAt: null }, expected: false },
+  { prev: { lost: false, pid: undefined, bootAt: undefined }, next: { lost: false, pid: undefined, bootAt: undefined }, expected: false },
+  { prev: { lost: true, pid: null, bootAt: null }, next: { lost: false, pid: null, bootAt: null }, expected: true },
+]
+
+const REGISTRY_CASES = [
+  { value: 'https://registry.npmjs.org', expected: true },
+  { value: 'http://localhost:4873', expected: true },
+  { value: 'HTTPS://MIRROR.EXAMPLE', expected: true },
+  { value: '  https://padded.example  ', expected: true },
+  { value: 'ftp://registry.example', expected: false },
+  { value: 'registry.npmjs.org', expected: false },
+  { value: '', expected: false },
+  { value: null, expected: false },
+  { value: undefined, expected: false },
+  { value: 123, expected: false },
+  // query/hash 会在拼接 dist-tags 路径时吞掉 API 路径,收紧后一律拒绝
+  { value: 'https://example.com?mirror=1', expected: false },
+  { value: 'https://example.com#frag', expected: false },
+]
+
+test('parity: shouldReloadAfterRestart 双实现全场景一致', () => {
+  for (const { prev, next, expected, note } of RELOAD_CASES) {
+    assert.equal(coreShouldReload(prev, next), expected, 'core ' + JSON.stringify({ prev, next }) + (note ? ' ' + note : ''))
+    assert.equal(clientShouldReload(prev, next), expected, 'client ' + JSON.stringify({ prev, next }) + (note ? ' ' + note : ''))
+  }
+})
+
+test('parity: isValidRegistryBase 双实现全场景一致', () => {
+  for (const { value, expected } of REGISTRY_CASES) {
+    assert.equal(coreIsValidRegistryBase(value), expected, 'core ' + JSON.stringify(value))
+    assert.equal(clientIsValidRegistryBase(value), expected, 'client ' + JSON.stringify(value))
+  }
+})
+
+test('parity: VERDICT 三常量 client 与 core 一致', () => {
+  assert.equal(extractConst('VERDICT_OUTDATED'), VERDICT_OUTDATED)
+  assert.equal(extractConst('VERDICT_UP_TO_DATE'), VERDICT_UP_TO_DATE)
+  assert.equal(extractConst('VERDICT_UNKNOWN'), VERDICT_UNKNOWN)
+})
+
+// host 侧锚点直接 import index.js 实现,防测试内手抄字面量漂移假绿
+import { DEFAULT_UPGRADE_TEMPLATE, DEFAULT_POLL_INTERVAL_SEC, DEFAULT_REGISTRY_BASE, TICK_MS, API_PATHS, UPGRADE_TIMEOUT_MS } from '../src/index.js'
+
+test('parity: 默认升级命令模板 client 字面量与 host 实现一致', () => {
+  assert.equal(extractConst('DEFAULT_UPGRADE_TEMPLATE'), DEFAULT_UPGRADE_TEMPLATE)
+})
+
+test('parity: 默认轮询间隔与镜像地址 client 与 host 实现一致', () => {
+  assert.equal(extractNumberConst('DEFAULT_POLL_INTERVAL_SEC'), DEFAULT_POLL_INTERVAL_SEC)
+  assert.equal(extractConst('DEFAULT_REGISTRY_BASE'), DEFAULT_REGISTRY_BASE)
+})
+
+test('parity: client 轮询粒度提示与 host TICK_MS 换算一致', () => {
+  assert.equal(extractNumberConst('POLL_MIN_TICK_SECONDS'), TICK_MS / 1000)
+})
+
+test('parity: client API 路径常量与 host 路由清单逐条一致', () => {
+  // client 侧常量名带 _URL 后缀,host 侧 API_PATHS 键名即语义段
+  const CLIENT_KEY_BY_HOST_KEY = {
+    STATUS: 'STATUS_URL',
+    REFRESH: 'REFRESH_URL',
+    CHANNEL: 'CHANNEL_URL',
+    UPGRADE_TEMPLATE: 'TEMPLATE_URL',
+    POLL_INTERVAL: 'POLL_INTERVAL_URL',
+    REGISTRY_BASE: 'REGISTRY_BASE_URL',
+    UPGRADE: 'UPGRADE_URL',
+    RESTART: 'RESTART_URL',
+  }
+  for (const [hostKey, hostPath] of Object.entries(API_PATHS)) {
+    assert.equal(extractConst(CLIENT_KEY_BY_HOST_KEY[hostKey]), hostPath, 'API 路径漂移: ' + hostKey)
+  }
+})
+
+// 窗口关系对拍:重启等待总时长必须大于宿主退出延迟,否则宿主还在延迟退出窗口内客户端已报超时
+import { RESTART_DELAY_MS } from '../src/index.js'
+
+test('parity: 重启等待总时长大于宿主退出延迟', () => {
+  const restartTimeoutMs = extractNumberConst('RESTART_TIMEOUT_MS')
+  assert.ok(restartTimeoutMs > RESTART_DELAY_MS, 'RESTART_TIMEOUT_MS 必须大于 RESTART_DELAY_MS')
+})
+
+test('parity: 升级观察上限不早于宿主升级超时(防抢跑转状态未知)', () => {
+  const watchMaxMs = extractNumberConst('UPGRADE_WATCH_MAX_MS')
+  assert.ok(watchMaxMs >= UPGRADE_TIMEOUT_MS, 'UPGRADE_WATCH_MAX_MS(' + watchMaxMs + ') 必须不小于宿主 UPGRADE_TIMEOUT_MS(' + UPGRADE_TIMEOUT_MS + ')')
+})
+
+test('parity: npm 版本页链接与追踪包名同源', () => {
+  assert.ok(extractConst('NPM_VERSIONS_URL').includes(TARGET_PACKAGE), 'NPM_VERSIONS_URL 应包含 TARGET_PACKAGE 字面量')
+})
+
+test('源码契约: 重启轮询与升级观察器不得回退 setInterval 重叠拍形态', () => {
+  // 顺序循环 + 代际令牌是 R4 修复形态;setInterval 回归即重叠拍竞态回归
+  assert.ok(!/setInterval\(/.test(CLIENT_SOURCE), 'client.js 禁止 setInterval(拍自调度取代)')
+  assert.ok(CLIENT_SOURCE.includes('AbortSignal.timeout(UPGRADE_POLL_TIMEOUT_MS)'), '升级观察拍必须带请求超时')
+  assert.ok(CLIENT_SOURCE.includes('upgradeWatch.generation !== generation'), '升级观察拍 settle 后必须验代际')
+})