@nubisco/openbridge 0.29.0

package/dist/server.js

@@ -0,0 +1,1744 @@
+import Fastify from 'fastify';
+import cors from '@fastify/cors';
+import websocket from '@fastify/websocket';
+import fastifyStatic from '@fastify/static';
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
+import { createRequire } from 'module';
+import os from 'os';
+const _req = createRequire(import.meta.url);
+import { Logger } from '@nubisco/openbridge-logger';
+import { startMetrics, onMetrics, getHistory } from './metrics.js';
+import { loadAuthConfig, registerAuthRoutes } from './auth.js';
+const log = Logger.create('system');
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Version: resolved in version.ts so the CLI can read it without loading this module.
+import { APP_VOLUME, VERSION_FILE, OPENBRIDGE_VERSION } from './version.js';
+export { OPENBRIDGE_VERSION };
+let updateProgress = { stage: 'idle' };
+const updateListeners = new Set();
+// Resolve UI dist: env override → npm layout (../ui-dist) → monorepo dev layout
+const uiDist = [process.env.OPENBRIDGE_UI_PATH, resolve(__dirname, '../ui-dist'), resolve(__dirname, '../../../apps/ui/dist')]
+    .filter(Boolean)
+    .find((p) => existsSync(p)) ?? '';
+const uiAvailable = !!uiDist;
+// Set once the optional node-pty dependency is confirmed loadable (see /ws/shell below).
+let shellAvailable = false;
+import { OPENBRIDGE_HOME, OB_PLUGINS_DIR, HB_PLUGINS_DIR } from './daemon.js';
+import { DeviceSeries } from './timeseries.js';
+import { CONVERTIBLE_SERVICES, isConvertible, } from './homekit-service-type.js';
+/** Find a registered device by id across every plugin. */
+function findDevice(registry, deviceId) {
+    for (const instance of registry.getAll()) {
+        const device = instance.devices?.[deviceId];
+        if (device)
+            return device;
+    }
+    return null;
+}
+export async function createServer(registry, hapAPI = null, hapInfo = null, localPluginSources = [], knownHbPackageNames = new Set(), controls = new Map(), restrictedControls = new Set(), homekitVisibility = null, homekitServiceTypes = null, 
+/**
+ * Resolve the HAP accessory a native plugin published for one of its
+ * devices. Native plugins add accessories to the bridge directly, so they
+ * never appear in /api/accessories; this is how the UI reaches them.
+ */
+resolveNativeAccessory = null, 
+/** UUID of the accessory a native plugin published for a device, if any. */
+nativeAccessoryUuid = null) {
+    const app = Fastify({ logger: false });
+    await app.register(cors, { origin: true });
+    await app.register(websocket);
+    // Optional: Nubisco Platform auth. No-op when PLATFORM_ENABLED is unset.
+    const authConfig = loadAuthConfig();
+    await registerAuthRoutes(app, authConfig);
+    if (authConfig.enabled) {
+        log.info(`Platform auth enabled, issuer=${authConfig.issuer ?? 'unset'} appId=${authConfig.appId ?? 'unset'}`);
+    }
+    // Start live metrics collection
+    startMetrics(2000);
+    // ─── Health ───────────────────────────────────────────────────────────────
+    app.get('/api/health', async () => {
+        return {
+            status: 'ok',
+            version: OPENBRIDGE_VERSION,
+            timestamp: new Date().toISOString(),
+            // Optional features that may be absent depending on how OpenBridge was installed.
+            capabilities: { shell: shellAvailable, ui: uiAvailable },
+        };
+    });
+    // ─── Update check ─────────────────────────────────────────────────────────
+    // The latest version is resolved from the github.com releases redirect,
+    // which is NOT subject to the API's 60 req/hour per-IP rate limit
+    // (api.github.com regularly 403s on home networks that share an IP).
+    // Release notes still come from the API, but only best-effort.
+    // Cache the last successful check so failed requests can still report a
+    // known latest version instead of "up to date".
+    let lastKnownLatest = null;
+    async function fetchLatestVersion() {
+        const res = await fetch('https://github.com/nubisco/openbridge/releases/latest', {
+            signal: AbortSignal.timeout(8000),
+            redirect: 'manual',
+            headers: { 'User-Agent': 'openbridge-daemon' },
+        });
+        const location = res.headers.get('location') ?? '';
+        const match = location.match(/\/releases\/tag\/v?([^/]+)$/);
+        if (!match)
+            return null;
+        return { version: decodeURIComponent(match[1]), url: location };
+    }
+    app.get('/api/updates/check', async () => {
+        try {
+            const found = await fetchLatestVersion();
+            if (found && (found.version !== lastKnownLatest?.version || lastKnownLatest.notes === null)) {
+                let notes = null;
+                try {
+                    const res = await fetch('https://api.github.com/repos/nubisco/openbridge/releases/latest', {
+                        signal: AbortSignal.timeout(8000),
+                        headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'openbridge-daemon' },
+                    });
+                    if (res.ok)
+                        notes = (await res.json()).body;
+                }
+                catch {
+                    /* notes are cosmetic: never fail the check over them */
+                }
+                lastKnownLatest = { version: found.version, url: found.url, notes };
+            }
+        }
+        catch {
+            // Network error, timeout, etc.: fall through to use lastKnownLatest
+        }
+        const latest = lastKnownLatest?.version ?? null;
+        const updateAvailable = latest !== null && latest !== OPENBRIDGE_VERSION;
+        // Detect if self-update is possible (volume is writable)
+        let updateMethod = 'manual';
+        try {
+            const testFile = join(APP_VOLUME, '.write-test');
+            writeFileSync(testFile, 'ok');
+            const { unlinkSync } = await import('fs');
+            unlinkSync(testFile);
+            updateMethod = 'self';
+        }
+        catch {
+            /* volume not writable: manual update only */
+        }
+        return {
+            current: OPENBRIDGE_VERSION,
+            latest,
+            updateAvailable,
+            updateMethod,
+            releaseUrl: lastKnownLatest?.url ?? null,
+            releaseNotes: lastKnownLatest?.notes ?? null,
+        };
+    });
+    // ─── Update progress WebSocket ────────────────────────────────────────────
+    app.get('/ws/updates', { websocket: true }, (connection) => {
+        const ws = connection.socket;
+        const listener = (msg) => {
+            try {
+                ws.send(JSON.stringify(msg));
+            }
+            catch {
+                /* disconnected */
+            }
+        };
+        updateListeners.add(listener);
+        // Send current state immediately
+        ws.send(JSON.stringify(updateProgress));
+        ws.on('close', () => updateListeners.delete(listener));
+    });
+    // ─── Self-update apply ────────────────────────────────────────────────────
+    app.post('/api/updates/apply', async () => {
+        if (updateProgress.stage !== 'idle' && updateProgress.stage !== 'error') {
+            throw { statusCode: 409, message: 'Update already in progress' };
+        }
+        const arch = os.arch() === 'x64' ? 'amd64' : os.arch() === 'arm64' ? 'arm64' : os.arch();
+        const currentDir = join(APP_VOLUME, 'current');
+        const stagingDir = join(APP_VOLUME, 'staging');
+        const previousDir = join(APP_VOLUME, 'previous');
+        // Check volume is writable
+        try {
+            mkdirSync(stagingDir, { recursive: true });
+        }
+        catch {
+            throw { statusCode: 503, message: 'Update volume not available. Mount /opt/openbridge as a Docker volume.' };
+        }
+        function broadcast(msg) {
+            updateProgress = msg;
+            for (const listener of updateListeners)
+                listener(msg);
+        }
+        // Run update async: respond immediately
+        ;
+        (async () => {
+            try {
+                // 1. Resolve latest version (github.com redirect, not rate-limited like the API)
+                log.info('Self-update: fetching release info...');
+                broadcast({ stage: 'downloading', progress: 0, message: 'Fetching release info...' });
+                const found = await fetchLatestVersion();
+                if (!found)
+                    throw new Error('Could not resolve the latest release from GitHub');
+                const version = found.version;
+                const assetName = `openbridge-v${version}-linux-${arch}.tar.gz`;
+                const assetUrl = `https://github.com/nubisco/openbridge/releases/download/v${version}/${assetName}`;
+                // 2. Download tarball
+                log.info(`Self-update: downloading ${assetName}...`);
+                broadcast({ stage: 'downloading', progress: 0.1, message: `Downloading v${version}...`, version });
+                const dlRes = await fetch(assetUrl, {
+                    headers: { 'User-Agent': 'openbridge-daemon' },
+                    redirect: 'follow',
+                });
+                if (dlRes.status === 404)
+                    throw new Error(`Release asset ${assetName} not found. Your architecture (${arch}) may not be supported yet.`);
+                if (!dlRes.ok || !dlRes.body)
+                    throw new Error(`Download failed: ${dlRes.status}`);
+                const tarballPath = join(APP_VOLUME, 'download.tar.gz');
+                const { createWriteStream } = await import('fs');
+                const { pipeline } = await import('stream/promises');
+                const { Readable } = await import('stream');
+                // Stream download with progress (size from response headers; 0 → indeterminate)
+                const totalSize = Number(dlRes.headers.get('content-length') ?? 0);
+                let downloaded = 0;
+                const progressStream = new (await import('stream')).Transform({
+                    transform(chunk, _encoding, callback) {
+                        downloaded += chunk.length;
+                        if (totalSize > 0) {
+                            const pct = Math.round((downloaded / totalSize) * 100) / 100;
+                            broadcast({
+                                stage: 'downloading',
+                                progress: pct,
+                                message: `Downloading v${version}... ${Math.round(pct * 100)}%`,
+                                version,
+                            });
+                        }
+                        callback(null, chunk);
+                    },
+                });
+                await pipeline(Readable.fromWeb(dlRes.body), progressStream, createWriteStream(tarballPath));
+                log.info(`Downloaded ${assetName} (${(downloaded / 1024 / 1024).toFixed(1)} MB)`);
+                // 3. Extract
+                broadcast({ stage: 'extracting', message: `Extracting v${version}...`, version });
+                // Clean staging
+                const { rmSync } = await import('fs');
+                rmSync(stagingDir, { recursive: true, force: true });
+                mkdirSync(stagingDir, { recursive: true });
+                await new Promise((resolve, reject) => {
+                    const tar = spawn('tar', ['xzf', tarballPath, '-C', stagingDir]);
+                    tar.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`tar exited with ${code}`))));
+                    tar.on('error', reject);
+                });
+                // Clean up tarball
+                rmSync(tarballPath, { force: true });
+                log.info(`Extracted to staging directory`);
+                // 4. Swap: current → previous, staging → current
+                broadcast({ stage: 'swapping', message: 'Installing update...', version });
+                rmSync(previousDir, { recursive: true, force: true });
+                if (existsSync(currentDir)) {
+                    const { renameSync } = await import('fs');
+                    renameSync(currentDir, previousDir);
+                }
+                const { renameSync } = await import('fs');
+                renameSync(stagingDir, currentDir);
+                // Fix node-pty permissions
+                try {
+                    const { execSync } = await import('child_process');
+                    execSync(`find "${currentDir}/apps/daemon/node_modules" -name "spawn-helper" -exec chmod +x {} \\;`, {
+                        stdio: 'ignore',
+                    });
+                }
+                catch {
+                    /* ignore */
+                }
+                // 5. Write version.json
+                writeFileSync(VERSION_FILE, JSON.stringify({
+                    version,
+                    arch,
+                    source: 'self-update',
+                    installedAt: new Date().toISOString(),
+                    previousVersion: OPENBRIDGE_VERSION,
+                }, null, 2));
+                log.info(`Update to v${version} installed successfully: restarting...`);
+                broadcast({ stage: 'restarting', message: `Restarting with v${version}...`, version });
+                // 6. Restart: just exit; Docker's restart policy will bring us back
+                // The entrypoint will see source:"self-update" in version.json and keep the updated files
+                setTimeout(() => {
+                    process.exit(0);
+                }, 500);
+            }
+            catch (err) {
+                log.error(`Self-update failed: ${err.message}`);
+                broadcast({ stage: 'error', message: err.message });
+                // Clean up staging on failure
+                try {
+                    const { rmSync } = await import('fs');
+                    rmSync(stagingDir, { recursive: true, force: true });
+                    rmSync(join(APP_VOLUME, 'download.tar.gz'), { force: true });
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        })();
+        return { updating: true };
+    });
+    // ─── Rollback ─────────────────────────────────────────────────────────────
+    app.post('/api/updates/rollback', async () => {
+        const currentDir = join(APP_VOLUME, 'current');
+        const previousDir = join(APP_VOLUME, 'previous');
+        if (!existsSync(previousDir)) {
+            throw { statusCode: 404, message: 'No previous version available for rollback' };
+        }
+        const { rmSync, renameSync } = await import('fs');
+        const rollbackDir = join(APP_VOLUME, 'rollback-tmp');
+        // Swap: current → rollback-tmp, previous → current
+        if (existsSync(currentDir))
+            renameSync(currentDir, rollbackDir);
+        renameSync(previousDir, currentDir);
+        rmSync(rollbackDir, { recursive: true, force: true });
+        // Read version from rolled-back files
+        let rolledBackVersion = 'unknown';
+        try {
+            const vf = JSON.parse(readFileSync(VERSION_FILE, 'utf8'));
+            rolledBackVersion = vf.previousVersion ?? 'unknown';
+        }
+        catch {
+            /* ignore */
+        }
+        writeFileSync(VERSION_FILE, JSON.stringify({
+            version: rolledBackVersion,
+            arch: os.arch() === 'x64' ? 'amd64' : os.arch(),
+            source: 'rollback',
+            installedAt: new Date().toISOString(),
+        }, null, 2));
+        log.info(`Rolled back to v${rolledBackVersion}: restarting...`);
+        // Restart
+        setTimeout(() => {
+            const child = spawn(process.execPath, process.argv.slice(1), {
+                detached: true,
+                stdio: 'inherit',
+                env: process.env,
+            });
+            child.unref();
+            process.exit(0);
+        }, 300);
+        return { rollingBack: true, version: rolledBackVersion };
+    });
+    // ─── System info ──────────────────────────────────────────────────────────
+    app.get('/api/system', async () => {
+        const ni = os.networkInterfaces();
+        const ip = Object.values(ni)
+            .flat()
+            .find((a) => a && !a.internal && a.family === 'IPv4')?.address ?? 'N/A';
+        return {
+            os: `${os.type()} ${os.release()}`,
+            arch: os.arch(),
+            hostname: os.hostname(),
+            user: os.userInfo().username,
+            nodeVersion: process.version,
+            ip,
+            configPath: join(OPENBRIDGE_HOME, 'config.json'),
+            obPluginsDir: OB_PLUGINS_DIR,
+            hbPluginsDir: HB_PLUGINS_DIR,
+            uptimeSystem: os.uptime(),
+            uptimeProcess: process.uptime(),
+        };
+    });
+    // ─── HomeKit QR ───────────────────────────────────────────────────────────
+    app.get('/api/qr', async () => {
+        return hapInfo ?? { setupURI: null, pincode: null };
+    });
+    // ─── Live metrics WebSocket ───────────────────────────────────────────────
+    app.get('/ws/metrics', { websocket: true }, (connection) => {
+        const ws = connection.socket;
+        // Send history immediately on connect
+        ws.send(JSON.stringify({ type: 'history', data: getHistory() }));
+        const unsub = onMetrics((snap) => {
+            if (ws.readyState === ws.OPEN) {
+                ws.send(JSON.stringify({ type: 'snapshot', data: snap }));
+            }
+        });
+        ws.on('close', unsub);
+    });
+    // ─── Plugins ─────────────────────────────────────────────────────────────
+    app.get('/api/plugins', async () => {
+        const plugins = registry.getAll();
+        // Attach cached enriched metadata to each plugin
+        const cache = loadMetadataCache();
+        for (const plugin of plugins) {
+            const pkgName = plugin.manifest.name;
+            if (cache[pkgName]) {
+                plugin.enrichedMetadata = cache[pkgName];
+            }
+        }
+        return { plugins };
+    });
+    // Re-scan HB plugins dir and register any newly installed packages
+    app.post('/api/plugins/refresh', async () => {
+        const manifestPath = join(HB_PLUGINS_DIR, 'package.json');
+        if (existsSync(manifestPath)) {
+            try {
+                const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+                const deps = manifest.dependencies ?? {};
+                for (const pkgName of Object.keys(deps)) {
+                    if (registry.get(pkgName))
+                        continue;
+                    if (knownHbPackageNames.has(pkgName))
+                        continue; // already running via config.platforms
+                    const pkgJsonPath = join(HB_PLUGINS_DIR, 'node_modules', pkgName, 'package.json');
+                    if (!existsSync(pkgJsonPath))
+                        continue;
+                    try {
+                        const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+                        const name = pkg.name ?? pkgName;
+                        const pseudoPlugin = {
+                            manifest: {
+                                name,
+                                version: pkg.version ?? '?.?.?',
+                                description: pkg.description ?? '',
+                                author: typeof pkg.author === 'string' ? pkg.author : (pkg.author?.name ?? ''),
+                            },
+                        };
+                        const instance = registry.register(pseudoPlugin);
+                        instance.source = 'homebridge';
+                        registry.updateStatus(name, 'stopped');
+                        log.info(`Discovered plugin: ${name}`);
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        const plugins = registry.getAll();
+        // Attach cached enriched metadata to each plugin
+        const cache = loadMetadataCache();
+        for (const plugin of plugins) {
+            const pkgName = plugin.manifest.name;
+            if (cache[pkgName]) {
+                plugin.enrichedMetadata = cache[pkgName];
+            }
+        }
+        return { plugins };
+    });
+    app.get('/api/plugins/:id', async (req) => {
+        const { id } = req.params;
+        const entry = registry.get(id);
+        if (!entry)
+            throw { statusCode: 404, message: `Plugin '${id}' not found` };
+        const instance = entry.instance;
+        // Attach cached enriched metadata if available
+        const cache = loadMetadataCache();
+        const pkgName = instance.manifest.name;
+        if (cache[pkgName]) {
+            instance.enrichedMetadata = cache[pkgName];
+        }
+        return instance;
+    });
+    app.get('/api/plugins/:id/telemetry', async (req) => {
+        const { id } = req.params;
+        const entry = registry.get(id);
+        if (!entry)
+            throw { statusCode: 404, message: `Plugin '${id}' not found` };
+        return { telemetry: entry.instance.telemetry ?? {} };
+    });
+    // Returns all devices across all plugins with their descriptors and latest telemetry
+    app.get('/api/devices', async () => {
+        // Load custom names
+        const namesPath = join(OPENBRIDGE_HOME, 'device-names.json');
+        let customNames = {};
+        try {
+            customNames = JSON.parse(readFileSync(namesPath, 'utf8'));
+        }
+        catch {
+            /* no custom names */
+        }
+        const devices = [];
+        for (const instance of registry.getAll()) {
+            if (!instance.devices)
+                continue;
+            for (const device of Object.values(instance.devices)) {
+                const telemetry = instance.telemetry?.[device.id] ?? {};
+                const name = customNames[device.id] ?? device.name;
+                // What the device is *presented* as, which may differ from the widget
+                // type its plugin declared. Sent so the card can show a relay driving a
+                // lamp as a light rather than contradicting the inspector next to it.
+                const accessoryUuid = nativeAccessoryUuid?.(device.id) ?? null;
+                const homekitType = accessoryUuid ? (homekitServiceTypes?.typeForAccessory(accessoryUuid) ?? null) : null;
+                devices.push({ ...device, name, telemetry, pluginStatus: instance.status, homekitType });
+            }
+        }
+        return { devices };
+    });
+    // ─── HomeKit visibility ─────────────────────────────────────────────────
+    // Hiding is per accessory, not per plugin: one plugin often provides both
+    // devices worth exposing (a switch) and devices HomeKit cannot represent
+    // (an energy meter). Enforced at the bridge, so it applies to native and
+    // Homebridge-compat plugins alike.
+    app.get('/api/homekit/hidden', async () => {
+        return { hidden: homekitVisibility?.hiddenList() ?? [] };
+    });
+    app.post('/api/homekit/visibility/:uuid', async (req) => {
+        const { uuid } = req.params;
+        const { visible } = req.body;
+        if (typeof visible !== 'boolean')
+            throw { statusCode: 400, message: 'visible (boolean) is required' };
+        if (!homekitVisibility)
+            throw { statusCode: 503, message: 'HomeKit bridge is not available' };
+        const result = homekitVisibility.setVisible(uuid, visible);
+        // `applied: false` means the preference is stored but the running bridge
+        // could not be updated, so the Home app will not reflect it until restart.
+        return { uuid, visible, ...result };
+    });
+    // ─── HomeKit service type ───────────────────────────────────────────────
+    // A plugin publishing a generic relay as a Switch cannot know it drives a
+    // light. HomeKit takes its tile, icon and Siri grammar from the service type
+    // and re-typing in the Home app does not survive a restart, so the choice is
+    // recorded here and re-applied every time the accessory is bridged.
+    app.get('/api/homekit/service-types', async () => {
+        return {
+            overrides: homekitServiceTypes?.all() ?? {},
+            // The UI builds its picker from this rather than hardcoding a parallel
+            // list that could drift from what the daemon will actually accept.
+            available: Object.entries(CONVERTIBLE_SERVICES).map(([key, def]) => ({
+                key,
+                label: def.label,
+                serviceUuid: def.uuid,
+            })),
+        };
+    });
+    app.post('/api/homekit/service-type/:uuid', async (req) => {
+        const { uuid } = req.params;
+        const { serviceUuid, type } = req.body;
+        if (!serviceUuid)
+            throw { statusCode: 400, message: 'serviceUuid is required' };
+        if (!homekitServiceTypes)
+            throw { statusCode: 503, message: 'HomeKit bridge is not available' };
+        if (type != null && !(type in CONVERTIBLE_SERVICES)) {
+            throw {
+                statusCode: 400,
+                message: `Unsupported type '${type}'. Expected one of: ${Object.keys(CONVERTIBLE_SERVICES).join(', ')}`,
+            };
+        }
+        // Only On-based services are interchangeable; anything else would lose the
+        // characteristics that give it meaning.
+        if (type != null && !isConvertible(serviceUuid)) {
+            throw { statusCode: 400, message: `Service ${serviceUuid} cannot be re-typed` };
+        }
+        homekitServiceTypes.set(uuid, serviceUuid, (type ?? null));
+        log.info(`HomeKit service type for ${uuid}/${serviceUuid} set to ${type ?? 'default'}`);
+        // Never applied live: HomeKit caches an accessory's shape at pairing, so a
+        // type swapped on a published accessory is not picked up until restart.
+        return { uuid, serviceUuid, type: type ?? null, applied: false };
+    });
+    /**
+     * The HAP accessory behind a native plugin's device, if it published one.
+     *
+     * Lets the devices inspector offer the same HomeKit controls for a native
+     * device as for a compat one. Returns `accessory: null` rather than 404ing
+     * when a plugin publishes no accessory at all, which is a normal state (a
+     * telemetry-only device) and not an error.
+     */
+    app.get('/api/devices/:deviceId/accessory', async (req) => {
+        const { deviceId } = req.params;
+        const accessory = resolveNativeAccessory?.(deviceId) ?? null;
+        return { accessory };
+    });
+    // ─── Device rename ──────────────────────────────────────────────────────
+    app.post('/api/devices/:deviceId/rename', async (req) => {
+        const { deviceId } = req.params;
+        const { name } = req.body;
+        if (!name?.trim())
+            throw { statusCode: 400, message: 'name is required' };
+        // Update in registry (native devices)
+        for (const instance of registry.getAll()) {
+            if (instance.devices?.[deviceId]) {
+                instance.devices[deviceId].name = name.trim();
+                break;
+            }
+        }
+        // Update HAP accessory name if it exists
+        if (hapAPI) {
+            const raw = hapAPI.getRawAccessories?.() ?? [];
+            const acc = raw.find((a) => a.UUID === deviceId);
+            if (acc) {
+                // Find AccessoryInformation service and set Name characteristic
+                for (const svc of acc.services ?? []) {
+                    for (const ch of svc.characteristics ?? []) {
+                        if (ch.displayName === 'Name' || ch.constructor?.name === 'Name') {
+                            try {
+                                ch.setValue(name.trim());
+                            }
+                            catch {
+                                /* ignore: some characteristics may not accept setValue */
+                            }
+                        }
+                    }
+                }
+                // Also update the displayName
+                acc.displayName = name.trim();
+            }
+        }
+        // Persist custom names to file
+        const namesPath = join(OPENBRIDGE_HOME, 'device-names.json');
+        let customNames = {};
+        try {
+            customNames = JSON.parse(readFileSync(namesPath, 'utf8'));
+        }
+        catch {
+            /* start fresh */
+        }
+        customNames[deviceId] = name.trim();
+        writeFileSync(namesPath, JSON.stringify(customNames, null, 2));
+        log.info(`Device ${deviceId} renamed to "${name.trim()}"`);
+        return { ok: true, deviceId, name: name.trim() };
+    });
+    app.post('/api/devices/:deviceId/control', async (req) => {
+        const { deviceId } = req.params;
+        const { control, value } = req.body;
+        const key = `${deviceId}::${control}`;
+        if (restrictedControls.has(key)) {
+            throw { statusCode: 403, message: `Control '${control}' is restricted for device '${deviceId}'` };
+        }
+        const handler = controls.get(key);
+        if (!handler)
+            throw { statusCode: 404, message: `No control '${control}' registered for device '${deviceId}'` };
+        await handler(value);
+        return { ok: true };
+    });
+    /**
+     * Metric-aware history.
+     *
+     * The older /history route below serves cumulative energy bucketed into
+     * day/month/year kWh and is kept working unchanged, since the shipped UI
+     * depends on it. This route serves any declared metric over an arbitrary
+     * range, which is what per-phase charting needs.
+     */
+    app.get('/api/devices/:deviceId/metrics', async (req) => {
+        const { deviceId } = req.params;
+        const { metric, from, to, maxPoints } = req.query;
+        const device = findDevice(registry, deviceId);
+        if (!device)
+            throw { statusCode: 404, message: `Device '${deviceId}' not found` };
+        const metrics = device.metrics ?? [];
+        if (metrics.length === 0)
+            return { deviceId, metrics: [], series: null };
+        // Without an explicit metric, report what this device offers so the UI can
+        // populate its selector without a second round trip.
+        if (!metric)
+            return { deviceId, metrics, series: null };
+        const descriptor = metrics.find((m) => m.key === metric);
+        if (!descriptor)
+            throw { statusCode: 404, message: `Device '${deviceId}' does not report '${metric}'` };
+        const now = Math.floor(Date.now() / 1000);
+        const toSec = to ? Number(to) : now;
+        const fromSec = from ? Number(from) : toSec - 86400;
+        if (!Number.isFinite(fromSec) || !Number.isFinite(toSec) || fromSec >= toSec) {
+            throw { statusCode: 400, message: 'Invalid from/to range' };
+        }
+        const series = new DeviceSeries(join(OPENBRIDGE_HOME, 'metrics'), deviceId, metrics);
+        const points = Math.min(5000, Math.max(10, Number(maxPoints) || 720));
+        const result = series.query(metric, fromSec, toSec, points);
+        return {
+            deviceId,
+            metrics,
+            series: {
+                metric: descriptor,
+                resolution: result.tier.interval,
+                tier: result.tier.name,
+                from: fromSec,
+                to: toSec,
+                points: result.points,
+            },
+        };
+    });
+    app.get('/api/devices/:deviceId/history', async (req) => {
+        const { deviceId } = req.params;
+        const { period = 'day', date } = req.query;
+        const historyDir = join(OPENBRIDGE_HOME, 'energy-history');
+        const filePath = join(historyDir, `${deviceId}.json`);
+        let samples = [];
+        try {
+            samples = JSON.parse(readFileSync(filePath, 'utf8'));
+        }
+        catch {
+            return { period, date: date ?? new Date().toISOString().slice(0, 10), buckets: [] };
+        }
+        const ref = date ? new Date(date) : new Date();
+        if (period === 'day') {
+            // 24 hourly buckets for ref day
+            const dayStr = ref.toISOString().slice(0, 10);
+            const buckets = Array.from({ length: 24 }, (_, h) => {
+                const label = `${String(h).padStart(2, '0')}:00`;
+                const start = new Date(`${dayStr}T${String(h).padStart(2, '0')}:00:00Z`);
+                const end = new Date(`${dayStr}T${String(h + 1).padStart(2, '0') === '24' ? '23:59:59' : String(h + 1).padStart(2, '0') + ':00:00'}Z`);
+                const inWindow = samples.filter((s) => s.t >= start.toISOString() && s.t < end.toISOString());
+                if (inWindow.length < 2)
+                    return { label, kwh: null };
+                const kwh = inWindow[inWindow.length - 1].e - inWindow[0].e;
+                return { label, kwh: Math.max(0, Math.round(kwh * 100) / 100) };
+            });
+            const totalKwh = buckets.reduce((sum, b) => sum + (b.kwh ?? 0), 0);
+            return { period, date: dayStr, buckets, totalKwh: Math.round(totalKwh * 100) / 100 };
+        }
+        if (period === 'month') {
+            // Daily buckets for ref month
+            const year = ref.getFullYear();
+            const month = ref.getMonth();
+            const daysInMonth = new Date(year, month + 1, 0).getDate();
+            const monthStr = `${year}-${String(month + 1).padStart(2, '0')}`;
+            const buckets = Array.from({ length: daysInMonth }, (_, d) => {
+                const dayStr = `${monthStr}-${String(d + 1).padStart(2, '0')}`;
+                const start = new Date(`${dayStr}T00:00:00Z`);
+                const end = new Date(`${dayStr}T23:59:59Z`);
+                const inWindow = samples.filter((s) => s.t >= start.toISOString() && s.t <= end.toISOString());
+                if (inWindow.length < 2)
+                    return { label: String(d + 1), kwh: null };
+                const kwh = inWindow[inWindow.length - 1].e - inWindow[0].e;
+                return { label: String(d + 1), kwh: Math.max(0, Math.round(kwh * 100) / 100) };
+            });
+            const totalKwh = buckets.reduce((sum, b) => sum + (b.kwh ?? 0), 0);
+            return { period, date: monthStr, buckets, totalKwh: Math.round(totalKwh * 100) / 100 };
+        }
+        // period === 'year'
+        const year = ref.getFullYear();
+        const buckets = Array.from({ length: 12 }, (_, m) => {
+            const monthStr = `${year}-${String(m + 1).padStart(2, '0')}`;
+            const start = new Date(`${monthStr}-01T00:00:00Z`);
+            const end = new Date(year, m + 1, 0, 23, 59, 59);
+            const inWindow = samples.filter((s) => s.t >= start.toISOString() && s.t <= end.toISOString());
+            if (inWindow.length < 2)
+                return {
+                    label: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'][m],
+                    kwh: null,
+                };
+            const kwh = inWindow[inWindow.length - 1].e - inWindow[0].e;
+            return {
+                label: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'][m],
+                kwh: Math.max(0, Math.round(kwh * 100) / 100),
+            };
+        });
+        const totalKwh = buckets.reduce((sum, b) => sum + (b.kwh ?? 0), 0);
+        return { period, date: String(year), buckets, totalKwh: Math.round(totalKwh * 100) / 100 };
+    });
+    app.post('/api/plugins/:id/disabled', async (req) => {
+        const { id } = req.params;
+        const { disabled } = req.body;
+        const entry = registry.get(id);
+        if (!entry)
+            throw { statusCode: 404, message: `Plugin '${id}' not found` };
+        // Update the instance
+        entry.instance.disabled = disabled;
+        // Persist to config.json under a disabledPlugins array
+        try {
+            let cfg = {};
+            try {
+                cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+            }
+            catch {
+                /* start fresh */
+            }
+            // Persist the npm package name when we know it, not the registry id.
+            // A Homebridge-compat plugin is registered under its *platform* name
+            // ("ShellyDS9") while the loader looks plugins up by *package* name
+            // ("homebridge-shelly-ds9"), so writing the id here meant the loader
+            // never matched and the plugin started anyway. For native plugins and
+            // legacy config.platforms[] entries the two are the same value.
+            const key = entry.instance.packageName ?? id;
+            // Remove every alias so a stale entry written under the old id cannot
+            // keep a re-enabled plugin switched off.
+            const aliases = new Set([id, key, entry.instance.platformName].filter(Boolean));
+            const disabledPlugins = (cfg.disabledPlugins ?? []).filter((n) => !aliases.has(n));
+            if (disabled)
+                disabledPlugins.push(key);
+            cfg.disabledPlugins = disabledPlugins;
+            writeFileSync(configPath, JSON.stringify(cfg, null, 2), 'utf8');
+            log.info(`Plugin disabled state toggled: ${key} -> ${disabled}`);
+        }
+        catch (err) {
+            log.warn(`Failed to persist disabled state: ${err}`);
+        }
+        return entry.instance;
+    });
+    // ─── Accessories (HAP / Homebridge) ───────────────────────────────────────
+    app.get('/api/accessories', async () => {
+        return { accessories: hapAPI ? hapAPI.getAccessories() : [] };
+    });
+    // Write a characteristic value: triggers the platform's onSet handler
+    app.post('/api/accessories/:uuid/characteristics', async (req) => {
+        if (!hapAPI)
+            throw { statusCode: 503, message: 'HAP not available' };
+        const { uuid } = req.params;
+        const { serviceUuid, charUuid, value } = req.body;
+        const raw = hapAPI.getRawAccessories();
+        const acc = raw.find((a) => a.UUID === uuid);
+        if (!acc)
+            throw { statusCode: 404, message: `Accessory '${uuid}' not found` };
+        const svc = acc.services?.find((s) => s.UUID === serviceUuid);
+        if (!svc)
+            throw { statusCode: 404, message: `Service '${serviceUuid}' not found` };
+        const ch = svc.characteristics?.find((c) => c.UUID === charUuid);
+        if (!ch)
+            throw { statusCode: 404, message: `Characteristic '${charUuid}' not found` };
+        try {
+            ch.setValue(value);
+        }
+        catch (err) {
+            throw { statusCode: 500, message: `setValue failed: ${err}` };
+        }
+        log.debug(`Set ${acc.displayName} / ${svc.displayName} / ${ch.displayName} = ${value}`);
+        return { uuid, serviceUuid, charUuid, value };
+    });
+    app.get('/api/accessories/debug', async () => {
+        if (!hapAPI)
+            return { hapAPI: false };
+        const raw = hapAPI.getRawAccessories();
+        return {
+            count: raw.length,
+            names: raw.map((a) => ({ displayName: a.displayName, UUID: a.UUID, category: a.category })),
+        };
+    });
+    // ─── Bridge config (structured) ───────────────────────────────────────────
+    app.get('/api/bridge', async () => {
+        try {
+            const cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+            return cfg.bridge ?? {};
+        }
+        catch {
+            return {};
+        }
+    });
+    app.post('/api/bridge', async (req) => {
+        const bridgeUpdate = req.body;
+        let cfg = {};
+        try {
+            cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+        }
+        catch {
+            /* start fresh */
+        }
+        cfg.bridge = { ...(cfg.bridge ?? {}), ...bridgeUpdate };
+        writeFileSync(configPath, JSON.stringify(cfg, null, 2), 'utf8');
+        log.info('Bridge config saved');
+        return { saved: true, bridge: cfg.bridge };
+    });
+    // ─── Config file editor ────────────────────────────────────────────────────
+    const configPath = resolve(os.homedir(), '.openbridge', 'config.json');
+    app.get('/api/config', async () => {
+        try {
+            return { content: readFileSync(configPath, 'utf8') };
+        }
+        catch {
+            return { content: '{}' };
+        }
+    });
+    app.post('/api/config', async (req) => {
+        const { content } = req.body;
+        try {
+            JSON.parse(content);
+        }
+        catch {
+            throw { statusCode: 400, message: 'Invalid JSON' };
+        }
+        writeFileSync(configPath, content, 'utf8');
+        log.info('Config saved');
+        return { saved: true };
+    });
+    // Upsert a single platform entry (add or replace by platform name)
+    app.post('/api/config/platform', async (req) => {
+        const { platform } = req.body;
+        if (!platform?.platform)
+            throw { statusCode: 400, message: 'platform.platform is required' };
+        let cfg = {};
+        try {
+            cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+        }
+        catch {
+            /* start fresh */
+        }
+        const platforms = cfg.platforms ?? [];
+        const idx = platforms.findIndex((p) => p.platform === platform.platform);
+        if (idx >= 0)
+            platforms[idx] = platform;
+        else
+            platforms.push(platform);
+        cfg.platforms = platforms;
+        writeFileSync(configPath, JSON.stringify(cfg, null, 2), 'utf8');
+        log.info(`Platform config saved: ${platform.platform}`);
+        return { saved: true, platform: platform.platform };
+    });
+    // Get a single platform's config (or empty object if not configured)
+    app.get('/api/config/platform/:name', async (req) => {
+        const { name } = req.params;
+        try {
+            const cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+            const entry = (cfg.platforms ?? []).find((p) => p.platform === name);
+            return { config: entry ?? null };
+        }
+        catch {
+            return { config: null };
+        }
+    });
+    // Get a single native plugin's config
+    app.get('/api/config/plugin/:name', async (req) => {
+        const { name } = req.params;
+        try {
+            const cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+            const entry = (cfg.plugins ?? []).find((p) => p.name === name);
+            return { config: entry?.config ?? null };
+        }
+        catch {
+            return { config: null };
+        }
+    });
+    // Upsert a native plugin's config entry
+    app.post('/api/config/plugin', async (req) => {
+        const { name, config } = req.body;
+        if (!name)
+            throw { statusCode: 400, message: 'name is required' };
+        let cfg = {};
+        try {
+            cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+        }
+        catch {
+            /* start fresh */
+        }
+        const plugins = cfg.plugins ?? [];
+        const idx = plugins.findIndex((p) => p.name === name);
+        if (idx >= 0)
+            plugins[idx] = { ...plugins[idx], config };
+        else
+            plugins.push({ name, enabled: true, config });
+        cfg.plugins = plugins;
+        writeFileSync(configPath, JSON.stringify(cfg, null, 2), 'utf8');
+        log.info(`Plugin config saved: ${name}`);
+        return { saved: true, name };
+    });
+    function readConfigFile() {
+        try {
+            return JSON.parse(readFileSync(configPath, 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    function findHbConfig(cfg, platformName, packageName) {
+        const platformEntry = (cfg.platforms ?? []).find((p) => p.platform === platformName);
+        if (platformEntry)
+            return { config: platformEntry, location: 'platforms' };
+        // Match on the package name when the UI knows it, else fall back to the
+        // platform name: some entries are keyed that way.
+        const pluginEntry = (cfg.plugins ?? []).find((p) => p.name === (packageName ?? platformName));
+        if (pluginEntry)
+            return { config: pluginEntry.config ?? {}, location: 'plugins' };
+        return { config: null, location: null };
+    }
+    app.get('/api/config/hb-plugin/:name', async (req) => {
+        const { name } = req.params;
+        const { packageName } = req.query;
+        return findHbConfig(readConfigFile(), name, packageName);
+    });
+    app.post('/api/config/hb-plugin', async (req) => {
+        const { name, packageName, config } = req.body;
+        if (!name)
+            throw { statusCode: 400, message: 'name is required' };
+        const cfg = readConfigFile();
+        const { location } = findHbConfig(cfg, name, packageName);
+        if (location === 'platforms') {
+            const platforms = cfg.platforms ?? [];
+            const idx = platforms.findIndex((p) => p.platform === name);
+            platforms[idx] = { ...config, platform: name };
+            cfg.platforms = platforms;
+        }
+        else {
+            // Default for anything not already in platforms[]: auto-discovered
+            // plugins are read from plugins[], so a new entry must go there or the
+            // save is silently ignored on the next start.
+            const key = packageName ?? name;
+            const plugins = cfg.plugins ?? [];
+            const idx = plugins.findIndex((p) => p.name === key);
+            if (idx >= 0)
+                plugins[idx] = { ...plugins[idx], config };
+            else
+                plugins.push({ name: key, enabled: true, config });
+            cfg.plugins = plugins;
+        }
+        writeFileSync(configPath, JSON.stringify(cfg, null, 2), 'utf8');
+        log.info(`Homebridge plugin config saved: ${name} (${location ?? 'plugins'})`);
+        return { saved: true, name, location: location ?? 'plugins' };
+    });
+    // ─── Marketplace ──────────────────────────────────────────────────────────
+    // Plugins are discovered by npm keyword. Native OpenBridge plugins declare
+    // `openbridge-plugin`; Homebridge-compat ones declare `homebridge-plugin`.
+    // npm's search API has no OR for keywords (both `a,b` and `a+b` mean AND and
+    // return nothing), so each keyword needs its own query and the results are
+    // merged here. Searching only one keyword hides an entire class of plugin
+    // from the marketplace, including natives the user can actually install.
+    const PLUGIN_KEYWORDS = ['homebridge-plugin', 'openbridge-plugin'];
+    app.get('/api/marketplace/search', async (req) => {
+        const { q = '', from = '0', size = '20' } = req.query;
+        const results = await Promise.all(PLUGIN_KEYWORDS.map(async (keyword) => {
+            const text = encodeURIComponent(`keywords:${keyword} ${q}`.trim());
+            const url = `https://registry.npmjs.org/-/v1/search?text=${text}&size=${size}&from=${from}`;
+            const res = await fetch(url);
+            if (!res.ok)
+                throw { statusCode: 502, message: `npm registry error: ${res.status}` };
+            return (await res.json());
+        }));
+        // Dedupe by package name: a plugin may legitimately declare both keywords.
+        const seen = new Set();
+        const objects = [];
+        for (const result of results) {
+            for (const obj of result.objects ?? []) {
+                const name = obj?.package?.name;
+                if (!name || seen.has(name))
+                    continue;
+                seen.add(name);
+                objects.push(obj);
+            }
+        }
+        // Restore npm's own relevance ordering across the merged set, then trim to
+        // the requested page size so the response stays the shape the UI expects.
+        objects.sort((a, b) => (b?.searchScore ?? 0) - (a?.searchScore ?? 0));
+        return {
+            objects: objects.slice(0, Number(size) || 20),
+            total: results.reduce((sum, r) => sum + (r.total ?? 0), 0),
+            time: results[0]?.time,
+        };
+    });
+    // Probe a marketplace plugin to discover its platform name(s) without fully starting it
+    app.get('/api/marketplace/plugin-info/:name', async (req) => {
+        const { name } = req.params;
+        const pkgDir = join(HB_PLUGINS_DIR, 'node_modules', name);
+        if (!existsSync(pkgDir))
+            throw { statusCode: 404, message: `Plugin '${name}' not installed` };
+        const pkgJsonPath = join(pkgDir, 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+        const mainFile = join(pkgDir, pkg.main ?? 'index.js');
+        const platforms = [];
+        const spyAPI = {
+            hap: { Characteristic: {}, Service: {}, Accessory: { Categories: {} }, uuid: { generate: () => '' } },
+            platformAccessory: class {
+            },
+            // Handle both calling conventions:
+            //   4-arg: registerPlatform(pluginName, platformName, Constructor, dynamic)
+            //   3-arg: registerPlatform(platformName, Constructor, dynamic)
+            registerPlatform: (...args) => {
+                const platformName = typeof args[0] === 'string' && typeof args[1] === 'string' ? args[1] : args[0];
+                if (typeof platformName === 'string')
+                    platforms.push(platformName);
+            },
+            registerAccessory: () => { },
+            on: () => spyAPI,
+            emit: () => false,
+            version: '2.0.0',
+            serverVersion: '2.0.0',
+            user: {
+                storagePath: () => join(os.homedir(), '.openbridge'),
+                configPath: () => join(os.homedir(), '.openbridge', 'config.json'),
+                persistPath: () => join(os.homedir(), '.openbridge', 'persist'),
+                cachedAccessoryPath: () => join(os.homedir(), '.openbridge', 'accessories'),
+            },
+        };
+        try {
+            const { loadHomebridgePlugin } = await import('@nubisco/openbridge-compatibility-homebridge');
+            const fn = loadHomebridgePlugin(mainFile);
+            fn(spyAPI);
+        }
+        catch {
+            /* plugin may fail without real HAP, but registration should have happened */
+        }
+        return { name, version: pkg.version, mainFile, platforms };
+    });
+    app.get('/api/marketplace/installed', async () => {
+        const nmDir = join(HB_PLUGINS_DIR, 'node_modules');
+        if (!existsSync(nmDir))
+            return { packages: [] };
+        try {
+            const pkgJson = join(HB_PLUGINS_DIR, 'package.json');
+            if (!existsSync(pkgJson))
+                return { packages: [] };
+            const pkg = JSON.parse(readFileSync(pkgJson, 'utf8'));
+            const deps = { ...pkg.dependencies };
+            return {
+                packages: Object.entries(deps).map(([name, version]) => {
+                    let mainFile = '';
+                    try {
+                        const pkgPath = join(nmDir, name, 'package.json');
+                        const p = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                        mainFile = join(nmDir, name, p.main ?? 'index.js');
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    return { name, version, mainFile };
+                }),
+            };
+        }
+        catch {
+            return { packages: [] };
+        }
+    });
+    // OpenBridge native + local dev plugins
+    // Always scans ~/.openbridge/plugins/openbridge (canonical install location)
+    // plus any extra directories in config.localPluginSources (for dev/testing)
+    app.get('/api/marketplace/local', async () => {
+        const plugins = [];
+        const seen = new Set();
+        // Helper: scan a directory for openbridge-* sub-packages
+        function scanDir(dir) {
+            if (!existsSync(dir))
+                return;
+            let entries;
+            try {
+                entries = readdirSync(dir, { encoding: 'utf8', withFileTypes: false });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                if (!entry.startsWith('openbridge-'))
+                    continue;
+                const pkgPath = join(dir, entry, 'package.json');
+                if (!existsSync(pkgPath))
+                    continue;
+                try {
+                    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                    const name = pkg.name ?? entry;
+                    if (seen.has(name))
+                        continue; // deduplicate across sources
+                    seen.add(name);
+                    plugins.push({
+                        name,
+                        version: pkg.version ?? '0.0.0',
+                        description: pkg.description ?? '',
+                        author: typeof pkg.author === 'string' ? pkg.author : (pkg.author?.name ?? ''),
+                        path: join(dir, entry),
+                        platform: pkg.openbridge?.platform,
+                        displayName: pkg.openbridge?.displayName,
+                    });
+                }
+                catch {
+                    /* skip */
+                }
+            }
+        }
+        // 1. Canonical install location (highest priority: shows installed native plugins)
+        scanDir(OB_PLUGINS_DIR);
+        // 2. Extra dev/test directories from config
+        for (const sourceDir of localPluginSources)
+            scanDir(sourceDir);
+        return { plugins };
+    });
+    // ─── Plugin metadata cache helpers ─────────────────────────────────────────
+    const metadataCachePath = resolve(os.homedir(), '.openbridge', 'plugin-metadata-cache.json');
+    function loadMetadataCache() {
+        try {
+            if (existsSync(metadataCachePath)) {
+                return JSON.parse(readFileSync(metadataCachePath, 'utf8'));
+            }
+        }
+        catch {
+            /* ignore */
+        }
+        return {};
+    }
+    function saveMetadataCache(cache) {
+        try {
+            mkdirSync(dirname(metadataCachePath), { recursive: true });
+            writeFileSync(metadataCachePath, JSON.stringify(cache, null, 2), 'utf8');
+        }
+        catch (err) {
+            log.warn(`Failed to save metadata cache: ${err}`);
+        }
+    }
+    async function fetchAndCacheEnrichedMetadata(pkgName) {
+        try {
+            // Fetch from the enriched endpoint (same logic as GET /api/marketplace/enriched/:name)
+            const enrichedRes = await fetch(`http://localhost:${process.env.PORT ?? 8000}/api/marketplace/enriched/${encodeURIComponent(pkgName)}`).catch(() => null);
+            if (enrichedRes?.ok) {
+                const enriched = await enrichedRes.json();
+                // Save to cache
+                const cache = loadMetadataCache();
+                cache[pkgName] = enriched;
+                saveMetadataCache(cache);
+                return enriched;
+            }
+        }
+        catch (err) {
+            log.warn(`Failed to fetch enriched metadata for ${pkgName}: ${err}`);
+        }
+        return undefined;
+    }
+    // ─── Plugin update checker ─────────────────────────────────────────────────
+    // Queries npm registry for latest versions of all installed plugins and
+    // sets `availableUpdate` on each PluginInstance when a newer version exists.
+    async function checkPluginUpdates() {
+        const plugins = registry.getAll();
+        let updatesFound = 0;
+        for (const plugin of plugins) {
+            const name = plugin.manifest.name;
+            const currentVersion = plugin.manifest.version;
+            if (!currentVersion || currentVersion === '?.?.?')
+                continue;
+            try {
+                const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`, {
+                    signal: AbortSignal.timeout(5000),
+                    headers: { Accept: 'application/json' },
+                });
+                if (!res.ok)
+                    continue;
+                const data = (await res.json());
+                const latest = data.version;
+                if (!latest)
+                    continue;
+                if (latest !== currentVersion) {
+                    plugin.availableUpdate = latest;
+                    updatesFound++;
+                }
+                else {
+                    plugin.availableUpdate = undefined;
+                }
+            }
+            catch {
+                // npm unreachable for this package, skip
+            }
+        }
+        if (updatesFound > 0) {
+            log.info(`Plugin update check: ${updatesFound} update(s) available`);
+        }
+        return updatesFound;
+    }
+    // Check for updates on startup (after a delay for plugins to register) and every 6 hours
+    setTimeout(() => checkPluginUpdates(), 60_000);
+    setInterval(() => checkPluginUpdates(), 6 * 60 * 60_000);
+    app.get('/api/plugins/updates', async () => {
+        const count = await checkPluginUpdates();
+        const updates = registry
+            .getAll()
+            .filter((p) => p.availableUpdate)
+            .map((p) => ({
+            name: p.manifest.name,
+            current: p.manifest.version,
+            latest: p.availableUpdate,
+        }));
+        return { count, updates };
+    });
+    app.post('/api/marketplace/install', async (req) => {
+        const { package: pkg } = req.body;
+        if (!pkg || !/^[a-z0-9@._/-]+$/i.test(pkg)) {
+            throw { statusCode: 400, message: 'Invalid package name' };
+        }
+        mkdirSync(HB_PLUGINS_DIR, { recursive: true });
+        await new Promise((ok, fail) => {
+            const child = spawn('npm', ['install', '--prefix', HB_PLUGINS_DIR, pkg], {
+                stdio: 'pipe',
+                env: { ...process.env },
+            });
+            child.on('close', (code) => (code === 0 ? ok() : fail(new Error(`npm exited with ${code}`))));
+        });
+        // Find the installed plugin's main file
+        let mainFile = '';
+        try {
+            const pkgPath = join(HB_PLUGINS_DIR, 'node_modules', pkg, 'package.json');
+            const p = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            mainFile = join(HB_PLUGINS_DIR, 'node_modules', pkg, p.main ?? 'index.js');
+        }
+        catch {
+            /* ignore */
+        }
+        // Detect if native OpenBridge plugin and register immediately
+        let isNative = false;
+        try {
+            const pkgPath = join(HB_PLUGINS_DIR, 'node_modules', pkg, 'package.json');
+            const p = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            isNative = (Array.isArray(p.keywords) && p.keywords.includes('openbridge-plugin')) || p.openbridge != null;
+            if (isNative) {
+                // Register as a pseudo-plugin so it appears in the UI immediately
+                // It will be fully loaded on next restart
+                const pseudoPlugin = {
+                    manifest: {
+                        name: p.name ?? pkg,
+                        version: p.version ?? '?.?.?',
+                        description: p.description ?? '',
+                        author: typeof p.author === 'string' ? p.author : (p.author?.name ?? ''),
+                    },
+                };
+                if (!registry.get(p.name ?? pkg)) {
+                    registry.register(pseudoPlugin);
+                    registry.updateStatus(p.name ?? pkg, 'stopped');
+                }
+                log.info(`Discovered plugin: ${p.name ?? pkg}`);
+            }
+        }
+        catch {
+            /* ignore detection errors */
+        }
+        // Fetch and cache enriched metadata in the background (non-blocking)
+        fetchAndCacheEnrichedMetadata(pkg).catch((err) => log.warn(`Failed to cache metadata for ${pkg}: ${err}`));
+        log.info(`Installed plugin: ${pkg}`);
+        return { installed: pkg, mainFile, pluginsDir: HB_PLUGINS_DIR, isNative, needsRestart: isNative };
+    });
+    app.post('/api/marketplace/update/:name', async (req) => {
+        const { name } = req.params;
+        if (!name || !/^[a-z0-9@._/-]+$/i.test(name)) {
+            throw { statusCode: 400, message: 'Invalid package name' };
+        }
+        const entry = registry.get(name);
+        const targetVersion = entry?.instance.availableUpdate;
+        const installArg = targetVersion ? `${name}@${targetVersion}` : name;
+        mkdirSync(HB_PLUGINS_DIR, { recursive: true });
+        await new Promise((ok, fail) => {
+            const child = spawn('npm', ['install', '--prefix', HB_PLUGINS_DIR, installArg], {
+                stdio: 'pipe',
+                env: { ...process.env },
+            });
+            child.on('close', (code) => (code === 0 ? ok() : fail(new Error(`npm exited with ${code}`))));
+        });
+        // Update the in-memory manifest version so the UI reflects the change immediately
+        if (entry) {
+            try {
+                const pkgPath = join(HB_PLUGINS_DIR, 'node_modules', name, 'package.json');
+                const p = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                entry.instance.manifest.version = p.version ?? entry.instance.manifest.version;
+                entry.instance.manifest.description = p.description ?? entry.instance.manifest.description;
+            }
+            catch {
+                // If we can't read the new version, the restart will pick it up
+            }
+            entry.instance.availableUpdate = undefined;
+        }
+        log.info(`Updated plugin: ${name} to ${targetVersion ?? 'latest'}`);
+        return { updated: name, version: targetVersion ?? 'latest', needsRestart: true };
+    });
+    app.delete('/api/marketplace/uninstall/:name', async (req) => {
+        const { name } = req.params;
+        if (!name || !/^[a-z0-9@._/-]+$/i.test(name)) {
+            throw { statusCode: 400, message: 'Invalid package name' };
+        }
+        await new Promise((ok, fail) => {
+            const child = spawn('npm', ['uninstall', '--prefix', HB_PLUGINS_DIR, name], {
+                stdio: 'pipe',
+                env: { ...process.env },
+            });
+            child.on('close', (code) => (code === 0 ? ok() : fail(new Error(`npm exited with ${code}`))));
+        });
+        // Remove stale plugin instances from in-memory registry so /plugins updates immediately.
+        const removedInstances = registry.unregisterWhere((instance) => {
+            if (instance.manifest.name === name)
+                return true;
+            const desc = instance.manifest.description ?? '';
+            // Backward compatibility for older pseudo-plugin descriptions.
+            return desc.includes(`Homebridge platform: ${name}`);
+        });
+        // Prune config.platforms AND config.plugins entries for this package.
+        try {
+            const cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+            let changed = false;
+            // Remove from platforms (Homebridge-compat plugins)
+            if (Array.isArray(cfg.platforms)) {
+                const before = cfg.platforms.length;
+                cfg.platforms = cfg.platforms.filter((p) => {
+                    const pluginPath = String(p?.plugin ?? '');
+                    return !pluginPath.includes(`/node_modules/${name}/`);
+                });
+                if (cfg.platforms.length !== before)
+                    changed = true;
+            }
+            // Remove from plugins (native OpenBridge plugins)
+            if (Array.isArray(cfg.plugins)) {
+                const before = cfg.plugins.length;
+                cfg.plugins = cfg.plugins.filter((p) => p?.name !== name);
+                if (cfg.plugins.length !== before)
+                    changed = true;
+            }
+            if (changed) {
+                writeFileSync(configPath, JSON.stringify(cfg, null, 2), 'utf8');
+            }
+        }
+        catch {
+            /* ignore config pruning errors */
+        }
+        // Remove any symlink in the native plugins dir
+        try {
+            const { readdirSync, lstatSync, unlinkSync, readlinkSync } = await import('fs');
+            const nativeDir = join(OPENBRIDGE_HOME, 'plugins', 'openbridge');
+            if (existsSync(nativeDir)) {
+                for (const entry of readdirSync(nativeDir)) {
+                    const entryPath = join(nativeDir, entry);
+                    try {
+                        const stat = lstatSync(entryPath);
+                        if (stat.isSymbolicLink()) {
+                            const target = readlinkSync(entryPath);
+                            if (entry.includes(name.replace(/^@[^/]+\//, '')) || target.includes(name)) {
+                                unlinkSync(entryPath);
+                                log.info(`Removed symlink: ${entryPath}`);
+                            }
+                        }
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+            }
+        }
+        catch {
+            /* ignore symlink cleanup errors */
+        }
+        // Clear metadata cache for this plugin
+        try {
+            const cache = loadMetadataCache();
+            delete cache[name];
+            saveMetadataCache(cache);
+        }
+        catch {
+            /* ignore cache cleanup errors */
+        }
+        log.info(`Uninstalled plugin: ${name}`);
+        return { uninstalled: name, removedInstances };
+    });
+    // ─── Daemon restart ───────────────────────────────────────────────────────
+    app.post('/api/daemon/restart', async (_req, reply) => {
+        log.info('Restart requested via API: respawning...');
+        await reply.send({ restarting: true });
+        setTimeout(() => {
+            // In dev mode (OPENBRIDGE_DEV=true set by the dev script), tsx watch detects the exit and restarts.
+            // In prod mode (node dist/index.js), we respawn using the same entry point.
+            const isTsx = process.env.OPENBRIDGE_DEV === 'true';
+            if (isTsx) {
+                // Let tsx watch restart us
+                process.exit(0);
+            }
+            else {
+                const child = spawn(process.execPath, process.argv.slice(1), {
+                    detached: true,
+                    stdio: 'inherit',
+                    env: process.env,
+                });
+                child.unref();
+                process.exit(0);
+            }
+        }, 300);
+    });
+    // ─── Logs ─────────────────────────────────────────────────────────────────
+    app.get('/api/logs', async (req) => {
+        const query = req.query;
+        const entries = Logger.getEntries(query.plugin, query.limit ? parseInt(query.limit) : 200);
+        return { entries };
+    });
+    app.get('/ws/logs', { websocket: true }, (connection) => {
+        const ws = connection.socket;
+        log.debug('Log WebSocket client connected');
+        const unsubscribe = Logger.subscribe((entry) => {
+            if (ws.readyState === ws.OPEN)
+                ws.send(JSON.stringify(entry));
+        });
+        ws.on('close', () => {
+            unsubscribe();
+            log.debug('Log WebSocket client disconnected');
+        });
+    });
+    // ─── Plugin config schema ────────────────────────────────────────────────
+    // Returns parsed config.schema.json for a given installed HB plugin
+    app.get('/api/marketplace/plugin-schema/:name', async (req) => {
+        const { name } = req.params;
+        const pkgDir = join(HB_PLUGINS_DIR, 'node_modules', name);
+        const schemaPath = join(pkgDir, 'config.schema.json');
+        if (!existsSync(schemaPath)) {
+            // Also try at package root (some plugins ship it differently)
+            const altPath = join(pkgDir, 'homebridge-ui', 'config.schema.json');
+            if (existsSync(altPath))
+                return { schema: JSON.parse(readFileSync(altPath, 'utf8')) };
+            return { schema: null };
+        }
+        return { schema: JSON.parse(readFileSync(schemaPath, 'utf8')) };
+    });
+    // Helper: Extract GitHub repo URL from various sources
+    function extractGithubRepo(pkg) {
+        let repo = pkg.repository?.url ?? pkg.repository ?? pkg.homepage ?? pkg.links?.repository ?? '';
+        if (typeof repo !== 'string')
+            return null;
+        // Normalize common npm package repository URL forms:
+        // - git+https://github.com/owner/repo.git
+        // - https://github.com/owner/repo
+        // - github:owner/repo
+        // - git@github.com:owner/repo.git
+        repo = repo
+            .trim()
+            .replace(/^github:/, 'https://github.com/')
+            .replace(/^git\+/, '')
+            .replace(/^git@github\.com:/, 'https://github.com/');
+        const match = repo.match(/github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?(?:[/?#].*)?$/);
+        return match ? `${match[1]}/${match[2]}` : null;
+    }
+    function parseCompactGithubCount(raw) {
+        const text = raw.trim().toLowerCase().replace(/,/g, '');
+        const m = text.match(/([0-9]*\.?[0-9]+)\s*([km])?/);
+        if (!m)
+            return undefined;
+        const value = Number(m[1]);
+        if (Number.isNaN(value))
+            return undefined;
+        if (m[2] === 'k')
+            return Math.round(value * 1000);
+        if (m[2] === 'm')
+            return Math.round(value * 1_000_000);
+        return Math.round(value);
+    }
+    // Enriched marketplace metadata endpoint
+    // Fetches npm download stats, GitHub stars, sponsors, and README
+    app.get('/api/marketplace/enriched/:name', async (req) => {
+        const { name } = req.params;
+        try {
+            // Start with basic package info from npm registry
+            const npmRes = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}`, {
+                signal: AbortSignal.timeout(5000),
+                headers: { Accept: 'application/json' },
+            });
+            if (!npmRes.ok)
+                return { name };
+            const npmData = (await npmRes.json());
+            const latestVersion = npmData['dist-tags']?.latest ?? npmData.version;
+            const packData = npmData.versions?.[latestVersion] ?? {};
+            // Fetch npm download stats
+            let weeklyDownloads;
+            try {
+                const statsRes = await fetch(`https://api.npmjs.org/downloads/point/last-week/${encodeURIComponent(name)}`, {
+                    signal: AbortSignal.timeout(3000),
+                    headers: { Accept: 'application/json' },
+                });
+                if (statsRes.ok) {
+                    const stats = (await statsRes.json());
+                    weeklyDownloads = stats.downloads;
+                }
+            }
+            catch {
+                /* stats not available */
+            }
+            // Extract GitHub repo and fetch stars + sponsors
+            const githubRepo = extractGithubRepo(packData);
+            let githubStars;
+            let githubSponsorsUrl;
+            if (githubRepo) {
+                const owner = githubRepo.split('/')[0];
+                if (owner) {
+                    // Keep sponsor link available even when GitHub API rate limits.
+                    githubSponsorsUrl = `https://github.com/sponsors/${owner}`;
+                }
+                try {
+                    const ghRes = await fetch(`https://api.github.com/repos/${githubRepo}`, {
+                        signal: AbortSignal.timeout(5000),
+                        headers: { Accept: 'application/json', 'User-Agent': 'OpenBridge' },
+                    });
+                    if (ghRes.ok) {
+                        const ghData = (await ghRes.json());
+                        githubStars = ghData.stargazers_count;
+                    }
+                }
+                catch {
+                    /* GitHub API not available */
+                }
+                // Fallback: scrape stars from repo page when API is unavailable/rate-limited.
+                if (githubStars == null) {
+                    try {
+                        const htmlRes = await fetch(`https://github.com/${githubRepo}`, {
+                            signal: AbortSignal.timeout(5000),
+                            headers: { 'User-Agent': 'OpenBridge' },
+                        });
+                        if (htmlRes.ok) {
+                            const html = await htmlRes.text();
+                            const starBlock = html.match(new RegExp(`href="/${githubRepo}/stargazers"[^>]*>\\s*([\\s\\S]*?)<\\/a>`, 'i'))?.[1] ?? '';
+                            const starText = starBlock
+                                .replace(/<[^>]*>/g, ' ')
+                                .replace(/\s+/g, ' ')
+                                .trim();
+                            githubStars = parseCompactGithubCount(starText);
+                        }
+                    }
+                    catch {
+                        /* HTML fallback unavailable */
+                    }
+                }
+            }
+            // Try to fetch README
+            let readme;
+            let badges;
+            if (githubRepo) {
+                try {
+                    const readmeRes = await fetch(`https://raw.githubusercontent.com/${githubRepo}/HEAD/README.md`, {
+                        signal: AbortSignal.timeout(3000),
+                    });
+                    if (readmeRes.ok) {
+                        const content = await readmeRes.text();
+                        readme = content;
+                        // Extract badge markdown links: ![...](...)
+                        const badgeMatches = content.match(/!\[.*?\]\(.*?\)/g) ?? [];
+                        badges = badgeMatches.slice(0, 5); // Limit to first 5 badges
+                    }
+                }
+                catch {
+                    /* README not available */
+                }
+            }
+            // Extract documentation URL from package.json
+            let documentationUrl;
+            if (packData.homepage)
+                documentationUrl = packData.homepage;
+            else if (packData.repository?.url) {
+                const match = packData.repository.url.match(/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+                if (match)
+                    documentationUrl = `https://github.com/${match[1]}/${match[2]}`;
+            }
+            const enrichedPayload = {
+                name,
+                version: latestVersion,
+                description: packData.description ?? npmData.description,
+                author: packData.author,
+                links: packData.links ?? {
+                    npm: `https://www.npmjs.com/package/${name}`,
+                    repository: githubRepo ? `https://github.com/${githubRepo}` : undefined,
+                    homepage: packData.homepage,
+                },
+                date: npmData.time?.[latestVersion] ?? new Date().toISOString(),
+                weeklyDownloads,
+                githubStars,
+                githubSponsorsUrl,
+                documentationUrl,
+                badges,
+                readme,
+            };
+            // Persist metadata so plugins page can reuse it across route changes/reloads.
+            try {
+                const cache = loadMetadataCache();
+                cache[name] = enrichedPayload;
+                saveMetadataCache(cache);
+            }
+            catch {
+                /* ignore cache save errors */
+            }
+            return enrichedPayload;
+        }
+        catch (err) {
+            log.debug(`Failed to enrich metadata for ${name}: ${err}`);
+            return { name };
+        }
+    });
+    // ─── Interactive shell WebSocket (PTY) ───────────────────────────────────
+    // node-pty is an optional dependency: it only powers the interactive shell pane.
+    // Everything else (HAP bridge, plugins, API, logs) works without it.
+    try {
+        const nodePtyDir = resolve(dirname(_req.resolve('node-pty')), '..');
+        // Ensure node-pty's spawn-helper has execute permission (pnpm doesn't preserve +x on prebuilds)
+        const arch = `${process.platform}-${process.arch}`;
+        const spawnHelper = join(nodePtyDir, 'prebuilds', arch, 'spawn-helper');
+        if (existsSync(spawnHelper))
+            chmodSync(spawnHelper, 0o755);
+        shellAvailable = true;
+    }
+    catch {
+        log.info('node-pty is not installed: the interactive shell pane is disabled. Everything else runs normally.');
+    }
+    app.get('/ws/shell', { websocket: true }, (connection) => {
+        const ws = connection.socket;
+        let pty = null;
+        if (!shellAvailable) {
+            ws.send(`\r\n\x1b[33mInteractive shell unavailable: the optional 'node-pty' dependency is not installed.\x1b[0m\r\n` +
+                `\x1b[2mInstall it to enable this pane, e.g. 'npm i -g node-pty'. All other OpenBridge features are unaffected.\x1b[0m\r\n`);
+            ws.close();
+            return;
+        }
+        try {
+            const nodePty = _req('node-pty');
+            const shell = process.env.SHELL || (process.platform === 'win32' ? 'cmd.exe' : '/bin/sh');
+            pty = nodePty.spawn(shell, [], {
+                name: 'xterm-256color',
+                cols: 80,
+                rows: 24,
+                cwd: process.env.HOME ?? process.cwd(),
+                env: { ...process.env },
+            });
+            pty.onData((data) => {
+                if (ws.readyState === ws.OPEN)
+                    ws.send(data);
+            });
+            pty.onExit(() => {
+                if (ws.readyState === ws.OPEN)
+                    ws.close();
+            });
+        }
+        catch (err) {
+            ws.send(`\r\n\x1b[31mFailed to start shell: ${err}\x1b[0m\r\n`);
+            ws.close();
+            return;
+        }
+        ws.on('message', (raw) => {
+            try {
+                const msg = JSON.parse(raw.toString());
+                if (msg.type === 'input')
+                    pty?.write(msg.data);
+                if (msg.type === 'resize')
+                    pty?.resize(Number(msg.cols), Number(msg.rows));
+            }
+            catch {
+                // plain string input fallback
+                pty?.write(raw.toString());
+            }
+        });
+        ws.on('close', () => {
+            try {
+                pty?.kill();
+            }
+            catch {
+                /* ignore */
+            }
+        });
+    });
+    // Terminal WebSocket: streams ANSI-formatted log lines for xterm.js
+    app.get('/ws/terminal', { websocket: true }, (connection) => {
+        const ws = connection.socket;
+        function ansiLine(entry) {
+            const ANSI = {
+                debug: '\x1b[90m',
+                info: '\x1b[36m',
+                warn: '\x1b[33m',
+                error: '\x1b[31m',
+            };
+            const reset = '\x1b[0m';
+            const dim = '\x1b[2m';
+            const time = new Date(entry.timestamp).toLocaleTimeString();
+            const level = entry.level.toUpperCase().padEnd(5);
+            const plugin = entry.plugin !== 'system' ? `\x1b[35m[${entry.plugin}]${reset} ` : '';
+            return `${dim}${time}${reset} ${ANSI[entry.level] ?? ''}${level}${reset} ${plugin}${entry.message}\r\n`;
+        }
+        // Replay recent history
+        const history = Logger.getEntries(undefined, 500);
+        for (const entry of history) {
+            if (ws.readyState === ws.OPEN)
+                ws.send(ansiLine(entry));
+        }
+        const unsubscribe = Logger.subscribe((entry) => {
+            if (ws.readyState === ws.OPEN)
+                ws.send(ansiLine(entry));
+        });
+        ws.on('close', unsubscribe);
+    });
+    // ─── Serve built UI ───────────────────────────────────────────────────────
+    if (uiAvailable) {
+        await app.register(fastifyStatic, { root: uiDist, wildcard: false });
+        app.setNotFoundHandler(async (_req, reply) => reply.sendFile('index.html'));
+        log.info(`Serving UI from ${uiDist}`);
+    }
+    else {
+        app.get('/', async () => ({
+            name: 'OpenBridge Daemon',
+            version: OPENBRIDGE_VERSION,
+            ui: 'not built: run: cd apps/ui && pnpm build',
+        }));
+    }
+    return app;
+}
+//# sourceMappingURL=server.js.map