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

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.