@camstack/server 0.1.3

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

@@ -0,0 +1,109 @@
+ 
+/**
+ * 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

@@ -0,0 +1,72 @@
+/* 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' },
+      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' },
+      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' },
+      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

@@ -0,0 +1,37 @@
+// 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

@@ -0,0 +1,37 @@
+// 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

@@ -0,0 +1,37 @@
+// 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

@@ -0,0 +1,40 @@
+// 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() {}
+}

package/src/__tests__/framework-allowlist.spec.ts

@@ -0,0 +1,95 @@
+/**
+ * Framework package allow-list coherence.
+ *
+ * Spec: docs/superpowers/specs/2026-05-14-framework-live-update-design.md
+ *
+ * Invariants:
+ *   - Every entry in `FRAMEWORK_PACKAGE_ALLOWLIST` resolves to a workspace
+ *     package whose `package.json` declares `camstack.system: true`.
+ *   - Every workspace package with `camstack.system: true` appears in the
+ *     allow-list — drift in either direction breaks live-update.
+ *   - `isFrameworkPackage` accepts framework names and rejects everything
+ *     else (sanity check on the gate the cap method uses).
+ */
+import { describe, it, expect } from 'vitest'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import {
+  FRAMEWORK_PACKAGE_ALLOWLIST,
+  isFrameworkPackage,
+} from '../core/addon/addon-package.service.js'
+
+function repoRoot(): string {
+  return path.resolve(__dirname, '..', '..', '..', '..')
+}
+
+interface PackageJsonView {
+  readonly name: string
+  readonly system: boolean
+  readonly path: string
+}
+
+function readPackageJson(pkgJsonPath: string): PackageJsonView | null {
+  try {
+    const raw: unknown = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'))
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+    const obj = raw as Record<string, unknown>
+    const name = obj['name']
+    if (typeof name !== 'string') return null
+    const camstack = obj['camstack']
+    const isSystem = camstack !== null
+      && typeof camstack === 'object'
+      && !Array.isArray(camstack)
+      && (camstack as Record<string, unknown>)['system'] === true
+    return { name, system: isSystem, path: pkgJsonPath }
+  } catch {
+    return null
+  }
+}
+
+function discoverWorkspacePackages(): readonly PackageJsonView[] {
+  const packagesDir = path.join(repoRoot(), 'packages')
+  if (!fs.existsSync(packagesDir)) return []
+  const results: PackageJsonView[] = []
+  for (const entry of fs.readdirSync(packagesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    const pkgJson = path.join(packagesDir, entry.name, 'package.json')
+    if (!fs.existsSync(pkgJson)) continue
+    const view = readPackageJson(pkgJson)
+    if (view !== null) results.push(view)
+  }
+  return results
+}
+
+describe('framework package allow-list — manifest parity', () => {
+  it('every allow-listed package exists in `packages/` with camstack.system: true', () => {
+    const pkgs = discoverWorkspacePackages()
+    for (const name of FRAMEWORK_PACKAGE_ALLOWLIST) {
+      const match = pkgs.find((p) => p.name === name)
+      expect(match, `expected ${name} in packages/`).toBeDefined()
+      expect(match?.system, `${name} must declare camstack.system: true`).toBe(true)
+    }
+  })
+
+  it('every workspace package with camstack.system: true is in the allow-list', () => {
+    const systemPkgs = discoverWorkspacePackages().filter((p) => p.system)
+    const allowSet = new Set(FRAMEWORK_PACKAGE_ALLOWLIST)
+    const orphans = systemPkgs.filter((p) => !allowSet.has(p.name))
+    expect(orphans.map((p) => p.name)).toEqual([])
+  })
+})
+
+describe('isFrameworkPackage', () => {
+  it('returns true for every allow-listed package', () => {
+    for (const name of FRAMEWORK_PACKAGE_ALLOWLIST) {
+      expect(isFrameworkPackage(name)).toBe(true)
+    }
+  })
+
+  it('returns false for addons and unknown packages', () => {
+    expect(isFrameworkPackage('@camstack/addon-stream-broker')).toBe(false)
+    expect(isFrameworkPackage('left-pad')).toBe(false)
+    expect(isFrameworkPackage('')).toBe(false)
+    expect(isFrameworkPackage('@camstack')).toBe(false)
+  })
+})

package/src/__tests__/https-e2e.test.ts

@@ -0,0 +1,118 @@
+/**
+ * HTTPS E2E tests — verify self-signed cert generation, HTTPS serving, and WSS agent connection.
+ */
+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 * as https from 'node:https'
+import { X509Certificate } from 'node:crypto'
+// Import directly from source submodule because vitest+swc doesn't resolve
+// `export * from './tls/index.js'` barrel re-exports in the @camstack/core index.
+import { ensureTlsCert, loadTlsCert } from '../../../../packages/core/src/tls/cert-manager'
+
+describe('HTTPS E2E', () => {
+  let tmpDir: string
+
+  beforeAll(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'camstack-https-e2e-'))
+  })
+
+  afterAll(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('generates a valid self-signed cert on first call', async () => {
+    const result = await ensureTlsCert(tmpDir)
+    expect(result.generated).toBe(true)
+
+    // Verify cert file is valid PEM
+    const certPem = fs.readFileSync(result.certPath, 'utf-8')
+    expect(certPem).toContain('-----BEGIN CERTIFICATE-----')
+
+    // Parse and validate
+    const x509 = new X509Certificate(certPem)
+    expect(x509.subject).toContain('CN=camstack.local')
+
+    // Check SAN includes localhost
+    const san = x509.subjectAltName ?? ''
+    expect(san).toContain('DNS:localhost')
+    expect(san).toContain('IP Address:127.0.0.1')
+
+    // Check validity (at least 1 year)
+    const validTo = new Date(x509.validTo)
+    const oneYear = new Date()
+    oneYear.setFullYear(oneYear.getFullYear() + 1)
+    expect(validTo.getTime()).toBeGreaterThan(oneYear.getTime() - 86400000)
+  })
+
+  it('reuses existing cert on subsequent calls', async () => {
+    const first = await ensureTlsCert(tmpDir)
+    const second = await ensureTlsCert(tmpDir)
+    expect(second.generated).toBe(false)
+
+    const cert1 = fs.readFileSync(first.certPath, 'utf-8')
+    const cert2 = fs.readFileSync(second.certPath, 'utf-8')
+    expect(cert1).toBe(cert2)
+  })
+
+  it('serves HTTPS with the generated cert', async () => {
+    const { certPath, keyPath } = await ensureTlsCert(tmpDir)
+    const { cert, key } = loadTlsCert(certPath, keyPath)
+
+    const server = https.createServer({ cert, key }, (_req, res) => {
+      res.writeHead(200, { 'Content-Type': 'text/plain' })
+      res.end('camstack-ok')
+    })
+
+    const port = 10000 + Math.floor(Math.random() * 50000)
+    await new Promise<void>((resolve) => server.listen(port, '127.0.0.1', resolve))
+
+    try {
+      const body = await new Promise<string>((resolve, reject) => {
+        const req = https.request(
+          { hostname: '127.0.0.1', port, path: '/', method: 'GET', rejectUnauthorized: false },
+          (res) => {
+            let data = ''
+            res.on('data', (c) => { data += c })
+            res.on('end', () => resolve(data))
+          },
+        )
+        req.on('error', reject)
+        req.end()
+      })
+
+      expect(body).toBe('camstack-ok')
+    } finally {
+      server.close()
+    }
+  })
+
+  it('TLS disabled falls back to HTTP', async () => {
+    // When tls.enabled = false, server should work over plain HTTP
+    // This is a config-level test, verified by checking that FastifyAdapter
+    // receives no https options when tls is disabled
+    const http = await import('node:http')
+    const server = http.createServer((_req, res) => {
+      res.writeHead(200)
+      res.end('http-ok')
+    })
+
+    const port = 10000 + Math.floor(Math.random() * 50000)
+    await new Promise<void>((resolve) => server.listen(port, '127.0.0.1', resolve))
+
+    try {
+      const body = await new Promise<string>((resolve, reject) => {
+        http.get(`http://127.0.0.1:${port}/`, (res) => {
+          let data = ''
+          res.on('data', (c) => { data += c })
+          res.on('end', () => resolve(data))
+        }).on('error', reject)
+      })
+
+      expect(body).toBe('http-ok')
+    } finally {
+      server.close()
+    }
+  })
+})