@camstack/server 1.0.0 → 1.0.1

package/src/__tests__/cap-routers/broker-routing.router.spec.ts

@@ -1,177 +0,0 @@
-/**
- * Routing regression spec for the `broker` system-collection cap.
- *
- * The bug: `broker` is `scope:'system', mode:'collection'`. Two addons
- * register a `broker` provider, each owning a DISJOINT id set
- * (mqtt-broker owns `mqtt_*`, provider-homeassistant owns `ha_*`). The
- * generated collection mount only fans out the array-output methods
- * (`list` / `listProviders`); every id-keyed method (`get` / `getSettings`
- * / `remove` / `testConnection` / …) falls through to `providers[0]`
- * (the FIRST-registered provider = mqtt-broker). So operating on an HA
- * broker `ha_1` hit mqtt-broker → "broker 'ha_1' not found".
- *
- * The fix: each broker carries its owning `addonId`; the admin UI threads
- * it back as the `{ addonId }` system-collection selector so the call
- * routes to the OWNING provider via `getProviderByAddonId`. Providers
- * also return `null` (not throw) for ids they don't own, so the
- * no-addonId fallback degrades gracefully.
- *
- * This spec exercises `createCapRouter_broker` with the SAME selector
- * the generated mount builds (registry-backed: addonId → provider, else
- * first-provider aggregate with array methods fanned out). It registers
- * two mock providers and asserts:
- *  - `list()` returns both, each tagged with its `addonId`.
- *  - `get({id:'ha_1'}, addonId:'ha')` routes to the HA provider.
- *  - `get({id:'ha_1'})` WITHOUT addonId returns null (graceful) — the
- *    HA-owned id isn't in providers[0]'s registry, so it doesn't throw.
- *  - `listProviders()` aggregates both providers' entries.
- */
-import { describe, it, expect } from 'vitest'
-import { createCapRouter_broker } from '../../api/trpc/generated-cap-routers.js'
-import { type IBrokerProvider, type BrokerInfo, type BrokerProviderInfo } from '@camstack/types'
-import { concatCollection } from '../../api/trpc/cap-mount-helpers.js'
-import { makeCtx, invokeProcedure } from './harness.js'
-
-/**
- * A self-contained mock `broker` provider that owns a fixed set of
- * broker ids and self-tags every returned record with its `addonId`.
- * Returns `null` / no-op for ids it does NOT own (never throws) — the
- * exact graceful-degradation contract the real providers must honour.
- */
-function makeProvider(addonId: string, ownedIds: readonly string[], kind: string): IBrokerProvider {
-  const owns = (id: string): boolean => ownedIds.includes(id)
-  const infoFor = (id: string): BrokerInfo => ({
-    id,
-    addonId,
-    name: `${kind}-${id}`,
-    kind,
-    status: 'connected',
-    info: {},
-    lastCheckedAt: null,
-    error: null,
-  })
-  return {
-    list: async () => ownedIds.map(infoFor),
-    get: async ({ id }) => (owns(id) ? infoFor(id) : null),
-    listProviders: async (): Promise<BrokerProviderInfo[]> => [
-      { addonId, kinds: [{ kind, label: kind }] },
-    ],
-    add: async () => ({ id: 'new' }),
-    remove: async () => {
-      // no-op for foreign ids (and owned ids in this mock)
-    },
-    testConnection: async ({ id }) =>
-      owns(id) ? { ok: true, latencyMs: 1 } : { ok: false, error: 'unknown broker' },
-    getSettings: async ({ id }) => (owns(id) ? { secret: id } : null),
-    setSettings: async () => {
-      // no-op
-    },
-    getBrokerConfig: async ({ id }) => (owns(id) ? { url: id } : null),
-    getSettingsSchema: async ({ kind: k }) => (k === kind ? { form: kind } : null),
-    testSettings: async () => ({ ok: true }),
-    publish: async () => null,
-    subscribe: async () => ({ subscriptionId: 's' }),
-    unsubscribe: async () => {
-      // no-op
-    },
-    getState: async () => null,
-    getStatus: async () => ({ brokerCount: ownedIds.length, connectedCount: ownedIds.length }),
-  }
-}
-
-/**
- * Mirror of the generated collection mount selector for `broker`
- * (`generated-cap-mounts.ts`): addonId → that provider directly; else a
- * first-provider aggregate whose array-output methods are
- * `concatCollection`-fanned. Two providers registered in order:
- * mqtt (owns `mqtt_1`) first, ha (owns `ha_1`) second.
- */
-function makeSelector(): (addonId?: string) => IBrokerProvider | null {
-  const mqtt = makeProvider('mqtt', ['mqtt_1'], 'mqtt')
-  const ha = makeProvider('ha', ['ha_1'], 'home-assistant')
-  const byAddonId: Record<string, IBrokerProvider> = { mqtt, ha }
-  const providers: readonly IBrokerProvider[] = [mqtt, ha]
-  return (addonId?: string): IBrokerProvider | null => {
-    if (addonId !== undefined) return byAddonId[addonId] ?? null
-    const first = providers[0]!
-    return {
-      ...first,
-      list: concatCollection(providers, 'list') as IBrokerProvider['list'],
-      listProviders: concatCollection(
-        providers,
-        'listProviders',
-      ) as IBrokerProvider['listProviders'],
-    }
-  }
-}
-
-describe('broker cap — addonId ownership routing', () => {
-  it('list() aggregates both providers, each broker tagged with its addonId', async () => {
-    const selector = makeSelector()
-    const router = createCapRouter_broker((_ctx, addonId) => selector(addonId))
-
-    const outcome = await invokeProcedure(router, 'list', makeCtx('admin'), {})
-
-    expect(outcome.ok).toBe(true)
-    if (!outcome.ok) return
-    const rows = outcome.value as BrokerInfo[]
-    const byId = new Map(rows.map((r) => [r.id, r]))
-    expect(byId.get('mqtt_1')?.addonId).toBe('mqtt')
-    expect(byId.get('ha_1')?.addonId).toBe('ha')
-  })
-
-  it('get({id:ha_1}, addonId:ha) routes to the HA provider (not mqtt-broker)', async () => {
-    const selector = makeSelector()
-    const router = createCapRouter_broker((_ctx, addonId) => selector(addonId))
-
-    const outcome = await invokeProcedure(router, 'get', makeCtx('admin'), {
-      id: 'ha_1',
-      addonId: 'ha',
-    })
-
-    expect(outcome.ok).toBe(true)
-    if (!outcome.ok) return
-    const row = outcome.value as BrokerInfo | null
-    expect(row).not.toBeNull()
-    expect(row?.id).toBe('ha_1')
-    expect(row?.addonId).toBe('ha')
-  })
-
-  it('get({id:ha_1}) WITHOUT addonId returns null gracefully (first provider does not own it)', async () => {
-    const selector = makeSelector()
-    const router = createCapRouter_broker((_ctx, addonId) => selector(addonId))
-
-    const outcome = await invokeProcedure(router, 'get', makeCtx('admin'), { id: 'ha_1' })
-
-    expect(outcome.ok).toBe(true)
-    if (!outcome.ok) return
-    expect(outcome.value).toBeNull()
-  })
-
-  it('testConnection({id:ha_1}, addonId:ha) routes to HA provider and succeeds', async () => {
-    const selector = makeSelector()
-    const router = createCapRouter_broker((_ctx, addonId) => selector(addonId))
-
-    const outcome = await invokeProcedure(router, 'testConnection', makeCtx('admin'), {
-      id: 'ha_1',
-      addonId: 'ha',
-    })
-
-    expect(outcome.ok).toBe(true)
-    if (!outcome.ok) return
-    expect(outcome.value).toEqual({ ok: true, latencyMs: 1 })
-  })
-
-  it('listProviders() aggregates both providers entries', async () => {
-    const selector = makeSelector()
-    const router = createCapRouter_broker((_ctx, addonId) => selector(addonId))
-
-    const outcome = await invokeProcedure(router, 'listProviders', makeCtx('admin'))
-
-    expect(outcome.ok).toBe(true)
-    if (!outcome.ok) return
-    const entries = outcome.value as BrokerProviderInfo[]
-    const addonIds = entries.map((e) => e.addonId).toSorted()
-    expect(addonIds).toEqual(['ha', 'mqtt'])
-  })
-})

package/src/__tests__/cap-routers/cap-route-error-formatter.spec.ts

@@ -1,125 +0,0 @@
-/**
- * Unit tests for the cap-route-error-formatter.
- *
- * `formatTrpcError` is a pure function — no tRPC plumbing required.
- * We hand-craft minimal TRPCError-like / DefaultErrorShape-like objects
- * to verify the augmentation logic.
- */
-import { describe, it, expect } from 'vitest'
-import { TRPCError } from '@trpc/server'
-import { CapRouteError } from '@camstack/kernel'
-import { formatTrpcError } from '../../api/trpc/cap-route-error-formatter.js'
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-/** Minimal DefaultErrorShape stub. */
-function makeShape(
-  overrides: Partial<{ message: string }> = {},
-): Parameters<typeof formatTrpcError>[0]['shape'] {
-  return {
-    message: overrides.message ?? 'Something went wrong',
-    code: -32603, // INTERNAL_SERVER_ERROR code number
-    data: {
-      code: 'INTERNAL_SERVER_ERROR',
-      httpStatus: 500,
-    },
-  }
-}
-
-/** Build a TRPCError-like object that formatTrpcError accepts. */
-function makeTrpcError(
-  message: string,
-  cause?: Error,
-): Parameters<typeof formatTrpcError>[0]['error'] {
-  return new TRPCError({
-    code: 'PRECONDITION_FAILED',
-    message,
-    cause,
-  })
-}
-
-// ── Tests ─────────────────────────────────────────────────────────────────────
-
-describe('formatTrpcError', () => {
-  it('returns shape unchanged when error is not a CapRouteError', () => {
-    const shape = makeShape({ message: 'Boom' })
-    const error = makeTrpcError('Some generic error')
-    const result = formatTrpcError({ error, shape })
-    expect(result).toStrictEqual(shape)
-    expect(result.data).not.toHaveProperty('capRouteReason')
-  })
-
-  it('augments shape with capRouteReason when error.cause is a CapRouteError', () => {
-    const capRouteErr = new CapRouteError('my-cap', undefined, {
-      reason: 'no-provider',
-      rejected: [{ kind: 'hub-in-process', why: 'no provider bound' }],
-    })
-    const shape = makeShape()
-    const error = makeTrpcError('Capability "my-cap" provider not available', capRouteErr)
-    const result = formatTrpcError({ error, shape })
-
-    expect(result.data.capRouteReason).toBe('no-provider')
-    expect(result.data.capRouteRejected).toStrictEqual([
-      { kind: 'hub-in-process', why: 'no provider bound' },
-    ])
-    expect(result.data.capRouteNodeId).toBeUndefined()
-    // Original shape fields preserved
-    expect(result.message).toBe(shape.message)
-    expect(result.code).toBe(shape.code)
-  })
-
-  it('augments shape with capRouteReason when error itself is a CapRouteError', () => {
-    const capRouteErr = new CapRouteError('some-cap', undefined, {
-      reason: 'node-offline',
-      nodeId: 'node-abc',
-      rejected: [{ kind: 'remote-moleculer', why: 'node node-abc is offline' }],
-    })
-    const shape = makeShape()
-    // Wrap as TRPCError with the CapRouteError AS the cause
-    const error = makeTrpcError('Transport failed', capRouteErr)
-    const result = formatTrpcError({ error, shape })
-
-    expect(result.data.capRouteReason).toBe('node-offline')
-    expect(result.data.capRouteNodeId).toBe('node-abc')
-    expect(result.data.capRouteRejected).toHaveLength(1)
-  })
-
-  it('surfaces transport-failed reason correctly (not absent provider)', () => {
-    const capRouteErr = new CapRouteError('stream-params', 'getStatus', {
-      reason: 'transport-failed',
-      rejected: [{ kind: 'hub-local-uds', why: 'socket closed' }],
-    })
-    const shape = makeShape()
-    const error = makeTrpcError('Transport failed', capRouteErr)
-    const result = formatTrpcError({ error, shape })
-
-    expect(result.data.capRouteReason).toBe('transport-failed')
-    expect(result.data.capRouteRejected).toStrictEqual([
-      { kind: 'hub-local-uds', why: 'socket closed' },
-    ])
-  })
-
-  it('walks a nested cause chain to find a CapRouteError', () => {
-    const capRouteErr = new CapRouteError('ptz', undefined, {
-      reason: 'cap-unknown',
-      rejected: [],
-    })
-    // Wrap two levels deep
-    const innerError = new Error('dispatch failed', { cause: capRouteErr })
-    const shape = makeShape()
-    const error = makeTrpcError('Outer error', innerError)
-    const result = formatTrpcError({ error, shape })
-
-    expect(result.data.capRouteReason).toBe('cap-unknown')
-  })
-
-  it('returns shape unchanged for a plain Error (non-CapRouteError cause)', () => {
-    const plainErr = new Error('plain cause')
-    const shape = makeShape()
-    const error = makeTrpcError('Wrapper', plainErr)
-    const result = formatTrpcError({ error, shape })
-
-    expect(result.data).not.toHaveProperty('capRouteReason')
-    expect(result).toStrictEqual(shape)
-  })
-})

package/src/__tests__/cap-routers/capabilities-node.spec.ts

@@ -1,68 +0,0 @@
-/**
- * Spec for the per-node singleton extension in capabilities.router.
- *
- * Exercises:
- *  - setActiveSingleton with nodeId → calls registry with (cap, addonId, nodeId)
- *    + persists `capabilities.singletonNode.<cap>.<nodeId>`
- *  - setActiveSingleton without nodeId → persists `capabilities.singleton.<cap>` (global key)
- *  - clearSingletonNodeOverride → calls registry.clearSingletonNodeOverride(cap, nodeId)
- *    + persists the per-node key as null
- */
-import { describe, it, expect, vi } from 'vitest'
-import type { CapabilityRegistry } from '@camstack/kernel'
-import type { ConfigService } from '../../core/config/config.service.js'
-import { createCapabilitiesRouter } from '../../api/core/capabilities.router.js'
-import { makeCtx } from './harness.js'
-
-function harness() {
-  const calls: { setActiveSingleton: unknown[][]; clear: unknown[][] } = {
-    setActiveSingleton: [],
-    clear: [],
-  }
-  const sets: Record<string, unknown> = {}
-  const registry = {
-    setActiveSingleton: vi.fn(async (...a: unknown[]) => {
-      calls.setActiveSingleton.push(a)
-    }),
-    clearSingletonNodeOverride: vi.fn((...a: unknown[]) => {
-      calls.clear.push(a)
-    }),
-    listCapabilities: () => [],
-  } as unknown as CapabilityRegistry
-  const config = {
-    set: (k: string, v: unknown) => {
-      sets[k] = v
-    },
-  } as unknown as ConfigService
-  const router = createCapabilitiesRouter(registry, config)
-  return { router, calls, sets, registry }
-}
-
-describe('capabilities.router — per-node singleton', () => {
-  it('setActiveSingleton with nodeId persists the per-node key', async () => {
-    const { router, calls, sets } = harness()
-    const caller = router.createCaller(makeCtx('admin'))
-    await caller.setActiveSingleton({
-      capability: 'webrtc-session',
-      addonId: 'webrtc-native',
-      nodeId: 'dev-agent-0',
-    })
-    expect(calls.setActiveSingleton[0]).toEqual(['webrtc-session', 'webrtc-native', 'dev-agent-0'])
-    expect(sets['capabilities.singletonNode.webrtc-session.dev-agent-0']).toBe('webrtc-native')
-  })
-
-  it('setActiveSingleton without nodeId persists the global key', async () => {
-    const { router, sets } = harness()
-    const caller = router.createCaller(makeCtx('admin'))
-    await caller.setActiveSingleton({ capability: 'webrtc-session', addonId: 'stream-broker' })
-    expect(sets['capabilities.singleton.webrtc-session']).toBe('stream-broker')
-  })
-
-  it('clearSingletonNodeOverride clears the per-node key', async () => {
-    const { router, calls, sets } = harness()
-    const caller = router.createCaller(makeCtx('admin'))
-    await caller.clearSingletonNodeOverride({ capability: 'webrtc-session', nodeId: 'dev-agent-0' })
-    expect(calls.clear[0]).toEqual(['webrtc-session', 'dev-agent-0'])
-    expect(sets['capabilities.singletonNode.webrtc-session.dev-agent-0']).toBe(null)
-  })
-})

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

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