@camstack/server 1.0.0 → 1.0.1

package/dist/core/addon/addon-package.service.js

@@ -0,0 +1,1560 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddonPackageService = exports.FRAMEWORK_PACKAGE_ALLOWLIST = void 0;
+exports.isFrameworkPackage = isFrameworkPackage;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const node_crypto_1 = require("node:crypto");
+const types_1 = require("@camstack/types");
+const kernel_1 = require("@camstack/kernel");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.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
+ */
+exports.FRAMEWORK_PACKAGE_ALLOWLIST = [
+    '@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. */
+function isFrameworkPackage(packageName) {
+    return exports.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) {
+    // Isolate the `any` from JSON.parse to this one assignment.
+    const parsed = JSON.parse(text);
+    return parsed;
+}
+function readJsonObject(filePath) {
+    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) {
+    const parsed = await response.json();
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return {};
+    }
+    return { ...parsed };
+}
+function asString(value, fallback = '') {
+    return typeof value === 'string' ? value : fallback;
+}
+function asRecord(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return { ...value };
+    }
+    return {};
+}
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Core packages that live in the server's own node_modules */
+const CORE_MANAGED_PACKAGES = ['@camstack/core', '@camstack/types'];
+class AddonPackageService {
+    loggingService;
+    eventBusService;
+    configService;
+    addonRegistry;
+    notificationService;
+    toastService;
+    logger;
+    /** AddonInstaller from @camstack/kernel (may be null if kernel unavailable) */
+    installer = null;
+    /** AddonLoader for reloadPackages (may be null) */
+    loader = null;
+    // -- Caches ---------------------------------------------------------------
+    cachedUpdates = null;
+    searchCache = null;
+    versionCache = new Map();
+    // -- Auto-update state ----------------------------------------------------
+    autoUpdateConfig = {
+        global: { channel: 'off', intervalSeconds: 21600 },
+        overrides: {},
+    };
+    autoUpdateTimer = 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.
+    static UPDATE_CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+    static SEARCH_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+    static VERSION_CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+    static NPM_REGISTRY = 'https://registry.npmjs.org';
+    static REGISTRY_TIMEOUT_MS = 10_000;
+    constructor(loggingService, eventBusService, configService, addonRegistry, notificationService, toastService) {
+        this.loggingService = loggingService;
+        this.eventBusService = eventBusService;
+        this.configService = configService;
+        this.addonRegistry = addonRegistry;
+        this.notificationService = notificationService;
+        this.toastService = toastService;
+        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 = (0, kernel_1.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 kernel_1.AddonInstaller({
+                addonsDir,
+                workspacePackagesDir: workspacePackagesDir ?? undefined,
+                ...(registry ? { registry } : {}),
+            });
+            (0, kernel_1.ensureDir)(addonsDir);
+        }
+        catch (error) {
+            const msg = (0, types_1.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, version) {
+        this.requireInstaller();
+        this.logger.info(`installFromNpm: ${name}@${version ?? 'latest'}`, {
+            meta: { addonsDir: this.installer['addonsDir'] },
+        });
+        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) {
+        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) {
+        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: (0, types_1.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) {
+        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) {
+                this.logger.warn('Restart failed after rollback', {
+                    tags: { addonId },
+                    meta: { error: (0, types_1.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) {
+        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, version) {
+        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 = (0, types_1.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 = (0, types_1.errMsg)(err);
+            this.logger.error('reloadPackages failed', { meta: { error: msg } });
+        }
+        let loaded = [];
+        let failed = [];
+        try {
+            const result = await this.addonRegistry.loadNewAddons();
+            loaded = result.loaded;
+            failed = result.failed;
+        }
+        catch (err) {
+            const msg = (0, types_1.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) {
+        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 = (0, types_1.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: (0, types_1.errMsg)(err) },
+            });
+        }
+        let loaded = [];
+        let failed = [];
+        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: (0, types_1.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) {
+        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 = (0, types_1.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: (0, types_1.errMsg)(err) },
+            });
+        });
+        await this.addonRegistry.loadNewAddons().catch((err) => {
+            this.logger.warn('Non-fatal: failed to load new addons after uninstall', {
+                meta: { error: (0, types_1.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() {
+        return this.installer?.workspaceDir != null;
+    }
+    /** List addon packages available in the workspace but not necessarily installed */
+    listWorkspacePackages() {
+        const workspaceDir = this.installer?.workspaceDir;
+        if (!workspaceDir)
+            return [];
+        const results = [];
+        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: (0, types_1.errMsg)(err) } });
+        }
+        return results;
+    }
+    // =========================================================================
+    // Query
+    // =========================================================================
+    /** List all installed addon packages */
+    listInstalled() {
+        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) {
+        const fromRegistry = this.addonRegistry?.isPackageProtected?.(name);
+        if (typeof fromRegistry === 'boolean')
+            return fromRegistry;
+        return kernel_1.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() {
+        if (!this.installer)
+            return new Set();
+        const out = new Set();
+        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) {
+        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 = [];
+        // 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() {
+        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) {
+        // De-dup by package name — one npm package may bundle several addons.
+        const seen = new Map();
+        for (const pkg of installed) {
+            if (pkg.name.length > 0 && !seen.has(pkg.name))
+                seen.set(pkg.name, pkg.version);
+        }
+        const updates = [];
+        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, version) {
+        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) {
+        const npmResults = await this.fetchSearchFromNpm();
+        let filtered = 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) {
+        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();
+            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 = 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) {
+            const msg = (0, types_1.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, version) {
+        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;
+            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;
+                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) {
+                        const msg = (0, types_1.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 Promise.resolve().then(() => __importStar(require('@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) {
+            const msg = (0, types_1.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) {
+        this.logger.info('Server restart requested -- initiating graceful shutdown');
+        const payload = {
+            kind: 'manual',
+            requestedAt: Date.now(),
+            ...(requestedBy !== undefined ? { requestedBy } : {}),
+        };
+        try {
+            (0, kernel_1.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: (0, types_1.errMsg)(err) },
+            });
+        }
+        this.eventBusService.emit({
+            id: (0, node_crypto_1.randomUUID)(),
+            timestamp: new Date(),
+            source: { type: 'core', id: 'addon-package-service' },
+            category: types_1.EventCategory.SystemRestarting,
+            data: payload,
+        });
+        // 10s grace gives in-flight requests time to drain.
+        (0, kernel_1.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() {
+        const registry = process.env['CAMSTACK_NPM_REGISTRY'];
+        const rows = await Promise.all(exports.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 = 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: (0, types_1.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) {
+        const { packageName } = input;
+        if (!exports.FRAMEWORK_PACKAGE_ALLOWLIST.includes(packageName)) {
+            throw new Error(`updateFrameworkPackage: '${packageName}' is not a framework package. Allowed: ${exports.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 = {
+            kind: 'framework-update',
+            packageName,
+            fromVersion,
+            toVersion,
+            requestedAt: restartingAt,
+            ...(input.requestedBy !== undefined ? { requestedBy: input.requestedBy } : {}),
+        };
+        try {
+            (0, kernel_1.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: (0, types_1.errMsg)(err) },
+            });
+        }
+        this.eventBusService.emit({
+            id: (0, node_crypto_1.randomUUID)(),
+            timestamp: new Date(),
+            source: { type: 'core', id: 'addon-package-service' },
+            category: types_1.EventCategory.SystemRestarting,
+            data: markerPayload,
+        });
+        (0, kernel_1.scheduleSelfRestart)({ delayMs: 500 });
+        return { packageName, fromVersion, toVersion, restartingAt };
+    }
+    // =========================================================================
+    // Reload
+    // =========================================================================
+    /** Re-discover addons from the addons directory (call after install/uninstall) */
+    async reloadPackages() {
+        try {
+            const kernel = await Promise.resolve().then(() => __importStar(require('@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) {
+            const msg = (0, types_1.errMsg)(error);
+            this.logger.warn('reloadPackages failed', { meta: { error: msg } });
+        }
+    }
+    // =========================================================================
+    // Auto-update channel resolution
+    // =========================================================================
+    /** Resolve effective auto-update channel for a package */
+    getEffectiveAutoUpdateChannel(_addonId, globalChannel, perAddonChannel) {
+        if (perAddonChannel !== 'inherit')
+            return perAddonChannel;
+        if (globalChannel === 'inherit')
+            return 'off'; // shouldn't happen at global level
+        return globalChannel;
+    }
+    // =========================================================================
+    // Auto-update settings
+    // =========================================================================
+    /** Get global auto-update settings */
+    getAutoUpdateSettings() {
+        return { ...this.autoUpdateConfig.global };
+    }
+    /** Set global auto-update settings and restart the timer */
+    async setAutoUpdateSettings(channel, intervalSeconds) {
+        this.autoUpdateConfig = {
+            ...this.autoUpdateConfig,
+            global: {
+                channel,
+                intervalSeconds: intervalSeconds ?? this.autoUpdateConfig.global.intervalSeconds,
+            },
+        };
+        this.saveAutoUpdateConfig();
+        this.scheduleAutoUpdate();
+    }
+    /** Get per-addon auto-update override */
+    getAddonAutoUpdate(addonId) {
+        return this.autoUpdateConfig.overrides[addonId] ?? 'inherit';
+    }
+    /** Set per-addon auto-update override */
+    async setAddonAutoUpdate(addonId, channel) {
+        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() {
+        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: (0, types_1.errMsg)(err) } });
+            });
+        }, intervalMs);
+    }
+    /** Run auto-update: check each installed package against its configured channel */
+    async runAutoUpdate() {
+        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: (0, types_1.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 */
+    loadAutoUpdateConfig() {
+        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 = 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 = 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: (0, types_1.errMsg)(err) },
+            });
+        }
+        return { global: { channel: 'off', intervalSeconds: 21600 }, overrides: {} };
+    }
+    /** Save auto-update config to disk */
+    saveAutoUpdateConfig() {
+        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: (0, types_1.errMsg)(err) } });
+        }
+    }
+    /** Resolve the top-level data directory */
+    resolveDataDir() {
+        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.
+     */
+    async checkAddonPackageUpdates() {
+        const addonsDir = this.resolveAddonsDir();
+        const updates = [];
+        if (!fs.existsSync(addonsDir))
+            return updates;
+        // Collect all package.json paths -- handles both flat and scoped layouts
+        const pkgJsonPaths = [];
+        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) {
+                const msg = (0, types_1.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.
+     */
+    resolveRegistryBase() {
+        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 */
+    async fetchLatestVersion(packageName) {
+        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) {
+            const msg = (0, types_1.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) */
+    async fetchSearchFromNpm() {
+        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 = [];
+            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) => typeof k === 'string'),
+                    date: asString(pkg['date']),
+                    publisher: { username: asString(publisher['username']) },
+                });
+            }
+            this.searchCache = { results, timestamp: Date.now() };
+            return results;
+        }
+        catch (err) {
+            this.logger.warn('npm search failed', { meta: { error: (0, types_1.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.
+     */
+    getInstalledPackageVersion(packageName) {
+        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: (0, types_1.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: (0, types_1.errMsg)(err) },
+            });
+            return '0.0.0';
+        }
+    }
+    /** Only allow @camstack/* scoped packages */
+    isAllowedPackage(name) {
+        return name.startsWith('@camstack/');
+    }
+    /** Categorize a package as 'addon' or 'core' */
+    categorize(name) {
+        if (CORE_MANAGED_PACKAGES.includes(name)) {
+            return 'core';
+        }
+        return name.includes('/addon-') ? 'addon' : 'core';
+    }
+    /** Extract addon ID from package name: '@camstack/addon-benchmark' -> 'benchmark' */
+    extractAddonId(packageName) {
+        const match = packageName.match(/@camstack\/addon-(.+)/);
+        return match?.[1] ?? null;
+    }
+    /** Resolve the addons directory from config or fall back to default */
+    resolveAddonsDir() {
+        const dataPath = this.configService.get('server.dataPath') ?? 'camstack-data';
+        return path.resolve(dataPath, 'addons');
+    }
+    /** Throw if installer was not initialised */
+    requireInstaller() {
+        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 */
+    sendUpdateNotification(name, version) {
+        this.notificationService
+            .notify({
+            title: 'Package Updated',
+            message: `${name} updated to v${version}`,
+            severity: 'info',
+            category: 'system',
+            timestamp: Date.now(),
+        })
+            .catch((err) => {
+            const msg = (0, types_1.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,
+        });
+    }
+}
+exports.AddonPackageService = AddonPackageService;
+// ---------------------------------------------------------------------------
+// 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) {
+    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, logger) {
+    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) {
+    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, versionSpec, registry) {
+    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;
+    }
+}