@huaqiu/dsh-tool-plugin-update 0.6.1 → 0.6.2

package/lib/index.mjs

@@ -3,6 +3,22 @@ import { getLogger } from "@huaqiu/dsh-plugin-log";
 const UPDATE_ROUTE_PREFIX = "/api/v1/huaqiu/plugin-update";
 /** End-to-end budget for one forwarded request, in milliseconds. */
 const DEFAULT_FORWARD_TIMEOUT_MS = 3e4;
+/**
+* Budget for `POST /runtime-update/request` — deliberately far larger than
+* {@link DEFAULT_FORWARD_TIMEOUT_MS}.
+*
+* This route is not a quick RPC. Before it answers, hq-edge re-reads the
+* update manifest, downloads the entire runtime bundle (hundreds of MB),
+* verifies its SHA-256, extracts it into the shared staging root and validates
+* the layout + version stamp. Measured end-to-end against a local update
+* server: 56 s (16:49:49 → 16:50:45).
+*
+* Under the generic 30 s budget the forwarder aborts mid-flight and answers
+* `504 hq-edge request timed out after 30000ms`, so the panel reports a failure
+* for an update that is still running perfectly well — and which then goes on
+* to complete, swap the runtime and restart HQ Edge underneath the error toast.
+*/
+const RUNTIME_REQUEST_TIMEOUT_MS = 6e5;
 function sendJson(res, status, body) {
 	const payload = JSON.stringify(body);
 	res.writeHead(status, {
@@ -37,34 +53,85 @@ function readBody(req) {
 		req.on("error", reject);
 	});
 }
-/** Map a sub-path to { method, path } on the hq-edge API. */
-function routeFor(sub) {
-	if (sub === "/report" || sub === "") return {
+/**
+* Map a sub-path + method to { method, path } on the hq-edge API.
+*
+* `timeoutMs` overrides {@link DEFAULT_FORWARD_TIMEOUT_MS} for routes whose
+* upstream work legitimately outlasts it (only `/runtime-request` today).
+*
+* The method is part of the lookup because one sub-path can carry both a read
+* and a write: `/runtime-source` is GET for the current value and POST to
+* change it. A method the route does not declare is `null`, which the
+* forwarder answers 405 rather than forwarding a GET to a POST-only upstream
+* and surfacing hq-edge's 404 as a plugin bug.
+*/
+function routeFor(sub, method) {
+	if (sub === "/runtime-source") {
+		if (method === "GET") return {
+			method: "GET",
+			path: "/api/v1/runtime-update/source"
+		};
+		if (method === "POST") return {
+			method: "POST",
+			path: "/api/v1/runtime-update/source"
+		};
+		return null;
+	}
+	if (sub === "/plugin-source") {
+		if (method === "GET") return {
+			method: "GET",
+			path: "/api/v1/plugin-updates/source"
+		};
+		if (method === "POST") return {
+			method: "POST",
+			path: "/api/v1/plugin-updates/source"
+		};
+		return null;
+	}
+	if (sub === "/report" || sub === "") return method === "GET" ? {
 		method: "GET",
 		path: "/api/v1/plugin-updates"
-	};
-	if (sub === "/runtime") return {
+	} : null;
+	if (sub === "/runtime") return method === "GET" ? {
 		method: "GET",
 		path: "/api/v1/runtime-update"
-	};
-	if (sub === "/check") return {
+	} : null;
+	if (sub === "/runtime-request") return method === "POST" ? {
+		method: "POST",
+		path: "/api/v1/runtime-update/request",
+		timeoutMs: RUNTIME_REQUEST_TIMEOUT_MS
+	} : null;
+	if (sub === "/check") return method === "POST" ? {
 		method: "POST",
 		path: "/api/v1/plugin-updates/check"
-	};
-	if (sub === "/install") return {
+	} : null;
+	if (sub === "/install") return method === "POST" ? {
 		method: "POST",
 		path: "/api/v1/plugin-updates/install"
-	};
-	if (sub === "/ignore") return {
+	} : null;
+	if (sub === "/ignore") return method === "POST" ? {
 		method: "POST",
 		path: "/api/v1/plugin-updates/ignore"
-	};
-	if (sub === "/unignore") return {
+	} : null;
+	if (sub === "/unignore") return method === "POST" ? {
 		method: "POST",
 		path: "/api/v1/plugin-updates/unignore"
-	};
+	} : null;
 	return null;
 }
+/** Every sub-path this forwarder serves — used to tell a 404 from a 405. */
+const ROUTE_SUB_PATHS = /* @__PURE__ */ new Set([
+	"",
+	"/report",
+	"/check",
+	"/install",
+	"/ignore",
+	"/unignore",
+	"/runtime",
+	"/runtime-request",
+	"/runtime-source",
+	"/plugin-source"
+]);
 /** Create the prefix-route handler forwarding to hq-edge. */
 function createUpdateForwarder(baseUrlResolver, timeoutMs = DEFAULT_FORWARD_TIMEOUT_MS) {
 	return async (req, res) => {
@@ -73,9 +140,9 @@ function createUpdateForwarder(baseUrlResolver, timeoutMs = DEFAULT_FORWARD_TIME
 			sendJson(res, 404, { error: "not found" });
 			return;
 		}
-		const target = routeFor(sub);
+		const target = routeFor(sub, req.method === "HEAD" ? "GET" : req.method ?? "");
 		if (target === null) {
-			sendJson(res, 404, { error: "not found" });
+			sendJson(res, sub === "" || ROUTE_SUB_PATHS.has(sub) ? 405 : 404, { error: sub === "" || ROUTE_SUB_PATHS.has(sub) ? `method ${req.method} not allowed on ${sub || "/"}` : "not found" });
 			return;
 		}
 		if (req.method !== "GET" && req.method !== "POST" && req.method !== "HEAD") {
@@ -94,8 +161,9 @@ function createUpdateForwarder(baseUrlResolver, timeoutMs = DEFAULT_FORWARD_TIME
 			sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
 			return;
 		}
+		const budget = target.timeoutMs ?? timeoutMs;
 		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		const timer = setTimeout(() => controller.abort(), budget);
 		try {
 			const upstream = await fetch(`${base}${target.path}`, {
 				method: target.method,
@@ -117,7 +185,7 @@ function createUpdateForwarder(baseUrlResolver, timeoutMs = DEFAULT_FORWARD_TIME
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			if (err instanceof Error && err.name === "AbortError") {
-				sendJson(res, 504, { error: `hq-edge request timed out after ${timeoutMs}ms` });
+				sendJson(res, 504, { error: `hq-edge request timed out after ${budget}ms` });
 				return;
 			}
 			sendJson(res, 502, { error: `hq-edge request failed: ${message}` });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-tool-plugin-update",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -31,8 +31,8 @@
     "@deepseek-ai/dsh-host-webserver": "0.1.0-rc.8"
   },
   "dependencies": {
-    "@huaqiu/dsh-plugin-log": "0.6.1",
-    "@huaqiu/dsh-sidebar-entry": "0.6.1"
+    "@huaqiu/dsh-plugin-log": "0.6.2",
+    "@huaqiu/dsh-sidebar-entry": "0.6.2"
   },
   "files": [
     "lib",

package/src/client/api.ts

@@ -24,13 +24,83 @@ export interface PluginUpdateItem {
   notes?: string[]
 }
 
+/**
+ * One downloadable HQ Edge runtime distribution, as hq-edge reports it
+ * (`RuntimeUpdateEntry` in `apps/server/src/dsh/PluginUpdateService.ts`).
+ *
+ * Note the shape: `runtime.latest` is this ENTRY OBJECT, not a bare version
+ * string. Reading it as a string is what once rendered "[object Object]".
+ */
+export interface RuntimeUpdateEntry {
+  /** Clean SemVer of the available distribution. */
+  version: string
+  /** SHA-256 of the release archive, lowercase hex (64 chars). */
+  sha256: string
+  /** Platform the archive targets: win | darwin | linux | all. */
+  platform: string
+  /** Optional CPU architecture: x64 | arm64 (absent = any). */
+  arch?: string
+  /** Exact absolute HTTPS URL of the release archive. */
+  url: string
+}
+
 export interface RuntimeUpdateInfo {
   configured: boolean
   currentVersion?: string | null
-  latest?: string | null
+  /** The latest compatible distribution, or null when the manifest had none. */
+  latest?: RuntimeUpdateEntry | null
   updateAvailable: boolean
   checkedAt?: string | null
   lastError?: string | null
+  /**
+   * Where the runtime-update manifest is read from. Optional: an older hq-edge
+   * does not send it, and the panel must degrade to a read-only source row.
+   */
+  source?: RuntimeUpdateSource
+}
+
+/**
+ * The runtime-update manifest source, editable from this panel.
+ *
+ * `origin` says which URL is in effect: `override` is a URL the user set here
+ * (persisted by hq-edge per host), `config` is the packaged/env default, and
+ * `unset` means runtime updates are not configured at all.
+ */
+export interface RuntimeUpdateSource {
+  /** The manifest URL currently in effect; empty when none is known. */
+  url: string
+  origin: 'override' | 'config' | 'unset'
+  /** The URL configuration supplies, independent of any user override. */
+  configuredUrl: string
+  /** True when a user override is shadowing the configured URL. */
+  override: boolean
+}
+
+/**
+ * The plugin release-manifest source (the gitee
+ * `plugins-release-manifest.json` by default) — same shape and same edit flow
+ * as {@link RuntimeUpdateSource}, because hq-edge serves both from one shared
+ * type.
+ */
+export type PluginUpdateSource = RuntimeUpdateSource
+
+/**
+ * The latest runtime version to display, or null when there is none.
+ *
+ * hq-edge sends the full release entry; an older or future server could send
+ * a bare string. Both are accepted here so the facts row can never again fall
+ * back to `String(object)` — i.e. "[object Object]" — in the DOM.
+ */
+export function runtimeLatestVersion(
+  runtime: RuntimeUpdateInfo | null | undefined,
+): string | null {
+  const latest: unknown = runtime?.latest
+  if (typeof latest === 'string') return latest.length > 0 ? latest : null
+  if (latest !== null && typeof latest === 'object' && 'version' in latest) {
+    const version = (latest as { version?: unknown }).version
+    if (typeof version === 'string' && version.length > 0) return version
+  }
+  return null
 }
 
 export interface PluginUpdateReport {
@@ -43,6 +113,11 @@ export interface PluginUpdateReport {
   fetchedAt?: string
   lastError?: string | null
   runtime: RuntimeUpdateInfo
+  /**
+   * Where the plugin release manifest is read from. Optional: an older
+   * hq-edge does not send it, and the panel must degrade to no source row.
+   */
+  pluginSource?: PluginUpdateSource
 }
 
 async function request<T>(path: string, init?: RequestInit): Promise<T> {
@@ -92,7 +167,87 @@ export function ignoreOffer(setVersion: string): Promise<unknown> {
   return request<unknown>('/ignore', { method: 'POST', body: JSON.stringify({ setVersion }) })
 }
 
+/**
+ * The outcome of a user-confirmed HQ Edge runtime update.
+ *
+ * hq-edge answers `202 { requestId, targetVersion, state: 'accepted' }` and
+ * then shuts itself down for the EDA host to swap the runtime, so a success
+ * here means "accepted", not "installed". Failures arrive as 409 (already
+ * updating → `busy`), 422 (preflight/manifest/download refused) or 503.
+ */
+export interface RuntimeUpdateRequestResult {
+  requestId?: string
+  targetVersion?: string
+  state?: string
+  ok?: boolean
+  error?: string
+  busy?: boolean
+}
+
+/** POST the user-confirmed HQ Edge runtime update for one target version. */
+export function requestRuntimeUpdate(
+  targetVersion: string,
+): Promise<RuntimeUpdateRequestResult> {
+  return request<RuntimeUpdateRequestResult>('/runtime-request', {
+    method: 'POST',
+    body: JSON.stringify({ targetVersion }),
+  })
+}
+
 /** POST unignore for the set version (reverses an ignore). */
 export function unignoreOffer(setVersion: string): Promise<unknown> {
   return request<unknown>('/unignore', { method: 'POST', body: JSON.stringify({ setVersion }) })
 }
+
+/**
+ * GET the runtime-update manifest source: the URL in effect, its origin
+ * (`override` | `config` | `unset`) and the configured URL behind it.
+ *
+ * Read-only upstream, so this is open like `/report` — only the mutation
+ * below is loopback-guarded (and reaches it same-origin anyway).
+ */
+export function getRuntimeUpdateSource(): Promise<RuntimeUpdateSource> {
+  return request<RuntimeUpdateSource>('/runtime-source')
+}
+
+/**
+ * POST a new runtime-update manifest URL, or `""` to clear a user override
+ * and fall back to the configured URL.
+ *
+ * hq-edge validates the URL itself (`https` required except for loopback, no
+ * embedded credentials) and answers 422 with a message meant for a person —
+ * this client surfaces it verbatim rather than pre-validating, so the rule
+ * lives in exactly one place. A successful answer is the NEW source; the
+ * caller must then re-run discovery, because the cached report still names
+ * the old manifest's offer.
+ */
+export function setRuntimeUpdateSource(url: string): Promise<RuntimeUpdateSource> {
+  return request<RuntimeUpdateSource>('/runtime-source', {
+    method: 'POST',
+    body: JSON.stringify({ url }),
+  })
+}
+
+/**
+ * GET the plugin release-manifest source: the URL discovery reads, its origin
+ * (`override` | `config` | `unset`) and the configured URL behind it. Same
+ * open/read-only contract as the runtime source.
+ */
+export function getPluginUpdateSource(): Promise<PluginUpdateSource> {
+  return request<PluginUpdateSource>('/plugin-source')
+}
+
+/**
+ * POST a new plugin release-manifest URL, or `""` to clear a user override.
+ *
+ * hq-edge persists the override per host AND re-runs discovery in the
+ * background, so the next report (and the sidebar badge) already reflect the
+ * new manifest. This client still re-checks explicitly after a save — the
+ * background pass is a safety net for other consumers, not a substitute.
+ */
+export function setPluginUpdateSource(url: string): Promise<PluginUpdateSource> {
+  return request<PluginUpdateSource>('/plugin-source', {
+    method: 'POST',
+    body: JSON.stringify({ url }),
+  })
+}

package/src/client/copy.ts

@@ -56,10 +56,42 @@ const zh = {
     unknown: '版本未知',
     notConfigured: '未配置更新源',
     note: '运行时更新由 EDA 安装器处理',
+    update: '安装运行时更新',
+    updateConfirm: (version: string) =>
+      `安装 HQ Edge 运行时 ${version}？HQ Edge 会先关闭并完成替换，然后重新启动。`,
+    updating: '正在下载并校验运行时包，可能需要一分钟…',
+    updateAccepted: '运行时更新已受理，HQ Edge 正在重启…',
+    // ── Update-source editor ──
+    sourceHint: '运行时更新清单的下载地址，保存后立即生效',
+    sourceEdit: '修改',
+    sourceSave: '保存',
+    sourceReset: '恢复默认',
+    saved: '更新源已保存，正在重新检查更新…',
+    saveFailed: '保存更新源失败',
+    sourceInputLabel: '运行时更新清单地址',
+    sourcePlaceholder: 'https://gitee.com/huaqiu-electronics/dsh-pcb-eda/raw/main/edge-headless-release-manifest.json',
   },
+  // ── Plugin release-manifest source editor ──
+  pluginSource: {
+    title: '插件更新源',
+    hint: '插件更新清单的下载地址，保存后立即生效',
+    edit: '修改',
+    save: '保存',
+    reset: '恢复默认',
+    saved: '更新源已保存，正在重新检查更新…',
+    saveFailed: '保存更新源失败',
+    inputLabel: '插件更新清单地址',
+    placeholder: 'https://gitee.com/huaqiu-electronics/dsh-pcb-eda/raw/main/plugins-release-manifest.json',
+  },
+  // Origin tags, shared by both source editors (hq-edge serves one type).
+  originOverride: '自定义',
+  originConfig: '默认配置',
+  originUnset: '未配置',
   lastError: '上次检查失败',
   installError: '安装失败',
   installSuccess: '更新已安装，正在重启 DSH…',
+  confirmInstall: '确认安装',
+  cancel: '取消',
 }
 
 export type UpdateCopy = typeof zh
@@ -111,10 +143,43 @@ const en: UpdateCopy = {
     unknown: 'Version unknown',
     notConfigured: 'No update source configured',
     note: 'Runtime updates are handled by the EDA installer',
+    update: 'Install runtime update',
+    updateConfirm: (version: string) =>
+      `Install HQ Edge runtime ${version}? HQ Edge shuts down to swap the runtime, then restarts.`,
+    updating: 'Downloading and verifying the runtime bundle — this can take a minute…',
+    updateAccepted: 'Runtime update accepted — HQ Edge is restarting…',
+    // ── Update-source editor ──
+    sourceHint: 'Where the runtime update manifest is fetched from; saved changes take effect immediately',
+    sourceEdit: 'Edit',
+    sourceSave: 'Save',
+    sourceReset: 'Reset to default',
+    saved: 'Update source saved — re-checking for updates…',
+    saveFailed: 'Failed to save the update source',
+    sourceInputLabel: 'Runtime update manifest URL',
+    sourcePlaceholder: 'https://gitee.com/huaqiu-electronics/dsh-pcb-eda/raw/main/edge-headless-release-manifest.json',
+  },
+  // ── Plugin release-manifest source editor ──
+  pluginSource: {
+    title: 'Plugin update source',
+    hint: 'Where the plugin update manifest is fetched from; saved changes take effect immediately',
+    edit: 'Edit',
+    save: 'Save',
+    reset: 'Reset to default',
+    saved: 'Update source saved — re-checking for updates…',
+    saveFailed: 'Failed to save the update source',
+    inputLabel: 'Plugin update manifest URL',
+    placeholder:
+      'https://gitee.com/huaqiu-electronics/dsh-pcb-eda/raw/main/plugins-release-manifest.json',
   },
+  // Origin tags, shared by both source editors (hq-edge serves one type).
+  originOverride: 'Custom',
+  originConfig: 'Configured',
+  originUnset: 'Not configured',
   lastError: 'Last check failed',
   installError: 'Install failed',
   installSuccess: 'Update installed — restarting DSH…',
+  confirmInstall: 'Confirm install',
+  cancel: 'Cancel',
 }
 
 export const COPY = { zh, en } as const

package/src/client/index.ts

@@ -694,6 +694,69 @@ const VIEW_CSS_TEXT = `
   gap: 8px;
 }
 
+/* ── Runtime update action row (arm → confirm step) ───────────────────── */
+.hqpu-runtime-actions {
+  margin-top: 12px;
+}
+.hqpu-runtime-confirm {
+  flex: 1 1 100%;
+  margin: 0;
+}
+
+/* ── Runtime update source (fact row + editable URL field) ────────────── */
+.hqpu-source-line {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+  max-width: 100%;
+}
+.hqpu-source-url {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.hqpu-source-editor {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: 12px;
+}
+/* The plugin-source editor sits inside its own group right under the fact
+ * row, so it needs less air than the runtime one under the facts block. */
+.hqpu-source-editor--plugin {
+  margin-top: 4px;
+}
+.hqpu-source-hint {
+  flex: 1 1 100%;
+  margin: 0;
+}
+.hqpu-source-controls {
+  flex: 1 1 100%;
+}
+.hqpu-source-input {
+  flex: 1 1 240px;
+  min-width: 0;
+  height: 28px;
+  box-sizing: border-box;
+  padding: 0 10px;
+  border: 0.5px solid var(--dsw-alias-border-l4);
+  border-radius: var(--dsw-radius-md);
+  background: var(--dsw-alias-bg-layer-3);
+  color: var(--dsw-alias-label-primary);
+  font: inherit;
+  font-size: 12.5px;
+}
+.hqpu-source-input:disabled {
+  opacity: 0.5;
+}
+.hqpu-source-input:focus-visible {
+  outline: var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary));
+  outline-offset: 1px;
+}
+
 /* ── Footer action row (ui-primitives Modal .footer) ───────────────────── */
 .hqpu-footer {
   display: flex;