@huaqiu/dsh-tool-plugin-update 0.0.0-stage → 0.5.21

package/src/client/update-view.ts

@@ -0,0 +1,301 @@
+/**
+ * Plugin-update review modal (browser half).
+ *
+ * Plain-DOM modal (no React tree) so it can never disturb the DSH shell's
+ * reconciliation — same rule as the sidebar entry rows. Rendered content:
+ *
+ *   - header: title + refresh
+ *   - plugin list (name, current → available, state badge, blocked reason)
+ *   - ignored-offer banner + reversible "show again"
+ *   - install action (disabled while installing / nothing actionable / offer
+ *     ignored); after install the UI keeps polling the backend state instead
+ *     of trusting the HTTP response alone, because activating a set restarts
+ *     DSH (spec §7.1: never report success on the 200/202 alone).
+ *   - independent HQ Edge runtime section (read-only report; the actual
+ *     upgrade is owned by the EDA installer).
+ *
+ * @module
+ */
+import {
+  checkUpdates,
+  ignoreOffer,
+  installSet,
+  unignoreOffer,
+  type PluginUpdateItem,
+  type PluginUpdateReport,
+} from './api.js'
+import type { UpdateCopy } from './copy.js'
+
+export interface UpdateStoreLike {
+  report(): PluginUpdateReport | null
+  installing(): boolean
+  refresh(): Promise<PluginUpdateReport | null>
+  subscribe(listener: () => void): () => void
+}
+
+function el<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  className: string,
+  text?: string,
+): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag)
+  node.className = className
+  if (text !== undefined) node.textContent = text
+  return node
+}
+
+function stateLabel(item: PluginUpdateItem, copy: UpdateCopy): string {
+  switch (item.state) {
+    case 'current':
+      return copy.state.current
+    case 'update':
+      return copy.state.update
+    case 'install':
+      return copy.state.install
+    case 'ignored':
+      return copy.state.ignored
+    case 'blocked':
+      return copy.state.blocked
+  }
+}
+
+function blockedReason(item: PluginUpdateItem, copy: UpdateCopy): string | undefined {
+  const by = item.blockedBy ?? []
+  if (by.includes('host')) return copy.blockedReason.host
+  if (by.includes('hq-edge-version')) return copy.blockedReason['hq-edge-version']
+  if (by.includes('runtime-unknown')) return copy.blockedReason['runtime-unknown']
+  return by.length > 0 ? by.join(', ') : undefined
+}
+
+/**
+ * Open (or focus) the update modal. Re-renders from the store; when the store
+ * is stale the modal first refreshes the report.
+ */
+export function openUpdateView(store: UpdateStoreLike, copy: UpdateCopy): void {
+  const existing = document.querySelector<HTMLElement>('[data-hq-plugin-update-view]')
+  if (existing !== null) {
+    existing.style.display = ''
+    return
+  }
+
+  const overlay = el('div', 'hqpu-overlay')
+  overlay.setAttribute('data-hq-plugin-update-view', '')
+  const panel = el('div', 'hqpu-panel')
+
+  // Header
+  const header = el('div', 'hqpu-header')
+  header.append(el('div', 'hqpu-title', copy.viewTitle))
+  const refreshBtn = el('button', 'hqpu-btn', copy.refresh)
+  header.append(refreshBtn)
+  const closeBtn = el('button', 'hqpu-btn hqpu-btn-ghost', copy.close)
+  header.append(closeBtn)
+
+  // Body: plugin list + ignored banner + install action + runtime section.
+  const body = el('div', 'hqpu-body')
+  const listSection = el('div', 'hqpu-section')
+  const runtimeSection = el('div', 'hqpu-section hqpu-runtime')
+  const actionBar = el('div', 'hqpu-actions')
+
+  panel.append(header, body)
+  body.append(listSection, runtimeSection, actionBar)
+  overlay.append(panel)
+  document.body.appendChild(overlay)
+
+  const disposers: Array<() => void> = []
+
+  const render = (): void => {
+    const report = store.report()
+    const installing = store.installing()
+    renderList(listSection, report, copy, installing, store)
+    renderRuntime(runtimeSection, report, copy)
+    renderActions(actionBar, report, copy, store, installing)
+  }
+
+  const unsubscribe = store.subscribe(render)
+  disposers.push(unsubscribe)
+
+  // Refresh on open (bounded; never block the shell).
+  void store.refresh().then(() => {
+    // Store notification re-renders already; nothing extra to do.
+  })
+
+  const onClose = (): void => {
+    for (const dispose of disposers) {
+      try {
+        dispose()
+      } catch {
+        /* already disposed */
+      }
+    }
+    overlay.remove()
+  }
+  closeBtn.addEventListener('click', onClose)
+  overlay.addEventListener('click', (ev) => {
+    if (ev.target === overlay) onClose()
+  })
+  refreshBtn.addEventListener('click', () => {
+    void store.refresh()
+  })
+  disposers.push(() => {
+    closeBtn.removeEventListener('click', onClose)
+    overlay.removeEventListener('click', onClose)
+    refreshBtn.removeEventListener('click', () => {})
+  })
+
+  render()
+}
+
+function renderList(
+  section: HTMLElement,
+  report: PluginUpdateReport | null,
+  copy: UpdateCopy,
+  installing: boolean,
+  store: UpdateStoreLike,
+): void {
+  section.textContent = ''
+  if (report === null) {
+    section.append(el('div', 'hqpu-empty', copy.checkFailed))
+    return
+  }
+  if (report.items.length === 0) {
+    section.append(el('div', 'hqpu-empty', copy.empty))
+    return
+  }
+
+  const manifestRow = el('div', 'hqpu-manifest')
+  manifestRow.append(
+    el('span', 'hqpu-manifest-label', `${copy.manifestVersion}`),
+    el('span', 'hqpu-manifest-value', report.manifestVersion),
+  )
+  section.append(manifestRow)
+
+  if (report.ignoredSet) {
+    const banner = el('div', 'hqpu-ignored-banner', copy.ignoredOffer)
+    const unignore = el('button', 'hqpu-btn hqpu-btn-small', copy.unignore)
+    unignore.addEventListener('click', () => {
+      void unignoreOffer(report.manifestVersion)
+        .then(() => store.refresh())
+        .catch(() => undefined)
+    })
+    banner.append(unignore)
+    section.append(banner)
+  }
+
+  const list = el('ul', 'hqpu-list')
+  for (const item of report.items) {
+    const row = el('li', `hqpu-item hqpu-item-${item.state}`)
+    const name = el('span', 'hqpu-item-name', item.name)
+    const version = el(
+      'span',
+      'hqpu-item-version',
+      item.state === 'current'
+        ? item.currentVersion
+        : `${item.currentVersion} → ${item.availableVersion}`,
+    )
+    const state = el('span', `hqpu-item-state hqpu-state-${item.state}`, stateLabel(item, copy))
+    row.append(name, version, state)
+    const reason = blockedReason(item, copy)
+    if (reason !== undefined) {
+      row.append(el('span', 'hqpu-item-reason', reason))
+    }
+    list.append(row)
+  }
+  section.append(list)
+}
+
+function renderRuntime(
+  section: HTMLElement,
+  report: PluginUpdateReport | null,
+  copy: UpdateCopy,
+): void {
+  section.textContent = ''
+  const title = el('div', 'hqpu-runtime-title', copy.runtime.title)
+  section.append(title)
+  const runtime = report?.runtime
+  if (runtime === undefined || runtime.configured === false) {
+    section.append(el('div', 'hqpu-runtime-line', copy.runtime.notConfigured))
+    return
+  }
+  if (runtime.updateAvailable && runtime.latest !== undefined) {
+    section.append(el('div', 'hqpu-runtime-line', copy.runtime.updateAvailable(runtime.latest)))
+  } else if (runtime.currentVersion !== undefined) {
+    section.append(el('div', 'hqpu-runtime-line', copy.runtime.current(runtime.currentVersion)))
+  } else {
+    section.append(el('div', 'hqpu-runtime-line', copy.runtime.unknown))
+  }
+  section.append(el('div', 'hqpu-runtime-note', copy.runtime.note))
+  if (runtime.lastError !== undefined && runtime.lastError.length > 0) {
+    section.append(el('div', 'hqpu-runtime-error', `${copy.lastError}: ${runtime.lastError}`))
+  }
+}
+
+function renderActions(
+  bar: HTMLElement,
+  report: PluginUpdateReport | null,
+  copy: UpdateCopy,
+  store: UpdateStoreLike,
+  installing: boolean,
+): void {
+  bar.textContent = ''
+  if (report === null) return
+
+  if (installing) {
+    bar.append(el('span', 'hqpu-installing', copy.installing))
+    return
+  }
+
+  const actionable = report.items.filter(
+    (item) => item.state === 'update' || item.state === 'install',
+  ).length
+  const installBtn = el(
+    'button',
+    'hqpu-btn hqpu-btn-primary',
+    actionable > 0 ? copy.installAll(actionable) : copy.state.current,
+  )
+  installBtn.disabled = actionable === 0 || report.ignoredSet
+  installBtn.addEventListener('click', () => {
+    void installSet(report.manifestVersion)
+      .then((result) => {
+        if (result.error !== undefined) {
+          bar.textContent = ''
+          bar.append(el('div', 'hqpu-error', `${copy.installError}: ${result.error}`))
+          return
+        }
+        // The set is activated atomically; DSH restarts. Keep polling the
+        // backend state rather than trusting the response alone (spec §7.1).
+        bar.textContent = ''
+        bar.append(el('span', 'hqpu-installing', copy.installSuccess))
+        void pollUntilSettled(store, report.manifestVersion)
+      })
+      .catch((err: unknown) => {
+        bar.textContent = ''
+        bar.append(
+          el('div', 'hqpu-error', `${copy.installError}: ${err instanceof Error ? err.message : String(err)}`),
+        )
+      })
+  })
+  bar.append(installBtn)
+}
+
+/** After an install, poll the backend until the update report settles
+ *  (installing flag clears or DSH restarts under us — the next load re-reads
+ *  the fresh state). */
+function pollUntilSettled(store: UpdateStoreLike, setVersion: string): void {
+  let attempts = 0
+  const tick = (): void => {
+    void store
+      .refresh()
+      .then((report) => {
+        if (store.installing()) return
+        if (report !== null && report.ignoredSet === false && attempts >= 2) return
+      })
+      .catch(() => undefined)
+      .finally(() => {
+        attempts += 1
+        if (attempts < 10) {
+          window.setTimeout(tick, 2000)
+        }
+      })
+  }
+  tick()
+}

package/src/index.ts

@@ -0,0 +1,108 @@
+/**
+ * Huaqiu EDA plugin-update DSH plugin (node half) — `@huaqiu/dsh-tool-plugin-update`.
+ *
+ * Thin adapter between the DSH Web update UI and the hq-edge plugin-update
+ * API (task dsh-plugin-discovery-and-update-with-hq-edge-update-reporting.md
+ * §7). The browser half mounts the sidebar toolbutton (badge = actionable
+ * count) and the review/confirm/ignore view; every request it makes lands on
+ * this package's same-origin prefix routes, which forward to hq-edge.
+ *
+ * ── Architectural boundary ─────────────────────────────────────────────────
+ * All update logic is owned ONCE by hq-edge (discovery, compatibility,
+ * ignore persistence, the install transaction with cross-process lock and
+ * atomic activation). This plugin is a thin adapter: no manifest fetching, no
+ * registry calls, no download/verify code, no `@hqedge/*` dependency. It only
+ * talks to hq-edge through the edge-bridge (`ctx.hqEdge.baseUrl`), matching
+ * the `@huaqiu/dsh-tool-quote` / `@huaqiu/dsh-eda-host` convention.
+ *
+ * `hqEdge` is a REQUIRED inject: without the bridge the update UI reports
+ * "hq-edge is not reachable" rather than showing stale data.
+ *
+ * @module @huaqiu/dsh-tool-plugin-update
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import { getLogger, type PluginLogger } from '@huaqiu/dsh-plugin-log'
+import { createUpdateForwarder, UPDATE_ROUTE_PREFIX } from './routes.js'
+
+/** Plugin id — matches package.json. */
+export const name = '@huaqiu/dsh-tool-plugin-update'
+
+/** Cordis services this half depends on: hq-edge bridge (REQUIRED) + the DSH
+ *  webServer surface that hosts the same-origin forwarding routes. */
+export const inject = ['hqEdge', 'webServer'] as const
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /**
+     * Provided by the hq-edge `edge-bridge` plugin (the HOST). `baseUrl` is
+     * the loopback HQ Edge endpoint, e.g. "http://localhost:18080". Read
+     * lazily on every request.
+     */
+    hqEdge: { baseUrl?: string }
+  }
+}
+
+/** Shared component name for the unified DSH-plugin log. */
+const COMPONENT = 'dsh-tool-plugin-update'
+
+let _log: PluginLogger | null = null
+function log(): PluginLogger {
+  if (_log === null) _log = getLogger(COMPONENT)
+  return _log
+}
+
+/**
+ * Host plugin body — register the forwarding routes.
+ *
+ * The HQ Edge endpoint is resolved lazily per request from `ctx.hqEdge`
+ * (edge-bridge). When the bridge is absent the plugin refuses to load: an
+ * update UI without a host would only mislead.
+ *
+ * @param ctx - real cordis context (node side).
+ * @returns disposer — unregisters the routes on plugin dispose.
+ */
+export function apply(ctx: Context): () => void {
+  const hq = ctx.hqEdge
+  if (!hq || typeof hq.baseUrl !== 'string' || hq.baseUrl.trim().length === 0) {
+    throw new Error(
+      '@huaqiu/dsh-tool-plugin-update requires a usable hq-edge context: the ' +
+        'edge-bridge plugin did not provide ctx.hqEdge.baseUrl. The update UI ' +
+        'cannot work without hq-edge — check that the bridge started.',
+    )
+  }
+
+  const getHqEdgeBaseUrl = (): string | undefined => {
+    const current = ctx.hqEdge
+    return current?.baseUrl && current.baseUrl.trim().length > 0 ? current.baseUrl : undefined
+  }
+
+  const disposers: Array<() => void> = []
+  if (ctx.webServer && typeof ctx.webServer.register === 'function') {
+    ctx.effect(() =>
+      ctx.webServer.register({
+        kind: 'prefix',
+        path: UPDATE_ROUTE_PREFIX,
+        handler: createUpdateForwarder(getHqEdgeBaseUrl),
+      }),
+    )
+  } else {
+    log().warn('webServer unavailable — plugin-update routes are not exposed; the sidebar UI cannot load data')
+  }
+
+  log().info('applying dsh-tool-plugin-update node half', {
+    routePrefix: UPDATE_ROUTE_PREFIX,
+    hqEdgeBaseUrl: getHqEdgeBaseUrl() ?? null,
+  })
+
+  return () => {
+    for (const dispose of disposers) {
+      try {
+        dispose()
+      } catch {
+        // best-effort teardown
+      }
+    }
+  }
+}

package/src/routes.ts

@@ -0,0 +1,149 @@
+/**
+ * Same-origin forwarding routes for the plugin-update UI (browser half).
+ *
+ * Browser → DSH webServer prefix route `/api/v1/huaqiu/plugin-update/…` →
+ * this handler → hq-edge loopback HTTP API `/api/v1/plugin-updates/…`.
+ *
+ * The forwarding is a THIN adapter: hq-edge owns discovery, compatibility,
+ * ignore persistence and the install transaction (with its loopback-only
+ * protection — every request below originates from this node process on the
+ * same host, so the loopback guard is satisfied naturally). This plugin
+ * carries no update logic and no `@hqedge/*` dependency.
+ *
+ * Routes (mirroring hq-edge apps/server/src/routes/plugin-updates.ts):
+ *   GET  /plugin-update/report   → GET  /api/v1/plugin-updates
+ *   POST /plugin-update/check    → POST /api/v1/plugin-updates/check
+ *   POST /plugin-update/install  → POST /api/v1/plugin-updates/install {setVersion}
+ *   POST /plugin-update/ignore   → POST /api/v1/plugin-updates/ignore {setVersion}
+ *   POST /plugin-update/unignore → POST /api/v1/plugin-updates/unignore {setVersion}
+ *   GET  /plugin-update/runtime  → GET  /api/v1/runtime-update
+ *
+ * @module
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+export const UPDATE_ROUTE_PREFIX = '/api/v1/huaqiu/plugin-update'
+
+/** End-to-end budget for one forwarded request, in milliseconds. */
+export const DEFAULT_FORWARD_TIMEOUT_MS = 30_000
+
+export type BaseUrlResolver = () => string | undefined
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(payload)
+}
+
+/** Split the sub-path off the prefix. Returns null on a bad shape. */
+function parsePath(req: IncomingMessage): string | null {
+  const url = req.url ?? ''
+  const q = url.indexOf('?')
+  const pathname = q >= 0 ? url.slice(0, q) : url
+  if (!pathname.startsWith(UPDATE_ROUTE_PREFIX)) return null
+  return pathname.slice(UPDATE_ROUTE_PREFIX.length)
+}
+
+/** Read the request body (bounded) as UTF-8 text. */
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > 64 * 1024) {
+        reject(new Error('request body too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+/** Map a sub-path to { method, path } on the hq-edge API. */
+function routeFor(sub: string): { method: string; path: string } | null {
+  if (sub === '/report' || sub === '') {
+    return { method: 'GET', path: '/api/v1/plugin-updates' }
+  }
+  if (sub === '/runtime') {
+    return { method: 'GET', path: '/api/v1/runtime-update' }
+  }
+  if (sub === '/check') return { method: 'POST', path: '/api/v1/plugin-updates/check' }
+  if (sub === '/install') return { method: 'POST', path: '/api/v1/plugin-updates/install' }
+  if (sub === '/ignore') return { method: 'POST', path: '/api/v1/plugin-updates/ignore' }
+  if (sub === '/unignore') return { method: 'POST', path: '/api/v1/plugin-updates/unignore' }
+  return null
+}
+
+/** Create the prefix-route handler forwarding to hq-edge. */
+export function createUpdateForwarder(
+  baseUrlResolver: BaseUrlResolver,
+  timeoutMs: number = DEFAULT_FORWARD_TIMEOUT_MS,
+): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+  return async (req: IncomingMessage, res: ServerResponse) => {
+    const sub = parsePath(req)
+    if (sub === null) {
+      sendJson(res, 404, { error: 'not found' })
+      return
+    }
+    const target = routeFor(sub)
+    if (target === null) {
+      sendJson(res, 404, { error: 'not found' })
+      return
+    }
+    if (req.method !== 'GET' && req.method !== 'POST' && req.method !== 'HEAD') {
+      sendJson(res, 405, { error: 'method not allowed' })
+      return
+    }
+    const base = (baseUrlResolver() ?? '').replace(/\/+$/, '')
+    if (base.length === 0) {
+      sendJson(res, 503, { error: 'hq-edge is not reachable from this plugin (no base URL)' })
+      return
+    }
+    let body = ''
+    if (req.method === 'POST') {
+      try {
+        body = await readBody(req)
+      } catch (err) {
+        sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) })
+        return
+      }
+    }
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    try {
+      const upstream = await fetch(`${base}${target.path}`, {
+        method: target.method,
+        headers: {
+          'content-type': 'application/json; charset=utf-8',
+          'user-agent': 'hq-edge-dsh-tool-plugin-update/0.5.21',
+        },
+        ...(body.length > 0 ? { body } : {}),
+        signal: controller.signal,
+      })
+      const upstreamBody = await upstream.text()
+      let json: unknown = null
+      try {
+        json = JSON.parse(upstreamBody)
+      } catch {
+        json = { raw: upstreamBody.slice(0, 512) }
+      }
+      sendJson(res, upstream.status, json)
+    } 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` })
+        return
+      }
+      sendJson(res, 502, { error: `hq-edge request failed: ${message}` })
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.