@camstack/server 0.1.3

package/src/core/addon/addon-package.service.ts

@@ -0,0 +1,1684 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { randomUUID } from 'node:crypto'
+import { LoggingService } from '../logging/logging.service'
+import { ConfigService } from '../config/config.service'
+import { EventBusService } from '../events/event-bus.service'
+import { AddonRegistryService } from './addon-registry.service'
+import { NotificationServiceWrapper } from '../notification/notification-wrapper.service'
+import { ToastServiceWrapper } from '../notification/toast-wrapper.service'
+import type { IScopedLogger, PendingRestartMarkerPayload } from '@camstack/types'
+import type {
+  InstalledPackage,
+  PackageUpdate,
+  UpdateResult,
+  PackageVersionInfo,
+  AutoUpdateChannel,
+} from '@camstack/types'
+import { EventCategory , errMsg } from '@camstack/types'
+import {
+  AddonInstaller,
+  detectWorkspacePackagesDir,
+  ensureDir,
+  scheduleSelfRestart,
+  writePendingRestart,
+} from '@camstack/kernel'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * Framework packages (manifest `camstack.system: true`) that the
+ * `updateFrameworkPackage` cap method is allowed to update. Any other
+ * `packageName` is rejected.
+ *
+ * Mirror of `camstack.system: true` in
+ *   packages/{types,kernel,core,sdk,ui-library,shm-ring}/package.json
+ */
+export const FRAMEWORK_PACKAGE_ALLOWLIST: readonly string[] = [
+  '@camstack/types',
+  '@camstack/kernel',
+  '@camstack/core',
+  '@camstack/sdk',
+  '@camstack/ui-library',
+  // Phase 5 / D9 — the cross-platform shared-memory frame plane. A system
+  // package (native N-API module + `FrameRing`) the stream-broker / decoder /
+  // frame consumers all depend on; it can't be uninstalled.
+  '@camstack/shm-ring',
+]
+
+/** Test-only: exported for spec parity check against the manifest. */
+export function isFrameworkPackage(packageName: string): boolean {
+  return FRAMEWORK_PACKAGE_ALLOWLIST.includes(packageName)
+}
+
+// ---------------------------------------------------------------------------
+// Typed JSON helpers
+//
+// JSON.parse returns `any`, which sprays `no-unsafe-*` violations all over
+// ESLint. These tiny wrappers keep the `any` contained to one place and
+// return the `unknown` that callers must then narrow structurally.
+// ---------------------------------------------------------------------------
+
+function parseJsonUnknown(text: string): unknown {
+  // Isolate the `any` from JSON.parse to this one assignment.
+  const parsed: unknown = JSON.parse(text)
+  return parsed
+}
+
+function readJsonObject(filePath: string): Record<string, unknown> | null {
+  try {
+    const parsed = parseJsonUnknown(fs.readFileSync(filePath, 'utf-8'))
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return { ...parsed }
+    }
+  } catch { /* ignore */ }
+  return null
+}
+
+async function fetchJsonObject(response: Response): Promise<Record<string, unknown>> {
+  const parsed: unknown = await response.json()
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {}
+  }
+  return { ...parsed }
+}
+
+function asString(value: unknown, fallback = ''): string {
+  return typeof value === 'string' ? value : fallback
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return { ...value }
+  }
+  return {}
+}
+
+// ---------------------------------------------------------------------------
+// Auto-update config types
+// ---------------------------------------------------------------------------
+
+interface AutoUpdateConfig {
+  readonly global: { channel: 'off' | 'latest' | 'beta'; intervalSeconds: number }
+  readonly overrides: Record<string, 'off' | 'latest' | 'beta' | 'inherit'>
+}
+
+type AddonLoader = import('@camstack/kernel').AddonLoader
+
+// ---------------------------------------------------------------------------
+// Npm search types
+// ---------------------------------------------------------------------------
+
+interface NpmSearchResult {
+  readonly name: string
+  readonly version: string
+  readonly description: string
+  readonly keywords: string[]
+  readonly date: string
+  readonly publisher: { readonly username: string }
+}
+
+interface AddonSearchResult {
+  readonly name: string
+  readonly version: string
+  readonly description: string
+  readonly keywords: readonly string[]
+  readonly publishedAt: string
+  readonly author: string
+  readonly installed: boolean
+  readonly installedVersion?: string
+}
+
+// ---------------------------------------------------------------------------
+// Cache types
+// ---------------------------------------------------------------------------
+
+interface CachedUpdates {
+  readonly updates: readonly PackageUpdate[]
+  readonly expiresAt: number
+}
+
+interface CachedSearch {
+  readonly results: readonly NpmSearchResult[]
+  readonly timestamp: number
+}
+
+interface CachedVersions {
+  readonly versions: readonly PackageVersionInfo[]
+  readonly expiresAt: number
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Core packages that live in the server's own node_modules */
+const CORE_MANAGED_PACKAGES: readonly string[] = ['@camstack/core', '@camstack/types']
+
+export class AddonPackageService {
+  private readonly logger: IScopedLogger
+
+  /** AddonInstaller from @camstack/kernel (may be null if kernel unavailable) */
+  private installer: AddonInstaller | null = null
+
+  /** AddonLoader for reloadPackages (may be null) */
+  private loader: AddonLoader | null = null
+
+  // -- Caches ---------------------------------------------------------------
+  private cachedUpdates: CachedUpdates | null = null
+  private searchCache: CachedSearch | null = null
+  private readonly versionCache = new Map<string, CachedVersions>()
+
+  // -- Auto-update state ----------------------------------------------------
+  private autoUpdateConfig: AutoUpdateConfig = {
+    global: { channel: 'off', intervalSeconds: 21600 },
+    overrides: {},
+  }
+  private autoUpdateTimer: ReturnType<typeof setInterval> | null = null
+
+  // -- Timing constants -----------------------------------------------------
+  // Short TTL — operators expect to see freshly-published versions
+  // within minutes of `npm publish`, not hours. The Addons page kicks
+  // a force-refresh on mount so the first navigation after publish
+  // always picks up the new version regardless of TTL state.
+  private static readonly UPDATE_CACHE_TTL_MS = 10 * 60 * 1000 // 10 minutes
+  private static readonly SEARCH_CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
+  private static readonly VERSION_CACHE_TTL_MS = 10 * 60 * 1000 // 10 minutes
+  private static readonly NPM_REGISTRY = 'https://registry.npmjs.org'
+  private static readonly REGISTRY_TIMEOUT_MS = 10_000
+
+  constructor(
+    private readonly loggingService: LoggingService,
+    private readonly eventBusService: EventBusService,
+    private readonly configService: ConfigService,
+    private readonly addonRegistry: AddonRegistryService,
+    private readonly notificationService: NotificationServiceWrapper,
+    private readonly toastService: ToastServiceWrapper,
+  ) {
+    this.logger = this.loggingService.createLogger('AddonPackageService')
+
+    // Initialize installer eagerly (no async needed).
+    // Ensures install/uninstall works before full module init completes.
+    try {
+      const dataDir = process.env.CAMSTACK_DATA ?? 'camstack-data'
+      const addonsDir = path.resolve(dataDir, 'addons')
+      const workspacePackagesDir = detectWorkspacePackagesDir(__dirname)
+      // `CAMSTACK_NPM_REGISTRY` override exists primarily for the e2e
+      // harness — it points the installer at a sandboxed verdaccio so
+      // the CLI-vs-npm version-interaction tests don't hit the public
+      // registry. In production this stays unset and the installer
+      // falls back to `https://registry.npmjs.org` (the default in
+      // AddonInstaller). Both the `npm install` shell-out AND the
+      // metadata HTTPS fetch honour this value.
+      const registry = process.env['CAMSTACK_NPM_REGISTRY']
+      this.installer = new AddonInstaller({
+        addonsDir,
+        workspacePackagesDir: workspacePackagesDir ?? undefined,
+        ...(registry ? { registry } : {}),
+      })
+      ensureDir(addonsDir)
+    } catch (error: unknown) {
+      const msg = errMsg(error)
+      this.logger.warn('Installer init failed', { meta: { error: msg } })
+    }
+
+    // Load auto-update config from disk
+    this.autoUpdateConfig = this.loadAutoUpdateConfig()
+
+    // Start auto-update timer after a delay (give server time to boot)
+    setTimeout(() => this.scheduleAutoUpdate(), 30_000)
+  }
+
+  // =========================================================================
+  // Install / Uninstall
+  // =========================================================================
+
+  /** Install an addon from npm registry */
+  async installFromNpm(name: string, version?: string): Promise<{ name: string; version: string }> {
+    this.requireInstaller()
+    this.logger.info(`installFromNpm: ${name}@${version ?? 'latest'}`, { meta: { addonsDir: this.installer!['addonsDir'] as string } })
+    const result = await this.installer!.installFromNpm(name, version)
+    this.logger.info('installFromNpm result', { meta: { name: result.name, version: result.version } })
+    return result
+  }
+
+  /** Install an addon from the local workspace (dev mode) */
+  async installFromWorkspace(name: string): Promise<{ name: string; version: string }> {
+    this.requireInstaller()
+    const result = await this.installer!.install(name)
+    this.logger.info('Installed from workspace', { meta: { name: result.name, version: result.version } })
+    return result
+  }
+
+  /** Install an addon from an uploaded tgz file */
+  async installFromUpload(tgzPath: string): Promise<{ name: string; version: string }> {
+    this.requireInstaller()
+    const result = await this.installer!.installFromTgz(tgzPath)
+
+    // Mark install source as 'upload' in both legacy marker + central manifest
+    const addonsDir = this.resolveAddonsDir()
+    const targetDir = path.join(addonsDir, result.name)
+    try {
+      fs.writeFileSync(path.join(targetDir, '.install-source'), 'upload')
+    } catch (err) {
+      this.logger.debug('Non-fatal: failed to write .install-source marker', { meta: { error: errMsg(err) } })
+    }
+    this.installer!.manifest.upsert(result.name, {
+      version: result.version,
+      source: 'upload',
+    })
+
+    this.logger.info('Installed from upload', { meta: { name: result.name, version: result.version } })
+    return result
+  }
+
+  /**
+   * Roll an addon back to the version it had before the most recent
+   * `updatePackage` call. The backup directory pointer lives in the
+   * AddonInstaller manifest; this method restores it, refreshes the
+   * registry, restarts the addon, and notifies the user via toast.
+   *
+   * Returns `{ rolledBackTo }` — null when there's no backup available
+   * (the previous update either succeeded its health check or never
+   * happened), the restored version string otherwise.
+   */
+  async rollbackPackage(name: string): Promise<{ rolledBackTo: string | null }> {
+    this.requireInstaller()
+    if (!this.isAllowedPackage(name)) {
+      throw new Error(`Package "${name}" is not an allowed @camstack/* package`)
+    }
+
+    const previousVersion = this.getInstalledPackageVersion(name)
+    const rolledBackTo = await this.installer!.rollbackAddon(name)
+    if (rolledBackTo == null) {
+      this.logger.info('No backup available to roll back', { meta: { name } })
+      return { rolledBackTo: null }
+    }
+
+    // Refresh registry + emit a synthetic 'updated' lifecycle event
+    // (the version went BACK, but downstream consumers care about the
+    // version change itself, not the direction).
+    this.addonRegistry.refreshPackageVersion(name, rolledBackTo)
+    this.addonRegistry.emitUpdateEvent(name, previousVersion, rolledBackTo)
+
+    const addonId = this.extractAddonId(name)
+    if (addonId) {
+      try {
+        await this.addonRegistry.restartAddon(addonId)
+        this.logger.info('Addon restarted after rollback', {
+          tags: { addonId },
+          meta: { rolledBackTo },
+        })
+      } catch (reloadError: unknown) {
+        this.logger.warn('Restart failed after rollback', {
+          tags: { addonId },
+          meta: { error: errMsg(reloadError) },
+        })
+      }
+    }
+
+    // Clear update cache so the UI reflects the new state.
+    this.cachedUpdates = null
+    return { rolledBackTo }
+  }
+
+  /** Uninstall an addon (refuses to uninstall protected/required packages) */
+  async uninstall(name: string): Promise<void> {
+    this.requireInstaller()
+
+    if (this.isProtected(name)) {
+      throw new Error(`Cannot uninstall protected package "${name}"`)
+    }
+
+    await this.installer!.uninstall(name)
+    this.logger.info('Uninstalled', { meta: { name } })
+  }
+
+  // =========================================================================
+  // Full install orchestration (npm install → reload → load addons → toast)
+  // =========================================================================
+
+  /**
+   * Full install-from-npm orchestration:
+   * 1. npm install
+   * 2. Reload packages
+   * 3. Load new addons into registry
+   * 4. Broadcast toast notification
+   *
+   * Returns loaded/failed addon ids.
+   */
+  async installAndLoad(
+    packageName: string,
+    version?: string,
+  ): Promise<{ success: true; loaded: string[]; failed: string[] }> {
+    const versionLabel = version ? `@${version}` : '@latest'
+    this.logger.info('Installing package...', { meta: { packageName, version: versionLabel } })
+
+    try {
+      const installResult = await this.installFromNpm(packageName, version)
+      this.logger.info('npm install complete', { meta: { name: installResult.name, version: installResult.version } })
+    } catch (err) {
+      const msg = errMsg(err)
+      this.logger.error('npm install failed', { meta: { packageName, error: msg } })
+      this.toastService.broadcast({
+        title: 'Install Failed',
+        message: `Failed to install ${packageName}: ${msg}`,
+        severity: 'warning',
+      })
+      throw new Error(`Install failed: ${msg}`, { cause: err })
+    }
+
+    try {
+      await this.reloadPackages()
+    } catch (err) {
+      const msg = errMsg(err)
+      this.logger.error('reloadPackages failed', { meta: { error: msg } })
+    }
+
+    let loaded: string[] = []
+    let failed: string[] = []
+    try {
+      const result = await this.addonRegistry.loadNewAddons()
+      loaded = result.loaded
+      failed = result.failed
+    } catch (err) {
+      const msg = errMsg(err)
+      this.logger.error('loadNewAddons failed', { meta: { error: msg } })
+      failed.push(packageName)
+    }
+
+    this.toastService.broadcast({
+      title: failed.length ? 'Addon Installed (with warnings)' : 'Addon Installed',
+      message: `${packageName} installed${loaded.length ? ` — addons: ${loaded.join(', ')}` : ''}${failed.length ? ` — failed: ${failed.join(', ')}` : ''}`,
+      severity: failed.length ? 'warning' : 'info',
+    })
+    return { success: true, loaded, failed }
+  }
+
+  /**
+   * Full install-from-workspace orchestration:
+   * 1. Workspace install
+   * 2. Reload packages
+   * 3. Load new addons into registry
+   * 4. Broadcast toast notification
+   */
+  async installFromWorkspaceAndLoad(
+    packageName: string,
+  ): Promise<{ success: true; loaded: string[]; failed: string[] }> {
+    this.logger.info('Installing from workspace...', { meta: { packageName } })
+
+    try {
+      const result = await this.installFromWorkspace(packageName)
+      this.logger.info('Workspace install complete', { meta: { name: result.name, version: result.version } })
+    } catch (err) {
+      const msg = errMsg(err)
+      this.logger.error('Workspace install failed', { meta: { error: msg } })
+      this.toastService.broadcast({ title: 'Install Failed', message: msg, severity: 'warning' })
+      throw new Error(`Workspace install failed: ${msg}`, { cause: err })
+    }
+
+    try {
+      await this.reloadPackages()
+    } catch (err) { this.logger.warn('Non-fatal: failed to reload packages after workspace install', { meta: { error: errMsg(err) } }) }
+
+    let loaded: string[] = []
+    let failed: string[] = []
+    try {
+      const result = await this.addonRegistry.loadNewAddons()
+      loaded = result.loaded
+      failed = result.failed
+    } catch (err) {
+      this.logger.warn('Failed to load new addons after install', { meta: { error: errMsg(err) } })
+      failed.push(packageName)
+    }
+
+    this.toastService.broadcast({
+      title: 'Addon Installed from Workspace',
+      message: `${packageName} installed${loaded.length ? ` — addons: ${loaded.join(', ')}` : ''}`,
+      severity: failed.length ? 'warning' : 'info',
+    })
+    return { success: true, loaded, failed }
+  }
+
+  /**
+   * Full uninstall orchestration:
+   * 1. Emit uninstall lifecycle event
+   * 2. Uninstall package
+   * 3. Reload packages
+   * 4. Load addons (to update registry)
+   * 5. Broadcast toast notification
+   */
+  async uninstallAndReload(packageName: string): Promise<{ success: true }> {
+    if (this.isProtected(packageName)) {
+      throw new Error(`Package ${packageName} is required and cannot be uninstalled`)
+    }
+
+    try {
+      this.addonRegistry.emitUninstallEvent(packageName)
+      this.logger.info('Uninstalling package...', { meta: { packageName } })
+      await this.uninstall(packageName)
+      this.logger.info('Uninstall complete', { meta: { packageName } })
+    } catch (err) {
+      const msg = errMsg(err)
+      this.logger.error('Uninstall failed', { meta: { packageName, error: msg } })
+      this.toastService.broadcast({ title: 'Uninstall Failed', message: msg, severity: 'warning' })
+      throw new Error(`Uninstall failed: ${msg}`, { cause: err })
+    }
+
+    await this.reloadPackages().catch((err) => { this.logger.warn('Non-fatal: failed to reload packages after uninstall', { meta: { error: errMsg(err) } }) })
+    await this.addonRegistry.loadNewAddons().catch((err) => { this.logger.warn('Non-fatal: failed to load new addons after uninstall', { meta: { error: errMsg(err) } }) })
+
+    this.toastService.broadcast({
+      title: 'Addon Uninstalled',
+      message: `${packageName} has been removed`,
+      severity: 'info',
+    })
+    return { success: true }
+  }
+
+  // =========================================================================
+  // Workspace
+  // =========================================================================
+
+  /** Check if workspace packages directory is available (dev mode) */
+  isWorkspaceAvailable(): boolean {
+    return this.installer?.workspaceDir != null
+  }
+
+  /** List addon packages available in the workspace but not necessarily installed */
+  listWorkspacePackages(): Array<{ name: string; version: string; installed: boolean }> {
+    const workspaceDir = this.installer?.workspaceDir
+    if (!workspaceDir) return []
+
+    const results: Array<{ name: string; version: string; installed: boolean }> = []
+    const installed = new Set(this.listInstalled().map((p) => p.name))
+
+    try {
+      for (const entry of fs.readdirSync(workspaceDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue
+        const pkgJsonPath = path.join(workspaceDir, entry.name, 'package.json')
+        if (!fs.existsSync(pkgJsonPath)) continue
+        const pkg = readJsonObject(pkgJsonPath)
+        if (!pkg) {
+          this.logger.debug('Skipping malformed package.json', { meta: { entryName: entry.name } })
+          continue
+        }
+        const name = asString(pkg['name'])
+        if (!name.startsWith('@camstack/')) continue
+        const camstack = asRecord(pkg['camstack'])
+        if (!Array.isArray(camstack['addons'])) continue
+        results.push({
+          name,
+          version: asString(pkg['version'], '0.0.0'),
+          installed: installed.has(name),
+        })
+      }
+    } catch (err) { this.logger.warn('Failed to read workspace directory', { meta: { error: errMsg(err) } }) }
+
+    return results
+  }
+
+  // =========================================================================
+  // Query
+  // =========================================================================
+
+  /** List all installed addon packages */
+  listInstalled(): InstalledPackage[] {
+    if (!this.installer) {
+      throw new Error('AddonInstaller is not available — cannot list installed packages. Ensure @camstack/kernel is installed and the addons directory is accessible')
+    }
+    return this.installer.listInstalled()
+  }
+
+  /**
+   * Check whether a package is currently protected from uninstall.
+   *
+   * Source of truth: the running `AddonRegistry`'s loaded manifests —
+   * any addon in this package with `camstack.addons[N].protected: true`
+   * marks the whole package non-removable. This replaces the legacy
+   * `AddonInstaller.REQUIRED_PACKAGES` hardcoded list.
+   *
+   * Fallback: if the registry hasn't loaded yet (early-boot install
+   * paths, tests with stub registries), fall back to the legacy list
+   * so we don't accidentally allow uninstalling `@camstack/core` etc.
+   * during a window where protection metadata isn't yet readable.
+   */
+  isProtected(name: string): boolean {
+    const fromRegistry = this.addonRegistry?.isPackageProtected?.(name)
+    if (typeof fromRegistry === 'boolean') return fromRegistry
+    return AddonInstaller.REQUIRED_PACKAGES.includes(name)
+  }
+
+  /**
+   * Set of package names with a pending pre-update backup on disk —
+   * i.e. packages where `applyUpdate` last ran and the post-update
+   * health-check hasn't cleared the backup pointer yet, OR the user
+   * explicitly hasn't called `clearBackup`.
+   *
+   * The Rollback button in admin-ui's AddonCard reads this via the
+   * cap-router's `hasBackup` flag on `addons.list`.
+   */
+  getRollbackablePackages(): ReadonlySet<string> {
+    if (!this.installer) return new Set()
+    const out = new Set<string>()
+    for (const entry of this.installer.manifest.list()) {
+      if (entry.lastBackupDir) out.add(entry.name)
+    }
+    return out
+  }
+
+  // =========================================================================
+  // Update checks
+  // =========================================================================
+
+  /**
+   * Check npm registry for newer versions of all managed @camstack/* packages.
+   * Includes both core packages (server root) and addon packages (data/addons).
+   * Results are cached for 6 hours.
+   */
+  async checkUpdates(force?: boolean): Promise<readonly PackageUpdate[]> {
+    if (force) {
+      this.cachedUpdates = null
+    }
+
+    const now = Date.now()
+    if (this.cachedUpdates && this.cachedUpdates.expiresAt > now) {
+      // this.logger.debug('Returning cached update check results')
+      return this.cachedUpdates.updates
+    }
+
+    this.logger.info('Checking for package updates...')
+    const updates: PackageUpdate[] = []
+
+    // Check installed addon packages in addons dir
+    const addonUpdates = await this.checkAddonPackageUpdates()
+    updates.push(...addonUpdates)
+
+    this.logger.info('Found package updates', { meta: { count: updates.length, updates: updates.map((u) => ({ name: u.name, currentVersion: u.currentVersion, latestVersion: u.latestVersion })) } })
+
+    this.cachedUpdates = {
+      updates,
+      expiresAt: now + AddonPackageService.UPDATE_CACHE_TTL_MS,
+    }
+    return updates
+  }
+
+  /** Clear the cached update check results */
+  clearUpdateCache(): void {
+    this.cachedUpdates = null
+    this.logger.info('Update cache cleared')
+  }
+
+  /**
+   * Diff an explicit list of installed packages against npm — the
+   * agent-targeted counterpart of `checkUpdates`. The hub owns the npm
+   * machinery; an agent only reports what it has installed (via
+   * `$agent.status`), so the hub does the registry lookups + diff here.
+   *
+   * Not cached: the caller decides freshness (an agent roster changes
+   * per deploy, and `forceRefresh` must always be live).
+   */
+  async checkUpdatesForInstalled(
+    installed: readonly { name: string; version: string }[],
+  ): Promise<readonly PackageUpdate[]> {
+    // De-dup by package name — one npm package may bundle several addons.
+    const seen = new Map<string, string>()
+    for (const pkg of installed) {
+      if (pkg.name.length > 0 && !seen.has(pkg.name)) seen.set(pkg.name, pkg.version)
+    }
+    const updates: PackageUpdate[] = []
+    await Promise.all(
+      [...seen].map(async ([name, version]) => {
+        if (!this.isAllowedPackage(name)) return
+        const latestVersion = await this.fetchLatestVersion(name)
+        if (latestVersion === null || latestVersion === version) return
+        const category = this.categorize(name)
+        updates.push({
+          name,
+          currentVersion: version,
+          latestVersion,
+          category,
+          requiresRestart: category === 'core',
+        })
+      }),
+    )
+    return updates
+  }
+
+  /**
+   * Resolve `name@version` and `npm pack` it into a tarball buffer
+   * WITHOUT installing. Used to push a package update to an agent: the
+   * hub packs here, then ships the tgz via `$agent.deploy` — agents
+   * need no npm runtime of their own.
+   */
+  async packPackage(
+    name: string,
+    version?: string,
+  ): Promise<{ buffer: Buffer; version: string; filename: string }> {
+    const registry = process.env['CAMSTACK_NPM_REGISTRY']
+    const resolvedVersion = await resolveNpmVersion(name, version ?? 'latest', registry)
+    const spec = `${name}@${resolvedVersion}`
+    const destDir = fs.mkdtempSync(path.join(os.tmpdir(), 'camstack-pack-'))
+    try {
+      const args = ['pack', spec, '--pack-destination', destDir, ...buildNpmRegistryArgs(registry)]
+      await execFileAsync('npm', args, { timeout: 120_000 })
+      const onDisk = fs.readdirSync(destDir).find((f) => f.endsWith('.tgz'))
+      if (onDisk === undefined) {
+        throw new Error(`packPackage: npm pack produced no tarball for ${spec}`)
+      }
+      const buffer = fs.readFileSync(path.join(destDir, onDisk))
+      return { buffer, version: resolvedVersion, filename: onDisk }
+    } finally {
+      fs.rmSync(destDir, { recursive: true, force: true })
+    }
+  }
+
+  // =========================================================================
+  // npm search
+  // =========================================================================
+
+  /** Search npm for camstack addon packages, optionally filtered by query */
+  async searchNpm(query?: string): Promise<AddonSearchResult[]> {
+    const npmResults = await this.fetchSearchFromNpm()
+
+    let filtered: readonly NpmSearchResult[] = npmResults
+    if (query) {
+      const q = query.toLowerCase()
+      filtered = npmResults.filter(
+        (r) =>
+          r.name.toLowerCase().includes(q) ||
+          r.description?.toLowerCase().includes(q) ||
+          r.keywords?.some((k) => k.toLowerCase().includes(q)),
+      )
+    }
+
+    return filtered.map((r) => ({
+      name: r.name,
+      version: r.version,
+      description: r.description ?? '',
+      keywords: r.keywords ?? [],
+      publishedAt: r.date ?? '',
+      author: r.publisher?.username ?? '',
+      installed: false, // caller will enrich
+      installedVersion: undefined,
+    }))
+  }
+
+  // =========================================================================
+  // Package versions
+  // =========================================================================
+
+  /**
+   * Fetch all published versions of a package from npm, including dist-tags.
+   * Results are cached for 10 minutes per package.
+   */
+  async getPackageVersions(name: string): Promise<readonly PackageVersionInfo[]> {
+    const now = Date.now()
+    const cached = this.versionCache.get(name)
+    if (cached && cached.expiresAt > now) {
+      return cached.versions
+    }
+
+    try {
+      const encodedName = name.replace('/', '%2F')
+      const url = `${AddonPackageService.NPM_REGISTRY}/${encodedName}`
+      const response = await fetch(url, {
+        signal: AbortSignal.timeout(AddonPackageService.REGISTRY_TIMEOUT_MS),
+      })
+
+      if (!response.ok) {
+        this.logger.debug('Registry returned non-ok status', { meta: { name, status: response.status } })
+        return []
+      }
+
+      const data = await fetchJsonObject(response)
+      const distTags = asRecord(data['dist-tags'])
+      const versions = asRecord(data['versions'])
+      const time = asRecord(data['time'])
+
+      // Build a reverse lookup: version -> list of dist-tag names
+      const tagsByVersion = new Map<string, string[]>()
+      for (const [tag, ver] of Object.entries(distTags)) {
+        const verStr = asString(ver)
+        if (!verStr) continue
+        const existing = tagsByVersion.get(verStr) ?? []
+        tagsByVersion.set(verStr, [...existing, tag])
+      }
+
+      const result: PackageVersionInfo[] = Object.entries(versions).map(
+        ([ver, rawMeta]) => {
+          const meta = asRecord(rawMeta)
+          return {
+            version: ver,
+            publishedAt: asString(time[ver]),
+            deprecated: typeof meta['deprecated'] === 'string' ? meta['deprecated'] : undefined,
+            distTags: tagsByVersion.get(ver) ?? [],
+          }
+        },
+      )
+
+      // Sort by published date descending (newest first)
+      result.sort((a, b) => {
+        if (!a.publishedAt && !b.publishedAt) return 0
+        if (!a.publishedAt) return 1
+        if (!b.publishedAt) return -1
+        return new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime()
+      })
+
+      this.versionCache.set(name, {
+        versions: result,
+        expiresAt: now + AddonPackageService.VERSION_CACHE_TTL_MS,
+      })
+
+      return result
+    } catch (error: unknown) {
+      const msg = errMsg(error)
+      this.logger.warn('Failed to fetch versions', { meta: { name, error: msg } })
+      return cached?.versions ?? []
+    }
+  }
+
+  // =========================================================================
+  // Update / restart
+  // =========================================================================
+
+  /**
+   * Update a specific package. For addon packages, triggers hot-reload.
+   * For core packages, installs in the server root and returns requiresRestart: true.
+   */
+  async updatePackage(name: string, version?: string): Promise<UpdateResult> {
+    if (!this.isAllowedPackage(name)) {
+      return {
+        success: false,
+        version: '',
+        requiresRestart: false,
+        error: `Package "${name}" is not an allowed @camstack/* package`,
+      }
+    }
+
+    // Dev-mode npm-install gate REMOVED (2026-05-12). The legacy
+    // workspace-link flow assumed addons in dev came from `packages/*`
+    // and a stray "Update" click would clobber the source. With the
+    // CLI's `camstack push` flow taking over that responsibility, the
+    // hub now treats every install identically — straight from npm
+    // (or from the operator's deliberate push). No more env var
+    // gymnastics required to update an addon from the UI.
+
+    const category = this.categorize(name)
+    this.logger.info('Updating package', { meta: { name, version, category } })
+
+    try {
+      let updatedVersion: string
+
+      if (category === 'addon') {
+        // Reuse the long-lived installer the registry already configured
+        // (correct addonsDir + installSource + workspaceDir) — building a
+        // fresh one with `new AI({ addonsDir })` would lose installSource
+        // detection and skip the central manifest write.
+        this.requireInstaller()
+        const addonInstaller = this.installer!
+        const previousVersion = this.getInstalledPackageVersion(name)
+        // getInstalledPackageVersion returns '' when not installed
+        const isFirstInstall = !previousVersion
+
+        // First-time installs go through the original installFromNpm path;
+        // applyUpdate explicitly refuses when the package isn't tracked yet.
+        // Subsequent updates take the safe path: backup current install,
+        // run the install, auto-restore on failure (PR2).
+        let result: { version: string; backupDir?: string }
+        if (isFirstInstall) {
+          const r = await addonInstaller.installFromNpm(name, version)
+          result = { version: r.version }
+        } else {
+          const r = await addonInstaller.applyUpdate(name, version)
+          result = { version: r.version, backupDir: r.backupDir }
+        }
+        updatedVersion = result.version
+
+        // Update version in registry so UI reflects the change immediately
+        this.addonRegistry.refreshPackageVersion(name, updatedVersion)
+
+        // Emit addon.updated lifecycle event
+        this.addonRegistry.emitUpdateEvent(name, previousVersion, updatedVersion)
+
+        this.logger.info('Addon package updated, triggering hot-reload', { meta: { name, updatedVersion } })
+        const addonId = this.extractAddonId(name)
+        if (addonId) {
+          try {
+            await this.addonRegistry.restartAddon(addonId)
+            this.logger.info('Addon restarted after update', { tags: { addonId } })
+            // Restart succeeded — drop the backup. We keep it on failure
+            // (caller can roll back manually via UI).
+            if (result.backupDir != null) {
+              addonInstaller.clearBackup(name)
+            }
+          } catch (reloadError: unknown) {
+            const msg = errMsg(reloadError)
+            this.logger.warn(
+              'Hot-reload failed for addon — backup retained for rollback',
+              { tags: { addonId }, meta: { error: msg, backupDir: result.backupDir } },
+            )
+          }
+        }
+
+        // Clear update cache so next check reflects new state
+        this.cachedUpdates = null
+
+        this.sendUpdateNotification(name, updatedVersion)
+        return { success: true, version: updatedVersion, requiresRestart: false }
+      }
+
+      // Core package -- install to data/addons/. Self-contained addon
+      // bundles no longer require the reverse symlink under
+      // hub/node_modules/@camstack/ — addons resolve everything from
+      // their own inlined deps.
+      const addonsDir = this.resolveAddonsDir()
+      const { installPackageFromNpmSync } = await import('@camstack/kernel')
+      const dirName = name.replace(/^@camstack\//, '')
+      const targetDir = path.join(addonsDir, dirName)
+      const packageSpec = version ? `${name}@${version}` : name
+      installPackageFromNpmSync(packageSpec, targetDir)
+
+      updatedVersion = this.getInstalledPackageVersion(name)
+
+      // Invalidate cache after update
+      this.cachedUpdates = null
+
+      this.logger.info('Core package updated -- restart required', { meta: { name, updatedVersion } })
+      this.sendUpdateNotification(name, updatedVersion)
+      return { success: true, version: updatedVersion, requiresRestart: true }
+    } catch (error: unknown) {
+      const msg = errMsg(error)
+      this.logger.error('Failed to update package', { meta: { name, error: msg } })
+      return { success: false, version: '', requiresRestart: false, error: msg }
+    }
+  }
+
+  /**
+   * Gracefully restart the server process.
+   *
+   * Writes a `manual` restart marker so the post-boot service can
+   * emit `system.restart-completed` on the next boot (powers the
+   * admin-UI "Server restarted" toast). Emits `system.restarting`
+   * with the same payload so subscribers can show a reconnect overlay
+   * immediately. Then delegates to `scheduleSelfRestart` which picks
+   * the right exit path (Electron `app.relaunch` vs supervisor-driven
+   * `process.exit`).
+   */
+  restartServer(requestedBy?: string): void {
+    this.logger.info('Server restart requested -- initiating graceful shutdown')
+
+    const payload: PendingRestartMarkerPayload = {
+      kind: 'manual',
+      requestedAt: Date.now(),
+      ...(requestedBy !== undefined ? { requestedBy } : {}),
+    }
+
+    try {
+      writePendingRestart(this.resolveDataDir(), payload)
+    } catch (err) {
+      // Marker write failure shouldn't block the restart — log + continue.
+      this.logger.warn('Failed to write restart marker; restart will proceed without completion toast', {
+        meta: { error: errMsg(err) },
+      })
+    }
+
+    this.eventBusService.emit({
+      id: randomUUID(),
+      timestamp: new Date(),
+      source: { type: 'core', id: 'addon-package-service' },
+      category: EventCategory.SystemRestarting,
+      data: payload,
+    })
+
+    // 10s grace gives in-flight requests time to drain.
+    scheduleSelfRestart({ delayMs: 10_000 })
+  }
+
+  // =========================================================================
+  // Framework live-update
+  //
+  // Spec: docs/superpowers/specs/2026-05-14-framework-live-update-design.md
+  // =========================================================================
+
+  /**
+   * Snapshot of installed framework packages — drives the admin-UI
+   * "System packages" panel. Best-effort: `latestVersion` is null when
+   * the npm lookup fails (offline, registry unreachable), and the UI
+   * hides the Update button for those rows.
+   *
+   * Latest-version lookups run in parallel against npm so the full
+   * snapshot returns in roughly the slowest individual lookup, not
+   * the sum.
+   */
+  async listFrameworkPackages(): Promise<readonly {
+    packageName: string
+    currentVersion: string
+    latestVersion: string | null
+    hasUpdate: boolean
+    description?: string
+  }[]> {
+    const registry = process.env['CAMSTACK_NPM_REGISTRY']
+
+    const rows = await Promise.all(
+      FRAMEWORK_PACKAGE_ALLOWLIST.map(async (packageName) => {
+        const manifest = readResolvedPackageManifest(packageName)
+        const currentVersion = manifest !== null && typeof manifest['version'] === 'string'
+          ? manifest['version']
+          : 'unknown'
+        const description = manifest !== null && typeof manifest['description'] === 'string'
+          ? manifest['description']
+          : undefined
+
+        let latestVersion: string | null = null
+        try {
+          const args = ['view', `${packageName}@latest`, 'version', ...buildNpmRegistryArgs(registry)]
+          const { stdout } = await execFileAsync('npm', args, { timeout: 15_000 })
+          const trimmed = stdout.trim()
+          latestVersion = trimmed.length > 0 ? trimmed : null
+        } catch (err) {
+          this.logger.debug('listFrameworkPackages: npm view failed', {
+            meta: { packageName, error: errMsg(err) },
+          })
+        }
+
+        const hasUpdate = latestVersion !== null
+          && currentVersion !== 'unknown'
+          && latestVersion !== currentVersion
+
+        return {
+          packageName,
+          currentVersion,
+          latestVersion,
+          hasUpdate,
+          ...(description !== undefined ? { description } : {}),
+        }
+      }),
+    )
+
+    return rows
+  }
+
+  /**
+   * Update one of the framework packages (manifest `camstack.system:
+   * true`) and schedule a hub restart.
+   *
+   * Steps:
+   *   1. Allow-list the package name (refuses anything not framework).
+   *   2. Resolve `'latest'`/`undefined` to a concrete version via `npm view`.
+   *   3. Run `npm install --prefix <appRoot> <name>@<version> --no-save`.
+   *   4. Write a `.restart-pending` marker (kind: `framework-update`).
+   *   5. Emit `system.restarting` event.
+   *   6. `scheduleSelfRestart({ delayMs: 500 })` — gives the cap method
+   *      time to return before the WS drops.
+   *
+   * Returns BEFORE the exit fires so the admin UI receives `restartingAt`
+   * and can pivot to the reconnect overlay.
+   */
+  async updateFrameworkPackage(input: {
+    readonly packageName: string
+    readonly version?: string
+    readonly requestedBy?: string
+  }): Promise<{
+    packageName: string
+    fromVersion: string
+    toVersion: string
+    restartingAt: number
+  }> {
+    const { packageName } = input
+    if (!FRAMEWORK_PACKAGE_ALLOWLIST.includes(packageName)) {
+      throw new Error(
+        `updateFrameworkPackage: '${packageName}' is not a framework package. Allowed: ${FRAMEWORK_PACKAGE_ALLOWLIST.join(', ')}`,
+      )
+    }
+
+    const appRoot = resolveFrameworkPackageAppRoot(packageName, this.logger)
+    const fromManifest = readResolvedPackageManifest(packageName)
+    const fromVersion = fromManifest !== null && typeof fromManifest['version'] === 'string'
+      ? fromManifest['version']
+      : 'unknown'
+    const requestedVersion = input.version ?? 'latest'
+    const toVersion = await resolveNpmVersion(packageName, requestedVersion, process.env['CAMSTACK_NPM_REGISTRY'])
+    const spec = `${packageName}@${toVersion}`
+
+    this.logger.info('updateFrameworkPackage: installing', {
+      meta: { packageName, fromVersion, toVersion, appRoot },
+    })
+
+    const registry = process.env['CAMSTACK_NPM_REGISTRY']
+    const args = ['install', '--prefix', appRoot, spec, '--no-save', ...buildNpmRegistryArgs(registry)]
+    await execFileAsync('npm', args, { timeout: 180_000 })
+
+    const restartingAt = Date.now()
+    const markerPayload: PendingRestartMarkerPayload = {
+      kind: 'framework-update',
+      packageName,
+      fromVersion,
+      toVersion,
+      requestedAt: restartingAt,
+      ...(input.requestedBy !== undefined ? { requestedBy: input.requestedBy } : {}),
+    }
+
+    try {
+      writePendingRestart(this.resolveDataDir(), markerPayload)
+    } catch (err) {
+      // The npm install already completed — the restart will still
+      // pick up the new version, just without the completion toast.
+      this.logger.warn('Failed to write restart marker after framework update', {
+        meta: { error: errMsg(err) },
+      })
+    }
+
+    this.eventBusService.emit({
+      id: randomUUID(),
+      timestamp: new Date(),
+      source: { type: 'core', id: 'addon-package-service' },
+      category: EventCategory.SystemRestarting,
+      data: markerPayload,
+    })
+
+    scheduleSelfRestart({ delayMs: 500 })
+
+    return { packageName, fromVersion, toVersion, restartingAt }
+  }
+
+  // =========================================================================
+  // Reload
+  // =========================================================================
+
+  /** Re-discover addons from the addons directory (call after install/uninstall) */
+  async reloadPackages(): Promise<void> {
+    try {
+      const kernel = await import('@camstack/kernel')
+      this.loader = new kernel.AddonLoader(this.logger.child('AddonLoader'))
+
+      const dataDir = process.env.CAMSTACK_DATA ?? 'camstack-data'
+      const addonsDir = path.resolve(dataDir, 'addons')
+      await this.loader.loadFromDirectory(addonsDir)
+
+      this.logger.info('Reloaded', { meta: { count: this.loader.listAddons().length } })
+    } catch (error: unknown) {
+      const msg = errMsg(error)
+      this.logger.warn('reloadPackages failed', { meta: { error: msg } })
+    }
+  }
+
+  // =========================================================================
+  // Auto-update channel resolution
+  // =========================================================================
+
+  /** Resolve effective auto-update channel for a package */
+  getEffectiveAutoUpdateChannel(
+    _addonId: string,
+    globalChannel: AutoUpdateChannel,
+    perAddonChannel: AutoUpdateChannel,
+  ): 'off' | 'latest' | 'beta' {
+    if (perAddonChannel !== 'inherit') return perAddonChannel as 'off' | 'latest' | 'beta'
+    if (globalChannel === 'inherit') return 'off' // shouldn't happen at global level
+    return globalChannel as 'off' | 'latest' | 'beta'
+  }
+
+  // =========================================================================
+  // Auto-update settings
+  // =========================================================================
+
+  /** Get global auto-update settings */
+  getAutoUpdateSettings(): { channel: 'off' | 'latest' | 'beta'; intervalSeconds: number } {
+    return { ...this.autoUpdateConfig.global }
+  }
+
+  /** Set global auto-update settings and restart the timer */
+  async setAutoUpdateSettings(channel: 'off' | 'latest' | 'beta', intervalSeconds?: number): Promise<void> {
+    this.autoUpdateConfig = {
+      ...this.autoUpdateConfig,
+      global: {
+        channel,
+        intervalSeconds: intervalSeconds ?? this.autoUpdateConfig.global.intervalSeconds,
+      },
+    }
+    this.saveAutoUpdateConfig()
+    this.scheduleAutoUpdate()
+  }
+
+  /** Get per-addon auto-update override */
+  getAddonAutoUpdate(addonId: string): 'off' | 'latest' | 'beta' | 'inherit' {
+    return this.autoUpdateConfig.overrides[addonId] ?? 'inherit'
+  }
+
+  /** Set per-addon auto-update override */
+  async setAddonAutoUpdate(addonId: string, channel: 'off' | 'latest' | 'beta' | 'inherit'): Promise<void> {
+    const newOverrides = { ...this.autoUpdateConfig.overrides }
+    if (channel === 'inherit') {
+      delete newOverrides[addonId]
+    } else {
+      newOverrides[addonId] = channel
+    }
+    this.autoUpdateConfig = { ...this.autoUpdateConfig, overrides: newOverrides }
+    this.saveAutoUpdateConfig()
+  }
+
+  /** Schedule periodic auto-update check */
+  scheduleAutoUpdate(): void {
+    if (this.autoUpdateTimer) {
+      clearInterval(this.autoUpdateTimer)
+      this.autoUpdateTimer = null
+    }
+
+    const hasOverrides = Object.values(this.autoUpdateConfig.overrides).some((ch) => ch !== 'off')
+    if (this.autoUpdateConfig.global.channel === 'off' && !hasOverrides) {
+      this.logger.info('Auto-update disabled')
+      return
+    }
+
+    const intervalMs = this.autoUpdateConfig.global.intervalSeconds * 1000
+    this.logger.info(
+      'Auto-update scheduled',
+      { meta: { intervalSeconds: this.autoUpdateConfig.global.intervalSeconds, channel: this.autoUpdateConfig.global.channel } },
+    )
+
+    this.autoUpdateTimer = setInterval(() => {
+      this.runAutoUpdate().catch((err) => {
+        this.logger.error('Auto-update check failed', { meta: { error: errMsg(err) } })
+      })
+    }, intervalMs)
+  }
+
+  /** Run auto-update: check each installed package against its configured channel */
+  async runAutoUpdate(): Promise<void> {
+    this.logger.info('Running auto-update check...')
+    const installed = this.listInstalled()
+    let updatedCount = 0
+
+    for (const pkg of installed) {
+      try {
+        // Determine effective channel for this addon
+        const addonId = pkg.name.replace('@camstack/addon-', '').replace('@camstack/', '')
+        const override = this.autoUpdateConfig.overrides[addonId]
+        const effectiveChannel = this.getEffectiveAutoUpdateChannel(
+          addonId,
+          this.autoUpdateConfig.global.channel,
+          override ?? 'inherit',
+        )
+
+        if (effectiveChannel === 'off') continue
+
+        // Fetch dist-tags for this package
+        const encodedName = pkg.name.replace('/', '%2F')
+        const url = `${AddonPackageService.NPM_REGISTRY}/${encodedName}`
+        const response = await fetch(url, {
+          signal: AbortSignal.timeout(AddonPackageService.REGISTRY_TIMEOUT_MS),
+        })
+        if (!response.ok) continue
+
+        const data = await fetchJsonObject(response)
+        const distTags = asRecord(data['dist-tags'])
+
+        // Determine target version based on channel
+        const targetVersion = effectiveChannel === 'beta'
+          ? asString(distTags['beta']) || asString(distTags['latest'])
+          : asString(distTags['latest'])
+
+        if (!targetVersion || targetVersion === pkg.version) continue
+
+        this.logger.info(
+          'Auto-updating package',
+          { meta: { name: pkg.name, currentVersion: pkg.version, targetVersion, channel: effectiveChannel } },
+        )
+        await this.updatePackage(pkg.name, targetVersion)
+        updatedCount++
+      } catch (err) {
+        this.logger.warn(
+          'Auto-update failed',
+          { meta: { name: pkg.name, error: errMsg(err) } },
+        )
+      }
+    }
+
+    if (updatedCount > 0) {
+      this.logger.info('Auto-update complete', { meta: { updatedCount } })
+    } else {
+      this.logger.debug('Auto-update: all packages up-to-date')
+    }
+  }
+
+  // =========================================================================
+  // Private: auto-update config persistence
+  // =========================================================================
+
+  /** Load auto-update config from disk */
+  private loadAutoUpdateConfig(): AutoUpdateConfig {
+    const configPath = path.join(this.resolveDataDir(), 'auto-update.json')
+    try {
+      if (fs.existsSync(configPath)) {
+        const raw = readJsonObject(configPath)
+        if (raw) {
+          const global = asRecord(raw['global'])
+          const channel = asString(global['channel'])
+          const validChannel: AutoUpdateConfig['global']['channel'] =
+            channel === 'latest' || channel === 'beta' ? channel : 'off'
+          return {
+            global: {
+              channel: validChannel,
+              intervalSeconds: typeof global['intervalSeconds'] === 'number' ? global['intervalSeconds'] : 3600,
+            },
+            overrides: Object.fromEntries(
+              Object.entries(asRecord(raw['overrides'])).map(([k, v]) => {
+                const s = asString(v)
+                const valid: AutoUpdateConfig['overrides'][string] =
+                  s === 'off' || s === 'latest' || s === 'beta' || s === 'inherit' ? s : 'inherit'
+                return [k, valid]
+              }),
+            ),
+          }
+        }
+      }
+    } catch (err) {
+      this.logger.debug('Corrupt auto-update config, falling back to defaults', { meta: { error: errMsg(err) } })
+    }
+    return { global: { channel: 'off', intervalSeconds: 21600 }, overrides: {} }
+  }
+
+  /** Save auto-update config to disk */
+  private saveAutoUpdateConfig(): void {
+    const dataDir = this.resolveDataDir()
+    try {
+      if (!fs.existsSync(dataDir)) {
+        fs.mkdirSync(dataDir, { recursive: true })
+      }
+      const configPath = path.join(dataDir, 'auto-update.json')
+      fs.writeFileSync(configPath, JSON.stringify(this.autoUpdateConfig, null, 2))
+    } catch (err) {
+      this.logger.warn('Failed to save auto-update config', { meta: { error: errMsg(err) } })
+    }
+  }
+
+  /** Resolve the top-level data directory */
+  private resolveDataDir(): string {
+    return path.resolve(process.env.CAMSTACK_DATA ?? 'camstack-data')
+  }
+
+  // =========================================================================
+  // Private: core package update checks
+  // =========================================================================
+
+  /**
+   * Check addon packages for updates by reading installed versions from
+   * data/addons/{name}/package.json and comparing against npm registry.
+   */
+  private async checkAddonPackageUpdates(): Promise<PackageUpdate[]> {
+    const addonsDir = this.resolveAddonsDir()
+    const updates: PackageUpdate[] = []
+
+    if (!fs.existsSync(addonsDir)) return updates
+
+    // Collect all package.json paths -- handles both flat and scoped layouts
+    const pkgJsonPaths: string[] = []
+    const topDirs = fs
+      .readdirSync(addonsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+
+    for (const dir of topDirs) {
+      const dirPath = path.join(addonsDir, dir.name)
+      if (dir.name.startsWith('@')) {
+        // Scoped package directory -- scan one level deeper
+        const scopedDirs = fs
+          .readdirSync(dirPath, { withFileTypes: true })
+          .filter((d) => d.isDirectory())
+        for (const scopedDir of scopedDirs) {
+          const pkgJson = path.join(dirPath, scopedDir.name, 'package.json')
+          if (fs.existsSync(pkgJson)) pkgJsonPaths.push(pkgJson)
+        }
+      } else {
+        const pkgJson = path.join(dirPath, 'package.json')
+        if (fs.existsSync(pkgJson)) pkgJsonPaths.push(pkgJson)
+      }
+    }
+
+    for (const pkgJsonPath of pkgJsonPaths) {
+      try {
+        const pkgJson = readJsonObject(pkgJsonPath)
+        if (!pkgJson) continue
+        const name = asString(pkgJson['name'])
+        const version = asString(pkgJson['version'])
+        if (!name || !version || !this.isAllowedPackage(name)) continue
+
+        // Skip non-addon packages (core, types, etc.) — only check packages with camstack.addons
+        const camstackField = asRecord(pkgJson['camstack'])
+        if (!camstackField['addons']) continue
+
+        // Skip workspace-installed packages (dev mode) — they always lag behind npm
+        const addonDir = path.dirname(pkgJsonPath)
+        const installSourcePath = path.join(addonDir, '.install-source')
+        if (fs.existsSync(installSourcePath)) {
+          const source = fs.readFileSync(installSourcePath, 'utf-8').trim()
+          if (source === 'workspace') continue
+        }
+
+        const latestVersion = await this.fetchLatestVersion(name)
+        if (!latestVersion) continue
+
+        if (latestVersion !== version) {
+          updates.push({
+            name,
+            currentVersion: version,
+            latestVersion,
+            category: this.categorize(name),
+            requiresRestart: this.categorize(name) === 'core',
+          })
+        }
+      } catch (error: unknown) {
+        const msg = errMsg(error)
+        this.logger.debug('Failed to check updates for addon', { meta: { pkgJsonPath, error: msg } })
+      }
+    }
+
+    return updates
+  }
+
+  // =========================================================================
+  // Private: npm registry helpers
+  // =========================================================================
+
+  /**
+   * Base URL for npm registry METADATA fetches.
+   *
+   * Honours `CAMSTACK_NPM_REGISTRY` so update checks resolve against
+   * the same registry the installer/pack paths use. Without this, a
+   * per-node `listUpdates` (which diffs an agent's roster via
+   * `checkUpdatesForInstalled` → `fetchLatestVersion`) would bypass a
+   * private registry — including the e2e harness's verdaccio — and
+   * silently report "no update" for packages that only exist there.
+   * Trailing slashes are stripped so the `${base}/${name}` join is clean.
+   */
+  private resolveRegistryBase(): string {
+    const override = process.env['CAMSTACK_NPM_REGISTRY']
+    const base = override && override.length > 0 ? override : AddonPackageService.NPM_REGISTRY
+    return base.replace(/\/+$/, '')
+  }
+
+  /** Fetch the latest published version of a package from the npm registry */
+  private async fetchLatestVersion(packageName: string): Promise<string | null> {
+    try {
+      const encodedName = packageName.replace('/', '%2F')
+      const url = `${this.resolveRegistryBase()}/${encodedName}/latest`
+      const response = await fetch(url, {
+        signal: AbortSignal.timeout(AddonPackageService.REGISTRY_TIMEOUT_MS),
+      })
+      if (!response.ok) {
+        this.logger.debug('Registry returned non-ok status', { meta: { packageName, status: response.status } })
+        return null
+      }
+      const data = await fetchJsonObject(response)
+      const version = asString(data['version'])
+      return version || null
+    } catch (error: unknown) {
+      const msg = errMsg(error)
+      this.logger.debug('Failed to fetch latest version', { meta: { packageName, error: msg } })
+      return null
+    }
+  }
+
+  /** Fetch npm search results for camstack addon packages (cached 5 min) */
+  private async fetchSearchFromNpm(): Promise<readonly NpmSearchResult[]> {
+    if (this.searchCache && Date.now() - this.searchCache.timestamp < AddonPackageService.SEARCH_CACHE_TTL_MS) {
+      return this.searchCache.results
+    }
+
+    const url = 'https://registry.npmjs.org/-/v1/search?text=keywords:camstack+keywords:addon&size=250'
+
+    try {
+      const response = await fetch(url, {
+        headers: { Accept: 'application/json' },
+        signal: AbortSignal.timeout(AddonPackageService.REGISTRY_TIMEOUT_MS),
+      })
+
+      if (!response.ok) {
+        throw new Error(`npm search failed: ${response.status}`)
+      }
+
+      const data = await fetchJsonObject(response)
+      const rawObjects = Array.isArray(data['objects']) ? data['objects'] : []
+      const results: NpmSearchResult[] = []
+      for (const raw of rawObjects) {
+        const wrapper = asRecord(raw)
+        const pkg = asRecord(wrapper['package'])
+        const name = asString(pkg['name'])
+        if (!name) continue
+        const rawKeywords = Array.isArray(pkg['keywords']) ? pkg['keywords'] : []
+        const publisher = asRecord(pkg['publisher'])
+        results.push({
+          name,
+          version: asString(pkg['version']),
+          description: asString(pkg['description']),
+          keywords: rawKeywords.filter((k): k is string => typeof k === 'string'),
+          date: asString(pkg['date']),
+          publisher: { username: asString(publisher['username']) },
+        })
+      }
+
+      this.searchCache = { results, timestamp: Date.now() }
+      return results
+    } catch (err: unknown) {
+      this.logger.warn('npm search failed', { meta: { error: errMsg(err) } })
+      // Stale cache is better than nothing on transient network failure
+      return this.searchCache?.results ?? []
+    }
+  }
+
+  // =========================================================================
+  // Private: general helpers
+  // =========================================================================
+
+  /**
+   * Read the currently installed version of a package.
+   * Checks data/addons/ first, then falls back to Node module resolution.
+   * Returns '0.0.0' if not found.
+   */
+  private getInstalledPackageVersion(packageName: string): string {
+    try {
+      const addonsDir = this.resolveAddonsDir()
+      const dirName = packageName.replace(/^@camstack\//, '')
+      const pkgJsonPath = path.join(addonsDir, dirName, 'package.json')
+      if (fs.existsSync(pkgJsonPath)) {
+        const pkgJson = readJsonObject(pkgJsonPath)
+        const v = asString(pkgJson?.['version'])
+        if (v) return v
+      }
+    } catch (err) {
+      this.logger.debug('Version lookup via fs failed, trying require.resolve', { meta: { packageName, error: errMsg(err) } })
+    }
+
+    try {
+      const pkgJsonPath = require.resolve(`${packageName}/package.json`)
+      const pkgJson = readJsonObject(pkgJsonPath)
+      return asString(pkgJson?.['version'], '0.0.0')
+    } catch (err) {
+      this.logger.debug('Could not resolve version, returning 0.0.0', { meta: { packageName, error: errMsg(err) } })
+      return '0.0.0'
+    }
+  }
+
+  /** Only allow @camstack/* scoped packages */
+  private isAllowedPackage(name: string): boolean {
+    return name.startsWith('@camstack/')
+  }
+
+  /** Categorize a package as 'addon' or 'core' */
+  private categorize(name: string): 'addon' | 'core' {
+    if (CORE_MANAGED_PACKAGES.includes(name)) {
+      return 'core'
+    }
+    return name.includes('/addon-') ? 'addon' : 'core'
+  }
+
+  /** Extract addon ID from package name: '@camstack/addon-benchmark' -> 'benchmark' */
+  private extractAddonId(packageName: string): string | null {
+    const match = packageName.match(/@camstack\/addon-(.+)/)
+    return match?.[1] ?? null
+  }
+
+  /** Resolve the addons directory from config or fall back to default */
+  private resolveAddonsDir(): string {
+    const dataPath = this.configService.get<string>('server.dataPath') ?? 'camstack-data'
+    return path.resolve(dataPath, 'addons')
+  }
+
+
+  /** Throw if installer was not initialised */
+  private requireInstaller(): void {
+    if (!this.installer) {
+      throw new Error('AddonInstaller is not available -- @camstack/kernel may not be installed')
+    }
+  }
+
+  /** Send notification and toast for a successful package update */
+  private sendUpdateNotification(name: string, version: string): void {
+    this.notificationService
+      .notify({
+        title: 'Package Updated',
+        message: `${name} updated to v${version}`,
+        severity: 'info',
+        category: 'system',
+        timestamp: Date.now(),
+      })
+      .catch((err: unknown) => {
+        const msg = errMsg(err)
+        this.logger.debug('Update notification failed', { meta: { error: msg } })
+      })
+
+    this.toastService.broadcast({
+      title: 'Package Updated',
+      message: `${name} updated to v${version}`,
+      severity: 'info',
+      duration: 5000,
+    })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Framework live-update helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the npm CLI args that pin every relevant registry to
+ * `CAMSTACK_NPM_REGISTRY`. We pass BOTH the default `--registry` and
+ * the scope-specific `--@camstack:registry=` flag because workspace or
+ * user-home `.npmrc` files commonly declare
+ * `@camstack:registry=https://registry.npmjs.org/`, and that scoped
+ * entry takes precedence over the plain `--registry` CLI flag for
+ * `@camstack/*` lookups — which is exactly the path framework-update
+ * traverses.
+ *
+ * Without this, the e2e suite's verdaccio gets bypassed even with
+ * `CAMSTACK_NPM_REGISTRY` set, AND in production any operator running
+ * their own private npm proxy via `@camstack:registry` would have
+ * `updateFrameworkPackage` silently route around it.
+ */
+function buildNpmRegistryArgs(registry: string | undefined): readonly string[] {
+  if (registry === undefined || registry.length === 0) return []
+  return ['--registry', registry, `--@camstack:registry=${registry}`]
+}
+
+/**
+ * Resolve the directory whose `node_modules/<pkg>/` holds the currently-
+ * installed copy of a framework package. `npm install --prefix <appRoot>`
+ * will then update that exact copy in place.
+ *
+ * Strategy: ask Node's resolver where it finds the package today, then walk
+ * up to the `node_modules/`-parent. This matches whatever resolution path
+ * the running hub actually uses (server-local node_modules in prod;
+ * workspace-root in dev; bundled in Electron) without hard-coding either.
+ *
+ * Test knob: `CAMSTACK_FRAMEWORK_APP_ROOT_OVERRIDE` short-circuits the walk
+ * and returns the env-supplied path. Used by the e2e suite to redirect the
+ * `npm install --prefix` side-effects into an isolated temp dir instead of
+ * the workspace's `server/backend/node_modules/`. Never set in production.
+ */
+function resolveFrameworkPackageAppRoot(
+  packageName: string,
+  logger: IScopedLogger,
+): string {
+  const override = process.env['CAMSTACK_FRAMEWORK_APP_ROOT_OVERRIDE']
+  if (override !== undefined && override.length > 0) {
+    return override
+  }
+  const resolved = require.resolve(`${packageName}/package.json`)
+  // …/<appRoot>/node_modules/<scope>/<name>/package.json
+  // walk up: package.json → name → scope → node_modules → appRoot
+  let dir = path.dirname(resolved)
+  while (dir !== path.dirname(dir)) {
+    if (path.basename(dir) === 'node_modules') {
+      return path.dirname(dir)
+    }
+    dir = path.dirname(dir)
+  }
+  logger.warn(`Could not resolve appRoot for ${packageName}; falling back to process.cwd()`)
+  return process.cwd()
+}
+
+/**
+ * Read a framework package's `package.json`, resolved however the
+ * running hub actually loads it — workspace symlink in dev, a real
+ * `node_modules` tree in prod, bundled in Electron.
+ *
+ * `require.resolve('<pkg>/package.json')` is the happy path. Packages
+ * whose `exports` map omits the `./package.json` subpath (e.g.
+ * `@camstack/sdk`, `@camstack/ui-library`) make that throw — so we
+ * fall back to resolving the package's main entry and walking up to
+ * the first `package.json` whose `name` matches.
+ *
+ * This is deliberately independent of `resolveFrameworkPackageAppRoot`:
+ * that walk only finds a real `node_modules`-parent, which doesn't
+ * exist for workspace-symlinked packages in dev — the cause of the
+ * `vunknown` version label in the System Packages UI.
+ */
+function readResolvedPackageManifest(packageName: string): Record<string, unknown> | null {
+  try {
+    return readJsonObject(require.resolve(`${packageName}/package.json`))
+  } catch {
+    // `exports` map blocks the package.json subpath — fall through.
+  }
+  try {
+    let dir = path.dirname(require.resolve(packageName))
+    while (dir !== path.dirname(dir)) {
+      const candidate = path.join(dir, 'package.json')
+      const obj = fs.existsSync(candidate) ? readJsonObject(candidate) : null
+      if (obj !== null && obj['name'] === packageName) return obj
+      dir = path.dirname(dir)
+    }
+  } catch {
+    // The package itself is not resolvable — treat as not installed.
+  }
+  return null
+}
+
+/**
+ * Resolve a version specifier (`'latest'`, semver tag, exact) to a concrete
+ * version string via `npm view <pkg>@<spec> version`. Returns the spec as-is
+ * when `npm view` is unavailable or fails — better to attempt the install
+ * than to block.
+ */
+async function resolveNpmVersion(
+  packageName: string,
+  versionSpec: string,
+  registry: string | undefined,
+): Promise<string> {
+  const args = ['view', `${packageName}@${versionSpec}`, 'version', ...buildNpmRegistryArgs(registry)]
+  try {
+    const { stdout } = await execFileAsync('npm', args, { timeout: 30_000 })
+    const trimmed = stdout.trim()
+    // `npm view` returns just the version line for a single match, or
+    // "pkg@1.2.3 '1.2.3'" lines for a range. Take the last token on the
+    // last non-empty line which is the most specific resolved version.
+    const lines = trimmed.split('\n').filter((line) => line.trim().length > 0)
+    if (lines.length === 0) return versionSpec
+    const last = lines[lines.length - 1]!.trim()
+    const match = last.match(/'([^']+)'\s*$/)
+    return match ? match[1]! : last
+  } catch {
+    return versionSpec
+  }
+}