@camstack/server 0.2.2 → 1.0.1

package/src/__tests__/device-settings-contribution-dispatch.spec.ts

@@ -1,280 +0,0 @@
-/**
- * device-settings-contribution-dispatch.spec.ts
- *
- * Regression tests for Bug-3: snapshot `getDeviceSettingsContribution` not
- * found on native provider.
- *
- * Root cause: device-manager.addon.ts used `getProviderForDevice` for the
- * three `exposesDeviceSettings` contribution methods. `getProviderForDevice`
- * returns the native first when present (e.g. Reolink/ONVIF); the native
- * only implements camera-specific operations (getSnapshot, invalidateCache),
- * NOT the contribution methods. The cross-process dispatch then throws
- * "native-provider: method 'getDeviceSettingsContribution' not found on
- * 'snapshot'".
- *
- * Fix: device-manager now uses `getProvider(capName)` — the active system
- * singleton (the wrapper, e.g. SnapshotAddon) — for all contribution method
- * calls. The native is never touched for these methods.
- *
- * Spec: docs/superpowers/plans/2026-05-21-addons-bulk-update-progress.md (Bug-3)
- */
-import { describe, it, expect, vi } from 'vitest'
-import { DeviceManagerAddon } from '@camstack/core'
-import { CapabilityRegistry, DeviceRegistry } from '@camstack/kernel'
-import { snapshotCapability } from '@camstack/types'
-import type {
-  AddonContext,
-  ConfigUISchemaWithValues,
-  IScopedLogger,
-  IEventBus,
-  ProviderRegistration,
-  IDeviceManagerProvider,
-} from '@camstack/types'
-
-// ── Fakes ────────────────────────────────────────────────────────────────────
-
-function makeLogger(): IScopedLogger {
-  const l: IScopedLogger = {
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-    debug: vi.fn(),
-    child: vi.fn(() => l),
-    withTags: vi.fn(() => l),
-  }
-  return l
-}
-
-function makeEventBus(): IEventBus {
-  return { emit: vi.fn(), subscribe: () => () => {}, getRecent: () => [] } as unknown as IEventBus
-}
-
-function makeSettings() {
-  return {
-    readAddonStore: vi.fn(async () => ({})),
-    writeAddonStore: vi.fn(async () => {}),
-    readDeviceStore: vi.fn(async () => ({})),
-    writeDeviceStore: vi.fn(async () => {}),
-  }
-}
-
-/**
- * Wrapper provider (SnapshotAddon equivalent): registered as a system
- * singleton via `registerProvider`. Implements ALL three contribution
- * methods plus the cap-specific operations (getSnapshot, invalidateCache).
- */
-function makeSnapshotWrapperProvider() {
-  return {
-    // Cap-specific methods
-    getSnapshot: vi.fn(async () => null),
-    invalidateCache: vi.fn(async () => undefined),
-
-    // Contribution methods — owned by the wrapper
-    getDeviceSettingsContribution: vi.fn(
-      async (_input: { deviceId: number }): Promise<ConfigUISchemaWithValues | null> => ({
-        sections: [
-          {
-            id: 'snapshot-settings',
-            title: 'Snapshot',
-            tab: 'general',
-            order: 99,
-            fields: [
-              {
-                type: 'text' as const,
-                key: 'preferredStreamId',
-                label: 'Preferred Stream',
-                default: '',
-                value: '',
-              },
-            ],
-          },
-        ],
-      }),
-    ),
-    getDeviceLiveContribution: vi.fn(
-      async (_input: { deviceId: number }): Promise<ConfigUISchemaWithValues | null> => null,
-    ),
-    applyDeviceSettingsPatch: vi.fn(async () => ({ success: true as const })),
-  }
-}
-
-/**
- * Native provider (Reolink/ONVIF/Hikvision equivalent): registered per-device
- * via `registerNativeProvider`. Implements ONLY the camera-specific operations
- * (getSnapshot, invalidateCache). Does NOT implement contribution methods.
- *
- * Calling any of the three contribution methods on this object simulates the
- * "method not found" scenario that was Bug-3.
- */
-function makeSnapshotNativeProvider() {
-  return {
-    getSnapshot: vi.fn(async () => ({
-      base64: 'abc123',
-      contentType: 'image/jpeg',
-    })),
-    invalidateCache: vi.fn(async () => undefined),
-    // Deliberately omit getDeviceSettingsContribution / getDeviceLiveContribution /
-    // applyDeviceSettingsPatch — these don't exist on native providers.
-  }
-}
-
-// ── Scenario setup ────────────────────────────────────────────────────────────
-
-async function setupBug3Scenario() {
-  const addon = new DeviceManagerAddon()
-  const settings = makeSettings()
-  const deviceRegistry = new DeviceRegistry()
-  const capabilityRegistry = new CapabilityRegistry(makeLogger())
-
-  const wrapperProvider = makeSnapshotWrapperProvider()
-  const nativeProvider = makeSnapshotNativeProvider()
-
-  // Declare the snapshot capability (kind:'wrapper', defaultActive:true,
-  // exposesDeviceSettings:true, mode:'singleton').
-  capabilityRegistry.declareCapability(snapshotCapability)
-
-  // Register the WRAPPER as the system singleton — this is what SnapshotAddon does.
-  capabilityRegistry.registerProvider(snapshotCapability.name, 'snapshot-addon', wrapperProvider)
-
-  // Register the default wrapper so auto-bind picks it up in getBindings step 2.
-  capabilityRegistry.registerWrapper(snapshotCapability.name, 'snapshot-addon', {
-    defaultActive: true,
-  })
-
-  const ctx = {
-    id: 'device-manager',
-    logger: makeLogger(),
-    eventBus: makeEventBus(),
-    addonConfig: {},
-    dataDir: '/tmp',
-    settings,
-    kernel: { deviceRegistry, capabilityRegistry },
-  }
-
-  const initResult = await addon.initialize(ctx as unknown as AddonContext)
-  let providers: readonly ProviderRegistration[] = []
-  if (Array.isArray(initResult)) {
-    providers = initResult as readonly ProviderRegistration[]
-  } else if (initResult && typeof initResult === 'object' && 'providers' in initResult) {
-    providers = (initResult.providers ?? []) as readonly ProviderRegistration[]
-  }
-  const provider = providers[0]!.provider as IDeviceManagerProvider
-
-  // Allocate and register the device.
-  const { id: deviceId } = await provider.allocateDeviceId({
-    addonId: 'reolink-addon',
-    stableId: 'cam-reolink-1',
-  })
-  await provider.registerDevice({
-    addonId: 'reolink-addon',
-    stableId: 'cam-reolink-1',
-    id: deviceId,
-    type: 'camera',
-    name: 'Reolink Camera',
-    parentDeviceId: null,
-    config: {},
-  })
-
-  // Register the NATIVE provider for the device — this is what a Reolink/ONVIF
-  // driver does. The native does NOT implement contribution methods.
-  capabilityRegistry.registerNativeProvider(
-    snapshotCapability.name,
-    deviceId,
-    'reolink-addon',
-    nativeProvider,
-  )
-
-  capabilityRegistry.ready()
-
-  return { provider, wrapperProvider, nativeProvider, deviceId }
-}
-
-// ── Tests ────────────────────────────────────────────────────────────────────
-
-describe('device-manager contribution dispatch — Bug-3 regression (snapshot wrapper vs native)', () => {
-  it('routes getDeviceSettingsContribution to the wrapper, never to the native', async () => {
-    const { provider, wrapperProvider, nativeProvider, deviceId } = await setupBug3Scenario()
-
-    // This MUST NOT throw "method not found on native" — the fix routes to the wrapper.
-    const aggregate = await provider.getDeviceSettingsAggregate({ deviceId })
-
-    expect(aggregate).not.toBeNull()
-    // The wrapper's contribution section must be present.
-    const snapshotSection = aggregate!.sections.find((s) => s.id === 'snapshot-settings')
-    expect(snapshotSection).toBeDefined()
-    expect(snapshotSection!.title).toBe('Snapshot')
-
-    // Wrapper was called exactly once.
-    expect(wrapperProvider.getDeviceSettingsContribution).toHaveBeenCalledTimes(1)
-    expect(wrapperProvider.getDeviceSettingsContribution).toHaveBeenCalledWith({ deviceId })
-
-    // Native was NOT called — it doesn't implement contribution methods.
-    expect(nativeProvider.getSnapshot).not.toHaveBeenCalled()
-  })
-
-  it('routes getDeviceLiveContribution to the wrapper, never to the native', async () => {
-    const { provider, wrapperProvider, nativeProvider, deviceId } = await setupBug3Scenario()
-
-    // This MUST NOT throw "method not found on native".
-    const liveAggregate = await provider.getDeviceLiveInfoAggregate({ deviceId })
-
-    // The wrapper returns null for live contributions in our fake (acceptable).
-    // Key assertion: the wrapper was invoked, and no error was thrown.
-    expect(wrapperProvider.getDeviceLiveContribution).toHaveBeenCalledTimes(1)
-    expect(wrapperProvider.getDeviceLiveContribution).toHaveBeenCalledWith({ deviceId })
-
-    // Native was NOT called for live contributions.
-    expect(nativeProvider.getSnapshot).not.toHaveBeenCalled()
-    // liveAggregate may be null (wrapper returned null for live) — that's fine.
-    // The important thing is no throw occurred.
-    expect(() => liveAggregate).not.toThrow()
-  })
-
-  it('routes applyDeviceSettingsPatch to the wrapper, never to the native', async () => {
-    const { provider, wrapperProvider, nativeProvider, deviceId } = await setupBug3Scenario()
-
-    // First get the aggregate to confirm the contribution fields are tagged correctly.
-    const aggregate = await provider.getDeviceSettingsAggregate({ deviceId })
-    expect(aggregate).not.toBeNull()
-
-    const field = aggregate!.sections
-      .find((s) => s.id === 'snapshot-settings')
-      ?.fields.find((f) => (f as Record<string, unknown>)['key'] === 'preferredStreamId') as
-      | Record<string, unknown>
-      | undefined
-
-    expect(field).toBeDefined()
-    expect(field!['writerCapName']).toBe('snapshot')
-
-    // Now apply a settings patch — must go to the wrapper, NOT the native.
-    await provider.updateDeviceField({
-      deviceId,
-      writerCapName: 'snapshot',
-      writerAddonId: field!['writerAddonId'] as string,
-      key: 'preferredStreamId',
-      value: 'high',
-    })
-
-    // Wrapper's applyDeviceSettingsPatch was called with the correct patch.
-    expect(wrapperProvider.applyDeviceSettingsPatch).toHaveBeenCalledWith({
-      deviceId,
-      patch: { preferredStreamId: 'high' },
-    })
-
-    // Native was NOT called for the settings write.
-    expect(nativeProvider.getSnapshot).not.toHaveBeenCalled()
-  })
-
-  it('does not throw when both a native and a wrapper provider are registered for the same cap', async () => {
-    // This is the exact Bug-3 scenario: native registered for device, wrapper
-    // registered as system singleton. Before the fix, calling
-    // getDeviceSettingsAggregate would throw because getProviderForDevice
-    // returned the native which lacks contribution methods.
-    const { provider, deviceId } = await setupBug3Scenario()
-
-    // Must complete without throwing.
-    await expect(provider.getDeviceSettingsAggregate({ deviceId })).resolves.not.toBeNull()
-
-    await expect(provider.getDeviceLiveInfoAggregate({ deviceId })).resolves.toBeDefined()
-  })
-})

package/src/__tests__/embedded-deps-e2e.test.ts

@@ -1,125 +0,0 @@
-/**
- * Embedded dependencies E2E — verify ffmpeg/python resolution and download.
- *
- * These tests check the resolution logic (PATH detection, embedded binary check)
- * without actually downloading large binaries (unless CAMSTACK_TEST_DOWNLOAD=true).
- */
-import { describe, it, expect, beforeAll, afterAll } from 'vitest'
-import * as fs from 'node:fs'
-import * as path from 'node:path'
-import * as os from 'node:os'
-// Import directly from source submodules because vitest+swc doesn't resolve
-// `export * from './deps/index.js'` barrel re-exports in the @camstack/core index.
-import {
-  findInPath,
-  getPlatformInfo,
-  buildBinaryPath,
-} from '../../../../packages/core/src/deps/binary-downloader'
-import {
-  getFfmpegDownloadUrl,
-  ensureFfmpeg,
-} from '../../../../packages/core/src/deps/ffmpeg-downloader'
-import {
-  getPythonDownloadUrl,
-  ensurePython,
-} from '../../../../packages/core/src/deps/python-downloader'
-import type { IScopedLogger } from '@camstack/types'
-
-function createMockLogger(): IScopedLogger {
-  const logger: IScopedLogger = {
-    info: () => {},
-    warn: () => {},
-    error: () => {},
-    debug: () => {},
-    child: () => createMockLogger(),
-  }
-  return logger
-}
-
-const mockLogger = createMockLogger()
-
-describe('Embedded Dependencies E2E', () => {
-  let tmpDir: string
-
-  beforeAll(() => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'camstack-deps-e2e-'))
-  })
-
-  afterAll(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true })
-  })
-
-  describe('Platform detection', () => {
-    it('returns valid platform and arch', () => {
-      const info = getPlatformInfo()
-      expect(['darwin', 'linux', 'win32']).toContain(info.platform)
-      expect(['x64', 'arm64', 'arm', 'ia32']).toContain(info.arch)
-    })
-  })
-
-  describe('Binary path resolution', () => {
-    it('builds correct path for deps directory', () => {
-      const p = buildBinaryPath('/data', 'ffmpeg')
-      expect(p).toBe('/data/deps/ffmpeg')
-    })
-  })
-
-  describe('FFmpeg', () => {
-    it('generates valid download URL for current platform', () => {
-      const url = getFfmpegDownloadUrl(process.platform, process.arch)
-      expect(url).toMatch(/^https:\/\//)
-      expect(url.length).toBeGreaterThan(20)
-    })
-
-    it('finds ffmpeg in PATH or reports not found', () => {
-      const result = findInPath('ffmpeg')
-      // Either found (returns the name) or null — both valid
-      expect(result === null || typeof result === 'string').toBe(true)
-    })
-
-    // Only run download test if explicitly enabled (downloads ~80MB)
-    const downloadTest = process.env.CAMSTACK_TEST_DOWNLOAD === 'true' ? it : it.skip
-    downloadTest(
-      'downloads ffmpeg binary',
-      async () => {
-        const ffmpegPath = await ensureFfmpeg(tmpDir, mockLogger)
-        expect(ffmpegPath).toBeTruthy()
-        expect(fs.existsSync(ffmpegPath)).toBe(true)
-      },
-      120000,
-    )
-  })
-
-  describe('Python', () => {
-    it('generates valid download URL for current platform', () => {
-      const url = getPythonDownloadUrl(process.platform, process.arch)
-      expect(url).toContain('python-headless')
-      if (process.platform === 'darwin') {
-        expect(url).toContain('universal2')
-      }
-    })
-
-    it('finds python in PATH or reports not found', () => {
-      const result = findInPath('python3') ?? findInPath('python')
-      // Either found or null — both valid
-      expect(result === null || typeof result === 'string').toBe(true)
-    })
-
-    // Only run download test if explicitly enabled (downloads ~25MB)
-    const downloadTest = process.env.CAMSTACK_TEST_DOWNLOAD === 'true' ? it : it.skip
-    downloadTest(
-      'downloads portable Python',
-      async () => {
-        const pythonPath = await ensurePython(tmpDir, mockLogger)
-        expect(pythonPath).toBeTruthy()
-        expect(fs.existsSync(pythonPath!)).toBe(true)
-
-        // Verify it actually runs
-        const { execFileSync } = await import('node:child_process')
-        const version = execFileSync(pythonPath!, ['--version'], { encoding: 'utf8' }).trim()
-        expect(version).toMatch(/Python 3\.12/)
-      },
-      120000,
-    )
-  })
-})

package/src/__tests__/event-bus-proxy-router.spec.ts

@@ -1,75 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unsafe-assignment -- test mock typing */
-import { describe, it, expect, vi } from 'vitest'
-import { createEventBusProxyRouter } from '../api/core/event-bus-proxy.router.js'
-import { makeCtx } from './cap-routers/harness.js'
-import type { IEventBus } from '@camstack/types'
-
-function createMockEventBus() {
-  return {
-    emit: vi.fn(),
-  } as unknown as IEventBus & { emit: ReturnType<typeof vi.fn> }
-}
-
-describe('event-bus-proxy router', () => {
-  it('emit calls eventBus.emit with the correct shape', async () => {
-    const bus = createMockEventBus()
-    const router = createEventBusProxyRouter(bus)
-    const caller = router.createCaller(makeCtx('admin'))
-
-    await caller.emit({
-      id: 'evt-1',
-      timestamp: '2026-01-15T10:00:00.000Z',
-      source: { type: 'addon', id: 'my-addon' },
-      // biome-ignore lint/plugin: synthetic test-only event category
-      category: 'motion',
-      data: { zone: 'front' },
-    })
-
-    expect(bus.emit).toHaveBeenCalledOnce()
-    expect(bus.emit).toHaveBeenCalledWith({
-      id: 'evt-1',
-      timestamp: expect.any(Date),
-      source: { type: 'addon', id: 'my-addon' },
-      category: 'motion',
-      data: { zone: 'front' },
-    })
-  })
-
-  it('emit returns { ok: true }', async () => {
-    const bus = createMockEventBus()
-    const router = createEventBusProxyRouter(bus)
-    const caller = router.createCaller(makeCtx('admin'))
-
-    const result = await caller.emit({
-      id: 'evt-2',
-      timestamp: '2026-01-15T10:00:00.000Z',
-      source: { type: 'device', id: 'cam-1' },
-      // biome-ignore lint/plugin: synthetic test-only event category
-      category: 'alert',
-      data: {},
-    })
-
-    expect(result).toEqual({ ok: true })
-  })
-
-  it('timestamp string is converted to a Date object', async () => {
-    const bus = createMockEventBus()
-    const router = createEventBusProxyRouter(bus)
-    const caller = router.createCaller(makeCtx('admin'))
-
-    const isoString = '2026-06-20T14:30:00.000Z'
-
-    await caller.emit({
-      id: 'evt-3',
-      timestamp: isoString,
-      source: { type: 'addon', id: 'test' },
-      // biome-ignore lint/plugin: synthetic test-only event category
-      category: 'info',
-      data: {},
-    })
-
-    const emittedEvent = bus.emit.mock.calls[0][0] as { timestamp: unknown }
-    expect(emittedEvent.timestamp).toBeInstanceOf(Date)
-    expect((emittedEvent.timestamp as Date).toISOString()).toBe(isoString)
-  })
-})

package/src/__tests__/fixtures/mock-analysis-addon-a.ts

@@ -1,37 +0,0 @@
-// server/backend/src/__tests__/fixtures/mock-analysis-addon-a.ts
-import type { ICamstackAddon, AddonDeclaration, AddonContext } from '@camstack/types'
-
-export class MockAnalysisAddonA implements ICamstackAddon {
-  readonly manifest: AddonDeclaration = {
-    id: 'mock-analysis-a',
-    name: 'Mock Analysis A',
-    version: '1.0.0',
-    capabilities: ['object-detector'],
-  }
-
-  private initialized = false
-  readonly provider = { id: 'analysis-a', processFrame: async () => [] }
-
-  async initialize(_context: AddonContext) {
-    this.initialized = true
-    return [{ capability: 'object-detector', provider: this.provider }]
-  }
-
-  async shutdown(): Promise<void> {
-    this.initialized = false
-  }
-
-  isInitialized(): boolean {
-    return this.initialized
-  }
-
-  getConfigSchema() {
-    return { sections: [] }
-  }
-
-  getConfig() {
-    return {}
-  }
-
-  async onConfigChange() {}
-}

package/src/__tests__/fixtures/mock-analysis-addon-b.ts

@@ -1,37 +0,0 @@
-// server/backend/src/__tests__/fixtures/mock-analysis-addon-b.ts
-import type { ICamstackAddon, AddonDeclaration, AddonContext } from '@camstack/types'
-
-export class MockAnalysisAddonB implements ICamstackAddon {
-  readonly manifest: AddonDeclaration = {
-    id: 'mock-analysis-b',
-    name: 'Mock Analysis B',
-    version: '1.0.0',
-    capabilities: ['object-detector'],
-  }
-
-  private initialized = false
-  readonly provider = { id: 'analysis-b', processFrame: async () => [] }
-
-  async initialize(_context: AddonContext) {
-    this.initialized = true
-    return [{ capability: 'object-detector', provider: this.provider }]
-  }
-
-  async shutdown(): Promise<void> {
-    this.initialized = false
-  }
-
-  isInitialized(): boolean {
-    return this.initialized
-  }
-
-  getConfigSchema() {
-    return { sections: [] }
-  }
-
-  getConfig() {
-    return {}
-  }
-
-  async onConfigChange() {}
-}

package/src/__tests__/fixtures/mock-log-addon.ts

@@ -1,37 +0,0 @@
-// server/backend/src/__tests__/fixtures/mock-log-addon.ts
-import type { ICamstackAddon, AddonDeclaration, AddonContext } from '@camstack/types'
-
-export class MockLogAddon implements ICamstackAddon {
-  readonly manifest: AddonDeclaration = {
-    id: 'mock-log-addon',
-    name: 'Mock Log Destination',
-    version: '1.0.0',
-    capabilities: ['log-destination'],
-  }
-
-  private initialized = false
-  readonly provider = { id: 'mock-log', write: async () => {} }
-
-  async initialize(_context: AddonContext) {
-    this.initialized = true
-    return [{ capability: 'log-destination', provider: this.provider }]
-  }
-
-  async shutdown(): Promise<void> {
-    this.initialized = false
-  }
-
-  isInitialized(): boolean {
-    return this.initialized
-  }
-
-  getConfigSchema() {
-    return { sections: [] }
-  }
-
-  getConfig() {
-    return {}
-  }
-
-  async onConfigChange() {}
-}

package/src/__tests__/fixtures/mock-storage-addon.ts

@@ -1,40 +0,0 @@
-// server/backend/src/__tests__/fixtures/mock-storage-addon.ts
-import type { ICamstackAddon, AddonDeclaration, AddonContext } from '@camstack/types'
-
-export class MockStorageAddon implements ICamstackAddon {
-  readonly manifest: AddonDeclaration = {
-    id: 'mock-storage',
-    name: 'Mock Storage',
-    version: '1.0.0',
-    capabilities: ['storage', 'settings-store'],
-  }
-
-  private initialized = false
-  readonly provider = { id: 'mock-storage', type: 'mock' }
-
-  async initialize(_context: AddonContext) {
-    this.initialized = true
-    return [
-      { capability: 'storage', provider: this.provider },
-      { capability: 'settings-store', provider: this.provider },
-    ]
-  }
-
-  async shutdown(): Promise<void> {
-    this.initialized = false
-  }
-
-  isInitialized(): boolean {
-    return this.initialized
-  }
-
-  getConfigSchema() {
-    return { sections: [] }
-  }
-
-  getConfig() {
-    return {}
-  }
-
-  async onConfigChange() {}
-}