@camstack/server 0.2.2 → 1.0.1

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

@@ -1,1787 +0,0 @@
-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
-    readonly deferRestart?: boolean
-  }): 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 })
-
-    if (input.deferRestart === true) {
-      this.logger.info(
-        `updateFrameworkPackage(${packageName}@${toVersion}): install done, restart deferred`,
-      )
-      // Sentinel: 0 signals "no restart scheduled" to the caller
-      return { packageName, fromVersion, toVersion, restartingAt: 0 }
-    }
-
-    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
-  }
-}