@camstack/server 0.2.2 → 1.0.1

package/src/__tests__/cap-routers/device-manager-aggregate.router.spec.ts

@@ -1,194 +0,0 @@
-/**
- * E2E test for the device-manager aggregator via the generated tRPC cap
- * router. Verifies the wire shape of `getDeviceSettingsAggregate`,
- * `getDeviceLiveInfoAggregate`, and `updateDeviceField` — the three
- * aggregator methods the admin UI consumes.
- *
- * Covers:
- *  - input validation at the router boundary
- *  - schema shape roundtrip (provider → router → caller)
- *  - auth enforcement (getters = protected, updateDeviceField = admin)
- */
-import { describe, it, expect, vi } from 'vitest'
-import { createCapRouter_deviceManager } from '../../api/trpc/generated-cap-routers.js'
-import type { IDeviceManagerProvider } from '@camstack/types'
-import { makeCtx, invokeProcedure } from './harness.js'
-
-function makeProvider(): IDeviceManagerProvider {
-  return {
-    // Aggregator methods we exercise
-    getDeviceSettingsAggregate: vi.fn(async ({ deviceId }) => ({
-      sections: [
-        {
-          id: 'identity',
-          title: 'Identity',
-          tab: 'general',
-          order: 0,
-          fields: [
-            {
-              type: 'text',
-              key: '_stableId',
-              label: 'Stable ID',
-              readonlyField: true,
-              value: String(deviceId),
-            },
-          ],
-        },
-        {
-          id: 'motion-tuning',
-          title: 'Motion Tuning',
-          tab: 'detection',
-          order: 5,
-          fields: [
-            {
-              type: 'number',
-              key: 'threshold',
-              label: 'Threshold',
-              writerCapName: 'motion-detection',
-              writerAddonId: 'motion-wasm',
-              source: 'settings',
-              value: 20,
-            },
-          ],
-        },
-      ],
-    })),
-    getDeviceLiveInfoAggregate: vi.fn(async ({ deviceId }) => ({
-      sections: [
-        {
-          id: 'orchestrator-live',
-          title: 'Pipeline Status',
-          tab: 'detection',
-          order: 100,
-          fields: [
-            {
-              type: 'text',
-              key: 'assignedRunner',
-              label: 'Assigned Runner',
-              readonlyField: true,
-              source: 'live',
-              value: deviceId === 1 ? 'hub' : '',
-            },
-          ],
-        },
-      ],
-    })),
-    updateDeviceField: vi.fn(async () => ({ success: true as const })),
-
-    // Placeholders for the other device-manager cap methods we don't
-    // exercise here — kept as no-ops so the IDeviceManagerProvider
-    // interface is fully satisfied.
-    registerDevice: vi.fn() as IDeviceManagerProvider['registerDevice'],
-    removeDevice: vi.fn() as IDeviceManagerProvider['removeDevice'],
-    persistConfig: vi.fn() as IDeviceManagerProvider['persistConfig'],
-    loadConfig: vi.fn(async () => ({})) as IDeviceManagerProvider['loadConfig'],
-    listPersistedByAddon: vi.fn(async () => []) as IDeviceManagerProvider['listPersistedByAddon'],
-    listAll: vi.fn(async () => []) as IDeviceManagerProvider['listAll'],
-    getDevice: vi.fn(async () => null) as IDeviceManagerProvider['getDevice'],
-    getChildren: vi.fn(async () => []) as IDeviceManagerProvider['getChildren'],
-    getStreamSources: vi.fn(async () => []) as IDeviceManagerProvider['getStreamSources'],
-    getConfigSchema: vi.fn(async () => []) as IDeviceManagerProvider['getConfigSchema'],
-    getSettingsSchema: vi.fn(async () => null) as IDeviceManagerProvider['getSettingsSchema'],
-    updateConfig: vi.fn(async () => ({
-      success: true as const,
-    })) as IDeviceManagerProvider['updateConfig'],
-    enable: vi.fn(async () => ({ success: true as const })) as IDeviceManagerProvider['enable'],
-    disable: vi.fn(async () => ({ success: true as const })) as IDeviceManagerProvider['disable'],
-    remove: vi.fn(async () => ({ success: true as const })) as IDeviceManagerProvider['remove'],
-    getStreamProfileMap: vi.fn(async () => ({})) as IDeviceManagerProvider['getStreamProfileMap'],
-    setStreamProfileMap: vi.fn(async () => ({
-      success: true as const,
-    })) as IDeviceManagerProvider['setStreamProfileMap'],
-    probeStreams: vi.fn(async () => []) as IDeviceManagerProvider['probeStreams'],
-    getBindings: vi.fn(async ({ deviceId }: { deviceId: number }) => ({
-      deviceId,
-      entries: [],
-    })) as IDeviceManagerProvider['getBindings'],
-    setWrapperActive: vi.fn() as IDeviceManagerProvider['setWrapperActive'],
-  }
-}
-
-describe('device-manager aggregator via tRPC router', () => {
-  const DEVICE_ID = 1
-
-  it('getDeviceSettingsAggregate returns the merged shape for a known device', async () => {
-    const provider = makeProvider()
-    const router = createCapRouter_deviceManager(() => provider)
-    const result = await invokeProcedure(router, 'getDeviceSettingsAggregate', makeCtx('admin'), {
-      deviceId: DEVICE_ID,
-    })
-
-    expect(result.ok).toBe(true)
-    if (!result.ok) return
-    const value = result.value as {
-      sections: readonly { id: string; tab?: string; fields: readonly unknown[] }[]
-    }
-    expect(value.sections.map((s) => s.id)).toEqual(['identity', 'motion-tuning'])
-    expect(provider.getDeviceSettingsAggregate).toHaveBeenCalledWith({ deviceId: DEVICE_ID })
-  })
-
-  it('getDeviceLiveInfoAggregate returns live sections', async () => {
-    const provider = makeProvider()
-    const router = createCapRouter_deviceManager(() => provider)
-    const result = await invokeProcedure(router, 'getDeviceLiveInfoAggregate', makeCtx('admin'), {
-      deviceId: DEVICE_ID,
-    })
-
-    expect(result.ok).toBe(true)
-    if (!result.ok) return
-    const value = result.value as {
-      sections: readonly { fields: readonly { key?: string; value?: unknown }[] }[]
-    }
-    const runner = value.sections[0]!.fields.find((f) => f.key === 'assignedRunner')
-    expect(runner?.value).toBe('hub')
-  })
-
-  it('updateDeviceField forwards the full payload (deviceId, writerCap, writerAddon, key, value)', async () => {
-    const provider = makeProvider()
-    const router = createCapRouter_deviceManager(() => provider)
-    const result = await invokeProcedure(router, 'updateDeviceField', makeCtx('admin'), {
-      deviceId: DEVICE_ID,
-      writerCapName: 'motion-detection',
-      writerAddonId: 'motion-wasm',
-      key: 'threshold',
-      value: 42,
-    })
-
-    expect(result.ok).toBe(true)
-    expect(provider.updateDeviceField).toHaveBeenCalledWith({
-      deviceId: DEVICE_ID,
-      writerCapName: 'motion-detection',
-      writerAddonId: 'motion-wasm',
-      key: 'threshold',
-      value: 42,
-    })
-  })
-
-  it('updateDeviceField enforces admin auth', async () => {
-    const provider = makeProvider()
-    const router = createCapRouter_deviceManager(() => provider)
-
-    const payload = {
-      deviceId: DEVICE_ID,
-      writerCapName: 'motion-detection',
-      writerAddonId: 'motion-wasm',
-      key: 'threshold',
-      value: 1,
-    }
-    const viewer = await invokeProcedure(router, 'updateDeviceField', makeCtx('user'), payload)
-    expect(viewer.ok).toBe(false)
-    if (!viewer.ok) expect(viewer.code).toBe('FORBIDDEN')
-
-    const admin = await invokeProcedure(router, 'updateDeviceField', makeCtx('admin'), payload)
-    expect(admin.ok).toBe(true)
-  })
-
-  it('router returns PRECONDITION_FAILED when the provider is missing', async () => {
-    const router = createCapRouter_deviceManager(() => null)
-    const result = await invokeProcedure(router, 'getDeviceSettingsAggregate', makeCtx('admin'), {
-      deviceId: DEVICE_ID,
-    })
-    expect(result.ok).toBe(false)
-    if (!result.ok) expect(result.code).toBe('PRECONDITION_FAILED')
-  })
-})

package/src/__tests__/cap-routers/harness.ts

@@ -1,163 +0,0 @@
-/**
- * Test harness for codegen'd capability tRPC routers.
- *
- * Provides helpers to:
- *  - Build a minimal `TrpcContext` per auth role (anonymous/user/admin/agent)
- *  - Wrap a `createCapRouter_X` with a mock provider and get a typed caller
- *  - Assert that a procedure enforces the expected auth level
- *  - Drive subscriptions via mock push callbacks
- *
- * This harness is the foundation for per-cap `.router.spec.ts` files. See
- * `system-info.router.spec.ts` for a usage example.
- */
-import { TRPCError } from '@trpc/server'
-import type { TrpcContext, AuthenticatedAgent } from '../../api/trpc/trpc.context.js'
-
-// v2 auth model — there's no role enum, just `isAdmin`. The harness
-// exposes four synthetic identities covering every gate we ship:
-//   anonymous : no auth (null user)
-//   user      : authenticated, isAdmin=false (the only non-admin tier)
-//   admin     : authenticated, isAdmin=true
-//   agent     : authenticated, isAdmin=true with `agentId` set
-export type AuthLevel = 'public' | 'protected' | 'admin'
-export type TestRole = 'anonymous' | 'user' | 'admin' | 'agent'
-
-/** Build an AuthenticatedAgent stub for a given synthetic identity. */
-export function makeUser(
-  role: Exclude<TestRole, 'anonymous'>,
-  overrides: Partial<AuthenticatedAgent> = {},
-): AuthenticatedAgent {
-  const isAdmin = role === 'admin' || role === 'agent'
-  const base: AuthenticatedAgent = {
-    id: `user-${role}`,
-    username: role,
-    isAdmin,
-    permissions: { isAdmin, allowedProviders: '*', allowedDevices: {} },
-    isApiKey: false,
-  }
-  if (role === 'agent') {
-    return { ...base, agentId: 'agent-test', ...overrides }
-  }
-  return { ...base, ...overrides }
-}
-
-/** Build a minimal TrpcContext with the given identity (or `anonymous` for an unauthenticated ctx). */
-export function makeCtx(role: TestRole, overrides: Partial<AuthenticatedAgent> = {}): TrpcContext {
-  const user = role === 'anonymous' ? null : makeUser(role, overrides)
-  // `req` is only used by subscription/WS plumbing which we don't exercise here.
-  // Cast via `unknown` to avoid pulling in a full Fastify stub.
-  return { user, req: {} as unknown as TrpcContext['req'] }
-}
-
-/**
- * Identities that SHOULD pass for each auth level (positive set).
- * Anything outside the allow-list should receive UNAUTHORIZED or FORBIDDEN.
- */
-export const ALLOWED_ROLES_BY_AUTH: Readonly<Record<AuthLevel, readonly TestRole[]>> = {
-  public: ['anonymous', 'user', 'admin', 'agent'],
-  protected: ['user', 'admin', 'agent'],
-  admin: ['admin', 'agent'],
-}
-
-export const ALL_ROLES: readonly TestRole[] = ['anonymous', 'user', 'admin', 'agent']
-
-/** Determine whether a synthetic identity should be allowed to call a procedure with the given auth level. */
-export function isRoleAllowed(role: TestRole, auth: AuthLevel): boolean {
-  return ALLOWED_ROLES_BY_AUTH[auth].includes(role)
-}
-
-/**
- * Minimal router interface returned by the codegen. Each method is a tRPC procedure;
- * calling `.createCaller(ctx)` returns an object with one async function per method.
- */
-export interface CreateCallerCapableRouter {
-  readonly createCaller: (ctx: TrpcContext) => Record<string, (input?: unknown) => unknown>
-}
-
-/**
- * Invoke a procedure and capture the outcome (ok | trpc error code | other throw).
- * Useful for auth matrix assertions without leaking exceptions.
- */
-export async function invokeProcedure(
-  router: CreateCallerCapableRouter,
-  procedure: string,
-  ctx: TrpcContext,
-  input?: unknown,
-): Promise<{ ok: true; value: unknown } | { ok: false; code: string; message: string }> {
-  try {
-    const caller = router.createCaller(ctx)
-    const fn = caller[procedure]
-    if (typeof fn !== 'function') {
-      return { ok: false, code: 'NOT_FOUND', message: `procedure "${procedure}" missing on caller` }
-    }
-    const value = await fn(input)
-    return { ok: true, value }
-  } catch (err) {
-    if (err instanceof TRPCError) {
-      return { ok: false, code: err.code, message: err.message }
-    }
-    const message = err instanceof Error ? err.message : String(err)
-    return { ok: false, code: 'THROWN', message }
-  }
-}
-
-/**
- * Assert that a procedure enforces the expected auth level: each identity in `ALL_ROLES`
- * should either succeed (allowed) or fail with UNAUTHORIZED/FORBIDDEN (denied).
- *
- * @returns An array of `{ role, allowed, outcome }` describing what happened — useful
- *          for building focused expectations in the calling test.
- */
-export async function checkAuthMatrix(
-  router: CreateCallerCapableRouter,
-  procedure: string,
-  auth: AuthLevel,
-  input?: unknown,
-): Promise<
-  ReadonlyArray<{
-    readonly role: TestRole
-    readonly allowed: boolean
-    readonly outcome: Awaited<ReturnType<typeof invokeProcedure>>
-  }>
-> {
-  const results: Array<{
-    role: TestRole
-    allowed: boolean
-    outcome: Awaited<ReturnType<typeof invokeProcedure>>
-  }> = []
-  for (const role of ALL_ROLES) {
-    const outcome = await invokeProcedure(router, procedure, makeCtx(role), input)
-    results.push({ role, allowed: isRoleAllowed(role, auth), outcome })
-  }
-  return results
-}
-
-/**
- * Collect the first N values pushed to a subscription within `timeoutMs`.
- * The codegen wraps subscriptions with `iterableSubscription`, which yields an
- * async iterator — this helper just reads `count` values and returns them.
- */
-export async function collectSubscription<T = unknown>(
-  iter: AsyncIterable<T>,
-  count: number,
-  timeoutMs = 1000,
-): Promise<readonly T[]> {
-  const out: T[] = []
-  const iterator = iter[Symbol.asyncIterator]()
-  const deadline = Date.now() + timeoutMs
-  while (out.length < count) {
-    const remaining = deadline - Date.now()
-    if (remaining <= 0) break
-    const result = await Promise.race([
-      iterator.next(),
-      new Promise<IteratorResult<T>>((_, reject) =>
-        setTimeout(() => reject(new Error('collectSubscription timeout')), remaining),
-      ),
-    ])
-    if (result.done) break
-    out.push(result.value)
-  }
-  // Best-effort cleanup — async generators from iterableSubscription handle return() in their finally block.
-  await iterator.return?.()
-  return out
-}

package/src/__tests__/cap-routers/metrics-provider.router.spec.ts

@@ -1,133 +0,0 @@
-/**
- * Example spec exercising the codegen'd metrics-provider router end-to-end:
- *  - Wires a mock provider into `createCapRouter_metricsProvider`
- *  - Verifies happy-path query dispatch + output validation for getCurrent()
- *  - Verifies provider-missing → PRECONDITION_FAILED
- */
-import { describe, it, expect } from 'vitest'
-import { createCapRouter_metricsProvider } from '../../api/trpc/generated-cap-routers.js'
-import { type IMetricsProvider } from '@camstack/types'
-import { makeCtx, invokeProcedure } from './harness.js'
-
-function makeMockProvider(overrides: Partial<IMetricsProvider> = {}): IMetricsProvider {
-  return {
-    collectSnapshot: async () => ({
-      cpu: { total: 0, user: 0, system: 0, irq: 0, nice: 0, loadAvg: [0, 0, 0], cores: 1 },
-      memory: {
-        percent: 0,
-        totalBytes: 0,
-        usedBytes: 0,
-        availableBytes: 0,
-        swapUsedBytes: 0,
-        swapTotalBytes: 0,
-      },
-      gpu: null,
-      network: {
-        rxBytes: 0,
-        txBytes: 0,
-        rxPackets: 0,
-        txPackets: 0,
-        rxErrors: 0,
-        txErrors: 0,
-        timestampMs: 0,
-      },
-      disk: { readBytes: 0, writeBytes: 0, readOps: 0, writeOps: 0, timestampMs: 0 },
-      pressure: { cpu: null, memory: null, io: null },
-      process: { openFds: 0, threadCount: 0, activeHandles: 0, activeRequests: 0 },
-      cpuTemperature: null,
-      timestampMs: 0,
-    }),
-    getCached: async () => null,
-    getCurrent: async () => ({
-      cpuPercent: 42.5,
-      memoryPercent: 68.2,
-      memoryUsedMB: 8192,
-      memoryTotalMB: 16384,
-      diskPercent: 55.1,
-      temperature: 48.0,
-    }),
-    getDiskSpace: async ({ dirPath }) => ({
-      path: dirPath,
-      totalBytes: 0,
-      usedBytes: 0,
-      availableBytes: 0,
-      percent: 0,
-    }),
-    getGpuInfo: async () => null,
-    getCpuTemperature: async () => null,
-    getProcessStats: async () => [],
-    ...overrides,
-  }
-}
-
-describe('createCapRouter_metricsProvider', () => {
-  describe('happy path', () => {
-    it('dispatches getCurrent() to the provider and returns typed metrics', async () => {
-      const provider = makeMockProvider()
-      const router = createCapRouter_metricsProvider(() => provider)
-
-      const outcome = await invokeProcedure(router, 'getCurrent', makeCtx('admin'))
-
-      expect(outcome.ok).toBe(true)
-      if (outcome.ok) {
-        expect(outcome.value).toMatchObject({
-          cpuPercent: 42.5,
-          memoryPercent: 68.2,
-          memoryUsedMB: 8192,
-          memoryTotalMB: 16384,
-        })
-      }
-    })
-
-    it('propagates optional fields (temperature, gpuPercent)', async () => {
-      const router = createCapRouter_metricsProvider(() =>
-        makeMockProvider({
-          getCurrent: async () => ({
-            cpuPercent: 10,
-            memoryPercent: 20,
-            memoryUsedMB: 1024,
-            memoryTotalMB: 8192,
-            gpuPercent: 75,
-            gpuMemoryPercent: 60,
-          }),
-        }),
-      )
-
-      const outcome = await invokeProcedure(router, 'getCurrent', makeCtx('admin'))
-
-      expect(outcome.ok).toBe(true)
-      if (outcome.ok) {
-        const value = outcome.value as { gpuPercent?: number; gpuMemoryPercent?: number }
-        expect(value.gpuPercent).toBe(75)
-        expect(value.gpuMemoryPercent).toBe(60)
-      }
-    })
-  })
-
-  describe('auth', () => {
-    it('rejects anonymous (protected endpoint)', async () => {
-      const router = createCapRouter_metricsProvider(() => makeMockProvider())
-      const outcome = await invokeProcedure(router, 'getCurrent', makeCtx('anonymous'))
-      expect(outcome.ok).toBe(false)
-      if (!outcome.ok) expect(outcome.code).toBe('UNAUTHORIZED')
-    })
-
-    it('allows viewer (protected endpoint)', async () => {
-      const router = createCapRouter_metricsProvider(() => makeMockProvider())
-      const outcome = await invokeProcedure(router, 'getCurrent', makeCtx('user'))
-      expect(outcome.ok).toBe(true)
-    })
-  })
-
-  describe('missing provider', () => {
-    it('throws PRECONDITION_FAILED when getProvider returns null', async () => {
-      const router = createCapRouter_metricsProvider(() => null)
-      const outcome = await invokeProcedure(router, 'getCurrent', makeCtx('admin'))
-      expect(outcome.ok).toBe(false)
-      if (!outcome.ok) {
-        expect(outcome.code).toBe('PRECONDITION_FAILED')
-        expect(outcome.message).toContain('metrics-provider')
-      }
-    })
-  })
-})

package/src/__tests__/cap-routers/null-provider-guard.spec.ts

@@ -1,64 +0,0 @@
-/**
- * Comprehensive null-provider spec — verifies that EVERY codegen'd cap
- * router returns PRECONDITION_FAILED when the provider is null.
- *
- * This is a safety net: if a new cap is added and the codegen'd router
- * doesn't guard against a null provider, this test catches it.
- *
- * NOTE: some caps have methods that require non-void input (z.object({...})).
- * For those, Zod input validation may reject our empty input before the
- * null-provider check runs — in which case we expect BAD_REQUEST or
- * PRECONDITION_FAILED (both are acceptable: the point is that the call
- * does NOT succeed and return garbage data).
- */
-import { describe, it, expect } from 'vitest'
-import * as generatedModule from '../../api/trpc/generated-cap-routers.js'
-import { makeCtx, invokeProcedure } from './harness.js'
-
-// Discover all createCapRouter_* functions from the generated module
-const routerFactories: Array<{ name: string; factory: (getProvider: () => null) => unknown }> = []
-for (const [key, value] of Object.entries(generatedModule)) {
-  if (key.startsWith('createCapRouter_') && typeof value === 'function') {
-    routerFactories.push({
-      name: key.replace('createCapRouter_', ''),
-      factory: value as (getProvider: () => null) => unknown,
-    })
-  }
-}
-
-describe('null-provider guard — all capabilities', () => {
-  it(`discovers ${routerFactories.length} cap router factories`, () => {
-    expect(routerFactories.length).toBeGreaterThanOrEqual(30)
-  })
-
-  for (const { name, factory } of routerFactories) {
-    it(`${name}: null provider does not return success`, async () => {
-      const router = factory(() => null)
-
-      // Find the first method on the router's caller
-      const caller = (
-        router as { createCaller: (ctx: unknown) => Record<string, unknown> }
-      ).createCaller(makeCtx('admin'))
-
-      const methods = Object.keys(caller).filter(
-        (k) => typeof caller[k] === 'function' && !k.startsWith('_'),
-      )
-
-      if (methods.length === 0) return // No methods — skip
-
-      // Try the first method with no input (will work for void-input methods)
-      const firstMethod = methods[0]!
-      const result = await invokeProcedure(
-        router as { createCaller: (ctx: unknown) => Record<string, (input?: unknown) => unknown> },
-        firstMethod,
-        makeCtx('admin'),
-      )
-
-      // The call should NOT succeed — either PRECONDITION_FAILED (null provider
-      // caught by codegen guard) or BAD_REQUEST (input validation before guard)
-      // or INTERNAL_SERVER_ERROR (provider method call on null).
-      // Any of these is acceptable — the important thing is ok !== true.
-      expect(result.ok, `${name}.${firstMethod} returned success with null provider!`).toBe(false)
-    })
-  }
-})