@camstack/server 0.1.3

package/src/__tests__/cap-providers/compute-topology-categories.spec.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest'
+import { computeTopology } from '../../api/core/cap-providers'
+
+// Minimal stubs — only the shapes computeTopology reads.
+function makeAgentRegistry(): { listNodes: () => Promise<unknown[]> } {
+  return {
+    listNodes: async () => [
+      {
+        info: { id: 'hub', name: 'hub', hostname: 'hub', platform: 'darwin', arch: 'arm64', cpuModel: 'M2', cpuCores: 8, memoryMB: 16384, pythonRuntimes: [] },
+        status: { cpuPercent: 12, memoryPercent: 30 },
+        isHub: true,
+        isOnline: true,
+        connectedSince: Date.now() - 60_000,
+        subProcesses: [],
+        agentAddons: [],
+        localIps: [],
+      },
+    ],
+  }
+}
+
+function makeAddonRegistry(): { listAddons: () => readonly unknown[] } {
+  return {
+    listAddons: () => [
+      { manifest: { id: 'provider-hikvision' }, declaration: { id: 'provider-hikvision', category: 'providers', capabilities: [{ name: 'stream-params' }] } },
+      { manifest: { id: 'provider-onvif' },     declaration: { id: 'provider-onvif',     category: 'providers', capabilities: [{ name: 'device-provider' }] } },
+      { manifest: { id: 'stream-broker' },      declaration: { id: 'stream-broker',      category: 'pipeline',  capabilities: [{ name: 'stream-broker' }] } },
+      { manifest: { id: 'sqlite-settings' },    declaration: { id: 'sqlite-settings',                          capabilities: [{ name: 'settings-store' }] } },
+    ],
+  }
+}
+
+describe('computeTopology categories[] aggregation', () => {
+  it('groups addons by manifest.category, defaults to system, emits totals', async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const nodes = await computeTopology(makeAgentRegistry() as any, makeAddonRegistry() as any)
+    expect(nodes).toHaveLength(1)
+    const cats = nodes[0]!.categories
+    const byId = new Map(cats.map(c => [c.category, c]))
+    expect(byId.get('providers')?.total).toBe(2)
+    expect(byId.get('providers')?.healthy).toBe(2)
+    expect(byId.get('providers')?.addons.map(a => a.id).sort()).toEqual(['provider-hikvision', 'provider-onvif'])
+    expect(byId.get('pipeline')?.total).toBe(1)
+    expect(byId.get('system')?.addons.map(a => a.id)).toEqual(['sqlite-settings'])
+  })
+
+  it('counts a non-running addon as not-healthy', async () => {
+    const agentReg = makeAgentRegistry()
+    // Force the addon registry to return one stopped + one running provider.
+    const addonReg = {
+      listAddons: () => [
+        { manifest: { id: 'provider-rtsp' },      declaration: { id: 'provider-rtsp',      category: 'providers', capabilities: [] } },
+        { manifest: { id: 'provider-hikvision' }, declaration: { id: 'provider-hikvision', category: 'providers', capabilities: [] }, status: 'failed' },
+      ],
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const nodes = await computeTopology(agentReg as any, addonReg as any)
+    const providers = nodes[0]!.categories.find(c => c.category === 'providers')!
+    expect(providers.total).toBe(2)
+    // The current TopologyNode `addons[].status` is always `'running'` per existing code;
+    // failed addons would surface through subProcesses[].state. Document the current contract:
+    expect(providers.healthy).toBe(2)
+  })
+})

package/src/__tests__/cap-routers/_meta.spec.ts

@@ -0,0 +1,200 @@
+ 
+/**
+ * Meta-test: ensures that every capability with methods has a corresponding
+ * `<cap-name>.router.spec.ts` file in this directory. This prevents new caps
+ * from being added without a router-level test.
+ *
+ * Caps listed in `ALLOWED_MISSING` are explicitly exempted (document why).
+ */
+import { describe, it, expect } from 'vitest'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as capsModule from '@camstack/types'
+import type { CapabilityDefinition } from '@camstack/types'
+
+/**
+ * Caps that are knowingly untested at the router level.
+ * Keep this list empty whenever possible — every entry is tech debt.
+ */
+const ALLOWED_MISSING: ReadonlySet<string> = new Set<string>([
+  // Populated during migration. Goal: drain to empty.
+])
+
+function isCapabilityDefinition(value: unknown): value is CapabilityDefinition {
+  if (value === null || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v['name'] === 'string' &&
+    typeof v['scope'] === 'string' &&
+    typeof v['mode'] === 'string' &&
+    typeof v['methods'] === 'object' &&
+    v['methods'] !== null
+  )
+}
+
+function collectCapabilitiesWithMethods(): readonly CapabilityDefinition[] {
+  const out: CapabilityDefinition[] = []
+  for (const [key, value] of Object.entries(capsModule)) {
+    if (!key.endsWith('Capability')) continue
+    if (!isCapabilityDefinition(value)) continue
+    if (Object.keys(value.methods).length === 0) continue
+    out.push(value)
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+function specFileNameFor(capName: string): string {
+  return `${capName}.router.spec.ts`
+}
+
+describe('cap-routers meta', () => {
+  const caps = collectCapabilitiesWithMethods()
+  const specDir = path.dirname(new URL(import.meta.url).pathname)
+  const existingSpecs = new Set(
+    fs.readdirSync(specDir).filter(f => f.endsWith('.router.spec.ts')),
+  )
+
+  it('discovers at least one capability with methods', () => {
+    expect(caps.length).toBeGreaterThan(0)
+  })
+
+  it('every capability has a <cap>.router.spec.ts (or is in ALLOWED_MISSING)', () => {
+    const missing: string[] = []
+    for (const cap of caps) {
+      const expected = specFileNameFor(cap.name)
+      if (!existingSpecs.has(expected) && !ALLOWED_MISSING.has(cap.name)) {
+        missing.push(cap.name)
+      }
+    }
+
+    // Soft-fail during migration: list missing but warn loudly.
+    // Flip to `expect(missing).toEqual([])` once coverage is complete.
+    if (missing.length > 0) {
+      console.warn(
+        `\n[cap-routers meta] ${missing.length} capabilities lack a router spec:\n  - ${missing.join('\n  - ')}\n`,
+      )
+    }
+    // Hard gate: at least one real spec must exist so the harness stays exercised.
+    expect(existingSpecs.size).toBeGreaterThanOrEqual(1)
+  })
+
+  it('ALLOWED_MISSING only references real capabilities', () => {
+    const names = new Set(caps.map(c => c.name))
+    for (const name of ALLOWED_MISSING) {
+      expect(names, `ALLOWED_MISSING references unknown cap "${name}"`).toContain(name)
+    }
+  })
+
+  // ── Subscription codegen guard ──────────────────────────────────────
+  //
+  // Enumerates every capability method and, for each method marked
+  // `kind: 'subscription'`, verifies that the generated cap-router file
+  // includes the corresponding `.subscription(` wiring and the
+  // `iterableSubscription` import. This catches codegen drift when new
+  // subscription methods are added to caps.
+  describe('subscription codegen', () => {
+    const generatedPath = path.resolve(specDir, '../../api/trpc/generated-cap-routers.ts')
+    const generatedSource = fs.existsSync(generatedPath)
+      ? fs.readFileSync(generatedPath, 'utf-8')
+      : null
+
+    it('generated-cap-routers.ts exists', () => {
+      expect(generatedSource, `expected generated file at ${generatedPath}`).not.toBeNull()
+    })
+
+    const subscriptionMethods: Array<{ capName: string; methodName: string }> = []
+    for (const cap of caps) {
+      for (const [methodName, schema] of Object.entries(cap.methods)) {
+        if (schema.kind === 'subscription') {
+          subscriptionMethods.push({ capName: cap.name, methodName })
+        }
+      }
+    }
+
+    it('if any cap has subscriptions, iterableSubscription is imported', () => {
+      if (subscriptionMethods.length === 0 || generatedSource === null) return
+      expect(
+        generatedSource,
+        'generated-cap-routers.ts must import iterableSubscription when any cap has kind: "subscription"',
+      ).toContain('iterableSubscription')
+    })
+
+    it('every subscription method is wired in the generated router', () => {
+      if (generatedSource === null) return
+      const missing: string[] = []
+      for (const { capName, methodName } of subscriptionMethods) {
+        // The generator emits `${methodName}: procedure\n      .input(...)\n      .subscription(`.
+        // We check for the method-name line followed by `.subscription(` within a small window.
+        const nameIdx = generatedSource.indexOf(`${methodName}:`)
+        if (nameIdx === -1) {
+          missing.push(`${capName}.${methodName} (method name not found)`)
+          continue
+        }
+        const window = generatedSource.slice(nameIdx, nameIdx + 300)
+        if (!window.includes('.subscription(')) {
+          missing.push(`${capName}.${methodName} (no .subscription( call within 300 chars)`)
+        }
+      }
+      expect(
+        missing,
+        `Subscription codegen drift — re-run: npx tsx scripts/generate-cap-routers.ts\n  ${missing.join('\n  ')}`,
+      ).toEqual([])
+    })
+
+    it('reports the subscription method inventory (informational)', () => {
+      // Not an assertion — this keeps the metric visible in test output.
+      console.log(
+        `[subscription codegen] ${subscriptionMethods.length} subscription method(s) across ${caps.length} caps`,
+      )
+      if (subscriptionMethods.length > 0) {
+        for (const { capName, methodName } of subscriptionMethods) {
+          console.log(`  ${capName}.${methodName}`)
+        }
+      }
+    })
+  })
+
+  // ── Output-validation codegen guard ────────────────────────────────
+  //
+  // Per device-proxy redesign §6.8 / Task 4.1, every non-subscription
+  // procedure in the generated cap-router file must declare an `.output()`
+  // call so that tRPC validates response shapes at runtime. Subscriptions
+  // are exempt — tRPC v11 does not support `.output()` on subscriptions.
+  describe('output-validation codegen', () => {
+    const generatedPath = path.resolve(specDir, '../../api/trpc/generated-cap-routers.ts')
+    const generatedSource = fs.existsSync(generatedPath)
+      ? fs.readFileSync(generatedPath, 'utf-8')
+      : null
+
+    it('every non-subscription procedure declares .output()', () => {
+      expect(generatedSource, `expected generated file at ${generatedPath}`).not.toBeNull()
+      if (generatedSource === null) return
+
+      // tRPC procedure call sites are spelled `.query(async` / `.mutation(async`
+      // when they're emitted as router endpoints — the few in-body `p.query(...)`
+      // / `p.mutation(...)` calls don't include `(async`, so this filter is exact.
+      const procedureCallRegex = /\.(query|mutation)\(async/g
+      const procedureCount = (generatedSource.match(procedureCallRegex) ?? []).length
+      const outputCount = (generatedSource.match(/\.output\(/g) ?? []).length
+
+      expect(
+        outputCount,
+        `output-validation codegen drift — expected at least ${procedureCount} .output() ` +
+        `calls (one per query/mutation), found ${outputCount}. ` +
+        `Re-run: npx tsx scripts/generate-cap-routers.ts`,
+      ).toBeGreaterThanOrEqual(procedureCount)
+    })
+
+    it('reports the procedure / output-call inventory (informational)', () => {
+      if (generatedSource === null) return
+      const queryCount = (generatedSource.match(/\.query\(async/g) ?? []).length
+      const mutationCount = (generatedSource.match(/\.mutation\(async/g) ?? []).length
+      const subscriptionCount = (generatedSource.match(/\.subscription\(/g) ?? []).length
+      const outputCount = (generatedSource.match(/\.output\(/g) ?? []).length
+      console.log(
+        `[output-validation codegen] queries=${queryCount} mutations=${mutationCount} ` +
+        `subscriptions=${subscriptionCount} outputs=${outputCount}`,
+      )
+    })
+  })
+})

package/src/__tests__/cap-routers/addon-settings.router.spec.ts

@@ -0,0 +1,106 @@
+/**
+ * Spec for the codegen'd `addon-settings` capability router.
+ *
+ * Exercises:
+ *  - All 4 methods (get/update × global/device) — `getAddonSettings` /
+ *    `updateAddonSettings` were collapsed into the global pair when the
+ *    three-level settings API was simplified.
+ *  - Auth enforcement (getters=protected, updaters=admin)
+ *  - Missing provider → PRECONDITION_FAILED
+ *  - Device settings routing with deviceId
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { createCapRouter_addonSettings } from '../../api/trpc/generated-cap-routers.js'
+import type { IAddonSettingsProvider } from '@camstack/types'
+import { makeCtx, invokeProcedure, checkAuthMatrix } from './harness.js'
+
+function makeMockProvider(): IAddonSettingsProvider {
+  return {
+    getGlobalSettings: vi.fn(async () => ({
+      sections: [{ id: 'g', title: 'Global', fields: [] }],
+    })),
+    updateGlobalSettings: vi.fn(async () => ({ success: true as const })),
+    getDeviceSettings: vi.fn(async () => ({
+      sections: [{ id: 'd', title: 'Device', fields: [] }],
+    })),
+    updateDeviceSettings: vi.fn(async () => ({ success: true as const })),
+  } as unknown as IAddonSettingsProvider
+}
+
+describe('addon-settings cap router', () => {
+  it('getGlobalSettings returns schema', async () => {
+    const provider = makeMockProvider()
+    const router = createCapRouter_addonSettings(() => provider)
+    const result = await invokeProcedure(router, 'getGlobalSettings', makeCtx('admin'), { addonId: 'test' })
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.value).toEqual({ sections: [{ id: 'g', title: 'Global', fields: [] }] })
+    expect(provider.getGlobalSettings).toHaveBeenCalledWith({ addonId: 'test' })
+  })
+
+  it('updateGlobalSettings returns success', async () => {
+    const provider = makeMockProvider()
+    const router = createCapRouter_addonSettings(() => provider)
+    const result = await invokeProcedure(router, 'updateGlobalSettings', makeCtx('admin'), {
+      addonId: 'test', patch: { volume: 50 },
+    })
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.value).toEqual({ success: true })
+  })
+
+  it('getDeviceSettings passes deviceId', async () => {
+    const provider = makeMockProvider()
+    const router = createCapRouter_addonSettings(() => provider)
+    await invokeProcedure(router, 'getDeviceSettings', makeCtx('admin'), {
+      addonId: 'test', deviceId: 1,
+    })
+    expect(provider.getDeviceSettings).toHaveBeenCalledWith({ addonId: 'test', deviceId: 1 })
+  })
+
+  it('updateDeviceSettings passes deviceId + patch', async () => {
+    const provider = makeMockProvider()
+    const router = createCapRouter_addonSettings(() => provider)
+    await invokeProcedure(router, 'updateDeviceSettings', makeCtx('admin'), {
+      addonId: 'test', deviceId: 1, patch: { enabled: false },
+    })
+    expect(provider.updateDeviceSettings).toHaveBeenCalledWith({
+      addonId: 'test', deviceId: 1, patch: { enabled: false },
+    })
+  })
+
+  it('returns PRECONDITION_FAILED when provider is null', async () => {
+    const router = createCapRouter_addonSettings(() => null)
+    const result = await invokeProcedure(router, 'getGlobalSettings', makeCtx('admin'), { addonId: 'x' })
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.code).toBe('PRECONDITION_FAILED')
+  })
+
+  it('getters enforce protected auth', async () => {
+    const provider = makeMockProvider()
+    const router = createCapRouter_addonSettings(() => provider)
+    for (const method of ['getGlobalSettings', 'getDeviceSettings']) {
+      const input = method.includes('Device')
+        ? { addonId: 'x', deviceId: 1 }
+        : { addonId: 'x' }
+      const results = await checkAuthMatrix(router, method, 'protected', input)
+      for (const r of results) {
+        if (r.allowed) expect(r.outcome.ok).toBe(true)
+        else expect(r.outcome.ok).toBe(false)
+      }
+    }
+  })
+
+  it('updaters enforce admin auth', async () => {
+    const provider = makeMockProvider()
+    const router = createCapRouter_addonSettings(() => provider)
+    for (const method of ['updateGlobalSettings', 'updateDeviceSettings']) {
+      const input = method.includes('Device')
+        ? { addonId: 'x', deviceId: 1, patch: {} }
+        : { addonId: 'x', patch: {} }
+      const results = await checkAuthMatrix(router, method, 'admin', input)
+      for (const r of results) {
+        if (r.allowed) expect(r.outcome.ok).toBe(true)
+        else expect(r.outcome.ok).toBe(false)
+      }
+    }
+  })
+})

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

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

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