@dickpy/dsh-imagegen 1.0.1 → 1.0.2

package/lib/index.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { promises } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { spawn } from "node:child_process";
 //#region src/protocol.ts
 /**
 * Wire contract shared by the host and client halves of dsh-imagegen: the
@@ -19,6 +20,11 @@ const SETTINGS_API = {
 };
 /** The image-generation proxy route. */
 const GENERATE_API = "/api/dsh-imagegen/generate";
+/** Host-mediated GitHub Release update routes. */
+const UPDATE_API = {
+	check: "/api/dsh-imagegen/update/check",
+	apply: "/api/dsh-imagegen/update/apply"
+};
 /**
 * Same-origin route family for the host-persisted generation history. Images
 * live as files under ~/.dsh/dsh-imagegen/images/ and are served back through
@@ -429,6 +435,106 @@ async function readHistoryImage(file) {
 	}
 }
 //#endregion
+//#region src/updater.ts
+/** GitHub Release discovery and explicit, user-triggered plugin updates. */
+/** Keep this in sync with package.json for each published release. */
+const CURRENT_VERSION = "1.0.2";
+const PACKAGE_NAME = "@dickpy/dsh-imagegen";
+const RELEASES_URL = "https://api.github.com/repos/dickpy/dsh-imagegen/releases/latest";
+const CHECK_TIMEOUT_MS = 1e4;
+const CACHE_TTL_MS = 15 * 6e4;
+let cached;
+/** Compare stable semver triples; returns positive when `left` is newer. */
+function compareVersions(left, right) {
+	const parse = (value) => {
+		const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(value.trim());
+		if (match === null) return [
+			0,
+			0,
+			0
+		];
+		return [
+			Number(match[1]),
+			Number(match[2]),
+			Number(match[3])
+		];
+	};
+	const a = parse(left);
+	const b = parse(right);
+	return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+function normalizedReleaseVersion(tag) {
+	if (typeof tag !== "string" || !/^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(tag.trim())) return void 0;
+	return tag.trim().replace(/^v/, "");
+}
+/** Read the latest stable GitHub Release, with a short host-side cache. */
+async function checkForUpdate(fetchFn = fetch, now = Date.now()) {
+	if (cached !== void 0 && cached.expiresAt > now) return cached.value;
+	const response = await fetchFn(RELEASES_URL, {
+		headers: {
+			accept: "application/vnd.github+json",
+			"user-agent": "dsh-imagegen-update-check"
+		},
+		signal: AbortSignal.timeout(CHECK_TIMEOUT_MS)
+	});
+	if (!response.ok) throw new Error(`GitHub Releases returned HTTP ${response.status}`);
+	const payload = await response.json();
+	if (payload === null || typeof payload !== "object") throw new Error("GitHub Releases returned malformed JSON");
+	const release = payload;
+	if (release.draft === true || release.prerelease === true) throw new Error("latest GitHub Release is not stable");
+	const latestVersion = normalizedReleaseVersion(release.tag_name);
+	if (latestVersion === void 0) throw new Error("latest GitHub Release has an invalid version tag");
+	const releaseUrl = typeof release.html_url === "string" ? release.html_url : "https://github.com/dickpy/dsh-imagegen/releases";
+	const value = {
+		currentVersion: CURRENT_VERSION,
+		latestVersion,
+		updateAvailable: compareVersions(latestVersion, CURRENT_VERSION) > 0,
+		releaseUrl,
+		...typeof release.published_at === "string" ? { publishedAt: release.published_at } : {}
+	};
+	cached = {
+		expiresAt: now + CACHE_TTL_MS,
+		value
+	};
+	return value;
+}
+/** Resolve the profile that launched the current DSH process. */
+function profileFromProcess(argv = process.argv, env = process.env) {
+	const envProfile = env.DSH_PROFILE?.trim();
+	if (envProfile !== void 0 && /^[a-zA-Z0-9_-]+$/.test(envProfile)) return envProfile;
+	const profileIndex = argv.indexOf("--profile");
+	const explicit = profileIndex >= 0 ? argv[profileIndex + 1]?.trim() : void 0;
+	if (explicit !== void 0 && /^[a-zA-Z0-9_-]+$/.test(explicit)) return explicit;
+	if (argv.includes("web")) return "web";
+	return "web";
+}
+/** Run the same official command documented for plugin installation. */
+function installUpdate(version, spawnFn = spawn, argv = process.argv, env = process.env) {
+	if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) return Promise.reject(/* @__PURE__ */ new Error("invalid update version"));
+	const profile = profileFromProcess(argv, env);
+	const child = spawnFn(process.platform === "win32" ? "dsh.cmd" : "dsh", [
+		"plugin",
+		"--profile",
+		profile,
+		"add",
+		`${PACKAGE_NAME}@${version}`
+	], {
+		shell: process.platform === "win32",
+		stdio: "ignore"
+	});
+	return new Promise((resolve, reject) => {
+		child.once("error", reject);
+		child.once("exit", (code, signal) => {
+			if (code === 0) resolve();
+			else reject(/* @__PURE__ */ new Error(signal === null ? `plugin update exited with code ${code ?? "unknown"}` : `plugin update terminated by ${signal}`));
+		});
+	});
+}
+/** Test helper: clear the host-side Release cache. */
+function clearUpdateCache() {
+	cached = void 0;
+}
+//#endregion
 //#region src/routes.ts
 /** Cap on JSON request bodies (settings ops and generate payloads are small). */
 const MAX_JSON_BODY_BYTES = 24 * 1024 * 1024;
@@ -727,6 +833,66 @@ function makeRoutes(deps) {
 				}
 			}
 		},
+		{
+			kind: "exact",
+			path: UPDATE_API.check,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				try {
+					writeJson(res, 200, {
+						ok: true,
+						update: await checkForUpdate()
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "update-check-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "exact",
+			path: UPDATE_API.apply,
+			handler: async (req, res) => {
+				if (!guard(req, res, "POST")) return;
+				const body = await readJsonBody(req);
+				const version = body !== void 0 && typeof body.version === "string" ? body.version.trim() : "";
+				if (version === "") {
+					writeJson(res, 200, {
+						ok: false,
+						code: "bad-request",
+						message: "update version is required"
+					});
+					return;
+				}
+				try {
+					const latest = await checkForUpdate();
+					if (!latest.updateAvailable || latest.latestVersion !== version) {
+						writeJson(res, 200, {
+							ok: false,
+							code: "update-not-available",
+							message: `version ${version} is not the latest available release`
+						});
+						return;
+					}
+					await installUpdate(version);
+					writeJson(res, 200, {
+						ok: true,
+						currentVersion: CURRENT_VERSION,
+						updatedVersion: version,
+						restartRequired: true
+					});
+				} catch (error) {
+					writeJson(res, 200, {
+						ok: false,
+						code: "update-failed",
+						message: messageOf(error)
+					});
+				}
+			}
+		},
 		{
 			kind: "exact",
 			path: HISTORY_API.list,
@@ -942,4 +1108,4 @@ function apply(ctx, config) {
 	sync();
 }
 //#endregion
-export { Config, IMAGEGEN_GUIDANCE, ImageGenError, ImageGenSettingsNamespace, apply, generateImage, inject, makeRoutes, name };
+export { CURRENT_VERSION, Config, IMAGEGEN_GUIDANCE, ImageGenError, ImageGenSettingsNamespace, apply, checkForUpdate, clearUpdateCache, compareVersions, generateImage, inject, installUpdate, makeRoutes, name, profileFromProcess };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dickpy/dsh-imagegen",
   "description": "AI 生图 (image generation) plugin for the dsh web GUI: text-to-image and image-to-image through a configurable OpenAI-compatible endpoint (gpt-image-2 / gpt-image-1 / dall-e-3), with a settings card for api_url / api_key and a sidebar entry opening a split-pane generation studio.",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "main": "lib/index.js",
   "exports": {

package/src/client/ImageGenPanel.tsx

@@ -13,7 +13,7 @@ import { createPortal } from 'react-dom'
 import { Button, Pill } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ImageGenApi } from './api.ts'
 import { errorMessage, tt } from './helpers.ts'
-import type { GeneratedImage, GenerateMode, GenerateRequest, HistoryEntry, HistoryImageRef } from '../protocol.ts'
+import type { GeneratedImage, GenerateMode, GenerateRequest, HistoryEntry, HistoryImageRef, UpdateInfo } from '../protocol.ts'
 import type { ImageGenConfig, ImageGenScope } from './settings-scope.ts'
 import css from './panel.module.css'
 
@@ -124,6 +124,10 @@ export function ImageGenPanel(props: {
   const [history, setHistory] = useState<HistoryEntry[]>([])
   const [viewingHistoryId, setViewingHistoryId] = useState<string | null>(null)
   const [preview, setPreview] = useState<{ images: GeneratedImage[]; index: number } | null>(null)
+  const [update, setUpdate] = useState<UpdateInfo | null>(null)
+  const [updating, setUpdating] = useState(false)
+  const [updateMessage, setUpdateMessage] = useState<string | null>(null)
+  const [updateResult, setUpdateResult] = useState<'success' | 'failed' | null>(null)
   const fileInput = useRef<HTMLInputElement>(null)
   const elapsed = useElapsed(generating, startedAt)
 
@@ -137,6 +141,35 @@ export function ImageGenPanel(props: {
     return () => { disposed = true }
   }, [api])
 
+  // Release checks are host-mediated and intentionally best-effort: a GitHub
+  // outage must never make the image-generation studio unavailable.
+  useEffect(() => {
+    let disposed = false
+    api.updateCheck()
+      .then(info => {
+        if (!disposed && info.updateAvailable) setUpdate(info)
+      })
+      .catch(() => { /* update discovery is optional */ })
+    return () => { disposed = true }
+  }, [api])
+
+  const applyUpdate = async (): Promise<void> => {
+    if (update === null || updating) return
+    setUpdating(true)
+    setUpdateMessage(null)
+    setUpdateResult(null)
+    try {
+      const result = await api.updateApply(update.latestVersion)
+      setUpdateMessage(tt('update.success', { version: result.updatedVersion }))
+      setUpdateResult('success')
+    } catch {
+      setUpdateMessage(tt('update.failed'))
+      setUpdateResult('failed')
+    } finally {
+      setUpdating(false)
+    }
+  }
+
   /** Read an uploaded reference image into a data URL. */
   const acceptFile = (file: File | undefined): void => {
     if (file === undefined) return
@@ -293,6 +326,20 @@ export function ImageGenPanel(props: {
           ? <div className={css.banner} data-kind="warn">{tt('config.missing')}</div>
           : <div className={css.banner} data-kind="ok">{tt('config.configured', { url: apiUrl })}</div>}
 
+      {update !== null ? (
+        <div className={css.updateBanner} data-kind={updateResult === 'success' ? 'ok' : 'warn'}>
+          <span className={css.updateText}>
+            {updateMessage ?? tt('update.available', { version: update.latestVersion })}
+          </span>
+          <span className={css.updateActions}>
+            <a className={css.updateRelease} href={update.releaseUrl} target="_blank" rel="noreferrer">{tt('update.release')}</a>
+            <Button variant="primary" size="sm" disabled={updating || updateMessage !== null} onClick={() => { void applyUpdate() }}>
+              {updating ? tt('update.installing') : tt('update.install')}
+            </Button>
+          </span>
+        </div>
+      ) : null}
+
       <div className={css.studio}>
         {/* ---------------------------------------------------- config sidebar */}
         <aside className={css.config}>

package/src/client/api.ts

@@ -3,7 +3,7 @@
  * data access path the panel uses — plain fetch, same origin.
  */
 
-import { GENERATE_API, HISTORY_API, type GenerateRequest, type GenerateResult, type HistoryEntry } from '../protocol.ts'
+import { GENERATE_API, HISTORY_API, UPDATE_API, type GenerateRequest, type GenerateResult, type HistoryEntry, type UpdateInfo } from '../protocol.ts'
 
 /** Error carrying the route's JSON error message. */
 export class ImageGenApiError extends Error {
@@ -40,6 +40,24 @@ async function readEnvelope<T>(response: Response): Promise<T> {
 
 /** The browser half's data entry point. */
 export class ImageGenApi {
+  /** Ask the host to check the latest stable GitHub Release. */
+  async updateCheck(): Promise<UpdateInfo> {
+    const response = await fetch(UPDATE_API.check, { method: 'POST' })
+    const body = await readEnvelope<{ ok: true; update: UpdateInfo }>(response)
+    return body.update
+  }
+
+  /** Ask the host to install a previously discovered Release. */
+  async updateApply(version: string): Promise<{ updatedVersion: string; restartRequired: boolean }> {
+    const response = await fetch(UPDATE_API.apply, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ version }),
+    })
+    const body = await readEnvelope<{ ok: true; updatedVersion: string; restartRequired: boolean }>(response)
+    return { updatedVersion: body.updatedVersion, restartRequired: body.restartRequired }
+  }
+
   /** Forward one generate request to the host proxy. */
   async generate(request: GenerateRequest): Promise<GenerateResult> {
     const response = await fetch(GENERATE_API, {

package/src/client/locales.ts

@@ -76,6 +76,13 @@ export const zh = {
   'config.missing': '尚未配置 API：请前往「设置 → 插件 → 可配置」为 AI 生图填写 api_url 与 api_key。',
   'config.configured': '已连接 {url}',
   'config.disabled': '插件已停用，请在设置中重新启用。',
+  // plugin update
+  'update.available': '检测到新版本：{version}',
+  'update.install': '在线更新',
+  'update.installing': '更新中…',
+  'update.success': '已更新到 {version}，请重启 DSH',
+  'update.failed': '更新失败，请重试',
+  'update.release': '查看 Release',
   // settings card
   'settings.title': 'AI 生图（dsh-imagegen）',
   'settings.description': '配置图像生成 API 地址与密钥',
@@ -171,6 +178,12 @@ export const en: Record<keyof typeof zh, string> = {
   'config.missing': 'API not configured: open "Settings → Plugins → Configurable" and fill in api_url and api_key for AI Image.',
   'config.configured': 'Connected to {url}',
   'config.disabled': 'The plugin is disabled — re-enable it in Settings.',
+  'update.available': 'A new version is available: {version}',
+  'update.install': 'Update online',
+  'update.installing': 'Updating…',
+  'update.success': 'Updated to {version}; restart DSH to load it',
+  'update.failed': 'Update failed; please try again',
+  'update.release': 'View Release',
   'settings.title': 'AI Image (dsh-imagegen)',
   'settings.description': 'Configure the image generation API endpoint and key',
   'settings.apiUrl': 'API URL (api_url)',

package/src/client/panel.module.css

@@ -166,6 +166,56 @@ html[data-dsh-imagegen-active]:not([data-dsh-taskboard-active]):not([data-dsh-ss
   border-color: var(--dsw-alias-state-warn-primary);
 }
 
+.updateBanner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  flex: none;
+  padding: 7px 10px 7px 12px;
+  font-size: 12px;
+  line-height: 1.5;
+  border-radius: 10px;
+  border: 1px solid var(--dsw-alias-state-warn-primary);
+  color: var(--dsw-alias-state-warn-primary);
+  overflow-wrap: anywhere;
+}
+
+.updateBanner[data-kind='ok'] {
+  color: var(--dsw-alias-state-success-primary);
+  border-color: var(--dsw-alias-state-success-primary);
+}
+
+.updateText {
+  min-width: 0;
+}
+
+.updateActions {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  flex: none;
+}
+
+.updateRelease {
+  color: inherit;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  white-space: nowrap;
+}
+
+@media (max-width: 700px) {
+  .updateBanner {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+
+  .updateActions {
+    width: 100%;
+    justify-content: space-between;
+  }
+}
+
 /* --- studio split: left config sidebar (narrow) + right canvas (wide) --------- */
 
 .studio {

package/src/index.ts

@@ -26,6 +26,7 @@ export const inject = ['webServer', 'systemPrompt']
 // contract only requires name / inject / Config / apply.
 export { makeRoutes } from './routes.ts'
 export { generateImage, ImageGenError } from './engine.ts'
+export { checkForUpdate, clearUpdateCache, compareVersions, CURRENT_VERSION, installUpdate, profileFromProcess } from './updater.ts'
 
 /** The branded settings namespace of this plugin (the card edits it). */
 export const ImageGenSettingsNamespace = settingsNamespace(IMAGEGEN_SETTINGS_NAMESPACE)

package/src/protocol.ts

@@ -16,6 +16,12 @@ export const SETTINGS_API = {
 /** The image-generation proxy route. */
 export const GENERATE_API = '/api/dsh-imagegen/generate'
 
+/** Host-mediated GitHub Release update routes. */
+export const UPDATE_API = {
+  check: '/api/dsh-imagegen/update/check',
+  apply: '/api/dsh-imagegen/update/apply',
+} as const
+
 /**
  * Same-origin route family for the host-persisted generation history. Images
  * live as files under ~/.dsh/dsh-imagegen/images/ and are served back through
@@ -82,6 +88,15 @@ export interface GenerateResult {
   historyError?: string
 }
 
+/** GitHub Release update information shown by the client. */
+export interface UpdateInfo {
+  currentVersion: string
+  latestVersion: string
+  updateAvailable: boolean
+  releaseUrl: string
+  publishedAt?: string
+}
+
 /** One history image reference as the browser consumes it (a served URL). */
 export interface HistoryImageRef {
   /** Same-origin URL: `${HISTORY_API.image}/<file>`. */

package/src/routes.ts

@@ -11,7 +11,8 @@ import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { SettingsConflictError, settingsNamespace, type SettingsDescriptor } from '@deepseek-ai/dsh-settings'
 import { generateImage, type UpstreamConfig } from './engine.ts'
 import { appendHistory, clearHistory, listHistory, readHistoryImage, removeHistory } from './history-store.ts'
-import { GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, SETTINGS_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput } from './protocol.ts'
+import { checkForUpdate, CURRENT_VERSION, installUpdate } from './updater.ts'
+import { GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, SETTINGS_API, UPDATE_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput } from './protocol.ts'
 
 /** Cap on JSON request bodies (settings ops and generate payloads are small). */
 const MAX_JSON_BODY_BYTES = 24 * 1024 * 1024
@@ -304,6 +305,44 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
         }
       },
     },
+    // ----------------------------------------------- update check
+    {
+      kind: 'exact',
+      path: UPDATE_API.check,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        try {
+          writeJson(res, 200, { ok: true, update: await checkForUpdate() })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'update-check-failed', message: messageOf(error) })
+        }
+      },
+    },
+    // ----------------------------------------------- update apply
+    {
+      kind: 'exact',
+      path: UPDATE_API.apply,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const version = body !== undefined && typeof body.version === 'string' ? body.version.trim() : ''
+        if (version === '') {
+          writeJson(res, 200, { ok: false, code: 'bad-request', message: 'update version is required' })
+          return
+        }
+        try {
+          const latest = await checkForUpdate()
+          if (!latest.updateAvailable || latest.latestVersion !== version) {
+            writeJson(res, 200, { ok: false, code: 'update-not-available', message: `version ${version} is not the latest available release` })
+            return
+          }
+          await installUpdate(version)
+          writeJson(res, 200, { ok: true, currentVersion: CURRENT_VERSION, updatedVersion: version, restartRequired: true })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'update-failed', message: messageOf(error) })
+        }
+      },
+    },
     // ----------------------------------------------------- history list
     {
       kind: 'exact',

package/src/updater.ts

@@ -0,0 +1,116 @@
+/** GitHub Release discovery and explicit, user-triggered plugin updates. */
+
+import { spawn, type ChildProcess } from 'node:child_process'
+
+/** Keep this in sync with package.json for each published release. */
+export const CURRENT_VERSION = '1.0.2'
+export const PACKAGE_NAME = '@dickpy/dsh-imagegen'
+export const RELEASES_URL = 'https://api.github.com/repos/dickpy/dsh-imagegen/releases/latest'
+
+const CHECK_TIMEOUT_MS = 10_000
+const CACHE_TTL_MS = 15 * 60_000
+
+export interface UpdateInfo {
+  currentVersion: string
+  latestVersion: string
+  updateAvailable: boolean
+  releaseUrl: string
+  publishedAt?: string
+}
+
+interface GitHubRelease {
+  tag_name?: unknown
+  html_url?: unknown
+  published_at?: unknown
+  draft?: unknown
+  prerelease?: unknown
+}
+
+let cached: { expiresAt: number; value: UpdateInfo } | undefined
+
+/** Compare stable semver triples; returns positive when `left` is newer. */
+export function compareVersions(left: string, right: string): number {
+  const parse = (value: string): [number, number, number] => {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(value.trim())
+    if (match === null) return [0, 0, 0]
+    return [Number(match[1]), Number(match[2]), Number(match[3])]
+  }
+  const a = parse(left)
+  const b = parse(right)
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2]
+}
+
+function normalizedReleaseVersion(tag: unknown): string | undefined {
+  if (typeof tag !== 'string' || !/^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(tag.trim())) return undefined
+  return tag.trim().replace(/^v/, '')
+}
+
+/** Read the latest stable GitHub Release, with a short host-side cache. */
+export async function checkForUpdate(fetchFn: typeof fetch = fetch, now = Date.now()): Promise<UpdateInfo> {
+  if (cached !== undefined && cached.expiresAt > now) return cached.value
+  const response = await fetchFn(RELEASES_URL, {
+    headers: {
+      accept: 'application/vnd.github+json',
+      'user-agent': 'dsh-imagegen-update-check',
+    },
+    signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+  })
+  if (!response.ok) throw new Error(`GitHub Releases returned HTTP ${response.status}`)
+  const payload: unknown = await response.json()
+  if (payload === null || typeof payload !== 'object') throw new Error('GitHub Releases returned malformed JSON')
+  const release = payload as GitHubRelease
+  if (release.draft === true || release.prerelease === true) throw new Error('latest GitHub Release is not stable')
+  const latestVersion = normalizedReleaseVersion(release.tag_name)
+  if (latestVersion === undefined) throw new Error('latest GitHub Release has an invalid version tag')
+  const releaseUrl = typeof release.html_url === 'string' ? release.html_url : 'https://github.com/dickpy/dsh-imagegen/releases'
+  const value: UpdateInfo = {
+    currentVersion: CURRENT_VERSION,
+    latestVersion,
+    updateAvailable: compareVersions(latestVersion, CURRENT_VERSION) > 0,
+    releaseUrl,
+    ...typeof release.published_at === 'string' ? { publishedAt: release.published_at } : {},
+  }
+  cached = { expiresAt: now + CACHE_TTL_MS, value }
+  return value
+}
+
+/** Resolve the profile that launched the current DSH process. */
+export function profileFromProcess(argv: readonly string[] = process.argv, env: NodeJS.ProcessEnv = process.env): string {
+  const envProfile = env.DSH_PROFILE?.trim()
+  if (envProfile !== undefined && /^[a-zA-Z0-9_-]+$/.test(envProfile)) return envProfile
+  const profileIndex = argv.indexOf('--profile')
+  const explicit = profileIndex >= 0 ? argv[profileIndex + 1]?.trim() : undefined
+  if (explicit !== undefined && /^[a-zA-Z0-9_-]+$/.test(explicit)) return explicit
+  if (argv.includes('web')) return 'web'
+  return 'web'
+}
+
+/** Run the same official command documented for plugin installation. */
+export function installUpdate(
+  version: string,
+  spawnFn: typeof spawn = spawn,
+  argv: readonly string[] = process.argv,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+    return Promise.reject(new Error('invalid update version'))
+  }
+  const profile = profileFromProcess(argv, env)
+  const command = process.platform === 'win32' ? 'dsh.cmd' : 'dsh'
+  const child = spawnFn(command, ['plugin', '--profile', profile, 'add', `${PACKAGE_NAME}@${version}`], {
+    shell: process.platform === 'win32',
+    stdio: 'ignore',
+  }) as ChildProcess
+  return new Promise((resolve, reject) => {
+    child.once('error', reject)
+    child.once('exit', (code, signal) => {
+      if (code === 0) resolve()
+      else reject(new Error(signal === null ? `plugin update exited with code ${code ?? 'unknown'}` : `plugin update terminated by ${signal}`))
+    })
+  })
+}
+
+/** Test helper: clear the host-side Release cache. */
+export function clearUpdateCache(): void {
+  cached = undefined
+}