@huaqiu/dsh-tool-plugin-update 0.6.6 → 0.6.8

package/lib/index.mjs

@@ -65,6 +65,18 @@ function readBody(req) {
 * forwarder answers 405 rather than forwarding a GET to a POST-only upstream
 * and surfacing hq-edge's 404 as a plugin bug.
 */
+/**
+* Match a dynamic `/status/<jobId>` sub-path. Returns the job id for a single
+* non-empty segment (no nested slashes), else null. The id is opaque — this
+* route forwards it verbatim; hq-edge owns validation and the 404 for unknown
+* ids.
+*/
+function matchJobStatusPath(sub) {
+	if (!sub.startsWith("/status/")) return null;
+	const id = sub.slice(8);
+	if (id.length === 0 || id.includes("/") || id.includes("?")) return null;
+	return id;
+}
 function routeFor(sub, method) {
 	if (sub === "/runtime-source") {
 		if (method === "GET") return {
@@ -92,6 +104,15 @@ function routeFor(sub, method) {
 		method: "GET",
 		path: "/api/v1/plugin-updates"
 	} : null;
+	if (sub === "/status") return method === "GET" ? {
+		method: "GET",
+		path: "/api/v1/plugin-updates/status"
+	} : null;
+	const jobId = matchJobStatusPath(sub);
+	if (jobId !== null) return method === "GET" ? {
+		method: "GET",
+		path: `/api/v1/plugin-updates/status/${encodeURIComponent(jobId)}`
+	} : null;
 	if (sub === "/runtime") return method === "GET" ? {
 		method: "GET",
 		path: "/api/v1/runtime-update"
@@ -119,8 +140,9 @@ function routeFor(sub, method) {
 	} : null;
 	return null;
 }
-/** Every sub-path this forwarder serves — used to tell a 404 from a 405. */
-const ROUTE_SUB_PATHS = /* @__PURE__ */ new Set([
+/** Every static sub-path this forwarder serves — used to tell a 404 from a
+*  405. The dynamic `/status/<id>` path is matched separately. */
+const STATIC_SUB_PATHS = /* @__PURE__ */ new Set([
 	"",
 	"/report",
 	"/check",
@@ -130,8 +152,17 @@ const ROUTE_SUB_PATHS = /* @__PURE__ */ new Set([
 	"/runtime",
 	"/runtime-request",
 	"/runtime-source",
-	"/plugin-source"
+	"/plugin-source",
+	"/status"
 ]);
+/**
+* Whether a sub-path names a route this forwarder recognizes at all. A
+* recognized sub-path hit with an unsupported method is a 405; an unrecognized
+* one is a 404. `/status/<id>` is recognized for any single-segment id.
+*/
+function isKnownSubPath(sub) {
+	return STATIC_SUB_PATHS.has(sub) || matchJobStatusPath(sub) !== null;
+}
 /** Create the prefix-route handler forwarding to hq-edge. */
 function createUpdateForwarder(baseUrlResolver, timeoutMs = DEFAULT_FORWARD_TIMEOUT_MS) {
 	return async (req, res) => {
@@ -142,7 +173,8 @@ function createUpdateForwarder(baseUrlResolver, timeoutMs = DEFAULT_FORWARD_TIME
 		}
 		const target = routeFor(sub, req.method === "HEAD" ? "GET" : req.method ?? "");
 		if (target === null) {
-			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" });
+			const known = isKnownSubPath(sub);
+			sendJson(res, known ? 405 : 404, { error: known ? `method ${req.method} not allowed on ${sub || "/"}` : "not found" });
 			return;
 		}
 		if (req.method !== "GET" && req.method !== "POST" && req.method !== "HEAD") {

package/package.json

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

package/src/client/api.ts

@@ -29,6 +29,15 @@ export interface PluginUpdateItem {
   ignored?: boolean
   reasons?: string[]
   notes?: string[]
+  /**
+   * User-facing release metadata (schemaVersion-2 manifests). ALL optional and
+   * absent for v1 manifests — the view falls back to the package short name
+   * and version line when they are missing.
+   */
+  displayName?: string
+  description?: string
+  sizeBytes?: number
+  changes?: string[]
 }
 
 /**
@@ -49,6 +58,33 @@ export interface RuntimeUpdateEntry {
   arch?: string
   /** Exact absolute HTTPS URL of the release archive. */
   url: string
+  /**
+   * Optional user-facing metadata (schemaVersion-2 runtime manifest). All
+   * absent for v1 manifests; the panel degrades gracefully without them.
+   */
+  publishedAt?: string
+  sizeBytes?: number
+  summary?: string
+  notesUrl?: string
+  notes?: string[]
+  breaking?: string[]
+  channel?: string
+}
+
+/**
+ * The EDA host's own report of the last runtime replacement, read from
+ * `runtime-update-result.json` by hq-edge. This is the authoritative outcome
+ * after HQ Edge exits and the host swaps the runtime — it must be rendered,
+ * not discarded. `state` is `succeeded`, `rolled_back` (swap failed but the
+ * previous runtime was restored) or `failed` (no confirmed rollback).
+ */
+export interface RuntimeLastResult {
+  state: 'succeeded' | 'rolled_back' | 'failed'
+  targetVersion?: string | null
+  installedVersion?: string | null
+  at?: string
+  errorCode?: string
+  message?: string
 }
 
 export interface RuntimeUpdateInfo {
@@ -59,6 +95,8 @@ export interface RuntimeUpdateInfo {
   updateAvailable: boolean
   checkedAt?: string | null
   lastError?: string | null
+  /** The host-reported outcome of the last runtime swap; null when none. */
+  lastResult?: RuntimeLastResult | 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.
@@ -110,6 +148,21 @@ export function runtimeLatestVersion(
   return null
 }
 
+/**
+ * Set-level release metadata from a schemaVersion-2 plugin manifest. ALL
+ * fields optional: v1 manifests send none, and the panel must fall back to
+ * showing just the version then.
+ */
+export interface ReleaseInfo {
+  publishedAt?: string
+  channel?: string
+  requiresRestart?: boolean
+  summary?: string
+  notesUrl?: string
+  notes?: string[]
+  breaking?: string[]
+}
+
 export interface PluginUpdateReport {
   /** The evaluated release set; null while no manifest has been read. */
   manifestVersion: string | null
@@ -118,7 +171,13 @@ export interface PluginUpdateReport {
   actionableCount: number
   ignoredSet: boolean
   fetchedAt?: string
+  /** When the last plugin discovery ran (ISO); drives the "上次检查" row. */
+  checkedAt?: string | null
+  /** Non-empty when the last plugin discovery FAILED — the panel must show
+   *  an error row with a Retry, never the silent "no updates" empty state. */
   lastError?: string | null
+  /** Set-level release metadata; absent for v1 manifests. */
+  release?: ReleaseInfo | null
   runtime: RuntimeUpdateInfo
   /**
    * Where the plugin release manifest is read from. Optional: an older
@@ -127,6 +186,198 @@ export interface PluginUpdateReport {
   pluginSource?: PluginUpdateSource
 }
 
+// ── Durable update-job lifecycle (GET /status, GET /status/:id) ────────────
+
+/** Lifecycle phases of one durable update job. Terminal phases end the poll. */
+export type UpdatePhase =
+  | 'queued'
+  | 'resolving'
+  | 'downloading'
+  | 'verifying'
+  | 'staging'
+  | 'activating'
+  | 'awaiting-host'
+  | 'restarting'
+  | 'verifying-after-restart'
+  | 'done'
+  | 'failed'
+  | 'rolled-back'
+  | 'abandoned'
+
+/** Phases after which a job never runs again — polling stops and a result view
+ *  replaces the active-job view. */
+export const TERMINAL_PHASES: ReadonlySet<UpdatePhase> = new Set<UpdatePhase>([
+  'done',
+  'failed',
+  'rolled-back',
+  'abandoned',
+])
+
+export type UpdateKind = 'plugin-set' | 'runtime'
+
+export interface UpdateJobProgress {
+  /** 0..100 when the phase has a meaningful percentage; null otherwise. */
+  percent: number | null
+  bytesDone?: number
+  bytesTotal?: number
+  bytesPerSecond?: number
+  etaSeconds?: number
+}
+
+export interface UpdateStep {
+  name: string
+  state: 'pending' | 'running' | 'installed' | 'skipped' | 'failed'
+  percent?: number
+  message?: string
+}
+
+export interface UpdateJobResult {
+  ok: boolean
+  installedVersion: string | null
+  errorCode?: string
+  message?: string
+  rolledBack: boolean
+  finishedAt: string
+}
+
+/**
+ * One durable update job, as hq-edge reports it (`GET /status` and
+ * `/status/:id`). The UI is a projection of this job: opening the panel
+ * resumes whatever the server says is active, rather than owning the
+ * lifecycle in a DOM closure.
+ */
+export interface UpdateJob {
+  id: string
+  kind: UpdateKind
+  targetVersion: string
+  previousVersion: string | null
+  startedAt: string
+  updatedAt: string
+  phase: UpdatePhase
+  message?: string
+  progress: UpdateJobProgress
+  steps?: UpdateStep[]
+  result?: UpdateJobResult
+  logHint?: string
+}
+
+/** `GET /status`: the current active job plus a bounded list of recent ones. */
+export interface UpdateJobStatus {
+  activeJob: UpdateJob | null
+  recentJobs: UpdateJob[]
+}
+
+const PHASE_VALUES: ReadonlySet<string> = new Set<string>([
+  'queued',
+  'resolving',
+  'downloading',
+  'verifying',
+  'staging',
+  'activating',
+  'awaiting-host',
+  'restarting',
+  'verifying-after-restart',
+  'done',
+  'failed',
+  'rolled-back',
+  'abandoned',
+])
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const out = value.filter((entry): entry is string => typeof entry === 'string')
+  return out.length > 0 ? out : undefined
+}
+
+function asFiniteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+/** Defensively normalize one job payload from the wire into {@link UpdateJob}.
+ *  Unknown/older servers may omit fields; a malformed `phase` falls back to
+ *  `queued` rather than crashing the view. */
+export function normalizeJob(raw: unknown): UpdateJob | null {
+  if (raw === null || typeof raw !== 'object') return null
+  const r = raw as Record<string, unknown>
+  if (typeof r.id !== 'string' || r.id.length === 0) return null
+  const phase = typeof r.phase === 'string' && PHASE_VALUES.has(r.phase)
+    ? (r.phase as UpdatePhase)
+    : 'queued'
+  const progressRaw = (r.progress ?? {}) as Record<string, unknown>
+  const percentRaw = asFiniteNumber(progressRaw.percent)
+  const progress: UpdateJobProgress = {
+    percent: percentRaw === undefined ? null : Math.min(100, Math.max(0, percentRaw)),
+  }
+  const bytesDone = asFiniteNumber(progressRaw.bytesDone)
+  const bytesTotal = asFiniteNumber(progressRaw.bytesTotal)
+  const bytesPerSecond = asFiniteNumber(progressRaw.bytesPerSecond)
+  const etaSeconds = asFiniteNumber(progressRaw.etaSeconds)
+  if (bytesDone !== undefined) progress.bytesDone = bytesDone
+  if (bytesTotal !== undefined) progress.bytesTotal = bytesTotal
+  if (bytesPerSecond !== undefined) progress.bytesPerSecond = bytesPerSecond
+  if (etaSeconds !== undefined) progress.etaSeconds = etaSeconds
+
+  const job: UpdateJob = {
+    id: r.id,
+    kind: r.kind === 'runtime' ? 'runtime' : 'plugin-set',
+    targetVersion: typeof r.targetVersion === 'string' ? r.targetVersion : '',
+    previousVersion:
+      typeof r.previousVersion === 'string' ? r.previousVersion : null,
+    startedAt: typeof r.startedAt === 'string' ? r.startedAt : '',
+    updatedAt: typeof r.updatedAt === 'string' ? r.updatedAt : '',
+    phase,
+    progress,
+  }
+  if (typeof r.message === 'string' && r.message.length > 0) job.message = r.message
+  if (typeof r.logHint === 'string' && r.logHint.length > 0) job.logHint = r.logHint
+
+  if (Array.isArray(r.steps)) {
+    const steps: UpdateStep[] = []
+    for (const entry of r.steps) {
+      if (entry === null || typeof entry !== 'object') continue
+      const s = entry as Record<string, unknown>
+      if (typeof s.name !== 'string') continue
+      const state =
+        s.state === 'running' || s.state === 'installed' || s.state === 'skipped' || s.state === 'failed'
+          ? s.state
+          : 'pending'
+      const step: UpdateStep = { name: s.name, state }
+      const pct = asFiniteNumber(s.percent)
+      if (pct !== undefined) step.percent = pct
+      if (typeof s.message === 'string' && s.message.length > 0) step.message = s.message
+      steps.push(step)
+    }
+    if (steps.length > 0) job.steps = steps
+  }
+
+  if (r.result !== null && typeof r.result === 'object') {
+    const res = r.result as Record<string, unknown>
+    const result: UpdateJobResult = {
+      ok: res.ok === true,
+      installedVersion:
+        typeof res.installedVersion === 'string' ? res.installedVersion : null,
+      rolledBack: res.rolledBack === true,
+      finishedAt: typeof res.finishedAt === 'string' ? res.finishedAt : '',
+    }
+    if (typeof res.errorCode === 'string' && res.errorCode.length > 0) result.errorCode = res.errorCode
+    if (typeof res.message === 'string' && res.message.length > 0) result.message = res.message
+    job.result = result
+  }
+  return job
+}
+
+/** Normalize a `GET /status` payload; an empty/absent body degrades to "no
+ *  active job" rather than throwing. */
+export function normalizeJobStatus(raw: unknown): UpdateJobStatus {
+  if (raw === null || typeof raw !== 'object') return { activeJob: null, recentJobs: [] }
+  const r = raw as Record<string, unknown>
+  const activeJob = normalizeJob(r.activeJob)
+  const recentJobs = Array.isArray(r.recentJobs)
+    ? r.recentJobs.map(normalizeJob).filter((j): j is UpdateJob => j !== null)
+    : []
+  return { activeJob, recentJobs }
+}
+
 async function request<T>(path: string, init?: RequestInit): Promise<T> {
   const res = await fetch(`${UPDATE_BASE}${path}`, {
     cache: 'no-store',
@@ -153,7 +404,14 @@ export function checkUpdates(): Promise<PluginUpdateReport> {
 }
 
 export interface InstallResult {
-  ok: boolean
+  /**
+   * New durable contract: `202 { jobId, state: 'accepted' }`. The install is
+   * now an async job — poll `/status/:jobId` for progress, don't read success
+   * off this response. Legacy boolean fields are kept for older hq-edge.
+   */
+  jobId?: string
+  state?: string
+  ok?: boolean
   installedSetVersion?: string
   installed?: number
   skipped?: number
@@ -183,6 +441,8 @@ export function ignoreOffer(setVersion: string): Promise<unknown> {
  * updating → `busy`), 422 (preflight/manifest/download refused) or 503.
  */
 export interface RuntimeUpdateRequestResult {
+  /** Durable job id — poll `/status/:jobId` for the accepted job's progress. */
+  jobId?: string
   requestId?: string
   targetVersion?: string
   state?: string
@@ -258,3 +518,23 @@ export function setPluginUpdateSource(url: string): Promise<PluginUpdateSource>
     body: JSON.stringify({ url }),
   })
 }
+
+/**
+ * GET the durable job status: the currently active job (if any) plus a bounded
+ * list of recent jobs. This is what the panel reads BEFORE running discovery
+ * on open, so an in-flight install/runtime update is resumed instead of
+ * forgotten. An older hq-edge without the status route 404s — callers catch
+ * that and degrade to "no active job".
+ */
+export function fetchJobStatus(): Promise<UpdateJobStatus> {
+  return request<unknown>('/status').then(normalizeJobStatus)
+}
+
+/** GET one job by id; rejects (upstream 404 `unknown job`) for an unknown id. */
+export function fetchJob(id: string): Promise<UpdateJob> {
+  return request<unknown>(`/status/${encodeURIComponent(id)}`).then((raw) => {
+    const job = normalizeJob(raw)
+    if (job === null) throw new Error('malformed job payload')
+    return job
+  })
+}