@camstack/server 0.1.6 → 0.1.8

package/src/__tests__/cap-routers/device-link-overlay.spec.ts

@@ -0,0 +1,132 @@
+/**
+ * Tests that `requireDeviceScoped` overlays `getStatus` results via
+ * `device-manager`'s `resolveLinkedStatus` when the device has linked
+ * properties for the requested cap.
+ *
+ * The overlay is transparent (null return = no-op) for the vast majority
+ * of reads; only devices with active links for the cap get the merged
+ * status back.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import type { CapabilityRegistry } from '@camstack/kernel'
+import { requireDeviceScoped } from '../../api/trpc/cap-mount-helpers.js'
+
+// ── Fake registry ────────────────────────────────────────────────────────────
+
+type ResolveLinkedStatus = (i: {
+  deviceId: number
+  cap: string
+  baseStatus: unknown
+}) => Promise<Record<string, unknown> | null>
+
+interface FakeDeviceManager {
+  resolveLinkedStatus: ResolveLinkedStatus
+}
+
+function makeRegistry(opts: {
+  nativeGetStatus: () => Promise<Record<string, unknown>>
+  nativeSetFanSpeed?: (i: unknown) => Promise<void>
+  resolveLinkedStatus: ResolveLinkedStatus
+}): CapabilityRegistry {
+  const nativeProvider = {
+    getStatus: opts.nativeGetStatus,
+    setFanSpeed: opts.nativeSetFanSpeed ?? vi.fn(async () => undefined),
+  }
+  const deviceManager: FakeDeviceManager = {
+    resolveLinkedStatus: opts.resolveLinkedStatus,
+  }
+  return {
+    getNativeProvider<T>(_capName: string, _deviceId: number): T | null {
+      return nativeProvider as unknown as T
+    },
+    getSingleton<T>(capability: string): T | null {
+      if (capability === 'device-manager') {
+        return deviceManager as unknown as T
+      }
+      return null
+    },
+    // Minimal no-op stubs for the rest of the CapabilityRegistry surface
+    // so TypeScript is satisfied without pulling in the real kernel class.
+    listCapabilities: vi.fn(() => []),
+    registerProvider: vi.fn(),
+    unregisterProvider: vi.fn(),
+    getCollection: vi.fn(() => []),
+    getCollectionEntries: vi.fn(() => []),
+    registerNativeProvider: vi.fn(),
+    unregisterNativeProvider: vi.fn(),
+    getProviderForDevice: vi.fn(() => null),
+    getBindings: vi.fn(() => ({ entries: [] })),
+    setActiveSingleton: vi.fn(),
+    getSingletonAddonId: vi.fn(() => null),
+    getAddonIdForProvider: vi.fn(() => null),
+    on: vi.fn(),
+    off: vi.fn(),
+    dispose: vi.fn(),
+  } as unknown as CapabilityRegistry
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+const DEVICE_ID = 668
+const CAP_NAME = 'vacuum-control' as Parameters<typeof requireDeviceScoped>[1]
+
+describe('requireDeviceScoped — getStatus overlay via resolveLinkedStatus', () => {
+  it('returns the overlaid status when resolveLinkedStatus returns a non-null object', async () => {
+    const base = { state: 'idle', battery: 80 }
+    const overlaid = { state: 'paused', cleanWater: { status: 'low', level: null } }
+
+    const registry = makeRegistry({
+      nativeGetStatus: vi.fn(async () => base),
+      resolveLinkedStatus: vi.fn(async () => overlaid),
+    })
+
+    const dispatcher = requireDeviceScoped(registry, CAP_NAME)
+    expect(dispatcher).not.toBeNull()
+
+    // Call via the Proxy — method is resolved lazily
+    const result = await (dispatcher as unknown as { getStatus: (i: { deviceId: number }) => Promise<unknown> })
+      .getStatus({ deviceId: DEVICE_ID })
+
+    expect(result).toEqual(overlaid)
+    expect(result).not.toEqual(base)
+  })
+
+  it('returns the base provider result unchanged when resolveLinkedStatus returns null (no links)', async () => {
+    const base = { state: 'cleaning', battery: 60 }
+
+    const registry = makeRegistry({
+      nativeGetStatus: vi.fn(async () => base),
+      resolveLinkedStatus: vi.fn(async () => null),
+    })
+
+    const dispatcher = requireDeviceScoped(registry, CAP_NAME)
+    expect(dispatcher).not.toBeNull()
+
+    const result = await (dispatcher as unknown as { getStatus: (i: { deviceId: number }) => Promise<unknown> })
+      .getStatus({ deviceId: DEVICE_ID })
+
+    expect(result).toEqual(base)
+  })
+
+  it('does NOT call resolveLinkedStatus for non-getStatus methods', async () => {
+    const base = { state: 'idle', battery: 90 }
+    const resolveLinkedStatus = vi.fn(async () => null)
+    const nativeSetFanSpeed = vi.fn(async () => undefined)
+
+    const registry = makeRegistry({
+      nativeGetStatus: vi.fn(async () => base),
+      nativeSetFanSpeed,
+      resolveLinkedStatus,
+    })
+
+    const dispatcher = requireDeviceScoped(registry, CAP_NAME)
+    expect(dispatcher).not.toBeNull()
+
+    await (dispatcher as unknown as { setFanSpeed: (i: { deviceId: number; speed: string }) => Promise<void> })
+      .setFanSpeed({ deviceId: DEVICE_ID, speed: 'high' })
+
+    expect(nativeSetFanSpeed).toHaveBeenCalledOnce()
+    // The overlay path must NOT be consulted for mutations
+    expect(resolveLinkedStatus).not.toHaveBeenCalled()
+  })
+})

package/src/__tests__/dev-bootstrap-shm-ring.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+describe('dev bootstrap — shm-ring prebuild availability', () => {
+  it('has at least one .node prebuild for the current platform-arch', () => {
+    const platform = process.platform
+    const arch = process.arch
+    const triple = `${platform}-${arch}`
+    const prebuildsDir = join(__dirname, '..', '..', '..', '..', 'packages', 'shm-ring', 'prebuilds', triple)
+    expect(existsSync(prebuildsDir)).toBe(true)
+    const files = readdirSync(prebuildsDir)
+    const nodeBinaries = files.filter(f => f.endsWith('.node'))
+    expect(nodeBinaries.length).toBeGreaterThan(0)
+  })
+
+  it('@camstack/shm-ring resolves and loads (smoke test)', () => {
+    // If this require() throws "No native build was found...", the
+    // dev bootstrap is broken — the regression Bug-2 is back.
+    let mod: unknown
+    expect(() => {
+      mod = require('@camstack/shm-ring')
+    }).not.toThrow()
+    expect(mod).toBeDefined()
+    // Should expose at least FrameRingReader/Writer (per the published API)
+    const m = mod as Record<string, unknown>
+    expect(typeof m['FrameRingReader']).toBe('function')
+    expect(typeof m['FrameRingWriter']).toBe('function')
+  })
+})

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

@@ -0,0 +1,249 @@
+/**
+ * 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__/framework-installer-defer-restart.spec.ts

@@ -0,0 +1,165 @@
+/**
+ * deferRestart flag on AddonPackageService.updateFrameworkPackage
+ *
+ * Spec: docs/superpowers/specs/2026-05-21-addons-bulk-update-progress-design.md
+ *
+ * Invariants:
+ *   - deferRestart: true  → npm install runs normally; marker write AND
+ *     scheduleSelfRestart are SKIPPED; restartingAt is 0 (sentinel).
+ *   - deferRestart omitted (default) → marker write AND scheduleSelfRestart
+ *     both fire; restartingAt > 0.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import * as fs from 'node:fs'
+import type { IScopedLogger } from '@camstack/types'
+
+// ── Module-level mocks ──────────────────────────────────────────────────────
+// Must be hoisted before any import that loads the module under test.
+// vi.mock is statically hoisted by vitest's transform, so the factories
+// run before the module graph is resolved.
+
+vi.mock('@camstack/kernel', async (importOriginal) => {
+  const real = await importOriginal<typeof import('@camstack/kernel')>()
+  return {
+    ...real,
+    scheduleSelfRestart: vi.fn(),
+    writePendingRestart: vi.fn(),
+    // resolveNpmVersion and resolveFrameworkPackageAppRoot are private module
+    // functions inside addon-package.service.ts — they are NOT exported from
+    // @camstack/kernel, so we don't need to stub them here.
+  }
+})
+
+// Mock node:child_process so no actual `npm install` / `npm view` is executed.
+vi.mock('node:child_process', async (importOriginal) => {
+  const real = await importOriginal<typeof import('node:child_process')>()
+  return {
+    ...real,
+    execFile: vi.fn(
+      (
+        _cmd: string,
+        _args: string[],
+        _opts: unknown,
+        callback: (err: null, result: { stdout: string; stderr: string }) => void,
+      ) => {
+        // Simulate `npm view @camstack/types@0.1.40 version` → '0.1.40'
+        callback(null, { stdout: '0.1.40\n', stderr: '' })
+        return { kill: () => undefined }
+      },
+    ),
+  }
+})
+
+// ── Imports that depend on the mocked modules ───────────────────────────────
+import { scheduleSelfRestart, writePendingRestart } from '@camstack/kernel'
+import { AddonPackageService } from '../core/addon/addon-package.service.js'
+import { EventCategory } from '@camstack/types'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeLogger(): IScopedLogger {
+  const logger: IScopedLogger = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+    trace: vi.fn(),
+    fatal: vi.fn(),
+    child: (() => logger) as IScopedLogger['child'],
+  } as unknown as IScopedLogger
+  return logger
+}
+
+interface ServiceEnv {
+  readonly service: AddonPackageService
+  readonly tmpDir: string
+  readonly scheduleSelfRestartMock: ReturnType<typeof vi.fn>
+  readonly writePendingRestartMock: ReturnType<typeof vi.fn>
+}
+
+function createEnv(): ServiceEnv {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'defer-restart-spec-'))
+
+  const logger = makeLogger()
+
+  const loggingService = {
+    createLogger: () => logger,
+  }
+
+  const eventBusService = {
+    emit: vi.fn(),
+  }
+
+  const configService = {}
+  const addonRegistry = {}
+  const notificationService = {}
+  const toastService = {}
+
+  const service = new AddonPackageService(
+    loggingService as never,
+    eventBusService as never,
+    configService as never,
+    addonRegistry as never,
+    notificationService as never,
+    toastService as never,
+  )
+
+  // Point the framework-package app-root resolver at our tmp dir so
+  // `npm install --prefix <appRoot>` (which is mocked anyway) has a
+  // valid-looking path without requiring the real workspace layout.
+  process.env['CAMSTACK_FRAMEWORK_APP_ROOT_OVERRIDE'] = tmpDir
+
+  return {
+    service,
+    tmpDir,
+    scheduleSelfRestartMock: scheduleSelfRestart as ReturnType<typeof vi.fn>,
+    writePendingRestartMock: writePendingRestart as ReturnType<typeof vi.fn>,
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe('AddonPackageService.updateFrameworkPackage — deferRestart flag', () => {
+  let env: ServiceEnv
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    env = createEnv()
+  })
+
+  afterEach(() => {
+    fs.rmSync(env.tmpDir, { recursive: true, force: true })
+    delete process.env['CAMSTACK_FRAMEWORK_APP_ROOT_OVERRIDE']
+    vi.restoreAllMocks()
+  })
+
+  it('skips restart seam (writePendingRestart + scheduleSelfRestart) when deferRestart is true', async () => {
+    const result = await env.service.updateFrameworkPackage({
+      packageName: '@camstack/types',
+      version: '0.1.40',
+      deferRestart: true,
+    })
+
+    expect(env.writePendingRestartMock).not.toHaveBeenCalled()
+    expect(env.scheduleSelfRestartMock).not.toHaveBeenCalled()
+    expect(result.packageName).toBe('@camstack/types')
+    expect(result.toVersion).toBe('0.1.40')
+    // Sentinel: 0 signals "no restart scheduled"
+    expect(result.restartingAt).toBe(0)
+  })
+
+  it('fires writePendingRestart + scheduleSelfRestart when deferRestart is omitted', async () => {
+    const result = await env.service.updateFrameworkPackage({
+      packageName: '@camstack/types',
+      version: '0.1.40',
+    })
+
+    expect(env.writePendingRestartMock).toHaveBeenCalledOnce()
+    expect(env.scheduleSelfRestartMock).toHaveBeenCalledOnce()
+    expect(result.packageName).toBe('@camstack/types')
+    expect(result.toVersion).toBe('0.1.40')
+    expect(result.restartingAt).toBeGreaterThan(0)
+  })
+})