@mzzsfy/dsh-maintain 0.5.3 → 0.6.1

package/test/client-scope.test.mjs

@@ -0,0 +1,54 @@
+// client.js 求值形态守卫:宿主以经典 script 整源求值,顶层词法声明落页面全局词法环境,
+// 跨 bundle 同名即整脚本 SyntaxError 拒载。本包 client.js 以单条 __ModuleLoader__.load
+// 语句承载全部代码(声明均在 factory 作用域内),本守卫锁定"顶层零词法声明"不变量,
+// 防未来声明误置顶层。vm.runInContext 与浏览器经典 script 同语义(全局词法环境跨脚本共享)。
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import vm from 'node:vm'
+
+const CLIENT_SOURCE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'client.js'), 'utf8').trimEnd()
+const DECLARATION_NAMES = [
+  ...new Set(
+    [...CLIENT_SOURCE.matchAll(/^(?:const|let|var|class|(?:async )?function\*?) ([A-Za-z_$][\w$]*)/gm)].map((match) => match[1])
+  ),
+]
+const BUNDLE_ID = '@mzzsfy/dsh-maintain'
+
+test('Given 同 context 已有外部 CSS 声明(宿主经典 script 全局词法环境), When 整源求值 client.js, Then 双源共存不拒载且外部声明原值不变', () => {
+  const ctx = vm.createContext({ window: { __ModuleLoader__: { load: () => {} } } })
+  vm.runInContext('const CSS = 1', ctx)
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  assert.equal(vm.runInContext('CSS', ctx), 1)
+})
+
+test('Given client.js 已整源求值, When 同 context 再声明外部 CSS, Then 双源共存不拒载', () => {
+  const ctx = vm.createContext({ window: { __ModuleLoader__: { load: () => {} } } })
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  vm.runInContext('const CSS = 1', ctx)
+})
+
+test('Given client.js 整源求值完成, When 逐名以 const 重声明探针行首声明名, Then 全局词法环境零泄漏', () => {
+  const ctx = vm.createContext({ window: { __ModuleLoader__: { load: () => {} } } })
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  const leaked = DECLARATION_NAMES.filter((name) => {
+    try {
+      vm.runInContext(`const ${name} = null`, ctx)
+      return false
+    } catch {
+      return true
+    }
+  })
+  assert.deepEqual(leaked, [])
+})
+
+test('Given 宿主 loader 就绪, When 整源求值 client.js, Then 自注册照常发生且 id 不变', () => {
+  const registrations = []
+  const ctx = vm.createContext({ window: { __ModuleLoader__: { load: (registration) => registrations.push(registration) } } })
+  vm.runInContext(CLIENT_SOURCE, ctx)
+  assert.equal(registrations.length, 1)
+  assert.equal(registrations[0].id, BUNDLE_ID)
+  assert.equal(typeof registrations[0].factory, 'function')
+})

package/test/core.test.mjs

@@ -5,6 +5,9 @@ import {
   parseSemver,
   gtSemver,
   judgeVersion,
+  judgeUpgradeFreshness,
+  isVersionPendingRestart,
+  classifyUpgradeFailure,
   buildUpgradeCommand,
   isValidChannelName,
   isValidRegistryBase,
@@ -12,6 +15,11 @@ import {
   VERDICT_OUTDATED,
   VERDICT_UP_TO_DATE,
   VERDICT_UNKNOWN,
+  UPGRADE_FAIL_TRANSIENT_NETWORK,
+  UPGRADE_FAIL_FILE_LOCKED,
+  UPGRADE_FAIL_NPM_MISSING,
+  UPGRADE_FAIL_TIMEOUT,
+  UPGRADE_FAIL_UNKNOWN,
 } from '../src/core.mjs'
 
 const CURRENT = '0.1.1-rc.2'
@@ -174,3 +182,130 @@ test('场景:未失联且实例标识未变不刷新', () => {
   // bootAt 单侧出现不构成证据(防旧宿主快照缺字段误判)
   assert.equal(shouldReloadAfterRestart({ lost: false, pid: 100, bootAt: null }, { lost: false, pid: 100, bootAt: 200 }), false)
 })
+
+// 升级失败分类:npm 输出特征取自 npm 10/11 真实错误行形态(npm error code/syscall),
+// 特征未命中一律宽松归 unknown,不可重试类绝不重试。
+test('分类:Windows 文件锁形态归 file-locked 且可重试', () => {
+  const samples = [
+    'npm error code EBUSY\nnpm error syscall rename\nnpm error path C:\\nvm\\node_modules\\@deepseek-ai\\dsh\\package.json',
+    'npm error code EPERM\nnpm error syscall unlink\nnpm error path C:\\nvm\\node_modules\\.bin\\dsh.cmd',
+    'npm error code ENOENT\nnpm error syscall rename\nnpm error path C:\\nvm\\node_modules\\@deepseek-ai\\dsh',
+    'C:\\nvm\\node_modules\\@deepseek-ai\\dsh\\lib\\index.js is being used by another process',
+    'EBUSY: resource busy or locked, unlink C:\\nvm\\node_modules\\@deepseek-ai\\dsh\\lib\\index.js',
+  ]
+  for (const stderrTail of samples) {
+    const result = classifyUpgradeFailure({ code: 1, timedOut: false, stillRunning: false, stdoutTail: '', stderrTail })
+    assert.equal(result.kind, UPGRADE_FAIL_FILE_LOCKED, stderrTail)
+    assert.equal(result.retryable, true, stderrTail)
+    assert.ok(typeof result.reason === 'string' && result.reason.length > 0)
+  }
+})
+
+test('分类:网络瞬断形态归 transient-network 且可重试', () => {
+  const samples = [
+    'npm error network request to https://registry.npmjs.org/@deepseek-ai%2fdsh failed, reason: socket hang up',
+    'npm error code ECONNRESET\nnpm error errno ECONNRESET\nnpm error network This is a problem related to network connectivity.',
+    'npm error code EAI_AGAIN\nnpm error syscall getaddrinfo',
+    'npm error code ECONNREFUSED',
+    'fetch failed',
+    'npm error code E503\nnpm error 503 Service Unavailable - GET https://registry.npmjs.org/dsh',
+  ]
+  for (const stderrTail of samples) {
+    const result = classifyUpgradeFailure({ code: 1, timedOut: false, stillRunning: false, stdoutTail: '', stderrTail })
+    assert.equal(result.kind, UPGRADE_FAIL_TRANSIENT_NETWORK, stderrTail)
+    assert.equal(result.retryable, true, stderrTail)
+  }
+})
+
+test('分类:命令未找到形态归 npm-missing 且不可重试', () => {
+  const samples = [
+    "'npmm' 不是内部或外部命令,也不是可运行的程序或批处理文件。",
+    '/bin/sh: 1: npmm: command not found',
+    '/bin/sh: 1: npmm: not found',
+    'spawn npmm ENOENT',
+  ]
+  for (const stderrTail of samples) {
+    const result = classifyUpgradeFailure({ code: 1, timedOut: false, stillRunning: false, stdoutTail: '', stderrTail })
+    assert.equal(result.kind, UPGRADE_FAIL_NPM_MISSING, stderrTail)
+    assert.equal(result.retryable, false, stderrTail)
+  }
+})
+
+test('分类:超时强杀优先归 timeout,尾流含文件锁特征也不重试', () => {
+  const result = classifyUpgradeFailure({ code: null, timedOut: true, stillRunning: false, stdoutTail: '', stderrTail: 'npm error code EBUSY' })
+  assert.equal(result.kind, UPGRADE_FAIL_TIMEOUT)
+  assert.equal(result.retryable, false)
+})
+
+test('分类:未识别输出归 unknown 兜底且不可重试', () => {
+  for (const input of [
+    { code: 3, timedOut: false, stillRunning: false, stdoutTail: '', stderrTail: 'boom-fail' },
+    { code: 1, timedOut: false, stillRunning: false, stdoutTail: '', stderrTail: '' },
+    { code: null, timedOut: false, stillRunning: true, stdoutTail: '', stderrTail: '' },
+    { code: 1, timedOut: false, stillRunning: false, stdoutTail: 'npm warn deprecated x', stderrTail: 'exit 1' },
+  ]) {
+    const result = classifyUpgradeFailure(input)
+    assert.equal(result.kind, UPGRADE_FAIL_UNKNOWN, JSON.stringify(input))
+    assert.equal(result.retryable, false, JSON.stringify(input))
+  }
+})
+
+test('分类:stdout 尾流特征同样参与匹配', () => {
+  const result = classifyUpgradeFailure({ code: 1, timedOut: false, stillRunning: false, stdoutTail: 'npm error code EBUSY', stderrTail: '' })
+  assert.equal(result.kind, UPGRADE_FAIL_FILE_LOCKED)
+  assert.equal(result.retryable, true)
+})
+
+test('分类:输入字段缺省容忍不抛错', () => {
+  const result = classifyUpgradeFailure({})
+  assert.equal(result.kind, UPGRADE_FAIL_UNKNOWN)
+  assert.equal(result.retryable, false)
+  assert.ok(typeof result.reason === 'string')
+})
+
+// 升级后磁盘版本复读判定:stale=版本未前进或未达通道目标;信息缺失宽松不误报。
+test('复读:版本前进且达通道目标判 fresh', () => {
+  assert.deepEqual(judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: '2.0.0', channelLatest: '2.0.0' }), { stale: false, reason: null })
+  // prerelease 目标达成也算 fresh;prerelease 低于正式版属未达目标(见下例)
+  assert.deepEqual(judgeUpgradeFreshness({ previousVersion: '2.0.0', installedVersion: '2.1.0-rc.1', channelLatest: '2.1.0-rc.1' }), { stale: false, reason: null })
+})
+
+test('复读:磁盘版本未前进或回退判 stale', () => {
+  const same = judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: '1.0.0', channelLatest: '2.0.0' })
+  assert.equal(same.stale, true)
+  assert.match(same.reason, /未前进/)
+  const rollback = judgeUpgradeFreshness({ previousVersion: '2.0.0', installedVersion: '1.9.0', channelLatest: '2.0.0' })
+  assert.equal(rollback.stale, true)
+})
+
+test('复读:前进但未达通道目标判 stale', () => {
+  const result = judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: '1.5.0', channelLatest: '2.0.0' })
+  assert.equal(result.stale, true)
+  assert.match(result.reason, /未达/)
+})
+
+// 运行/已装版本区分:磁盘版本领先运行版本即待重启生效;任一侧不可解析一律 false 不误报。
+test('重启待生效:仅已装版本严格领先运行版本时为真', () => {
+  assert.equal(isVersionPendingRestart({ runningVersion: '1.0.0', installedVersion: '2.0.0' }), true)
+  assert.equal(isVersionPendingRestart({ runningVersion: '2.1.0-rc.1', installedVersion: '2.1.0' }), true)
+  assert.equal(isVersionPendingRestart({ runningVersion: '2.0.0', installedVersion: '2.0.0' }), false)
+  assert.equal(isVersionPendingRestart({ runningVersion: '3.0.0', installedVersion: '2.0.0' }), false)
+  assert.equal(isVersionPendingRestart({ runningVersion: null, installedVersion: '2.0.0' }), false)
+  assert.equal(isVersionPendingRestart({ runningVersion: '2.0.0', installedVersion: null }), false)
+  assert.equal(isVersionPendingRestart({ runningVersion: 'dev-main', installedVersion: '2.0.0' }), false)
+})
+
+test('复读:installed 解析失败判 stale,previous 缺失不豁免未达目标', () => {
+  const broken = judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: null, channelLatest: '2.0.0' })
+  assert.equal(broken.stale, true)
+  assert.match(broken.reason, /解析失败|读取/)
+  const garbage = judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: 'dev-main', channelLatest: '2.0.0' })
+  assert.equal(garbage.stale, true)
+  // 旧版本未知只豁免"未前进"分支:磁盘低于通道目标仍判 stale
+  const unknownPrevious = judgeUpgradeFreshness({ previousVersion: null, installedVersion: '1.5.0', channelLatest: '2.0.0' })
+  assert.equal(unknownPrevious.stale, true)
+  assert.match(unknownPrevious.reason, /未达/)
+  assert.deepEqual(judgeUpgradeFreshness({ previousVersion: null, installedVersion: '2.0.0', channelLatest: '2.0.0' }), { stale: false, reason: null })
+  // 通道目标缺失时无法证明未达标,宽松判 fresh
+  assert.deepEqual(judgeUpgradeFreshness({ previousVersion: '1.0.0', installedVersion: '2.0.0', channelLatest: null }), { stale: false, reason: null })
+})

package/test/parity.test.mjs

@@ -16,6 +16,7 @@ import {
   TARGET_PACKAGE,
 } from '../src/core.mjs'
 import { clientSource, extractLogic } from './logic-extract.mjs'
+import { KILL_GRACE_MS } from '../src/upgrade.mjs'
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
 const CLIENT_SOURCE = clientSource()
@@ -92,7 +93,17 @@ test('parity: VERDICT 三常量 client 与 core 一致', () => {
 })
 
 // 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'
+import {
+  DEFAULT_UPGRADE_TEMPLATE,
+  DEFAULT_POLL_INTERVAL_SEC,
+  DEFAULT_REGISTRY_BASE,
+  TICK_MS,
+  API_PATHS,
+  UPGRADE_TIMEOUT_MS,
+  UPGRADE_MAX_ATTEMPTS,
+  UPGRADE_RETRY_BACKOFF_MS,
+  AUTO_RESTART_DELAY_MS,
+} from '../src/index.js'
 
 test('parity: 默认升级命令模板 client 字面量与 host 实现一致', () => {
   assert.equal(extractConst('DEFAULT_UPGRADE_TEMPLATE'), DEFAULT_UPGRADE_TEMPLATE)
@@ -132,15 +143,31 @@ test('parity: 重启等待总时长大于宿主退出延迟', () => {
   assert.ok(restartTimeoutMs > RESTART_DELAY_MS, 'RESTART_TIMEOUT_MS 必须大于 RESTART_DELAY_MS')
 })
 
-test('parity: 升级观察上限不早于宿主升级超时(防抢跑转状态未知)', () => {
+test('parity: 升级观察上限覆盖宿主重试链上限(防抢跑转状态未知)', () => {
+  // 重试链上限 = 尝试次数×单次超时 + 最大退避累计 + 强杀宽限;超时强杀只会终止链,不叠加
+  const maxBackoffTotal = Object.values(UPGRADE_RETRY_BACKOFF_MS)
+    .reduce((max, seq) => Math.max(max, seq.reduce((sum, ms) => sum + ms, 0)), 0)
+  const chainUpperBound = UPGRADE_MAX_ATTEMPTS * UPGRADE_TIMEOUT_MS + maxBackoffTotal + KILL_GRACE_MS
   const watchMaxMs = extractNumberConst('UPGRADE_WATCH_MAX_MS')
-  assert.ok(watchMaxMs >= UPGRADE_TIMEOUT_MS, 'UPGRADE_WATCH_MAX_MS(' + watchMaxMs + ') 必须不小于宿主 UPGRADE_TIMEOUT_MS(' + UPGRADE_TIMEOUT_MS + ')')
+  assert.ok(
+    watchMaxMs >= chainUpperBound,
+    'UPGRADE_WATCH_MAX_MS(' + watchMaxMs + ') 必须不小于重试链上限(' + chainUpperBound + ')',
+  )
 })
 
 test('parity: npm 版本页链接与追踪包名同源', () => {
   assert.ok(extractConst('NPM_VERSIONS_URL').includes(TARGET_PACKAGE), 'NPM_VERSIONS_URL 应包含 TARGET_PACKAGE 字面量')
 })
 
+test('parity: 落定补查宽限覆盖宿主自动重启调度延迟', () => {
+  // 落定拍与调度置位之间存在宿主侧 await 窗口:client 补查宽限必须不小于调度延迟 + 观察裕量
+  const graceMs = extractNumberConst('UPGRADE_AUTO_RESTART_GRACE_MS')
+  assert.ok(
+    graceMs >= AUTO_RESTART_DELAY_MS + 1 * 1000,
+    'UPGRADE_AUTO_RESTART_GRACE_MS(' + graceMs + ') 必须不小于 AUTO_RESTART_DELAY_MS(' + AUTO_RESTART_DELAY_MS + ') 加观察裕量',
+  )
+})
+
 test('源码契约: 重启轮询与升级观察器不得回退 setInterval 重叠拍形态', () => {
   // 顺序循环 + 代际令牌是 R4 修复形态;setInterval 回归即重叠拍竞态回归
   assert.ok(!/setInterval\(/.test(CLIENT_SOURCE), 'client.js 禁止 setInterval(拍自调度取代)')

package/test/restart-ready.test.mjs

@@ -188,15 +188,6 @@ test('restartPostLost: 无应答失败(网络/中止)属于失联', () => {
   assert.equal(clientRestartPostLost('boom'), true)
 })
 
-test('apiError: 携带 status 与 payload.error,解析失败回退 HTTP 码', () => {
-  const withBody = clientApiError({ status: 409 }, { error: '升级进行中,禁止重启;等待升级完成后重试' })
-  assert.equal(withBody.status, 409)
-  assert.equal(withBody.message, '升级进行中,禁止重启;等待升级完成后重试')
-  const withoutBody = clientApiError({ status: 500 }, {})
-  assert.equal(withoutBody.status, 500)
-  assert.equal(withoutBody.message, 'HTTP 500')
-})
-
 test('restartTick 调用点实参完整性:轮询 effect 必须传 readyStreak=prev.readyStreak', () => {
   // 回归:f58f47b 给 restartTick 加 readyStreak 参数时调用点漏传,ready=true 分支
   // undefined+1=NaN,NaN>=门槛恒 false,宿主恢复后页面永不自动刷新。
@@ -205,3 +196,68 @@ test('restartTick 调用点实参完整性:轮询 effect 必须传 readyStreak=p
   assert.ok(callSite, 'client.js 找不到 effect 内 restartTick 调用点')
   assert.match(callSite[1], /readyStreak:\s*prev\.readyStreak/, 'restartTick 调用点缺少 readyStreak: prev.readyStreak 实参')
 })
+
+// 升级浮条终态文案:ok 落定后 stale / 手动直跑 / 自动重启三条终态分流,失败与未知不在此列
+const clientUpgradeFinalText = extractLogic('upgradeFinalText')
+
+// 重启确认态文案:armed 且有活跃计数时改「仍要重启」
+const clientRestartConfirmLabel = extractLogic('restartConfirmLabel')
+
+test('upgradeFinalText: stale 优先于两种重启指引,不得引导重启', () => {
+  const text = clientUpgradeFinalText({ ok: true, stale: true, requiresManualRestart: true, autoRestartScheduled: true })
+  assert.match(text, /未前进|未达目标/)
+  assert.doesNotMatch(text, /重启/)
+})
+
+test('upgradeFinalText: 手动直跑终态指向手动重启,自动重启终态指向页面自恢复', () => {
+  assert.match(clientUpgradeFinalText({ ok: true, stale: false, requiresManualRestart: true, autoRestartScheduled: false }), /手动重启/)
+  assert.match(clientUpgradeFinalText({ ok: true, stale: false, requiresManualRestart: false, autoRestartScheduled: true }), /自动重启/)
+  // 默认成功终态
+  assert.match(clientUpgradeFinalText({ ok: true, stale: false, requiresManualRestart: false, autoRestartScheduled: false }), /重启宿主/)
+})
+
+test('restartConfirmLabel: armed 且活跃计数>0 才显示仍要重启文案', () => {
+  assert.equal(clientRestartConfirmLabel(false, 0), '重启宿主')
+  assert.equal(clientRestartConfirmLabel(true, 0), '确认重启')
+  assert.equal(clientRestartConfirmLabel(false, 3), '重启宿主', '未进入确认态不得显示仍要重启')
+  assert.equal(clientRestartConfirmLabel(true, 3), '仍要重启(3 项活跃工作)')
+})
+
+test('client 自动重启接管:单一守卫函数,订阅回调与初始加载两路同走', () => {
+  const source = clientSource()
+  const guardFn = source.match(/function takeOverAutoRestart\(snapshot\)\s*\{([\s\S]*?)\n  \}/)
+  assert.ok(guardFn, 'client.js 缺少 takeOverAutoRestart 接管守卫')
+  assert.match(guardFn[1], /autoRestartScheduled !== true/, '守卫必须以 autoRestartScheduled 触发')
+  assert.match(guardFn[1], /restartPendingRef\.current === true/, '重启 POST 在途不得接管')
+  assert.match(guardFn[1], /autoRestartTakenRef\.current === true/, '不得重复接管')
+  assert.match(guardFn[1], /pid:\s*snapshot\.pid/, '接管基线必须取快照 pid')
+  assert.match(guardFn[1], /bootAt:\s*snapshot\.bootAt/, '接管基线必须取快照 bootAt')
+  // 两路调用:观察器订阅回调(升级落定拍)+ 初始 load 快照(页面刷新落在调度窗口)
+  assert.match(source, /subscribeUpgradeStatus\(\(snapshot\)\s*=>\s*\{[\s\S]*?takeOverAutoRestart\(snapshot\)/, '订阅回调必须走接管守卫')
+  assert.match(source, /void load\(\)\.then\(\(next\)\s*=>\s*\{[\s\S]*?takeOverAutoRestart\(next\)/, '初始快照必须走接管守卫')
+})
+
+test('client 落定补查:未见自动重启标记时延迟宽限补查一拍再终判', () => {
+  const source = clientSource()
+  // 落定拍 running 翻转与宿主置调度标记之间存在 await 窗口:未见标记不得立即终判
+  assert.match(source, /setTimeout\(\(\)\s*=>\s*\{[\s\S]*?recheckUpgradeSettle\(/, '落定拍未见标记必须延迟补查')
+  assert.match(source, /async function recheckUpgradeSettle\([\s\S]*?broadcastUpgradeStatus\(final\)/, '补查必须广播以驱动接管守卫')
+  assert.match(source, /upgradeWatch\.generation !== null\) return[\s\S]*?recheckUpgradeSettle|recheckUpgradeSettle\([\s\S]*?upgradeWatch\.generation !== null\) return/, '补查前后必须验让位新观察')
+})
+
+test('force 发送条件锁定:仅活跃计数>0 的重启确认带 force', () => {
+  const callSite = clientSource().match(/post\(RESTART_URL,\s*([^)]+)\)/)
+  assert.ok(callSite, 'client.js 找不到重启 POST 调用点')
+  assert.match(callSite[1], /activeWorkTotal > 0 \? \{ force: true \} : undefined/, 'force 必须仅在活跃计数>0 时携带')
+})
+
+test('apiError: 携带 status 与完整 payload,解析失败回退 HTTP 码', () => {
+  const withBody = clientApiError({ status: 409 }, { error: '升级进行中,禁止重启;等待升级完成后重试', items: { total: 2 } })
+  assert.equal(withBody.status, 409)
+  assert.equal(withBody.message, '升级进行中,禁止重启;等待升级完成后重试')
+  assert.deepEqual(withBody.payload, { error: '升级进行中,禁止重启;等待升级完成后重试', items: { total: 2 } }, 'payload 必须挂在错误对象上供回写计数')
+  const withoutBody = clientApiError({ status: 500 }, {})
+  assert.equal(withoutBody.status, 500)
+  assert.equal(withoutBody.message, 'HTTP 500')
+  assert.deepEqual(withoutBody.payload, {})
+})