dsh-pwsh-plugin 0.2.14 → 0.2.16

package/plugin/update-apply.mjs

@@ -1,274 +0,0 @@
-/**
- * 把「查到新版本」变成「装上新版本」——走 DSH 自己的 pluginManager，不自己下载覆盖文件。
- *
- * 为什么不学 our-free-model 自带下载器
- *   那个插件是独立包，安装目录里就是自己那几十个文件，所以它能做「清单签名 + 逐文件 sha256 +
- *   备份 + 原地替换 + 热重载回滚」这一整套事务。本插件是 profile 里的一个 bundle 依赖：
- *   文件躺在 node_modules/dsh-pwsh-plugin，版本钉在 profile 的 package.json 与 pnpm-lock.yaml 里。
- *   绕开包管理器去改这些文件，会立刻让 lockfile 与磁盘不一致，下一次 dsh plugin add/remove 就会
- *   踩到脏状态。所以安装这一步交给 dsh-plugin-manager（Plugins 页面用的同一个服务），
- *   它自己跑 pnpm、自己回滚 package.json / lockfile。
- *
- * 为什么装完必须回读磁盘版本
- *   pnpm 有供应链冷却期（minimumReleaseAge，v11 起默认 1440 分钟）。请求 dsh-pwsh-plugin@0.2.13
- *   而该版本刚发布几小时，pnpm 会装到它能接受的那个版本；installBundle 的返回值里没有版本号，
- *   只有 application 这个枚举。所以「装了什么」只能从装完的 package.json 读回来 ——
- *   把这里的判决当成既成事实去宣称，就是在说一句没人验证过的话。
- *
- * 能不能不重启
- *   bundle 行的 name 是包名，拿不到 URL 上的缓存破坏参数，ESM 按 URL 缓存模块 —— 光重新 apply
- *   只是再 import 同一个 URL。但 installBundle 走 HMR 的 runExclusive，重组合会比对文件指纹
- *   （inode:size:mtime），把变了的模块驱逐、重新 import，所以**在 HMR 在场的宿主上是真换掉了**，
- *   实测 137ms 生效。前提是调用点在 HMR 事务之外，否则嵌套会被拒（见 auto-update.mjs）。
- *   没有 HMR 的宿主上 application 才是 'restart-required'，这里照实转述。
- */
-
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-
-import { compareVersions, packageVersion } from './update-check.mjs'
-
-/** 本包的包名：profile 的 dependencies 用它记录安装规格。 */
-const OWN_NAME = (() => {
-  try {
-    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
-    return typeof pkg.name === 'string' && pkg.name.length > 0 ? pkg.name : 'dsh-pwsh-plugin'
-  } catch {
-    return 'dsh-pwsh-plugin'
-  }
-})()
-
-/** `v1.2.3` 与 `1.2.3` 是同一个版本；不是这个形态时返回 undefined。 */
-export function bareVersion(value) {
-  const text = String(value ?? '').trim().replace(/^v/i, '')
-  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(text) ? text : undefined
-}
-
-/**
- * 安装规格末尾钉的版本：`dsh-pwsh-plugin@1.2.3` → `1.2.3`。
- *
- * 只认包名之后的那一段：npm 规格里 @ 既是 scope 分隔符也是版本分隔符，
- * 所以取**最后一个** @ 之后的部分，并对 `@scope/name@1.2.3` 同样成立。
- */
-export function specVersion(spec) {
-  const text = typeof spec === 'string' ? spec.trim() : ''
-  const at = text.lastIndexOf('@')
-  if (at <= 0) return undefined
-  return bareVersion(text.slice(at + 1))
-}
-
-/**
- * 从一份 package.json 里读版本号。
- *
- * @param path - package.json 的路径。
- * @returns 版本号；文件不存在、坏 JSON、没有 version 字段时返回 undefined。
- */
-export function readVersionAt(path) {
-  try {
-    const pkg = JSON.parse(readFileSync(path, 'utf8'))
-    return typeof pkg.version === 'string' ? pkg.version : undefined
-  } catch {
-    return undefined
-  }
-}
-
-/**
- * profile 里为本包记录的那条依赖值。
- *
- * @param profileDir - profile 目录，取自 ctx.get('profileContext').dir。
- * @param packageName - 要查的包名，默认本包。
- * @returns 记不下时（没有 package.json、没这条依赖、值不是字符串）返回 undefined。
- */
-export function readInstalledSpec(profileDir, packageName = OWN_NAME) {
-  if (typeof profileDir !== 'string' || profileDir.length === 0) return undefined
-  try {
-    const manifest = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'))
-    const value = manifest?.dependencies?.[packageName]
-    return typeof value === 'string' && value.length > 0 ? value.trim() : undefined
-  } catch {
-    return undefined
-  }
-}
-
-/**
- * 装之前的预检：这次安装有没有意义。
- *
- * 为什么要有它
- *   dsh-plugin-manager 在 HMR 在场的宿主上，对「规格与 profile 里已记录的完全相同」的安装会在
- *   pnpm 之前直接抛 already-installed。有三种情形会撞上，而它们都不该真去装一次：
- *     1. 别人（终端 dsh plugin add、Plugins 页面）已经装好了，只是进程还没重启；
- *     2. 发版时打了 tag 却忘了改 package.json 的 version —— 装的永远是同一个包内版本，
- *        于是每一轮都「有新版、装不进去」，静默循环到天荒地老；
- *     3. pnpm 的冷却期让这次安装只会落到已经装好的那个版本上（见下面的 cooled 参数）。
- *   都能用手里已有的事实判掉，判掉之后要能说清是哪一种。
- *
- * @param options - `{ spec, latest, disk, running, installed, cooled }`。
- *   `disk` 缺省时现读本包 package.json；`running` 缺省时不比对运行版本。
- *   `cooled` 是「上一次安装实际落到的版本」——冷却期让这次不可能装到 latest 时，
- *   调用方把它传进来，这里就不再发起注定落空的安装。
- * @returns 该装时返回 null；否则返回 `{ ok, outcome, text }`——几种情形成因不同，都不该重试。
- */
-export function checkInstallNeed(options = {}) {
-  const latest = bareVersion(options.latest)
-  if (latest === undefined) return null
-  // 「没传 disk」和「传了但读不到」必须分开：前者现读本包，后者说明本包的版本号有问题，
-  // 那时不该拿它去判别人的发布坏了。
-  const disk = bareVersion(Object.hasOwn(options, 'disk') ? options.disk : packageVersion())
-  const running = bareVersion(options.running)
-  const spec = typeof options.spec === 'string' ? options.spec.trim() : undefined
-  const installed = typeof options.installed === 'string' ? options.installed.trim() : undefined
-  const cooled = bareVersion(options.cooled)
-
-  if (disk === latest) {
-    // 磁盘上已经是这个版本了，再装一次要么被拒，要么装个同样的东西。
-    if (running === latest) {
-      return {
-        ok: true,
-        outcome: 'already-current',
-        text: 'v' + latest + ' is already installed and already running in this process — nothing to do.',
-      }
-    }
-    return {
-      ok: true,
-      outcome: 'restart-required',
-      text: 'v' + latest + ' is already on disk, but this process still runs '
-        + (running === undefined ? 'the previous version' : 'v' + running)
-        + '. Restart DSH to load it; installing again would only be refused as already-installed.',
-    }
-  }
-
-  // 读不到包内版本时不做这个判断：那是「本插件自己的 package.json 有问题」，不是发布的问题，
-  // 按未知处理比按坏发布处理安全。
-  if (disk !== undefined && spec !== undefined && spec.length > 0 && installed === spec) {
-    // profile 已经指向这个版本，而磁盘上的包仍报别的版本：发布本身坏了。
-    return {
-      ok: false,
-      outcome: 'broken-release',
-      text: 'The release ' + latest + ' still declares version ' + disk
-        + ' in its package.json, and the profile already points at that version. Every install attempt would be '
-        + 'refused as already-installed and could never change anything. This release is broken: it was published '
-        + 'without bumping package.json.',
-    }
-  }
-
-  // 冷却期：上一次装同一个包时落在 cooled 上，而这次的目标比它新 —— pnpm 会重演同一个决定。
-  // 说清是策略在拦，并给出越过它的唯一官方办法（显式指定版本仍会被拦，所以要靠卸载重装）。
-  if (cooled !== undefined && compareVersions(cooled, latest) < 0 && compareVersions(cooled, running ?? disk ?? '0.0.0') >= 0) {
-    return {
-      ok: true,
-      outcome: 'cooling-down',
-      text: 'pnpm\'s supply-chain policy (minimumReleaseAge) refuses releases younger than its window, so ' + latest
-        + ' cannot be installed yet; the previous install landed on ' + cooled + '. Wait for the window to pass '
-        + '(24 hours by default from the publish time), or install it by hand after disabling the policy.',
-    }
-  }
-
-  return null
-}
-
-/**
- * 从插件上下文里凑齐预检要的事实。
- *
- * @param ctx - 插件上下文；profileContext 缺席时读不到已装规格（预检只剩版本比对）。
- * @param checker - UpdateChecker 实例，用来取进程里在跑的版本。
- * @param spec - 要装的规格，末尾钉着版本号。
- * @param options - `{ cooled }`：上一次安装实际落到的版本。
- * @returns checkInstallNeed 的结果：null 表示该装。
- */
-export function preflightInstall(ctx, checker, spec, options = {}) {
-  const profileDir = ctx?.get?.('profileContext')?.dir
-  return checkInstallNeed({
-    spec,
-    latest: specVersion(spec),
-    running: checker?.version,
-    installed: readInstalledSpec(profileDir),
-    ...(options.cooled === undefined ? {} : { cooled: options.cooled }),
-  })
-}
-
-/** 安装后要把 application 这个枚举翻译成一句能照做的话。 */
-export function describeInstallOutcome(result, options = {}) {
-  const application = typeof result?.application === 'string' ? result.application : 'unknown'
-  const error = result?.error
-  if (application === 'failed' || application === 'cancelled') {
-    const code = typeof error?.code === 'string' ? error.code : 'operation-error'
-    // 预检（checkInstallNeed）已经拦掉正常的 already-installed，走到这里说明 profile 目录读不到、
-    // 或者中途被别处抢先装了。这不是故障，说清楚「已经在了」比报一串 operation-error 有用。
-    if (code === 'already-installed') {
-      return {
-        ok: true,
-        text: 'This release is already installed in the profile, so there was nothing to install. '
-          + 'If the running process still shows an older version, restart DSH to load what is already on disk.',
-      }
-    }
-    const diagnostic = typeof error?.diagnostic === 'string' && error.diagnostic.length > 0 ? ': ' + error.diagnostic : ''
-    return {
-      ok: false,
-      text: 'pwsh_run could not install the release (' + code + diagnostic + '). '
-        + 'Nothing was changed in the profile if pnpm failed before the swap; '
-        + 'run the same command from a terminal to see the full output: ',
-    }
-  }
-  // HMR 在场且安装是在它的事务之外发起时，application 仍是 'applied'，但这次是**真的**换掉了：
-  // HMR 重组合会驱逐本插件的模块、重新 import 并重新 apply（实测改文件后 137ms 生效）。
-  if (options?.live === true && application === 'applied') {
-    return {
-      ok: true,
-      text: 'The release is installed and the new code is already running (application: applied, '
-        + 'HMR replaced the plugin in place — no restart needed).',
-    }
-  }
-  // 没有 HMR，或安装是在 HMR 事务里发起的：磁盘是新版，进程里仍是旧模块。bundle 行给不出
-  // 新的 module URL，ESM 按 URL 缓存，重新 apply 也只是再 import 同一个 URL（实测过）。
-  return {
-    ok: true,
-    text: 'The release is installed on disk (application: ' + application + '). Restart DSH to load it: a bundle row '
-      + 'names the package, so the module URL does not change and the running process keeps the old code until a restart.',
-  }
-}
-
-/**
- * 装一个钉住版本号的规格，然后回读磁盘上真正落地的版本。
- *
- * @param manager - ctx.get('pluginManager')；缺席时传 null。
- * @param spec - 例如 `dsh-pwsh-plugin@0.2.13`。
- * @param options - `{ requestId, signal, log, live, profileDir }`。
- *   `profileDir` 用来回读装完后的 package.json —— 冷却期会让实际装到的版本比 spec 旧。
- * @returns `{ ok, outcome, text, error, installedVersion }`，永不抛出：安装失败是正常结果，不是程序缺陷。
- */
-export async function installRelease(manager, spec, options = {}) {
-  if (manager === null || manager === undefined) {
-    return {
-      ok: false,
-      outcome: 'no-manager',
-      text: 'This profile does not expose ctx.pluginManager, so pwsh_run cannot install the release itself.',
-    }
-  }
-  if (typeof manager.installBundle !== 'function') {
-    return { ok: false, outcome: 'no-manager', text: 'ctx.pluginManager does not offer installBundle in this DSH build.' }
-  }
-  try {
-    const result = await manager.installBundle(spec, options.requestId === undefined ? {} : { requestId: options.requestId })
-    // 返回值里没有版本号：装了哪个版本只能从装完的磁盘读回来。冷却期会让它与 spec 不同，
-    // 而「说装好了」这句话必须对着磁盘上的事实说。
-    const installedVersion = typeof options.profileDir === 'string' && options.profileDir.length > 0
-      ? readVersionAt(join(options.profileDir, 'node_modules', OWN_NAME, 'package.json'))
-      : undefined
-    const described = describeInstallOutcome(result, { live: options.live === true })
-    const text = installedVersion !== undefined && described.ok === true && compareVersions(installedVersion, specVersion(spec) ?? '0') < 0
-      // 装到了别的版本：pnpm 的冷却期在起作用。必须说出来，否则用户会以为升级成功了。
-      ? described.text + ' pnpm installed ' + installedVersion + ' rather than ' + String(specVersion(spec))
-        + ': its minimumReleaseAge policy withholds versions that are too recent.'
-      : described.text
-    return {
-      ok: described.ok,
-      outcome: typeof result?.application === 'string' ? result.application : 'unknown',
-      text,
-      ...(installedVersion === undefined ? {} : { installedVersion }),
-      ...(result?.error === undefined ? {} : { error: result.error }),
-    }
-  } catch (error) {
-    // change() 只在拿不到 profile 锁或服务正在销毁时 reject；两种都值得原样带出去。
-    return { ok: false, outcome: 'threw', text: 'pwsh_run could not install the release: ' + String(error?.message ?? error) }
-  }
-}

package/plugin/update-check.mjs

@@ -1,270 +0,0 @@
-/**
- * pwsh-run 的更新检查 —— 只查不装。装这一步由 update-apply.mjs 走 DSH 自己的 pluginManager。
- *
- * 为什么单独一个模块
- *   这个插件是纯宿主平面的工具插件，没有配置页面，也没有 client 入口。
- *   把「读发布源 / 比版本 / 记状态」这几件事独立出来，就能在纯 node 里
- *   完整单测，不必起一个 DSH。
- *
- * 发布源是 npm registry，不是 git 标签
- *   早期版本读 GitHub 的 vX.Y.Z 标签，安装规格是 github:owner/repo#vX.Y.Z。
- *   改到 registry 之后同一份发布既是 npm 包、也是 profile 里能被 pnpm 解析的依赖，
- *   「装到的是哪个版本」由 pnpm 说了算，插件不必自己拼 git 规格。
- *   更要紧的一条：pnpm 有供应链冷却期（minimumReleaseAge，默认 1440 分钟），
- *   当天发布的版本当天可能解析不到 —— 于是「最新版」与「实际装到的版本」不是一回事。
- *   检查阶段只认 registry 的 dist-tags，安装之后必须回读磁盘上的版本，
- *   拿这里的判决去宣称装好了就是在说一句没人验证过的话。
- *
- * 它做什么
- *   启动几秒后读一次 registry 的 dist-tags.latest，之后大约每 12 小时再读一次，
- *   与 package.json 里的版本比较。**从不自己安装**：发现新版本时只把版本号与
- *   安装规格（<package>@X.Y.Z）记下来。一个版本一个规格，所以装新版本就是盖掉旧的。
- *
- * 发布源可覆盖
- *   DSH_PWSH_UPDATE_REGISTRY 覆盖 registry 基址（测试与自建镜像靠它）。
- *   DSH_PWSH_UPDATE_DELAY_MS 覆盖首次检查的延迟（测试用）。
- */
-
-import { readFileSync } from 'node:fs'
-
-/** 发布在哪：这个包名在 npm registry 上的 dist-tags 就是发布。 */
-export const UPDATE_PACKAGE = 'dsh-pwsh-plugin'
-
-/** 默认 registry。 */
-export const UPDATE_REGISTRY = 'https://registry.npmjs.org'
-
-/** 启动后先让启动流程跑完，再查更新。 */
-const UPDATE_DELAY_MS = 5000
-const UPDATE_INTERVAL_MS = 12 * 60 * 60 * 1000
-
-/** 三段数字，可选预发布尾巴；npm 的版本号允许的形态。 */
-const RELEASE_VERSION = /^(?:v)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/
-
-/**
- * 读一个版本号。
- *
- * @param value - 版本号，可带 v 前缀与预发布尾巴（1.2.3 / v1.2.3 / 1.2.3-rc.1）。
- * @returns `{ parts: [major, minor, patch], prerelease }`；不是版本形态时返回 undefined。
- */
-export function parseVersion(value) {
-  const match = RELEASE_VERSION.exec(String(value ?? '').trim())
-  if (match === null) return undefined
-  const prerelease = match[4] === undefined ? undefined : match[4]
-  return { parts: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease }
-}
-
-/**
- * 比两个版本，写 X.Y.Z 或 vX.Y.Z 都行。
- *
- * 预发布（1.2.3-rc.1）按 semver 的规矩排在对应的正式版**之下**：
- * 否则一个 rc 会被当成「比 1.2.3 还新」，自动更新就会把用户推到预发布上。
- *
- * @returns 像排序比较器那样返回负数、零或正数；解析不出来的版本排在所有能解析的之下。
- */
-export function compareVersions(a, b) {
-  const pa = parseVersion(a)
-  const pb = parseVersion(b)
-  if (pa === undefined || pb === undefined) return (pa === undefined ? 0 : 1) - (pb === undefined ? 0 : 1)
-  for (let i = 0; i < 3; i += 1) if (pa.parts[i] !== pb.parts[i]) return pa.parts[i] - pb.parts[i]
-  if (pa.prerelease === pb.prerelease) return 0
-  // 都没有预发布尾巴 → 相等（上面已处理）；一个有一个没有 → 有尾巴的那个更旧。
-  if (pa.prerelease === undefined) return 1
-  if (pb.prerelease === undefined) return -1
-  return pa.prerelease < pb.prerelease ? -1 : pa.prerelease > pb.prerelease ? 1 : 0
-}
-
-/**
- * 发布从哪来。默认是 npm 公共 registry；DSH_PWSH_UPDATE_REGISTRY 可以指向自建镜像
- * 或测试用的本地服务器 —— 发布正式上线前先在本地预演就靠它。
- *
- * @param env - 要读的环境。
- * @returns `{ kind: 'registry', registry, name, spec }`；`spec` 是不带版本的安装规格。
- */
-export function updateSource(env = process.env) {
-  const raw = String(env.DSH_PWSH_UPDATE_REGISTRY ?? '').trim()
-  const registry = raw.length === 0 ? UPDATE_REGISTRY : raw.replace(/\/+$/, '')
-  return { kind: 'registry', registry, name: UPDATE_PACKAGE, spec: UPDATE_PACKAGE }
-}
-
-/** 一个发布的、钉住版本号的安装规格：每个版本一个规格，DSH 会拿它盖掉旧的。 */
-export function releaseSpec(source, version) {
-  return source.name + '@' + String(version).replace(/^v/, '')
-}
-
-/**
- * 读 registry 上的包摘要（abbreviated metadata）。
- *
- * 用 abbreviated 而不是完整文档：完整文档带每个版本的全部 package.json，动辄几百 KB，
- * 而这里只需要 dist-tags 与版本清单。
- *
- * @param source - 由 updateSource() 给出。
- * @param options - `{ fetch, signal }`：可替换的 fetch（测试用）与中止信号。
- * @returns `{ latest, versions, deprecated }`：dist-tags.latest、版本清单、被废弃的版本集合。
- */
-export async function fetchRegistry(source, { fetch: fetchImpl = globalThis.fetch, signal } = {}) {
-  const url = source.registry + '/' + encodeURIComponent(source.name)
-  const response = await fetchImpl(url, {
-    headers: { accept: 'application/vnd.npm.install-v1+json', 'user-agent': 'dsh-pwsh-plugin' },
-    signal,
-  })
-  if (!response.ok) {
-    // 404 是「这个包还不存在」，与「网络不通」必须分开说：前者重试一万次也不会好。
-    const reason = response.status === 404 ? 'not published on ' + source.registry : 'registry answered HTTP ' + response.status
-    throw new Error(reason)
-  }
-  const body = await response.json()
-  if (body === null || typeof body !== 'object') throw new Error('registry answered something other than a package document')
-  const versions = Object.keys(body.versions ?? {})
-  const deprecated = new Set(versions.filter((version) => typeof body.versions[version]?.deprecated === 'string'))
-  const tagged = body['dist-tags']?.latest
-  return {
-    ...(typeof tagged === 'string' ? { latest: tagged } : {}),
-    versions,
-    deprecated,
-  }
-}
-
-/**
- * 拿 registry 的摘要与正在跑的版本比一次。
- *
- * dist-tags.latest 缺失时从版本清单里挑：只认正式版（预发布不自动推），取语义最高。
- *
- * @param document - fetchRegistry() 的返回。
- * @param current - 本包版本（X.Y.Z）。
- * @returns 有更新的发布时 `{ state: 'available', latest }`，否则 `{ state: 'current', latest? }`。
- */
-export function updateVerdict(document, current) {
-  const versions = Array.isArray(document?.versions) ? document.versions : []
-  const deprecated = document?.deprecated instanceof Set ? document.deprecated : new Set()
-  let latest = typeof document?.latest === 'string' ? document.latest : undefined
-  if (latest === undefined) {
-    for (const version of versions) {
-      const parsed = parseVersion(version)
-      if (parsed === undefined || parsed.prerelease !== undefined || deprecated.has(version)) continue
-      if (latest === undefined || compareVersions(version, latest) > 0) latest = version
-    }
-  }
-  // 被标为 deprecated 的「最新版」不可信：那是发布者自己说的「别用这个」。
-  if (latest !== undefined && deprecated.has(latest)) return { state: 'current', deprecated: latest }
-  if (latest !== undefined && compareVersions(latest, current) > 0) return { state: 'available', latest }
-  return { state: 'current', ...(latest !== undefined ? { latest } : {}) }
-}
-
-/**
- * 本包自己的版本。每次**调用**都现读 package.json —— 注意 UpdateChecker 只在构造时调一次，
- * 所以实例上的版本是构造那一刻的磁盘值。热替换会重新 apply、重建实例，两者因此仍然对齐。
- */
-export function packageVersion(fromUrl = import.meta.url) {
-  try {
-    const pkg = JSON.parse(readFileSync(new URL('../package.json', fromUrl), 'utf8'))
-    return typeof pkg.version === 'string' ? pkg.version : undefined
-  } catch {
-    return undefined
-  }
-}
-
-/**
- * 一个更新检查器：定时读 registry、记下判决、供工具层取用。
- *
- * 状态 `state`：off | pending | checking | current | available | failed。
- * 任何失败（断网、镜像挂掉、包还没发布）只记下来给调用方看，绝不抛出，也不提前重试：
- * 下一轮定时检查会再试。
- */
-export class UpdateChecker {
-  /**
-   * @param options - `{ env, fetch, delayMs, intervalMs, log, source, version }`。
-   *   `version` 缺省时在**构造这一刻**读一次本包 package.json，之后固定在实例上；
-   *   `log` 是接受一行文本的日志函数。
-   */
-  constructor(options = {}) {
-    this.env = options.env ?? process.env
-    this.fetch = options.fetch
-    this.delayMs = options.delayMs
-    this.intervalMs = options.intervalMs ?? UPDATE_INTERVAL_MS
-    this.log = options.log ?? (() => undefined)
-    this.version = options.version ?? packageVersion()
-    this.source = options.source ?? updateSource(this.env)
-    this.state = { state: 'pending' }
-    this.timer = undefined
-    this.interval = undefined
-    this.checking = undefined
-    this.announced = undefined
-    this.abort = new AbortController()
-  }
-
-  /** 已经报过的那次「有新版」：只在第一次把提示交给调用方，避免每次调用都刷一行。 */
-  get announce() {
-    if (this.state.state !== 'available') return undefined
-    if (this.announced === this.state.latest) return undefined
-    this.announced = this.state.latest
-    return { latest: this.state.latest, spec: releaseSpec(this.source, this.state.latest) }
-  }
-
-  /** 开始定时检查。 */
-  start() {
-    if (this.timer !== undefined || this.interval !== undefined) return
-    const delay = Number(this.env.DSH_PWSH_UPDATE_DELAY_MS ?? this.delayMs)
-    this.timer = setTimeout(() => {
-      this.timer = undefined
-      void this.check()
-      this.interval = setInterval(() => void this.check(), this.intervalMs)
-      this.interval.unref?.()
-    }, Number.isFinite(delay) && delay >= 0 ? delay : UPDATE_DELAY_MS)
-    this.timer.unref?.()
-  }
-
-  /** 停掉定时检查并中止在途的那一次。 */
-  stop() {
-    clearTimeout(this.timer)
-    clearInterval(this.interval)
-    this.timer = undefined
-    this.interval = undefined
-    this.abort.abort()
-  }
-
-  /**
-   * 立刻查一次（定时器与手动都走这里）。重入时返回同一次 Promise。
-   *
-   * @returns 查完之后的状态对象。
-   */
-  check() {
-    if (this.checking !== undefined) return this.checking
-    if (this.version === undefined) {
-      this.state = { state: 'failed', error: 'own version unreadable', checkedAt: new Date().toISOString() }
-      return Promise.resolve(this.state)
-    }
-    const previous = this.state
-    this.state = { ...previous, state: 'checking' }
-    const signal = AbortSignal.any([this.abort.signal, AbortSignal.timeout(20000)])
-    this.checking = fetchRegistry(this.source, { ...(this.fetch === undefined ? {} : { fetch: this.fetch }), signal })
-      .then((document) => {
-        const verdict = updateVerdict(document, this.version)
-        this.state = { ...verdict, checkedAt: new Date().toISOString() }
-        this.log('update check: ' + this.state.state + (this.state.latest === undefined ? '' : ' (newest ' + this.state.latest + ', running ' + this.version + ')'))
-      }, (error) => {
-        if (this.abort.signal.aborted) return
-        const message = error?.name === 'TimeoutError' || error?.name === 'AbortError' ? 'timed out' : String(error?.message ?? error).split('\n')[0].slice(0, 200)
-        // 早先查到过的发布不因一次瞬时失败而消失。
-        this.state = {
-          ...(previous.latest === undefined ? {} : { latest: previous.latest }),
-          state: 'failed',
-          error: message,
-          checkedAt: new Date().toISOString(),
-          ...(previous.state === 'available' ? { stale: 'available' } : {}),
-        }
-        this.log('update check failed: ' + message)
-      })
-      .finally(() => {
-        this.checking = undefined
-      })
-    return this.checking.then(() => this.state)
-  }
-
-  /** 给调用方/测试看的一份纯净快照。 */
-  document() {
-    const doc = { ...this.state, source: this.source.spec }
-    if (this.version !== undefined) doc.running = this.version
-    if (doc.latest !== undefined) doc.spec = releaseSpec(this.source, doc.latest)
-    return doc
-  }
-}