@camstack/server 0.1.3

package/src/core/capability/capability.service.ts

@@ -0,0 +1,57 @@
+/**
+ * CapabilityService — NestJS-injectable wrapper around the CapabilityRegistry.
+ *
+ * Server services inject this instead of accessing the registry directly.
+ * The registry reference is set once during boot by AddonRegistryService.
+ */
+
+import type { CapabilityRegistry } from '@camstack/kernel'
+
+export class CapabilityService {
+  private registry: CapabilityRegistry | null = null
+
+  /** Called once during boot by AddonRegistryService to wire the registry */
+  setRegistry(registry: CapabilityRegistry): void {
+    this.registry = registry
+  }
+
+  /** Get the underlying registry (may be null before boot completes) */
+  getRegistry(): CapabilityRegistry | null {
+    return this.registry
+  }
+
+  /** Get the active singleton provider for a capability */
+  getSingleton<T>(capability: string): T | null {
+    return this.registry?.getSingleton<T>(capability) ?? null
+  }
+
+  /** Get the addon ID of the active singleton provider for a capability */
+  getSingletonAddonId(capability: string): string | null {
+    return this.registry?.getSingletonAddonId(capability) ?? null
+  }
+
+  /** Get all active collection providers for a capability */
+  getCollection<T>(capability: string): readonly T[] {
+    return this.registry?.getCollection<T>(capability) ?? []
+  }
+
+  /**
+   * Like {@link getCollection} but returns `[addonId, provider]` tuples
+   * so callers can attribute work back to the contributing addon —
+   * required by the addon-widgets static file route to validate that
+   * the requested `addonId` is a registered widget provider.
+   */
+  getCollectionEntries<T>(capability: string): readonly (readonly [string, T])[] {
+    return this.registry?.getCollectionEntries<T>(capability) ?? []
+  }
+
+  /** Resolve a singleton provider for a specific device (with per-device override support) */
+  resolveForDevice<T>(capability: string, deviceId: string): T | null {
+    return this.registry?.resolveForDevice<T>(capability, deviceId) ?? null
+  }
+
+  /** Resolve collection providers for a specific device (with per-device filter support) */
+  resolveCollectionForDevice<T>(capability: string, deviceId: string): readonly T[] {
+    return this.registry?.resolveCollectionForDevice<T>(capability, deviceId) ?? []
+  }
+}

package/src/core/config/config.schema.ts

@@ -0,0 +1,3 @@
+// Re-export from @camstack/kernel
+export { bootstrapSchema, RUNTIME_DEFAULTS } from '@camstack/kernel'
+export type { BootstrapConfig, AppConfig, ServerMode } from '@camstack/kernel'

package/src/core/config/config.service.spec.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import * as yaml from 'js-yaml'
+import { ConfigService } from './config.service'
+
+describe('ConfigService', () => {
+  let tmpDir: string
+  let originalEnv: Record<string, string | undefined>
+
+  beforeEach(() => {
+    // Phase 13 (settings redesign test fix): `ConfigManager` applies
+    // `ENV_VAR_MAP` overrides on top of YAML values. When this suite
+    // runs in parallel with others under `nx run-many`, environment
+    // variables set by sibling tests (or the parent nx process) leak
+    // in and override our carefully seeded YAML fixtures — making
+    // `auth.adminPassword` come back as `'admin'` instead of
+    // `'secret123'` and `server.dataPath` come back as the default
+    // `'camstack-data'` instead of `'/custom/data'`.
+    //
+    // Snapshot and clear every env var that `ENV_VAR_MAP` consults.
+    //
+    // NOTE: `ADMIN_PASSWORD` is intentionally NOT cleared here.
+    // `bootstrapSchema` in @camstack/kernel uses
+    // `z.string().default(process.env.ADMIN_PASSWORD ?? 'changeme')`
+    // which is evaluated once at module load time — clearing
+    // `ADMIN_PASSWORD` here has no effect on the already-baked-in
+    // schema default, and the "uses defaults when config file does
+    // not exist" test still has to read that original value via
+    // `process.env.ADMIN_PASSWORD ?? 'changeme'`. So we leave the
+    // var alone.
+    const envKeys = [
+      'CAMSTACK_PORT',
+      'CAMSTACK_HOST',
+      'CAMSTACK_DATA',
+      'CAMSTACK_JWT_SECRET',
+      'CAMSTACK_ADMIN_USER',
+      'CAMSTACK_ADMIN_PASS',
+    ] as const
+    originalEnv = {}
+    for (const key of envKeys) {
+      originalEnv[key] = process.env[key]
+      delete process.env[key]
+    }
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'camstack-config-'))
+  })
+
+  afterEach(() => {
+    for (const [key, value] of Object.entries(originalEnv)) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  const createConfigFile = (config: Record<string, unknown>): string => {
+    const filePath = path.join(tmpDir, 'config.yaml')
+    fs.writeFileSync(filePath, yaml.dump(config), 'utf-8')
+    return filePath
+  }
+
+  const createService = async (configPath: string): Promise<ConfigService> => {
+    return new ConfigService(configPath)
+  }
+
+  it('loads and validates a minimal config.yaml', async () => {
+    const configPath = createConfigFile({
+      server: { port: 5000, host: '127.0.0.1' },
+      auth: { adminPassword: 'secret123' },
+    })
+
+    const service = await createService(configPath)
+    const raw = service.raw
+
+    expect(raw.server.port).toBe(5000)
+    expect(raw.server.host).toBe('127.0.0.1')
+    expect(raw.auth.adminPassword).toBe('secret123')
+    expect(raw.auth.adminUsername).toBe('admin')
+  })
+
+  it('returns runtime defaults for optional sections via raw', async () => {
+    const configPath = createConfigFile({
+      server: { port: 4443 },
+      auth: { adminPassword: 'secret123' },
+    })
+
+    const service = await createService(configPath)
+    const raw = service.raw
+
+    expect(raw.features.streaming).toBe(true)
+    expect(raw.features.objectDetection).toBe(false)
+    expect(raw.storage.provider).toBe('sqlite-storage')
+    expect(raw.logging.level).toBe('info')
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access -- 
+    expect((raw.logging as any).retentionDays).toBe(30)
+    expect(raw.eventBus.ringBufferSize).toBe(10000)
+    // addons.enabled removed — installed = active
+  })
+
+  it('throws on invalid config (port as string)', async () => {
+    const configPath = createConfigFile({
+      server: { port: 'not-a-number' },
+      auth: { adminPassword: 'secret123' },
+    })
+
+    await expect(createService(configPath)).rejects.toThrow()
+  })
+
+  it('dot-path access works for bootstrap keys', async () => {
+    const configPath = createConfigFile({
+      server: { port: 9090 },
+      auth: { adminPassword: 'secret123' },
+    })
+
+    const service = await createService(configPath)
+
+    expect(service.get<number>('server.port')).toBe(9090)
+    expect(service.get<string>('auth.adminPassword')).toBe('secret123')
+  })
+
+  it('dot-path access returns runtime defaults for non-bootstrap keys', async () => {
+    const configPath = createConfigFile({
+      server: { port: 4443 },
+      auth: { adminPassword: 'secret123' },
+    })
+
+    const service = await createService(configPath)
+
+    expect(service.get<string>('logging.level')).toBe('info')
+    expect(service.get<number>('retention.detectionEventsDays')).toBe(30)
+    expect(service.get<boolean>('features.objectDetection')).toBe(false)
+    // addons.enabled removed — installed = active
+  })
+
+  it('uses defaults when config file does not exist', async () => {
+    const configPath = path.join(tmpDir, 'nonexistent.yaml')
+
+    const service = await createService(configPath)
+    const raw = service.raw
+
+    expect(raw.server.port).toBe(4443)
+    expect(raw.server.host).toBe('0.0.0.0')
+    expect(raw.auth.adminUsername).toBe('admin')
+    expect(raw.auth.adminPassword).toBe(process.env.ADMIN_PASSWORD ?? 'changeme')
+  })
+
+  it('returns features via features getter with runtime defaults', async () => {
+    const configPath = createConfigFile({
+      server: { port: 4443 },
+      auth: { adminPassword: 'secret123' },
+    })
+
+    const service = await createService(configPath)
+    const features = service.features
+
+    // Features come from RUNTIME_DEFAULTS (not YAML bootstrap config)
+    expect(features.streaming).toBe(true)
+    expect(features.objectDetection).toBe(false)
+    expect(features.notifications).toBe(true)
+  })
+
+  it('getBootstrap returns bootstrap-only values', async () => {
+    const configPath = createConfigFile({
+      server: { port: 7777, dataPath: '/custom/data' },
+      auth: { adminPassword: 'mypass', jwtSecret: 'mysecret' },
+    })
+
+    const service = await createService(configPath)
+
+    expect(service.getBootstrap<number>('server.port')).toBe(7777)
+    expect(service.getBootstrap<string>('server.dataPath')).toBe('/custom/data')
+    expect(service.getBootstrap<string>('auth.jwtSecret')).toBe('mysecret')
+  })
+})

package/src/core/config/config.service.ts

@@ -0,0 +1,7 @@
+import { ConfigManager } from '@camstack/kernel'
+
+export class ConfigService extends ConfigManager {
+  constructor(configPath: string) {
+    super(configPath)
+  }
+}

package/src/core/events/event-bus.service.spec.ts

@@ -0,0 +1,212 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import * as yaml from 'js-yaml'
+import { ServiceBroker } from 'moleculer'
+import { EventBusService } from './event-bus.service'
+import { ConfigService } from '../config/config.service'
+import type { ISettingsStore } from '@camstack/kernel'
+import type { SystemEvent } from '@camstack/types'
+
+/** Flush pending queueMicrotask callbacks */
+const flush = () => new Promise<void>(resolve => queueMicrotask(resolve))
+
+const makeEvent = (category: string, overrides: Partial<SystemEvent> = {}): SystemEvent => ({
+  id: `evt-${Math.random().toString(36).slice(2, 8)}`,
+  timestamp: new Date(),
+  source: { type: 'device', id: 'cam-1' },
+  category,
+  data: {},
+  ...overrides,
+})
+
+/**
+ * In-memory settings store used by the test to drive `ConfigService.get`
+ * for the `eventBus.ringBufferSize` key. The bootstrap YAML schema does not
+ * declare `eventBus`, so writing it to the YAML file would be discarded by
+ * `bootstrapSchema.parse`. Wiring an ISettingsStore is the clean path to
+ * feed runtime values into `ConfigService` without casts.
+ */
+class InMemorySettingsStore implements ISettingsStore {
+  private readonly system: Record<string, unknown>
+
+  constructor(seed: Record<string, unknown>) {
+    this.system = { ...seed }
+  }
+
+  getSystem(key: string): unknown { return this.system[key] }
+  setSystem(key: string, value: unknown): void { this.system[key] = value }
+  getAllSystem(): Record<string, unknown> { return { ...this.system } }
+
+  getAllAddon(_addonId: string): Record<string, unknown> { return {} }
+  setAllAddon(_addonId: string, _config: Record<string, unknown>): void { /* no-op */ }
+  getAllProvider(_providerId: string): Record<string, unknown> { return {} }
+  setProvider(_providerId: string, _key: string, _value: unknown): void { /* no-op */ }
+  getAllDevice(_deviceId: string): Record<string, unknown> { return {} }
+  setDevice(_deviceId: string, _key: string, _value: unknown): void { /* no-op */ }
+  getAddonDevice(_addonId: string, _deviceId: string): Record<string, unknown> { return {} }
+  setAddonDevice(_addonId: string, _deviceId: string, _values: Record<string, unknown>): void { /* no-op */ }
+  clearAddonDevice(_addonId: string, _deviceId: string): void { /* no-op */ }
+}
+
+describe('EventBusService', () => {
+  let tmpDir: string
+  // Brokers spawned by `createService` — torn down in `afterEach` so
+  // every test runs in isolation. The bus is a thin delegate over the
+  // shared broker bus (`getBrokerEventBus(broker)`); attaching is the
+  // entrypoint that wires `subscribe` / `emit` to a real implementation.
+  const brokers: ServiceBroker[] = []
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'camstack-eventbus-'))
+  })
+
+  afterEach(async () => {
+    for (const b of brokers.splice(0)) {
+      await b.stop()
+    }
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  const createService = async (bufferSize = 100): Promise<EventBusService> => {
+    const configPath = path.join(tmpDir, 'config.yaml')
+    fs.writeFileSync(
+      configPath,
+      yaml.dump({
+        server: { port: 4443 },
+        auth: { adminPassword: 'secret123' },
+      }),
+      'utf-8',
+    )
+    const configService = new ConfigService(configPath)
+    configService.setSettingsStore(new InMemorySettingsStore({
+      'eventBus.ringBufferSize': bufferSize,
+    }))
+    const service = new EventBusService(configService)
+    // EventBusService is a delegate that needs a broker to dispatch
+    // through. Use a unique nodeID per call so each test gets its own
+    // shared bus instance (`getBrokerEventBus(broker)` keys by broker).
+    const broker = new ServiceBroker({
+      nodeID: `eventbus-test-${brokers.length}`,
+      transporter: 'Fake',
+      logger: false,
+    })
+    await broker.start()
+    brokers.push(broker)
+    service.attachBroker(broker)
+    return service
+  }
+
+  it('emits events to subscribers', async () => {
+    const service = await createService()
+    const received: SystemEvent[] = []
+
+    service.subscribe({}, (event) => received.push(event))
+
+    const event = makeEvent('device.online')
+    service.emit(event)
+    await flush()
+
+    // The shared broker bus enriches every emit with `sourceNodeId`,
+    // so the delivered object is a copy — assert key fields instead of
+    // strict identity. See `addon-context-factory.ts::createSharedBus`.
+    expect(received).toHaveLength(1)
+    expect(received[0]).toMatchObject({ id: event.id, category: event.category })
+  })
+
+  it('filters by category wildcard (device.* matches device.online)', async () => {
+    const service = await createService()
+    const received: SystemEvent[] = []
+
+    service.subscribe({ category: 'device.*' }, (event) => received.push(event))
+
+    service.emit(makeEvent('device.online'))
+    service.emit(makeEvent('device.offline'))
+    service.emit(makeEvent('addon.started'))
+    await flush()
+
+    expect(received).toHaveLength(2)
+
+    expect(received[0]!.category).toBe('device.online')
+
+    expect(received[1]!.category).toBe('device.offline')
+  })
+
+  it('filters by exact category', async () => {
+    const service = await createService()
+    const received: SystemEvent[] = []
+
+    service.subscribe({ category: 'device.online' }, (event) => received.push(event))
+
+    service.emit(makeEvent('device.online'))
+    service.emit(makeEvent('device.offline'))
+    await flush()
+
+    expect(received).toHaveLength(1)
+
+    expect(received[0]!.category).toBe('device.online')
+  })
+
+  it('filters by source', async () => {
+    const service = await createService()
+    const received: SystemEvent[] = []
+
+    service.subscribe(
+      { source: { type: 'addon', id: 'frigate' } },
+      (event) => received.push(event),
+    )
+
+    service.emit(makeEvent('addon.started', { source: { type: 'addon', id: 'frigate' } }))
+    service.emit(makeEvent('addon.started', { source: { type: 'addon', id: 'scrypted' } }))
+    await flush()
+
+    expect(received).toHaveLength(1)
+  })
+
+  it('maintains a chronological recent-events buffer', async () => {
+    // Buffer size is now hub-fixed at 10000 (see `createSharedBusState`),
+    // so the legacy `bufferSize=3` argument no longer caps it. The
+    // contract under test today is: every emit is appended in order and
+    // surfaces via `getRecent()`, oldest first.
+    const service = await createService()
+
+    service.emit(makeEvent('a'))
+    service.emit(makeEvent('b'))
+    service.emit(makeEvent('c'))
+    service.emit(makeEvent('d'))
+
+    const recent = service.getRecent()
+    expect(recent).toHaveLength(4)
+    expect(recent[0]!.category).toBe('a')
+    expect(recent[3]!.category).toBe('d')
+  })
+
+  it('unsubscribe stops delivery', async () => {
+    const service = await createService()
+    const received: SystemEvent[] = []
+
+    const unsubscribe = service.subscribe({}, (event) => received.push(event))
+
+    service.emit(makeEvent('first'))
+    await flush()
+    unsubscribe()
+    service.emit(makeEvent('second'))
+    await flush()
+
+    expect(received).toHaveLength(1)
+
+    expect(received[0]!.category).toBe('first')
+  })
+
+  it('getRecent supports filter', async () => {
+    const service = await createService()
+
+    service.emit(makeEvent('device.online'))
+    service.emit(makeEvent('addon.started'))
+    service.emit(makeEvent('device.offline'))
+
+    const recent = service.getRecent({ category: 'device.*' })
+    expect(recent).toHaveLength(2)
+  })
+})

package/src/core/events/event-bus.service.ts

@@ -0,0 +1,85 @@
+import type { ServiceBroker } from 'moleculer'
+import { getBrokerEventBus } from '@camstack/kernel'
+import type { SystemEvent, IEventBus, EventFilter } from '@camstack/types'
+import { ConfigService } from '../config/config.service'
+
+/**
+ * Hub-side event bus. Pre-broker boot the service buffers nothing —
+ * subscribers / emits are no-ops until `attachBroker` lands the
+ * underlying per-broker shared bus. Once attached every operation
+ * delegates to the unified `getBrokerEventBus(broker)` instance,
+ * which is the SAME bus that group-runner / agent subprocess addons
+ * see when they call `ctx.eventBus.emit`. Single in-process delivery
+ * map per broker, single `broker.broadcast` for cross-broker
+ * delivery — no more dual hub-vs-subprocess implementations.
+ *
+ * **Persistence scope**: the in-memory ring buffer (10 000 events,
+ * owned by `getBrokerEventBus`) survives admin-ui browser refreshes
+ * but NOT server restarts — that's intentional. UI panels read
+ * `getRecent` on mount and live-subscribe via `live.onEvent` /
+ * `systemEvents.subscribe`, which is enough for the operator to see
+ * continuity across page reloads.
+ */
+export class EventBusService implements IEventBus {
+  private broker: ServiceBroker | null = null
+  private inner: IEventBus | null = null
+  // Used only as a loose ring buffer for the very first events emitted
+  // before `attachBroker` runs (NestJS-era boot legacy). Drained into
+  // the real bus on attach.
+  private pending: SystemEvent[] = []
+  private deferredSubs: Array<{ filter: EventFilter; handler: (event: SystemEvent) => void; unsub?: () => void }> = []
+
+  constructor(_configService: ConfigService) {
+    // The shared bus owns the ring-buffer size — hub-side config is
+    // accepted for API compatibility but no longer drives the bus.
+    void _configService
+  }
+
+  attachBroker(broker: ServiceBroker): void {
+    if (this.broker === broker) return
+    this.broker = broker
+    const inner = getBrokerEventBus(broker)
+    this.inner = inner
+    // Replay deferred subscriptions onto the real bus.
+    for (const sub of this.deferredSubs) {
+      sub.unsub = inner.subscribe(sub.filter, sub.handler)
+    }
+    // Flush events emitted before the broker was ready.
+    for (const evt of this.pending) {
+      inner.emit(evt)
+    }
+    this.pending = []
+  }
+
+  detachBroker(): void {
+    for (const sub of this.deferredSubs) {
+      sub.unsub?.()
+      sub.unsub = undefined
+    }
+    this.broker = null
+    this.inner = null
+  }
+
+  emit(event: SystemEvent): void {
+    if (!this.inner) {
+      this.pending.push(event)
+      return
+    }
+    this.inner.emit(event)
+  }
+
+  subscribe(filter: EventFilter, handler: (event: SystemEvent) => void): () => void {
+    if (this.inner) return this.inner.subscribe(filter, handler)
+    const sub = { filter, handler, unsub: undefined as (() => void) | undefined }
+    this.deferredSubs.push(sub)
+    return () => {
+      if (sub.unsub) sub.unsub()
+      const idx = this.deferredSubs.indexOf(sub)
+      if (idx >= 0) this.deferredSubs.splice(idx, 1)
+    }
+  }
+
+  getRecent(filter?: EventFilter, limit?: number): readonly SystemEvent[] {
+    return this.inner?.getRecent(filter, limit) ?? []
+  }
+}

package/src/core/feature/feature.service.spec.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import * as yaml from 'js-yaml'
+import { FeatureService } from './feature.service'
+import { ConfigService } from '../config/config.service'
+import type { FeatureManifest } from '@camstack/types'
+
+/**
+ * Test-only ConfigService subclass that overrides the `features` getter
+ * to return a fixed manifest. Avoids wiring a full settings-store just to
+ * drive a FeatureService. The bootstrap YAML still has to be real so the
+ * ConfigManager constructor succeeds.
+ */
+class StaticFeatureConfigService extends ConfigService {
+  constructor(configPath: string, private readonly staticFeatures: FeatureManifest) {
+    super(configPath)
+  }
+
+  override get features(): FeatureManifest {
+    return this.staticFeatures
+  }
+}
+
+describe('FeatureService', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'camstack-feature-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  const createService = (features: Partial<FeatureManifest> = {}): FeatureService => {
+    const fullFeatures: FeatureManifest = {
+      streaming: true,
+      notifications: true,
+      objectDetection: false,
+      remoteAccess: true,
+      agentCluster: false,
+      smartHome: true,
+      recordings: true,
+      backup: true,
+      repl: true,
+      ...features,
+    }
+
+    const configPath = path.join(tmpDir, 'config.yaml')
+    fs.writeFileSync(
+      configPath,
+      yaml.dump({
+        server: { port: 4443 },
+        auth: { adminPassword: 'secret123' },
+      }),
+      'utf-8',
+    )
+    const configService = new StaticFeatureConfigService(configPath, fullFeatures)
+    return new FeatureService(configService)
+  }
+
+  it('returns true for enabled features', () => {
+    const service = createService({ streaming: true, notifications: true })
+
+    expect(service.isEnabled('streaming')).toBe(true)
+    expect(service.isEnabled('notifications')).toBe(true)
+    expect(service.isEnabled('remoteAccess')).toBe(true)
+  })
+
+  it('returns false for disabled features', () => {
+    const service = createService({ objectDetection: false, agentCluster: false })
+
+    expect(service.isEnabled('objectDetection')).toBe(false)
+    expect(service.isEnabled('agentCluster')).toBe(false)
+  })
+
+  it('returns full manifest', () => {
+    const customFeatures: Partial<FeatureManifest> = {
+      streaming: false,
+      objectDetection: true,
+    }
+    const service = createService(customFeatures)
+
+    const manifest = service.getManifest()
+
+    expect(manifest.streaming).toBe(false)
+
+    expect(manifest.objectDetection).toBe(true)
+
+    expect(manifest.notifications).toBe(true)
+
+    expect(manifest.remoteAccess).toBe(true)
+  })
+})

package/src/core/feature/feature.service.ts

@@ -0,0 +1,8 @@
+import { FeatureManager } from '@camstack/core'
+import { ConfigService } from '../config/config.service'
+
+export class FeatureService extends FeatureManager {
+  constructor(configService: ConfigService) {
+    super(configService)
+  }
+}