dsh-plugin-upgrader 1.0.0 → 1.0.2

package/src/index.js

@@ -1,275 +0,0 @@
-/**
- * Host half of the dsh-plugin-upgrader bundle.
- *
- * The Plugins page's own tabs run in the browser, and the browser cannot read
- * the profile's dependency list or reach the npm registry reliably (CORS,
- * private registries, tokens). This half owns the four things the page needs:
- *
- *   GET  /api/plugin-upgrader/overview      installed bundles + published versions
- *   POST /api/plugin-upgrader/job           start a batch of upgrade/switch steps
- *   GET  /api/plugin-upgrader/job?id=<id>   poll that batch
- *   POST /api/plugin-upgrader/cancel        stop the in-flight step
- *
- * Every route is loopback-only: a batch installs packages, so a paired remote
- * device or a cross-site page must never reach it.
- *
- * Upgrade semantics follow the profile manager itself: a different version of
- * an already-installed package is a removal plus an installation, because
- * `installBundle` refuses a spec that names an installed dependency
- * (`already-installed`). The old version is reported back so the caller can
- * offer a restore.
- *
- * @module dsh-plugin-upgrader
- */
-
-import { writeJson, isLoopbackRequest, readJsonBody } from './lib/http.js'
-import { buildOverview } from './lib/overview.js'
-import { runStep, validateStep } from './lib/install.js'
-
-/** Stable plugin name; matches the cordis.patch.yml insert id. */
-export const name = 'plugin-upgrader'
-
-/** The web server is the only hard dependency; pluginManager is read lazily. */
-export const inject = ['webServer']
-
-/**
- * Prefix every route this bundle owns. The prefix is registered without a
- * trailing slash because the carrier matches `path` exactly or `path + '/'`;
- * a trailing slash here would only ever match the bare prefix itself.
- */
-const API_PREFIX = '/api/plugin-upgrader'
-
-/** Path segments are sliced off after the registered prefix. */
-const API_BASE = `${API_PREFIX}/`
-
-/** Finished jobs are kept only long enough for the last poll to read them. */
-const JOB_RETENTION_MS = 10 * 60 * 1000
-
-/**
- * A job that stops reporting progress for this long is treated as abandoned
- * and no longer blocks new work. Installs report progress per step, so a step
- * that legitimately runs longer than this is a hung child process, not work.
- */
-const STALE_JOB_MS = 15 * 60 * 1000
-
-/** How many log lines one job keeps for the panel. */
-const JOB_LOG_LIMIT = 200
-
-/** How many log lines the overview ships for a job the tab adopts. */
-const ADOPTED_LOG_LIMIT = 40
-
-/**
- * Mount the host half.
- * @param {any} ctx - the plugin context.
- */
-export function apply(ctx) {
-  /** @type {Map<string, { at: number, data: any }>} */
-  const packumentCache = new Map()
-  /** @type {Map<string, { at: number, tags?: Set<string>, error?: string }>} */
-  const tagCache = new Map()
-  /** @type {Map<string, any>} */
-  const jobs = new Map()
-  /** @type {{ requestId: string } | null} */
-  let inFlight = null
-
-  const pruneJobs = () => {
-    const cutoff = Date.now() - JOB_RETENTION_MS
-    for (const [id, job] of jobs) {
-      if (job.finishedAt !== undefined && job.finishedAt < cutoff) jobs.delete(id)
-    }
-  }
-
-  /**
-   * Run a batch job to completion in the background.
-   * @param {any} job - the mutable job record.
-   * @param {any[]} steps - the requested steps.
-   */
-  const runJob = async (job, steps) => {
-    const manager = ctx.get('pluginManager', false)
-    job.status = 'running'
-    job.heartbeatAt = Date.now()
-    for (const step of steps) {
-      if (job.cancelled === true) break
-      inFlight = { requestId: step.requestId ?? '' }
-      job.current = `${step.name}@${step.version}`
-      job.log.push(`→ ${job.current}`)
-      const outcome = await runStep(manager, step, (message) => {
-        job.log.push(message)
-        if (job.log.length > JOB_LOG_LIMIT) job.log.splice(0, job.log.length - JOB_LOG_LIMIT)
-      })
-      inFlight = null
-      job.heartbeatAt = Date.now()
-      job.results.push(outcome)
-      job.done = job.results.length
-      if (outcome.ok !== true) job.failed += 1
-      job.log.push(
-        outcome.ok === true
-          ? `✓ ${job.current} ${outcome.application ?? 'applied'}`
-          : `✗ ${job.current} ${outcome.message ?? 'failed'}`,
-      )
-    }
-    job.status = job.cancelled === true ? 'cancelled' : 'finished'
-    job.current = undefined
-    job.finishedAt = Date.now()
-    job.cacheDirty = true
-  }
-
-  /**
-   * A running job is only blocking while it is actually making progress.
-   * @returns {any | undefined} the live job, if one is genuinely running.
-   */
-  const activeJob = () => {
-    for (const job of jobs.values()) {
-      if (job.status !== 'running' && job.status !== 'queued') continue
-      const seen = job.heartbeatAt ?? job.startedAt ?? 0
-      if (Date.now() - seen < STALE_JOB_MS) return job
-      job.status = 'finished'
-      job.abandoned = true
-      job.current = undefined
-      job.finishedAt = Date.now()
-      job.log.push('! job abandoned: no progress for 15 minutes')
-    }
-    return undefined
-  }
-
-  /**
-   * One dispatcher for every route under the prefix.
-   * @param {import('node:http').IncomingMessage} req - the request.
-   * @param {import('node:http').ServerResponse} res - the response.
-   */
-  const handler = async (req, res) => {
-    if (!isLoopbackRequest(req)) {
-      writeJson(res, 403, { error: 'loopback-only' })
-      return
-    }
-    const url = new URL(req.url ?? '/', 'http://localhost')
-    const pathname = url.pathname.endsWith('/') && url.pathname.length > API_BASE.length
-      ? url.pathname.slice(0, -1)
-      : url.pathname
-    const route = pathname.slice(API_BASE.length)
-    try {
-      if (req.method === 'GET' && route === 'overview') {
-        const force = url.searchParams.get('refresh') === '1'
-        const locale = url.searchParams.get('locale') === 'zh' ? 'zh' : 'en'
-        pruneJobs()
-        const live = activeJob()
-        writeJson(res, 200, {
-          ...(await buildOverview(ctx, packumentCache, tagCache, { force, locale })),
-          /**
-           * The tab is remounted whenever the Plugins page is reopened, and the
-           * job map only lives in this process. Reporting the live job lets a
-           * fresh tab adopt work that is still running instead of firing a
-           * second batch into a 409.
-           */
-          active: live === undefined
-            ? null
-            : {
-                id: live.id,
-                status: live.status,
-                total: live.total,
-                done: live.done,
-                failed: live.failed,
-                current: live.current,
-                startedAt: live.startedAt,
-                log: live.log.slice(-ADOPTED_LOG_LIMIT),
-              },
-          jobs: [...jobs.entries()]
-            .filter(([, job]) => job.finishedAt !== undefined)
-            .map(([id, job]) => ({
-              id,
-              status: job.status,
-              failed: job.failed,
-              done: job.done,
-              total: job.total,
-              finishedAt: job.finishedAt,
-            })),
-        })
-        return
-      }
-      if (req.method === 'POST' && route === 'job') {
-        const body = await readJsonBody(req)
-        const steps = Array.isArray(body?.steps) ? body.steps : []
-        if (steps.length === 0) {
-          writeJson(res, 400, { error: 'no-steps' })
-          return
-        }
-        for (const step of steps) {
-          const problem = validateStep(step)
-          if (problem !== undefined) {
-            writeJson(res, 400, { error: problem })
-            return
-          }
-        }
-        const running = activeJob()
-        if (running !== undefined) {
-          writeJson(res, 409, {
-            error: 'busy',
-            id: running.id,
-            current: running.current,
-            done: running.done,
-            total: running.total,
-          })
-          return
-        }
-        const id = globalThis.crypto?.randomUUID?.() ?? `job-${Date.now()}-${Math.random().toString(36).slice(2)}`
-        const job = {
-          id,
-          status: 'queued',
-          total: steps.length,
-          done: 0,
-          failed: 0,
-          results: [],
-          log: [],
-          cancelled: false,
-          startedAt: Date.now(),
-        }
-        jobs.set(id, job)
-        void runJob(job, steps).catch((error) => {
-          job.status = 'finished'
-          job.finishedAt = Date.now()
-          job.log.push(`job failed: ${error instanceof Error ? error.message : String(error)}`)
-        })
-        writeJson(res, 202, { id })
-        return
-      }
-      if (req.method === 'GET' && route === 'job') {
-        const id = url.searchParams.get('id')
-        const job = id === null ? undefined : jobs.get(id)
-        if (job === undefined) {
-          writeJson(res, 404, { error: 'unknown-job' })
-          return
-        }
-        writeJson(res, 200, job)
-        return
-      }
-      if (req.method === 'POST' && route === 'cancel') {
-        const running = [...jobs.values()].find((job) => job.status === 'running')
-        if (running === undefined) {
-          writeJson(res, 200, { status: 'not-running' })
-          return
-        }
-        running.cancelled = true
-        const manager = ctx.get('pluginManager', false)
-        const target = inFlight
-        if (manager !== undefined && manager !== null && target !== null && target.requestId !== '') {
-          try {
-            await manager.cancelInstall(target.requestId)
-          } catch {
-            /* the step settles on its own; the flag above already stops the batch */
-          }
-        }
-        writeJson(res, 200, { status: 'cancelling' })
-        return
-      }
-      writeJson(res, 404, { error: 'not-found' })
-    } catch (error) {
-      const status = typeof error?.status === 'number' ? error.status : 500
-      writeJson(res, status, { error: error instanceof Error ? error.message : String(error) })
-    }
-  }
-
-  ctx.effect(
-    () => ctx.webServer.register({ kind: 'prefix', path: API_PREFIX, handler }),
-    'plugin-upgrader: routes',
-  )
-}

package/src/lib/bundle.js

@@ -1,64 +0,0 @@
-/**
- * Bundle metadata helpers.
- *
- * These translate what the profile manager reports into the fields the tab
- * renders. Pure functions again: given the same bundle they answer the same
- * thing, which is what makes them testable.
- *
- * @module dsh-plugin-upgrader/lib/bundle
- */
-
-/**
- * Classify how a profile dependency was declared.
- * @param {string | undefined} source - `BundleInfo.source`.
- * @returns {'registry' | 'path' | 'git' | 'tarball' | 'unknown'} the source family.
- */
-export function sourceKind(source) {
-  if (typeof source !== 'string' || source.trim() === '') return 'unknown'
-  const value = source.trim()
-  if (value.startsWith('file:') || value.startsWith('link:') || value.startsWith('.') || value.startsWith('/')) {
-    return 'path'
-  }
-  if (/^(git|git\+|github:|https?:\/\/[^/]*\.git)/.test(value)) return 'git'
-  if (/\.(tgz|tar\.gz)$/.test(value)) return 'tarball'
-  if (/^(npm:|[\^~]?\d|[\^~]?(latest|next|beta|canary|rc)\b)/.test(value)) return 'registry'
-  return 'unknown'
-}
-
-/**
- * Localized metadata value for the active display language.
- * @param {unknown} text - a string or `{ en, zh, … }`.
- * @param {'zh' | 'en'} locale - the requested language.
- * @returns {string | undefined} the best available text.
- */
-export function pickText(text, locale) {
-  if (typeof text === 'string') return text
-  if (text !== null && typeof text === 'object') {
-    const record = /** @type {Record<string, string>} */ (text)
-    return record[locale] ?? record.en ?? record.zh ?? Object.values(record)[0]
-  }
-  return undefined
-}
-
-/**
- * Keep an icon only when it is cheap to send: bundle metadata often embeds a
- * base64 data URL, which would bloat every overview response by ~150 KB.
- * @param {unknown} icon - the manifest icon.
- * @param {number} limit - the largest inline data URL worth sending.
- * @returns {string | undefined} a usable reference.
- */
-export function inlineIcon(icon, limit) {
-  if (typeof icon !== 'string' || icon === '') return undefined
-  return icon.startsWith('data:') && icon.length > limit ? undefined : icon
-}
-
-/**
- * Registry base URL: `null` is pnpm's own configured registry.
- * @param {{ registry?: string | null, resolved?: string | null } | undefined} registries - manager answer.
- * @returns {string} a URL without a trailing slash.
- */
-export function registryBase(registries) {
-  const candidate = registries?.registry ?? registries?.resolved ?? null
-  const value = typeof candidate === 'string' && candidate !== '' ? candidate : 'https://registry.npmjs.org/'
-  return value.replace(/\/+$/, '')
-}

package/src/lib/http.js

@@ -1,93 +0,0 @@
-/**
- * HTTP helpers shared by every route.
- *
- * The host half answers a small, fixed set of JSON endpoints, so these helpers
- * stay deliberately narrow: one trust fence, one bounded body reader, one
- * response writer.
- *
- * @module dsh-plugin-upgrader/lib/http
- */
-
-/**
- * Whether a socket address names the loopback range.
- * @param {string | undefined} address - `req.socket.remoteAddress`.
- * @returns {boolean} true for 127/8 and ::1.
- */
-export function isLoopbackAddress(address) {
-  if (address === undefined) return false
-  const normalized = address.toLowerCase()
-  if (normalized === '::1') return true
-  const v4 = normalized.startsWith('::ffff:') ? normalized.slice(7) : normalized
-  const parts = v4.split('.')
-  return parts.length === 4 && parts[0] === '127' && parts.every((part) => /^\d{1,3}$/.test(part))
-}
-
-/**
- * Request-level trust fence for a route that can install packages.
- * @param {import('node:http').IncomingMessage} req - the incoming request.
- * @returns {boolean} true when the request comes from this machine and origin.
- */
-export function isLoopbackRequest(req) {
-  if (!isLoopbackAddress(req.socket?.remoteAddress)) return false
-  const host = req.headers.host
-  if (typeof host !== 'string') return false
-  if (req.headers['sec-fetch-site'] === 'cross-site') return false
-  const origin = req.headers.origin
-  if (origin === undefined) return true
-  try {
-    return new URL(origin).host === new URL(`http://${host}`).host
-  } catch {
-    return false
-  }
-}
-
-/**
- * Read a bounded JSON object body.
- * @param {import('node:http').IncomingMessage} req - the request.
- * @param {number} maxBytes - cap before the body is dropped.
- * @returns {Promise<Record<string, unknown> | null>} the parsed object, or null.
- */
-export async function readJsonBody(req, maxBytes = 256 * 1024) {
-  const chunks = []
-  let size = 0
-  try {
-    for await (const chunk of req) {
-      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
-      size += buffer.length
-      if (size > maxBytes) {
-        req.destroy()
-        return null
-      }
-      chunks.push(buffer)
-    }
-  } catch {
-    return null
-  }
-  let text = Buffer.concat(chunks).toString('utf8')
-  if (text.charCodeAt(0) === 0xfeff) text = text.slice(1)
-  if (text === '') return null
-  let parsed
-  try {
-    parsed = JSON.parse(text)
-  } catch {
-    return null
-  }
-  return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null
-}
-
-/**
- * Write one JSON response.
- * @param {import('node:http').ServerResponse} res - the response.
- * @param {number} status - HTTP status.
- * @param {unknown} body - JSON payload.
- */
-export function writeJson(res, status, body) {
-  const payload = JSON.stringify(body)
-  res.writeHead(status, {
-    'content-type': 'application/json; charset=utf-8',
-    'cache-control': 'no-store',
-    'referrer-policy': 'no-referrer',
-    'content-length': Buffer.byteLength(payload),
-  })
-  res.end(payload)
-}

package/src/lib/install.js

@@ -1,163 +0,0 @@
-/**
- * Installing one version, and putting the plugin's state back afterwards.
- *
- * `installBundle` refuses a spec that names an already-installed dependency, so
- * replacing a version means removing first. These helpers wrap that two-step in
- * one call and undo the side effects a reinstall has on the enabled flag.
- *
- * @module dsh-plugin-upgrader/lib/install
- */
-
-/**
- * Re-apply the enabled state a step asked for after the package was replaced.
- * `installBundle` activates what it installs, so a disabled plugin would
- * otherwise come back enabled; the bundle switch is the persistent lever.
- * @param {any} manager - the plugin manager.
- * @param {{ name: string }} step - the step that just ran.
- * @param {boolean | undefined} wanted - the state to restore, if any.
- * @param {(message: string) => void} log - progress sink.
- * @returns {Promise<boolean | undefined>} the state now in effect, if known.
- */
-export async function restoreEnabledState(manager, step, wanted, log) {
-  if (wanted === undefined) return undefined
-  let current
-  try {
-    const bundles = await manager.listBundles()
-    const entry = Array.isArray(bundles) ? bundles.find((item) => item?.name === step.name) : undefined
-    current = entry?.enabled
-  } catch {
-    current = undefined
-  }
-  if (current === wanted) return current
-  log(`${wanted ? 'enable' : 'disable'} ${step.name} (restoring the previous state)`)
-  try {
-    const outcome = await manager.setBundleEnabled(step.name, wanted)
-    if (outcome?.error !== undefined) {
-      log(`  ! could not restore the enabled state: ${outcome.error.code}`)
-      return current
-    }
-    return wanted
-  } catch (error) {
-    log(`  ! could not restore the enabled state: ${error instanceof Error ? error.message : String(error)}`)
-    return current
-  }
-}
-
-/**
- * Run one step: install the exact version, falling back to remove + install,
- * then restore the plugin's previous enabled state.
- *
- * Every outcome — including a thrown manager call — comes back as one record so
- * the job log can report per-plugin success without a second error channel.
- *
- * @param {any} manager - the plugin manager.
- * @param {{ name: string, version: string, enabled?: boolean, approveBuilds?: string[] }} step - the requested change.
- * @param {(message: string) => void} log - progress sink.
- * @returns {Promise<any>} the outcome record.
- */
-export async function runStep(manager, step, log) {
-  const spec = `${step.name}@${step.version}`
-  const requestId = globalThis.crypto?.randomUUID?.() ?? `pu-${Date.now()}-${Math.random().toString(36).slice(2)}`
-  const buildApproval = Array.isArray(step.approveBuilds) && step.approveBuilds.length > 0
-    ? { approvedBuilds: step.approveBuilds }
-    : {}
-  const base = { name: step.name, version: step.version, spec, requestId }
-  const restoreEnabled = typeof step.enabled === 'boolean' ? step.enabled : undefined
-  log(`install ${spec}`)
-
-  let result
-  try {
-    result = await manager.installBundle(spec, {
-      saveExact: true,
-      requestId,
-      ...(restoreEnabled === undefined ? {} : { enabled: restoreEnabled }),
-      ...buildApproval,
-    })
-  } catch (error) {
-    return { ...base, ok: false, stage: 'install', message: error instanceof Error ? error.message : String(error) }
-  }
-  if (result?.error?.code === 'already-installed') {
-    log(`remove ${step.name} (replacing an installed dependency)`)
-    let removed
-    try {
-      removed = await manager.removeBundle(step.name)
-    } catch (error) {
-      return {
-        ...base,
-        ok: false,
-        stage: 'remove',
-        application: 'failed',
-        message: `removal failed: ${error instanceof Error ? error.message : String(error)}`,
-      }
-    }
-    if (removed?.application === 'failed' || removed?.error !== undefined) {
-      return {
-        ...base,
-        ok: false,
-        stage: 'remove',
-        application: removed?.application,
-        message: removed?.error?.code ?? 'removal refused',
-        detail: removed?.error?.diagnostic,
-      }
-    }
-    try {
-      result = await manager.installBundle(spec, {
-        saveExact: true,
-        requestId: undefined,
-        ...(restoreEnabled === undefined ? {} : { enabled: restoreEnabled }),
-        ...buildApproval,
-      })
-    } catch (error) {
-      return {
-        ...base,
-        ok: false,
-        stage: 'install',
-        application: 'failed',
-        message: `install after removal failed: ${error instanceof Error ? error.message : String(error)}`,
-      }
-    }
-  }
-  const enabled = await restoreEnabledState(manager, step, restoreEnabled, log)
-  return {
-    ...base,
-    ...(enabled === undefined ? {} : { enabled }),
-    ok: result?.application === 'applied' || result?.application === 'restart-required',
-    application: result?.application,
-    changed: result?.changed === true,
-    stage: result?.stage,
-    restartReason: result?.restartReason,
-    version: result?.version ?? step.version,
-    message: result?.error === undefined ? undefined : result.error.code,
-    detail: result?.error?.diagnostic,
-    pendingBuilds: result?.pendingBuilds,
-    warnings: result?.warnings,
-    packageResult: result?.packageResult === undefined
-      ? undefined
-      : {
-          exitCode: result.packageResult.exitCode,
-          kind: result.packageResult.kind,
-          timedOut: result.packageResult.timedOut,
-          tail: typeof result.packageResult.output === 'string'
-            ? result.packageResult.output.slice(-1600)
-            : undefined,
-        },
-  }
-}
-
-/**
- * Whether a step names something this plugin is willing to install.
- * @param {unknown} step - one element of the request body.
- * @returns {string | undefined} an error code, or undefined when valid.
- */
-export function validateStep(step) {
-  if (step === null || typeof step !== 'object') return 'invalid-step'
-  const record = /** @type {Record<string, unknown>} */ (step)
-  if (typeof record.name !== 'string' || typeof record.version !== 'string') return 'invalid-step'
-  if (record.action !== undefined && !ACTIONS.has(/** @type {string} */ (record.action))) {
-    return 'invalid-action'
-  }
-  return undefined
-}
-
-/** Allowed per-step actions. */
-export const ACTIONS = new Set(['upgrade', 'switch'])