@mzzsfy/dsh-maintain 0.7.1 → 0.9.0

package/test/route.test.mjs

@@ -6,7 +6,7 @@ import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import { EventEmitter } from 'node:events'
 
-import { apply, RESTART_DELAY_MS, AUTO_RESTART_DELAY_MS, UPGRADE_LOCK_PATH, collectActiveWork } from '../src/index.js'
+import { apply, RESTART_DELAY_MS, AUTO_RESTART_DELAY_MS, UPGRADE_LOCK_PATH, RELEASE_NOTES_CACHE_MAX, collectActiveWork } from '../src/index.js'
 import { rmSync, readFileSync } from 'node:fs'
 
 // 锁文件是固定共享路径:测试进程中断可能残留幽灵锁毒化后续运行,用例前预热清理
@@ -137,10 +137,10 @@ const realSleep = (ms) => new Promise((resolve) => {
   setImmediate(spin)
 })
 
-test('挂载:8 条路由注册,启动检查后快照就绪', async () => {
+test('挂载:9 条路由注册,启动检查后快照就绪', async () => {
   const { ctx, routes } = makeCtx()
   apply(ctx)
-  assert.equal(routes.size, 8)
+  assert.equal(routes.size, 9)
   assert.deepEqual(
     [...routes.keys()].sort(),
     [
@@ -148,6 +148,7 @@ test('挂载:8 条路由注册,启动检查后快照就绪', async () => {
       '/api/maintain/poll-interval',
       '/api/maintain/refresh',
       '/api/maintain/registry-base',
+      '/api/maintain/release-notes',
       '/api/maintain/restart',
       '/api/maintain/status',
       '/api/maintain/upgrade',
@@ -156,16 +157,7 @@ test('挂载:8 条路由注册,启动检查后快照就绪', async () => {
   )
   // 启动检查是异步链(mock fetch 微任务 + resolveHostVersion 真实文件读),
   // 轮询等快照落定后再断言
-  let snapshotReady = false
-  for (let waited = 0; waited < 5000; waited += 25) {
-    const poll = await call(routes, '/api/maintain/status', makeReq({ method: 'GET' }))
-    if (poll.payload.checkedAt !== null) {
-      snapshotReady = true
-      break
-    }
-    await new Promise((resolve) => setTimeout(resolve, 25))
-  }
-  assert.ok(snapshotReady, '启动检查 5 秒内未完成')
+  assert.ok(await waitSnapshotReady(routes), '启动检查 5 秒内未完成')
   const res = await call(routes, '/api/maintain/status', makeReq({ method: 'GET' }))
   assert.equal(res.status, 200)
   assert.equal(res.payload.packageName, '@deepseek-ai/dsh')
@@ -209,8 +201,10 @@ test('interval dispose 回归:fiber 停用后轮询 tick 失效(防双 interval
 test('方法守卫:全部路由错误方法一律 405', async () => {
   const { ctx, routes } = makeCtx()
   apply(ctx)
+  // GET 端点(status/release-notes)以 POST 拒绝,其余以 GET 拒绝
+  const readPaths = ['/api/maintain/status', '/api/maintain/release-notes']
   for (const path of routes.keys()) {
-    const expected = path === '/api/maintain/status' ? 'POST' : 'GET'
+    const expected = readPaths.indexOf(path) >= 0 ? 'POST' : 'GET'
     const res = await call(routes, path, makeReq({ method: expected }))
     assert.equal(res.status, 405, path + ' 应拒绝 ' + expected)
   }
@@ -295,28 +289,38 @@ test('registry-base:非法 scheme 400;合法值持久化', async () => {
   assert.equal(store.registryBase, 'https://mirror.example')
 })
 
-test('upgrade:运行版本已是通道最新 409 拒绝(防降级),unknown 放行', async () => {
+test('upgrade:运行版本已是通道最新放行(重装/回退场景),不再 409 拒绝', async () => {
   const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
   // 版本探测注入受控值:CI 无 dsh 本体,真实盘读回 null 会把 verdict 打成 unknown,
-  // 防降级门控(核心断言)在 CI 恒不触发
+  // 重装放行断言(本用例核心)在 CI 恒不触发
   const { ctx, routes } = makeCtx({
     settingsStore: store,
     services: { hostVersionProbe: () => Promise.resolve('5.4.3') },
   })
   apply(ctx)
-  // 注入运行版本远低于假目标版本:verdict 应转 up-to-date,升级入口拒绝
+  // 注入运行版本远高于假目标版本:verdict 应转 up-to-date,安装入口照常放行
   const originalFetch = globalThis.fetch
   globalThis.fetch = async () => tagsBody({ latest: '0.0.1', next: '0.0.2' })
+  const warns = []
+  const originalWarn = console.warn
+  console.warn = (text) => warns.push(String(text))
   try {
     const refreshed = await post(routes, '/api/maintain/refresh')
     assert.equal(refreshed.status, 200)
     assert.equal(refreshed.payload.verdict, 'up-to-date', '前置:注入运行版本应高于 0.0.1 假目标')
-    const denied = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
-    assert.equal(denied.status, 409)
-    assert.match(denied.payload.error, /已是通道最新版/)
-    assert.equal(store.upgradeCommandTemplate, 'node -e "process.exit(0)"', '拒绝路径不得触发升级')
+    const accepted = await post(routes, '/api/maintain/upgrade', { autoRestart: true })
+    assert.equal(accepted.status, 200, '已是通道最新必须放行:重装修复与回退是显式用户意图')
+    assert.equal(accepted.payload.upgrade.running, true)
+    for (let i = 0; i < 50; i += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      const status = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
+      if (status && status.upgrade && status.upgrade.running === false && status.upgrade.last !== null) break
+    }
+    assert.equal(store.upgradeCommandTemplate, 'node -e "process.exit(0)"', '放行路径命令模板不得被改动')
+    assert.ok(warns.some((text) => /audit endpoint=upgrade outcome=triggered/.test(text)), '放行安装须留审计行')
   } finally {
     globalThis.fetch = originalFetch
+    console.warn = originalWarn
   }
 })
 
@@ -586,6 +590,39 @@ test('upgrade:未勾选自动重启,升级成功落定继续运行并标 stale',
   }
 })
 
+test('upgrade:模板钉定版本时按钉定意图判 fresh(通道目标不参与对拍)', async (t) => {
+  // 假命令携带钉定 token(参数位),语义等同 `npm i -g pkg@1.0.0` 但不真装
+  const store = { upgradeCommandTemplate: 'node -e "process.exit(0)" @deepseek-ai/dsh@1.0.0' }
+  const exits = []
+  const { ctx, routes } = makeCtx({
+    settingsStore: store,
+    appExit: (code) => exits.push(code),
+    // 探针恒读 1.0.0:钉定 1.0.0 时"磁盘未变"即达成,不得按通道目标误报 stale
+    services: { hostVersionProbe: () => Promise.resolve('1.0.0') },
+  })
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  apply(ctx)
+  await drainMicrotasks()
+  const trigger = await post(routes, '/api/maintain/upgrade', { autoRestart: false })
+  assert.equal(trigger.status, 200)
+  let settled = null
+  try {
+    for (let i = 0; i < 50 && settled === null; i += 1) {
+      await realSleep(30)
+      const status = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
+      if (status && status.upgrade && status.upgrade.running === false && status.upgrade.last !== null) settled = status
+    }
+    assert.ok(settled, '升级应在假命令退出后落定')
+    assert.equal(settled.upgrade.last.ok, true)
+    assert.equal(settled.upgrade.last.stale, false, '钉定版本装到位即达成')
+    assert.equal(settled.upgrade.last.reason, null)
+    t.mock.timers.tick(AUTO_RESTART_DELAY_MS + 1)
+    assert.deepEqual(exits, [])
+  } finally {
+    rmSync(UPGRADE_LOCK_PATH, { force: true })
+  }
+})
+
 test('upgrade:勾选自动重启+落定,延迟窗口后调度宿主退出', async (t) => {
   const store = { upgradeCommandTemplate: 'node -e "process.exit(0)"' }
   const exits = []
@@ -891,4 +928,216 @@ test('audit:触发/落定/拒绝各留一行结构化日志', async () => {
   }
   assert.equal(plainWarns.some((text) => /audit endpoint=upgrade outcome=triggered/.test(text)), true, '升级触发须留审计行')
   assert.equal(plainWarns.some((text) => /audit endpoint=upgrade outcome=(ok|failed) durationMs=[0-9]+ code=/.test(text)), true, '升级落定须留审计行')
-})
+})
+
+// ---- release notes 路由 ----
+
+const RELEASE_PATH = '/api/maintain/release-notes'
+// 发布页 fixture:与真实页面同构(relative-time + markdown-body 正文容器),正文映射由 core 提取器完成
+const RELEASE_HTML = '<!doctype html><html><body>'
+  + '<relative-time datetime="2026-09-10T03:09:00Z"></relative-time>'
+  + '<div data-test-selector="body-content" class="markdown-body">'
+  + '<h3>更新内容</h3>'
+  + '<ul><li>新功能</li><li>问题修复</li></ul>'
+  + '<p>详情见发布页。</p>'
+  + '</div></body></html>'
+const RELEASE_URL = 'https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v9.9.9'
+const RELEASE_BODY = ['### 更新内容', '- 新功能', '- 问题修复', '', '详情见发布页。'].join('\n')
+
+function releaseHtmlBody() {
+  const chunks = [new TextEncoder().encode(RELEASE_HTML)]
+  return {
+    getReader: () => ({
+      read: async () => (chunks.length ? { done: false, value: chunks.shift() } : { done: true, value: undefined }),
+      cancel: async () => {},
+    }),
+  }
+}
+
+// dist-tags 与 GitHub 发布页双上游分流:registry 路径回 tags 形态,GitHub 路径回页面形态
+function installDualUpstream({ requestedUrls, releaseThrows }) {
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = async (url, options) => {
+    const text = String(url)
+    if (text.includes('/releases/tag/')) {
+      requestedUrls.push(text)
+      if (releaseThrows) throw new Error(releaseThrows)
+      return { ok: true, status: 200, body: releaseHtmlBody() }
+    }
+    void options
+    return tagsBody(MOCK_TAGS)
+  }
+  return () => { globalThis.fetch = originalFetch }
+}
+
+async function waitSnapshotReady(routes) {
+  for (let waited = 0; waited < 5000; waited += 25) {
+    const poll = await get(routes, '/api/maintain/status').then((r) => r.payload).catch(() => null)
+    if (poll && poll.checkedAt !== null) return poll
+    await new Promise((resolve) => setTimeout(resolve, 25))
+  }
+  return null
+}
+
+test('release-notes:默认取通道最新版,200 返回发布说明', async () => {
+  const requestedUrls = []
+  const restore = installDualUpstream({ requestedUrls })
+  try {
+    const { ctx, routes } = makeCtx({ services: { hostVersionProbe: () => Promise.resolve('5.4.3') } })
+    apply(ctx)
+    assert.ok(await waitSnapshotReady(routes), '启动检查 5 秒内未完成')
+    const res = await get(routes, RELEASE_PATH)
+    assert.equal(res.status, 200)
+    assert.deepEqual(res.payload, {
+      version: '9.9.9',
+      url: RELEASE_URL,
+      publishedAt: '2026-09-10T03:09:00Z',
+      body: RELEASE_BODY,
+    })
+    assert.equal(requestedUrls.length, 1)
+    assert.ok(requestedUrls[0].endsWith('/releases/tag/dsh-v9.9.9'), '默认版本必须取通道 latest 的目标')
+  } finally {
+    restore()
+  }
+})
+
+test('release-notes:缓存生效,切通道后按新通道版本拉取', async () => {
+  const requestedUrls = []
+  const restore = installDualUpstream({ requestedUrls })
+  try {
+    const { ctx, routes } = makeCtx()
+    apply(ctx)
+    assert.ok(await waitSnapshotReady(routes), '启动检查 5 秒内未完成')
+    const first = await get(routes, RELEASE_PATH)
+    assert.equal(first.status, 200)
+    assert.equal(first.payload.version, '9.9.9')
+    assert.ok(requestedUrls[0].endsWith('/releases/tag/dsh-v9.9.9'))
+    const again = await get(routes, RELEASE_PATH)
+    assert.equal(again.status, 200)
+    assert.equal(requestedUrls.length, 1, '同版本两次调用必须命中缓存,上游仅一次')
+    const switched = await post(routes, '/api/maintain/channel', { channel: 'next' })
+    assert.equal(switched.status, 200)
+    assert.equal(switched.payload.channelLatest, '10.0.0')
+    const after = await get(routes, RELEASE_PATH)
+    assert.equal(after.status, 200)
+    assert.equal(after.payload.version, '10.0.0')
+    assert.equal(requestedUrls.length, 2, '通道版本变化必须重新拉取')
+    assert.ok(requestedUrls[1].endsWith('/releases/tag/dsh-v10.0.0'))
+  } finally {
+    restore()
+  }
+})
+
+test('release-notes:tags 未就绪且无 version 400 提示先检查更新', async () => {
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = async () => { throw new Error('ECONNREFUSED') }
+  try {
+    const { ctx, routes } = makeCtx()
+    apply(ctx)
+    assert.ok(await waitSnapshotReady(routes), '启动检查 5 秒内未完成')
+    const res = await get(routes, RELEASE_PATH)
+    assert.equal(res.status, 400)
+    assert.match(res.payload.error, /检查更新/)
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
+
+test('release-notes:通道标签非 semver,构建上游标签前归一 400', async () => {
+  const requestedUrls = []
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = async (url, options) => {
+    const text = String(url)
+    if (text.includes('/releases/tag/')) {
+      requestedUrls.push(text)
+      return { ok: true, status: 200, body: releaseHtmlBody() }
+    }
+    return tagsBody({ latest: 'banana' })
+  }
+  try {
+    const { ctx, routes } = makeCtx()
+    apply(ctx)
+    assert.ok(await waitSnapshotReady(routes), '启动检查 5 秒内未完成')
+    const res = await get(routes, RELEASE_PATH)
+    assert.equal(res.status, 400)
+    assert.match(res.payload.error, /semver/, '病理标签必须在触达上游前被 semver 白名单拦截')
+    assert.equal(requestedUrls.length, 0, '拒绝路径不得触达上游')
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
+
+test('release-notes:重启调度窗口内 409,不发起上游请求', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] })
+  const requestedUrls = []
+  const restore = installDualUpstream({ requestedUrls })
+  try {
+    const { ctx, routes } = makeCtx({ appExit: () => {} })
+    apply(ctx)
+    const restart = await post(routes, '/api/maintain/restart')
+    assert.equal(restart.status, 200)
+    const res = await get(routes, RELEASE_PATH)
+    assert.equal(res.status, 409, '关机窗口内查询更新内容必须拒绝')
+    assert.match(res.payload.error, /重启已调度/)
+    assert.equal(requestedUrls.length, 0, '关机窗口内不得发起上游请求')
+    t.mock.timers.tick(RESTART_DELAY_MS + 1)
+  } finally {
+    restore()
+  }
+})
+
+test('release-notes:缓存超限 FIFO 淘汰,最早键被逐出', async () => {
+  // N+1 个通道各配独立版本:逐个切换并查看,第 N+1 键入缓存时第 1 键必被淘汰;
+  // 回访第 1 通道触发重新拉取,回访末位通道命中缓存不再拉取
+  const channels = {}
+  for (let i = 1; i <= RELEASE_NOTES_CACHE_MAX + 1; i += 1) channels['c' + i] = '1.0.' + i
+  const requestedUrls = []
+  const originalFetch = globalThis.fetch
+  globalThis.fetch = async (url) => {
+    if (String(url).includes('/releases/tag/')) {
+      requestedUrls.push(String(url))
+      return { ok: true, status: 200, body: releaseHtmlBody() }
+    }
+    return tagsBody(channels)
+  }
+  try {
+    const { ctx, routes } = makeCtx()
+    apply(ctx)
+    assert.ok(await waitSnapshotReady(routes), '启动检查 5 秒内未完成')
+    for (const [name, version] of Object.entries(channels)) {
+      const switched = await post(routes, '/api/maintain/channel', { channel: name })
+      assert.equal(switched.status, 200)
+      const res = await get(routes, RELEASE_PATH)
+      assert.equal(res.status, 200)
+      assert.equal(res.payload.version, version)
+    }
+    assert.equal(requestedUrls.length, RELEASE_NOTES_CACHE_MAX + 1, '每通道版本独立,各拉取一次')
+    const first = Object.keys(channels)[0]
+    const last = Object.keys(channels)[RELEASE_NOTES_CACHE_MAX]
+    const backToFirst = await post(routes, '/api/maintain/channel', { channel: first })
+    assert.equal(backToFirst.status, 200)
+    await get(routes, RELEASE_PATH)
+    assert.equal(requestedUrls.length, RELEASE_NOTES_CACHE_MAX + 2, '最早键已被淘汰,回访必须重新拉取')
+    const backToLast = await post(routes, '/api/maintain/channel', { channel: last })
+    assert.equal(backToLast.status, 200)
+    await get(routes, RELEASE_PATH)
+    assert.equal(requestedUrls.length, RELEASE_NOTES_CACHE_MAX + 2, '未淘汰键回访必须命中缓存')
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})
+
+test('release-notes:上游失败 400 带错误信息', async () => {
+  const requestedUrls = []
+  const restore = installDualUpstream({ requestedUrls, releaseThrows: 'ECONNRESET' })
+  try {
+    const { ctx, routes } = makeCtx()
+    apply(ctx)
+    assert.ok(await waitSnapshotReady(routes), '启动检查 5 秒内未完成')
+    const res = await get(routes, RELEASE_PATH)
+    assert.equal(res.status, 400)
+    assert.match(res.payload.error, /ECONNRESET/)
+  } finally {
+    restore()
+  }
+})