@camstack/server 1.0.0 → 1.0.1

package/{src/core/addon/addon-row-manifest.ts → dist/core/addon/addon-row-manifest.js}

@@ -1,3 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.overlayDeclaration = overlayDeclaration;
 /**
  * Overlay the fresh on-disk `declaration` onto a live addon instance's
  * `manifest` when building the rows returned by `listAddons()`.
@@ -21,9 +24,6 @@
  * values), so the spread overlays only the keys the declaration actually
  * defines; the instance manifest fills any gaps.
  */
-export function overlayDeclaration<M extends object>(
-  instanceManifest: M,
-  declaration: Partial<M> | undefined,
-): M {
-  return { ...instanceManifest, ...declaration }
+function overlayDeclaration(instanceManifest, declaration) {
+    return { ...instanceManifest, ...declaration };
 }

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

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddonSearchService = void 0;
+const types_1 = require("@camstack/types");
+class AddonSearchService {
+    loggingService;
+    cache = null;
+    CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+    constructor(loggingService) {
+        this.loggingService = loggingService;
+    }
+    async searchAddons(query) {
+        const npmResults = await this.fetchFromNpm();
+        // Filter by additional query if provided
+        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 without install status — the caller can merge with installed list
+        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 this
+            installedVersion: undefined,
+        }));
+    }
+    async fetchFromNpm() {
+        // Return from cache if still fresh
+        if (this.cache && Date.now() - this.cache.timestamp < this.CACHE_TTL_MS) {
+            return this.cache.results;
+        }
+        // npm registry v1 search: packages with BOTH "camstack" and "addon" keywords
+        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(10000),
+            });
+            if (!response.ok) {
+                throw new Error(`npm search failed: ${response.status}`);
+            }
+            const data = (await response.json());
+            const results = data.objects.map((o) => o.package);
+            this.cache = { results, timestamp: Date.now() };
+            return results;
+        }
+        catch (err) {
+            const logger = this.loggingService.createLogger('addon-search');
+            logger.warn('npm search failed', { meta: { error: (0, types_1.errMsg)(err) } });
+            // Stale cache is better than nothing on transient network failure
+            return this.cache?.results ?? [];
+        }
+    }
+}
+exports.AddonSearchService = AddonSearchService;

package/dist/core/addon/addon-settings-provider.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAddonSettingsProvider = createAddonSettingsProvider;
+function reshapeForOutput(schema) {
+    return {
+        tabs: schema.tabs
+            ? schema.tabs.map((t) => ({ id: t.id, label: t.label, icon: t.icon, order: t.order }))
+            : undefined,
+        sections: schema.sections.map((s) => ({
+            id: s.id,
+            title: s.title,
+            description: s.description,
+            style: s.style,
+            defaultCollapsed: s.defaultCollapsed,
+            columns: s.columns,
+            tab: s.tab,
+            order: s.order,
+            fields: [...s.fields],
+        })),
+    };
+}
+/**
+ * True for Moleculer's `ServiceNotFoundError` — raised when a
+ * `<addonId>.settings.*` action is called before the owning forked
+ * addon has registered its service (still booting, or wedged in
+ * `onInitialize`). Matched by `name` so we don't depend on Moleculer's
+ * error class being importable here.
+ */
+function isServiceNotFoundError(err) {
+    return err instanceof Error && err.name === 'ServiceNotFoundError';
+}
+function createAddonSettingsProvider(deps) {
+    const { getAddon, gateway } = deps;
+    // Forked READ — route through the shared gateway (UDS hub-local-child OR
+    // Moleculer remote agent). Degrades to null when the forked addon can't
+    // answer yet (mid-boot / missing service) so the panel shows its empty state
+    // instead of bubbling a 500.
+    async function forkedGet(addonId, method, args, nodeId) {
+        try {
+            const result = await gateway.callForked(addonId, { target: 'settings', method, args }, nodeId);
+            return result ? reshapeForOutput(result) : null;
+        }
+        catch (err) {
+            if (isServiceNotFoundError(err))
+                return null;
+            throw err;
+        }
+    }
+    // Forked UPDATE — route through the shared gateway; returns the ack.
+    async function forkedUpdate(addonId, method, args, nodeId) {
+        await gateway.callForked(addonId, { target: 'settings', method, args }, nodeId);
+        return { success: true };
+    }
+    // ── Provider implementation ──────────────────────────────────────
+    return {
+        async getGlobalSettings(input) {
+            if (gateway.isInProcess(input.addonId, input.nodeId)) {
+                const addon = getAddon(input.addonId);
+                if (!addon || typeof addon.getGlobalSettings !== 'function')
+                    return null;
+                const result = await addon.getGlobalSettings(input.overlay, input.cap);
+                return result ? reshapeForOutput(result) : null;
+            }
+            return forkedGet(input.addonId, 'getGlobalSettings', {
+                ...(input.overlay ? { overlay: input.overlay } : {}),
+                ...(input.cap ? { cap: input.cap } : {}),
+            }, input.nodeId);
+        },
+        async updateGlobalSettings(input) {
+            if (gateway.isInProcess(input.addonId, input.nodeId)) {
+                const addon = getAddon(input.addonId);
+                if (!addon || typeof addon.updateGlobalSettings !== 'function') {
+                    throw new Error(`Addon "${input.addonId}" does not implement updateGlobalSettings`);
+                }
+                await addon.updateGlobalSettings(input.patch);
+                return { success: true };
+            }
+            return forkedUpdate(input.addonId, 'updateGlobalSettings', { patch: input.patch }, input.nodeId);
+        },
+        async getDeviceSettings(input) {
+            if (gateway.isInProcess(input.addonId, input.nodeId)) {
+                const addon = getAddon(input.addonId);
+                if (!addon || typeof addon.getDeviceSettings !== 'function')
+                    return null;
+                const result = await addon.getDeviceSettings(input.deviceId);
+                return result ? reshapeForOutput(result) : null;
+            }
+            return forkedGet(input.addonId, 'getDeviceSettings', { deviceId: input.deviceId }, input.nodeId);
+        },
+        async updateDeviceSettings(input) {
+            if (gateway.isInProcess(input.addonId, input.nodeId)) {
+                const addon = getAddon(input.addonId);
+                if (!addon || typeof addon.updateDeviceSettings !== 'function') {
+                    throw new Error(`Addon "${input.addonId}" does not implement updateDeviceSettings`);
+                }
+                await addon.updateDeviceSettings(input.deviceId, input.patch);
+                return { success: true };
+            }
+            return forkedUpdate(input.addonId, 'updateDeviceSettings', { deviceId: input.deviceId, patch: input.patch }, input.nodeId);
+        },
+    };
+}

package/dist/core/addon/addon.tokens.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_ADDONS = exports.ADDON_REGISTRY = void 0;
+exports.ADDON_REGISTRY = Symbol('ADDON_REGISTRY');
+exports.BUILTIN_ADDONS = Symbol('BUILTIN_ADDONS');

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

@@ -0,0 +1,145 @@
+"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.AddonBridgeService = void 0;
+const path = __importStar(require("node:path"));
+const types_1 = require("@camstack/types");
+/**
+ * AddonBridgeService — slim package-management surface.
+ *
+ * Historically this service also cached per-camera pipeline configs + per-
+ * addon config records + hosted an in-process `PipelineRunner` that consumers
+ * called via `processFrame` / `processMotionFrame`. Every piece of that
+ * plumbing was dead post commit 2c (the runtime scheduler moved to
+ * `addon-pipeline-runner`) and the pipeline page redesign finishes the job
+ * by deleting the cache, the AddonEngineManager wiring, the bridge-pipeline
+ * tRPC router, and the PipelineWiringModule that bolted the legacy addon
+ * resolver onto this service.
+ *
+ * What's left is ONLY the addon package management surface: the installer
+ * + the loader + `reloadPackages` + `listAvailableAddons`. These are still
+ * used by:
+ *  - `server/backend/src/api/addon-upload.ts` (multipart upload → install
+ *    → loader reload)
+ *  - `server/backend/src/api/bridge-addons.router.ts` (install/uninstall
+ *    package lifecycle, addon list via the loader)
+ */
+class AddonBridgeService {
+    loggingService;
+    logger;
+    loader;
+    installer = null;
+    /** Whether the bridge initialised successfully */
+    available = false;
+    constructor(loggingService) {
+        this.loggingService = loggingService;
+        this.logger = this.loggingService.createLogger('AddonBridge');
+        // Initialize installer eagerly in constructor (no async needed).
+        // This ensures install/uninstall works even before onModuleInit completes.
+        try {
+            const kernel = require('@camstack/kernel');
+            const dataDir = process.env.CAMSTACK_DATA ?? 'camstack-data';
+            const addonsDir = path.resolve(dataDir, 'addons');
+            const workspacePackagesDir = kernel.detectWorkspacePackagesDir(__dirname);
+            this.installer = new kernel.AddonInstaller({
+                addonsDir,
+                workspacePackagesDir: workspacePackagesDir ?? undefined,
+            });
+            kernel.ensureDir(addonsDir);
+        }
+        catch (error) {
+            const msg = (0, types_1.errMsg)(error);
+            this.logger.warn('Installer init failed', { meta: { error: msg } });
+        }
+    }
+    async onModuleInit() {
+        this.logger.info('Initializing addon bridge (package management only)...');
+        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.available = true;
+            this.logger.info('Addon bridge initialized', {
+                meta: { count: this.loader.listAddons().length },
+            });
+        }
+        catch (error) {
+            const msg = (0, types_1.errMsg)(error);
+            this.logger.warn('Addon bridge loader failed — install/uninstall still available', {
+                meta: { error: msg },
+            });
+        }
+    }
+    async onModuleDestroy() {
+        this.logger.info('Addon bridge shut down');
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /** Whether the bridge is ready for use */
+    isAvailable() {
+        return this.available;
+    }
+    /** Return the underlying AddonLoader (for querying / introspection) */
+    getLoader() {
+        return this.loader;
+    }
+    /** List IDs of all successfully loaded addons */
+    listAvailableAddons() {
+        if (!this.available)
+            return [];
+        return this.loader.listAddons().map((a) => a.declaration.id);
+    }
+    /** Return the AddonInstaller instance (may be null if bridge failed to init) */
+    getInstaller() {
+        return this.installer;
+    }
+    /** Re-discover addons from the addons directory (call after install/uninstall) */
+    async reloadPackages() {
+        if (!this.available) {
+            this.logger.warn('reloadPackages called but bridge is unavailable — skipping');
+            return;
+        }
+        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 } });
+    }
+}
+exports.AddonBridgeService = AddonBridgeService;

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

@@ -0,0 +1,107 @@
+"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.AddonPagesService = void 0;
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+/**
+ * AddonPagesService — server-side helper that backs the static file
+ * route `/api/addon-pages/:addonId/*` (registered in `main.ts`).
+ *
+ * The public listing surface (`addonPages.listPages` on the AppRouter)
+ * has been split out of this class — it now lives in the
+ * `addon-pages-aggregator` builtin (`@camstack/core/builtins/...`)
+ * which walks every `addon-pages-source` collection provider and
+ * stamps versioned `bundleUrl`s. The split lets both ends flow through
+ * codegen instead of relying on a hand-written wrapper.
+ *
+ * What stays here: filesystem path resolution + traversal protection
+ * for the static file route. Both rely on `CapabilityService` to
+ * enumerate registered page providers (so unknown / unregistered
+ * addons can't be probed via path traversal tricks) and on
+ * `ConfigService` to locate the addons directory.
+ */
+class AddonPagesService {
+    loggingService;
+    configService;
+    caps;
+    logger;
+    constructor(loggingService, configService, caps) {
+        this.loggingService = loggingService;
+        this.configService = configService;
+        this.caps = caps;
+        this.logger = this.loggingService.createLogger('AddonPagesService');
+    }
+    /**
+     * Resolve the filesystem path to an addon's page bundle file.
+     * Returns null if the addon is not registered, the file doesn't exist,
+     * or the path would escape the addon directory (path traversal protection).
+     */
+    resolveBundle(addonId, filePath) {
+        // Check if the addon is a registered page provider via the
+        // collection cap. `addon-pages-source` is the new home for the raw
+        // per-provider declarations (the public `addon-pages` cap is the
+        // aggregated singleton — different shape, different surface).
+        const providers = this.caps.getCollection('addon-pages-source');
+        const isRegistered = providers.some((p) => p.id === addonId);
+        if (!isRegistered) {
+            this.logger.warn('Bundle resolve failed: addon not registered as page provider', {
+                tags: { addonId },
+            });
+            return null;
+        }
+        const addonsDir = this.resolveAddonsDir();
+        // Addon packages are at addons/@camstack/addon-<id>/dist/
+        const addonDistPath = path.join(addonsDir, '@camstack', `addon-${addonId}`, 'dist');
+        const resolvedBase = path.resolve(addonDistPath);
+        const resolvedFile = path.resolve(addonDistPath, filePath);
+        // Path traversal protection
+        if (!resolvedFile.startsWith(resolvedBase + path.sep) && resolvedFile !== resolvedBase) {
+            this.logger.warn('Path traversal denied for addon', { tags: { addonId }, meta: { filePath } });
+            return null;
+        }
+        if (!fs.existsSync(resolvedFile)) {
+            this.logger.debug('Bundle file not found', { meta: { resolvedFile } });
+            return null;
+        }
+        return resolvedFile;
+    }
+    /** Resolve the addons directory from config */
+    resolveAddonsDir() {
+        const dataPath = this.configService.get('server.dataPath') ?? 'camstack-data';
+        return path.resolve(dataPath, 'addons');
+    }
+}
+exports.AddonPagesService = AddonPagesService;

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

@@ -0,0 +1,120 @@
+"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.AddonWidgetsService = void 0;
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+/**
+ * Strip the `@<nodeId>` suffix the CapabilityBridge appends to
+ * collection-provider registry keys for cross-node addons. The widget
+ * static-file route always receives the bare manifest id.
+ */
+function stripNodeSuffix(registryKey) {
+    const at = registryKey.indexOf('@');
+    return at === -1 ? registryKey : registryKey.slice(0, at);
+}
+/**
+ * AddonWidgetsService — server-side helper that backs the static file
+ * route `/api/addon-widgets/:addonId/*` (registered in `main.ts`).
+ *
+ * Mirrors `AddonPagesService` exactly. The public listing surface
+ * (`addonWidgets.listWidgets` on the AppRouter) lives in the
+ * `addon-widgets-aggregator` builtin which walks every
+ * `addon-widgets-source` collection provider and stamps versioned
+ * `bundleUrl`s. Both ends flow through codegen.
+ *
+ * What stays here: filesystem path resolution + traversal protection
+ * for the static file route. The registered-provider check uses
+ * `CapabilityService` (so unknown / unregistered addons can't be
+ * probed via path traversal tricks); the on-disk path comes from
+ * `AddonRegistryService.getAddonInstallPath()` so bundled addons
+ * (where one npm package ships multiple addon entries under
+ * `dist/<entryId>/`) resolve to the right sub-folder instead of the
+ * pre-bundle `addons/@camstack/addon-<id>/dist/` layout.
+ */
+class AddonWidgetsService {
+    loggingService;
+    caps;
+    registry;
+    logger;
+    constructor(loggingService, caps, registry) {
+        this.loggingService = loggingService;
+        this.caps = caps;
+        this.registry = registry;
+        this.logger = this.loggingService.createLogger('AddonWidgetsService');
+    }
+    /**
+     * Resolve the filesystem path to an addon's widget bundle file.
+     * Returns null if the addon is not registered, the file doesn't exist,
+     * or the path would escape the addon directory (path traversal protection).
+     */
+    resolveBundle(addonId, filePath) {
+        // The collection cap doesn't carry an `id` on its provider, so we
+        // attribute via `getCollectionEntries` (returns `[addonId, provider]`).
+        //
+        // For cross-node addons the CapabilityBridge registers the provider
+        // under a node-qualified key `<addonId>@<nodeId>` (see
+        // `moleculer.service.ts`). The bundle is hub-resident and keyed by
+        // the bare manifest id, so the route always carries the bare
+        // `addonId` — match it against each registry key with the
+        // `@<nodeId>` suffix stripped.
+        const entries = this.caps.getCollectionEntries('addon-widgets-source');
+        const isRegistered = entries.some(([id]) => stripNodeSuffix(id) === addonId);
+        if (!isRegistered) {
+            this.logger.warn('Bundle resolve failed: addon not registered as widget provider', {
+                tags: { addonId },
+            });
+            return null;
+        }
+        const installPath = this.registry.getAddonInstallPath(addonId);
+        if (!installPath) {
+            this.logger.warn('Bundle resolve failed: addon install path not found', { tags: { addonId } });
+            return null;
+        }
+        const resolvedBase = path.resolve(installPath.distDir);
+        const resolvedFile = path.resolve(installPath.distDir, filePath);
+        // Path traversal protection
+        if (!resolvedFile.startsWith(resolvedBase + path.sep) && resolvedFile !== resolvedBase) {
+            this.logger.warn('Path traversal denied for addon', { tags: { addonId }, meta: { filePath } });
+            return null;
+        }
+        if (!fs.existsSync(resolvedFile)) {
+            this.logger.debug('Bundle file not found', { meta: { resolvedFile } });
+            return null;
+        }
+        return resolvedFile;
+    }
+}
+exports.AddonWidgetsService = AddonWidgetsService;