@camstack/server 1.0.0 → 1.0.1

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

@@ -1,91 +0,0 @@
-import { LoggingService } from '../logging/logging.service'
-import { errMsg } from '@camstack/types'
-
-interface NpmSearchResult {
-  name: string
-  version: string
-  description: string
-  keywords: string[]
-  date: string
-  publisher: { username: string }
-}
-
-interface AddonSearchResult {
-  name: string
-  version: string
-  description: string
-  keywords: string[]
-  publishedAt: string
-  author: string
-  installed: boolean
-  installedVersion?: string
-}
-
-export class AddonSearchService {
-  private cache: { results: NpmSearchResult[]; timestamp: number } | null = null
-  private readonly CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
-
-  constructor(private readonly loggingService: LoggingService) {}
-
-  async searchAddons(query?: string): Promise<AddonSearchResult[]> {
-    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,
-    }))
-  }
-
-  private async fetchFromNpm(): Promise<NpmSearchResult[]> {
-    // 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()) as { objects: Array<{ package: NpmSearchResult }> }
-      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: errMsg(err) } })
-      // Stale cache is better than nothing on transient network failure
-      return this.cache?.results ?? []
-    }
-  }
-}

package/src/core/addon/addon-settings-provider.ts

@@ -1,220 +0,0 @@
-/**
- * Hub-side singleton provider for the `addon-settings` capability.
- *
- * Resolves `addonId` and delegates the settings call. In-process hub builtins
- * are called directly; every FORKED addon (hub-local child over UDS, or remote
- * agent over Moleculer) routes through the shared {@link AddonCallGateway} —
- * the SAME centralised router routes/custom-actions use. Settings used to live
- * on its own Moleculer-only path here, which is why forked hub-local addons'
- * panels went empty after the UDS migration; that path is gone.
- */
-import type { ICamstackAddon, ConfigUISchemaWithValues } from '@camstack/types'
-import type { IAddonSettingsProvider } from '@camstack/types'
-import type { AddonSettingsMethod } from '@camstack/kernel'
-import type { AddonCallGateway } from './addon-call-gateway.js'
-
-// ── Dependency interfaces ────────────────────────────────────────────
-
-/** Resolve an addon by id. Returns null if not loaded on this node. */
-type AddonLookup = (addonId: string) => ICamstackAddon | null
-
-// ── Input types (match the cap definition's z.infer) ─────────────────
-
-interface AddonIdInput {
-  readonly addonId: string
-  readonly nodeId?: string
-  readonly overlay?: Record<string, unknown>
-  readonly cap?: string
-}
-
-interface AddonPatchInput {
-  readonly addonId: string
-  readonly nodeId?: string
-  readonly patch: Record<string, unknown>
-}
-
-interface DeviceGetInput {
-  readonly addonId: string
-  readonly deviceId: number
-  readonly nodeId?: string
-}
-
-interface DeviceUpdateInput {
-  readonly addonId: string
-  readonly deviceId: number
-  readonly nodeId?: string
-  readonly patch: Record<string, unknown>
-}
-
-interface SettingsUpdateResult {
-  readonly success: true
-}
-
-// ── Reshape helper ───────────────────────────────────────────────────
-
-/**
- * Deep-copy a `ConfigUISchemaWithValues` into mutable-array shape for
- * Zod output. The domain type uses `readonly` arrays; Zod's inferred
- * output uses mutable arrays. Structurally identical at runtime.
- */
-interface ReshapedSchema {
-  tabs?: Array<{ id: string; label: string; icon: string; order?: number }>
-  sections: Array<{
-    id: string
-    title: string
-    description?: string
-    style?: 'card' | 'accordion'
-    defaultCollapsed?: boolean
-    columns?: 1 | 2 | 3 | 4
-    tab?: string
-    order?: number
-    fields: unknown[]
-  }>
-}
-
-function reshapeForOutput(schema: ConfigUISchemaWithValues): ReshapedSchema {
-  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: unknown): boolean {
-  return err instanceof Error && err.name === 'ServiceNotFoundError'
-}
-
-// ── Provider factory ─────────────────────────────────────────────────
-
-interface AddonSettingsProviderDeps {
-  /** Look up a loaded IN-PROCESS addon by id (the `@camstack/core` builtins). */
-  readonly getAddon: AddonLookup
-  /** Shared router for forked addon-level calls (hub-local-child / remote). */
-  readonly gateway: AddonCallGateway
-}
-
-function createAddonSettingsProvider(deps: AddonSettingsProviderDeps): IAddonSettingsProvider {
-  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: string,
-    method: AddonSettingsMethod,
-    args: Record<string, unknown>,
-    nodeId?: string,
-  ): Promise<ReshapedSchema | null> {
-    try {
-      const result = await gateway.callForked(addonId, { target: 'settings', method, args }, nodeId)
-      return result ? reshapeForOutput(result as ConfigUISchemaWithValues) : null
-    } catch (err) {
-      if (isServiceNotFoundError(err)) return null
-      throw err
-    }
-  }
-
-  // Forked UPDATE — route through the shared gateway; returns the ack.
-  async function forkedUpdate(
-    addonId: string,
-    method: AddonSettingsMethod,
-    args: Record<string, unknown>,
-    nodeId?: string,
-  ): Promise<SettingsUpdateResult> {
-    await gateway.callForked(addonId, { target: 'settings', method, args }, nodeId)
-    return { success: true as const }
-  }
-
-  // ── Provider implementation ──────────────────────────────────────
-
-  return {
-    async getGlobalSettings(input: AddonIdInput) {
-      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: AddonPatchInput) {
-      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 as const }
-      }
-      return forkedUpdate(
-        input.addonId,
-        'updateGlobalSettings',
-        { patch: input.patch },
-        input.nodeId,
-      )
-    },
-
-    async getDeviceSettings(input: DeviceGetInput) {
-      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: DeviceUpdateInput) {
-      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 as const }
-      }
-      return forkedUpdate(
-        input.addonId,
-        'updateDeviceSettings',
-        { deviceId: input.deviceId, patch: input.patch },
-        input.nodeId,
-      )
-    },
-  }
-}
-
-export { createAddonSettingsProvider }
-export type { AddonSettingsProviderDeps }

package/src/core/addon/addon.tokens.ts

@@ -1,2 +0,0 @@
-export const ADDON_REGISTRY = Symbol('ADDON_REGISTRY')
-export const BUILTIN_ADDONS = Symbol('BUILTIN_ADDONS')

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

@@ -1,130 +0,0 @@
-import * as path from 'node:path'
-import { LoggingService } from '../logging/logging.service'
-import type { IScopedLogger } from '@camstack/types'
-import { errMsg } from '@camstack/types'
-
-// Dynamically imported to tolerate missing / unbuilt packages at startup
-type AddonLoader = import('@camstack/kernel').AddonLoader
-type AddonInstaller = import('@camstack/kernel').AddonInstaller
-type RegisteredAddon = import('@camstack/kernel').RegisteredAddon
-
-/**
- * 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)
- */
-export class AddonBridgeService {
-  private readonly logger: IScopedLogger
-
-  private loader!: AddonLoader
-  private installer: AddonInstaller | null = null
-
-  /** Whether the bridge initialised successfully */
-  private available = false
-
-  constructor(private readonly 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') as typeof import('@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: unknown) {
-      const msg = errMsg(error)
-      this.logger.warn('Installer init failed', { meta: { error: msg } })
-    }
-  }
-
-  async onModuleInit(): Promise<void> {
-    this.logger.info('Initializing addon bridge (package management only)...')
-
-    try {
-      const kernel = await import('@camstack/kernel')
-
-      this.loader = new kernel.AddonLoader(this.logger.child('AddonLoader'))
-
-      const dataDir = process.env.CAMSTACK_DATA ?? 'camstack-data'
-      const addonsDir = path.resolve(dataDir, 'addons')
-      await this.loader.loadFromDirectory(addonsDir)
-
-      this.available = true
-      this.logger.info('Addon bridge initialized', {
-        meta: { count: this.loader.listAddons().length },
-      })
-    } catch (error: unknown) {
-      const msg = errMsg(error)
-      this.logger.warn('Addon bridge loader failed — install/uninstall still available', {
-        meta: { error: msg },
-      })
-    }
-  }
-
-  async onModuleDestroy(): Promise<void> {
-    this.logger.info('Addon bridge shut down')
-  }
-
-  // ---------------------------------------------------------------------------
-  // Public API
-  // ---------------------------------------------------------------------------
-
-  /** Whether the bridge is ready for use */
-  isAvailable(): boolean {
-    return this.available
-  }
-
-  /** Return the underlying AddonLoader (for querying / introspection) */
-  getLoader(): AddonLoader {
-    return this.loader
-  }
-
-  /** List IDs of all successfully loaded addons */
-  listAvailableAddons(): string[] {
-    if (!this.available) return []
-    return this.loader.listAddons().map((a: RegisteredAddon) => a.declaration.id)
-  }
-
-  /** Return the AddonInstaller instance (may be null if bridge failed to init) */
-  getInstaller(): AddonInstaller | null {
-    return this.installer
-  }
-
-  /** Re-discover addons from the addons directory (call after install/uninstall) */
-  async reloadPackages(): Promise<void> {
-    if (!this.available) {
-      this.logger.warn('reloadPackages called but bridge is unavailable — skipping')
-      return
-    }
-
-    const kernel = await import('@camstack/kernel')
-    this.loader = new kernel.AddonLoader(this.logger.child('AddonLoader'))
-
-    const dataDir = process.env.CAMSTACK_DATA ?? 'camstack-data'
-    const addonsDir = path.resolve(dataDir, 'addons')
-    await this.loader.loadFromDirectory(addonsDir)
-
-    this.logger.info('Reloaded', { meta: { count: this.loader.listAddons().length } })
-  }
-}

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

@@ -1,117 +0,0 @@
-import { describe, it, expect, vi } from 'vitest'
-
-vi.mock('node:fs', () => ({
-  existsSync: vi.fn(),
-}))
-
-import * as fs from 'node:fs'
-import { AddonPagesService } from './addon-pages.service'
-import type { CapabilityService } from '../capability/capability.service'
-import type { LoggingService } from '../logging/logging.service'
-import type { ConfigService } from '../config/config.service'
-import type { IAddonPageProvider, AddonPageDeclaration, IScopedLogger } from '@camstack/types'
-
-function createMockLogger(): IScopedLogger {
-  return {
-    debug: vi.fn(),
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-    child: vi.fn().mockReturnThis(),
-  }
-}
-
-function createMockLoggingService(): LoggingService {
-  return {
-    createLogger: vi.fn().mockReturnValue(createMockLogger()),
-  } as unknown as LoggingService
-}
-
-function createMockConfigService(): ConfigService {
-  return {
-    get: vi.fn().mockReturnValue('./data'),
-  } as unknown as ConfigService
-}
-
-function createMockPageProvider(
-  id: string,
-  pages: readonly AddonPageDeclaration[],
-): IAddonPageProvider {
-  return {
-    id,
-    listPages: () => pages,
-  }
-}
-
-/**
- * AddonPagesService now resolves bundles via the `addon-pages-source`
- * collection cap (split from the public `addon-pages` singleton cap
- * earlier this session).
- */
-function createMockCapabilityService(providers: IAddonPageProvider[] = []): CapabilityService {
-  return {
-    getSingleton: vi.fn(() => null),
-    getCollection: vi.fn((capability: string) => {
-      if (capability === 'addon-pages-source') return providers
-      return []
-    }),
-    resolveForDevice: vi.fn(() => null),
-    resolveCollectionForDevice: vi.fn(() => []),
-    setRegistry: vi.fn(),
-    getRegistry: vi.fn(() => null),
-  } as unknown as CapabilityService
-}
-
-function buildService(providers: IAddonPageProvider[] = []): AddonPagesService {
-  return new AddonPagesService(
-    createMockLoggingService(),
-    createMockConfigService(),
-    createMockCapabilityService(providers),
-  )
-}
-
-describe('AddonPagesService.resolveBundle', () => {
-  it('should return null for unregistered addon', () => {
-    const service = buildService([])
-    const result = service.resolveBundle('nonexistent', 'dist/pages/main.js')
-    expect(result).toBeNull()
-  })
-
-  it('should return null when file does not exist', () => {
-    const provider = createMockPageProvider('benchmark', [])
-    const service = buildService([provider])
-
-    const existsMock = fs.existsSync as unknown as ReturnType<typeof vi.fn>
-    existsMock.mockReturnValue(false)
-
-    const result = service.resolveBundle('benchmark', 'dist/pages/benchmark.js')
-    expect(result).toBeNull()
-  })
-
-  it('should return resolved path when file exists', () => {
-    const provider = createMockPageProvider('benchmark', [])
-    const service = buildService([provider])
-
-    const existsMock = fs.existsSync as unknown as ReturnType<typeof vi.fn>
-    existsMock.mockReturnValue(true)
-
-    const result = service.resolveBundle('benchmark', 'dist/pages/benchmark.js')
-    expect(result).not.toBeNull()
-    expect(result).toContain('addon-benchmark')
-    expect(result).toContain('dist/pages/benchmark.js')
-  })
-
-  it('should deny path traversal attempts', () => {
-    const provider = createMockPageProvider('benchmark', [])
-    const service = buildService([provider])
-    const result = service.resolveBundle('benchmark', '../../etc/passwd')
-    expect(result).toBeNull()
-  })
-
-  it('should deny absolute path traversal', () => {
-    const provider = createMockPageProvider('benchmark', [])
-    const service = buildService([provider])
-    const result = service.resolveBundle('benchmark', '../../../etc/passwd')
-    expect(result).toBeNull()
-  })
-})

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

@@ -1,82 +0,0 @@
-import * as path from 'node:path'
-import * as fs from 'node:fs'
-import { LoggingService } from '../logging/logging.service'
-import { ConfigService } from '../config/config.service'
-import { CapabilityService } from '../capability/capability.service'
-import type { IScopedLogger } from '@camstack/types'
-import type { IAddonPageProvider } from '@camstack/types'
-
-/**
- * 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.
- */
-export class AddonPagesService {
-  private readonly logger: IScopedLogger
-
-  constructor(
-    private readonly loggingService: LoggingService,
-    private readonly configService: ConfigService,
-    private readonly caps: CapabilityService,
-  ) {
-    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: string, filePath: string): string | null {
-    // 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<IAddonPageProvider>('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 */
-  private resolveAddonsDir(): string {
-    const dataPath = this.configService.get<string>('server.dataPath') ?? 'camstack-data'
-    return path.resolve(dataPath, 'addons')
-  }
-}