From 3719143bc47574ff7c896d0fd6099d6ef90a9744 Mon Sep 17 00:00:00 2001 From: QQ Date: Tue, 17 Nov 2026 08:48:11 +0800 Subject: [PATCH] Import packages/plugin/src/plugin-self-update.ts --- packages/plugin/src/plugin-self-update.ts | 168 ++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 packages/plugin/src/plugin-self-update.ts diff --git a/packages/plugin/src/plugin-self-update.ts b/packages/plugin/src/plugin-self-update.ts new file mode 100644 index 0000000..20643fb --- /dev/null +++ b/packages/plugin/src/plugin-self-update.ts @@ -0,0 +1,168 @@ +import { randomUUID } from 'node:crypto' +import { compareVersions } from './version-compare.js' +import type { PluginUpdateSnapshot } from './update-check.js' + +/** npm package name the official plugin manager uses for this bundle. */ +export const REMOTE_PLUGIN_PACKAGE = 'ds-harness-remote' + +/** + * Result of asking the local Host to replace this plugin. + * `rejected` is a version the registry check did not publish. + * `manual` means this install cannot use the official online update. + * `started` means the manager passed its preflight and is replacing the bundle; + * the caller must return before that replacement unloads this plugin. + */ +export type PluginSelfUpdateResult = + | { status: 'rejected' } + | { status: 'manual' } + | { status: 'started' } + | { status: 'failed'; message: string } + +/** Official plugin-manager face this plugin needs. Older hosts simply lack it. */ +export interface PluginManagerUpdate { + listBundles(): Promise + updateBundle(name: string, version: string, options: { requestId: string }): Promise +} + +interface UpdateProgress { + requestId?: unknown + step?: unknown +} + +interface UpdateChecker { + snapshot(): PluginUpdateSnapshot | undefined +} + +/** + * Local Desktop upgrade through Harness `pluginManager.updateBundle`. + * + * The encrypted Remote channel must not call this: replacing this plugin from + * a connected device is refused in the Host bridge. Only the loopback control + * plane on this computer may start it, and only for the version the registry + * check already published. + */ +export class LocalPluginUpgrade { + private decidedVersion: string | undefined + private ready = false + private probeFlight: Promise | undefined + private startFlight: Promise | undefined + + constructor( + private readonly checker: UpdateChecker, + private readonly manager: () => PluginManagerUpdate | undefined, + private readonly subscribe: (listener: (event: UpdateProgress) => void) => () => void, + private readonly requestId: () => string = randomUUID, + ) {} + + /** Registry snapshot, plus `upgrade: 'ready'` once this install is confirmed updatable. */ + snapshot(): PluginUpdateSnapshot | undefined { + const base = this.checker.snapshot() + if (base === undefined) return undefined + if (compareVersions(base.currentVersion, base.latestVersion) < 0) { + if (this.decidedVersion !== base.latestVersion) this.probe(base.latestVersion) + if (this.ready && this.decidedVersion === base.latestVersion) return { ...base, upgrade: 'ready' } + } + return base + } + + /** + * Replace this plugin with `version` when it is the checked latest and the + * official manager marks the installed bundle updatable. + */ + start(version: string): Promise { + const refused = this.refusal(version) + if (refused !== undefined) return Promise.resolve(refused) + this.startFlight ??= this.execute(version).finally(() => { this.startFlight = undefined }) + return this.startFlight + } + + private refusal(version: string): PluginSelfUpdateResult | undefined { + const current = this.checker.snapshot() + if ( + current === undefined + || version !== current.latestVersion + || compareVersions(current.currentVersion, version) >= 0 + ) return { status: 'rejected' } + return undefined + } + + private probe(version: string): void { + if (this.probeFlight !== undefined) return + this.probeFlight = this.readReady() + .then(ready => { + this.ready = ready + this.decidedVersion = version + }) + .finally(() => { this.probeFlight = undefined }) + } + + private async readReady(): Promise { + try { + const manager = this.manager() + if (manager === undefined) return false + return bundleUpdatable(await manager.listBundles(), REMOTE_PLUGIN_PACKAGE) + } catch { + return false + } + } + + private async execute(version: string): Promise { + const manager = this.manager() + if (manager === undefined) return { status: 'manual' } + let updatable = false + try { + updatable = bundleUpdatable(await manager.listBundles(), REMOTE_PLUGIN_PACKAGE) + } catch { + return { status: 'manual' } + } + if (!updatable) return { status: 'manual' } + + const requestId = this.requestId() + let dispose = (): void => {} + const started = new Promise(resolve => { + dispose = this.subscribe(event => { + if (event.requestId !== requestId) return + if (event.step === 'removing' || event.step === 'installing') resolve({ status: 'started' }) + }) + }) + try { + const settled = manager.updateBundle(REMOTE_PLUGIN_PACKAGE, version, { requestId }) + .then(result => classifyUpdateResult(result)) + .catch(() => ({ status: 'failed', message: 'update-failed' }) satisfies PluginSelfUpdateResult) + return await Promise.race([started, settled]) + } finally { + dispose() + } + } +} + +/** Whether one `listBundles` row is this package and officially updatable. */ +export function bundleUpdatable(listed: unknown, packageName: string): boolean { + if (!Array.isArray(listed)) return false + return listed.some(row => isRecord(row) && row.name === packageName + // RC.3 names the update source. Never send a registry version to a Git install; + // consult the legacy boolean only when the new field is absent. + && (row.update === 'registry' || (row.update === undefined && row.updatable === true))) +} + +function classifyUpdateResult(result: unknown): PluginSelfUpdateResult { + if (!isRecord(result) || !isRecord(result.result)) return { status: 'failed', message: 'update-failed' } + const application = result.result.application + if (application === 'applied' || application === 'restart-required') return { status: 'started' } + return { status: 'failed', message: failureMessage(result.result.error) } +} + +function failureMessage(error: unknown): string { + if (!isRecord(error)) return 'update-failed' + const code = typeof error.code === 'string' && error.code.length > 0 && error.code.length <= 80 + ? error.code + : 'update-failed' + const diagnostic = typeof error.diagnostic === 'string' + ? error.diagnostic.replace(/\s+/g, ' ').trim().slice(0, 180) + : '' + return diagnostic === '' ? code : `${code}: ${diagnostic}` +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +}