@camstack/server 0.1.3

package/src/api/core/capabilities.router.ts

@@ -0,0 +1,119 @@
+/**
+ * Capability admin router — fixed core API (not a capability).
+ *
+ * Lets admins inspect the capability registry and set system/device
+ * overrides. Wraps `CapabilityRegistry` directly (kernel primitive).
+ */
+import { z } from 'zod'
+import type { CapabilityRegistry } from '@camstack/kernel'
+import type { ConfigService } from '../../core/config/config.service.js'
+import { trpcRouter, adminProcedure } from '../trpc/trpc.middleware.js'
+
+export function createCapabilitiesRouter(
+  registry: CapabilityRegistry | null,
+  config: ConfigService,
+) {
+  return trpcRouter({
+    listCapabilities: adminProcedure
+      .input(z.void())
+      .query(() => registry?.listCapabilities() ?? []),
+
+    getCapability: adminProcedure
+      .input(z.object({ name: z.string() }))
+      .query(({ input }) => {
+        if (!registry) return null
+        return registry.listCapabilities().find(
+          (c: { name: string }) => c.name === input.name,
+        ) ?? null
+      }),
+
+    setActiveSingleton: adminProcedure
+      .input(z.object({ capability: z.string(), addonId: z.string() }))
+      .output(z.void())
+      .mutation(async ({ input }) => {
+        if (!registry) throw new Error('Capability registry unavailable')
+        await registry.setActiveSingleton(input.capability, input.addonId)
+        config.update('capabilities', { [input.capability]: input.addonId })
+      }),
+
+    /**
+     * Set the enabled set of providers for a collection capability in
+     * one shot. Providers already registered on the capability that are
+     * NOT in `enabledAddonIds` get disabled; the ones in the list are
+     * re-enabled. Other collections are untouched. Intended as the
+     * save endpoint for a bulk multi-select UI.
+     */
+    setCollectionEnabledProviders: adminProcedure
+      .input(z.object({
+        capability: z.string(),
+        enabledAddonIds: z.array(z.string()),
+      }))
+      .output(z.void())
+      .mutation(({ input }) => {
+        if (!registry) throw new Error('Capability registry unavailable')
+        const caps = registry.listCapabilities()
+        const entry = caps.find((c) => c.name === input.capability)
+        if (!entry) throw new Error(`Capability "${input.capability}" not declared`)
+        if (entry.mode !== 'collection') {
+          throw new Error(`Capability "${input.capability}" is not a collection`)
+        }
+        const wanted = new Set(input.enabledAddonIds)
+        for (const providerId of entry.providers) {
+          if (wanted.has(providerId)) {
+            registry.enableCollectionProvider(input.capability, providerId)
+          } else {
+            registry.disableCollectionProvider(input.capability, providerId)
+          }
+        }
+      }),
+
+    setDeviceCapability: adminProcedure
+      .input(z.object({ deviceId: z.string(), capability: z.string(), addonId: z.string() }))
+      .output(z.void())
+      .mutation(({ input }) => {
+        if (!registry) throw new Error('Capability registry unavailable')
+        registry.setDeviceOverride(input.deviceId, input.capability, input.addonId)
+      }),
+
+    clearDeviceCapability: adminProcedure
+      .input(z.object({ deviceId: z.string(), capability: z.string() }))
+      .output(z.void())
+      .mutation(({ input }) => {
+        if (!registry) throw new Error('Capability registry unavailable')
+        registry.clearDeviceOverride(input.deviceId, input.capability)
+      }),
+
+    getDeviceCapabilities: adminProcedure
+      .input(z.object({ deviceId: z.string() }))
+      .output(z.record(z.string(), z.string()))
+      .query(({ input }) => {
+        if (!registry) return {}
+        const overrides = registry.getDeviceOverrides(input.deviceId)
+        const result: Record<string, string> = {}
+        for (const [cap, addonId] of overrides) {
+          result[cap] = addonId
+        }
+        return result
+      }),
+
+    setDeviceCollectionFilter: adminProcedure
+      .input(z.object({
+        deviceId: z.string(),
+        capability: z.string(),
+        addonIds: z.array(z.string()),
+      }))
+      .output(z.void())
+      .mutation(({ input }) => {
+        if (!registry) throw new Error('Capability registry unavailable')
+        registry.setDeviceCollectionFilter(input.deviceId, input.capability, input.addonIds)
+      }),
+
+    clearDeviceCollectionFilter: adminProcedure
+      .input(z.object({ deviceId: z.string(), capability: z.string() }))
+      .output(z.void())
+      .mutation(({ input }) => {
+        if (!registry) throw new Error('Capability registry unavailable')
+        registry.clearDeviceCollectionFilter(input.deviceId, input.capability)
+      }),
+  })
+}

package/src/api/core/collection-preference.ts

@@ -0,0 +1,40 @@
+/**
+ * Single canonical writer for the collection-capability enable/disable
+ * preference.
+ *
+ * A collection capability can have individual providers disabled by an
+ * operator. The disabled-set must survive a hub reboot — otherwise a
+ * provider an operator deliberately disabled (TURN relay, an auth or
+ * export backend, …) silently re-enables on the next restart.
+ *
+ * The persistence key/format is `capabilities.collection.<capName>` holding
+ * `JSON.stringify({ disabled: string[] })`. This module is the ONE place
+ * that writes that key so the format never drifts between the two callers
+ * (`capabilities` core router and the `addons` cap's
+ * `setCapabilityProviderEnabled`). The kernel `CapabilityRegistry` reads
+ * it back at boot through the `CollectionConfigReader` hook wired in
+ * `addon-registry.service.ts`.
+ */
+import type { ConfigService } from '../../core/config/config.service'
+
+/** ConfigService key holding the persisted disabled-set for a collection cap. */
+export function collectionPreferenceKey(capability: string): string {
+  return `capabilities.collection.${capability}`
+}
+
+/**
+ * Persist the disabled-addonId set for a collection capability. Pass the
+ * authoritative set straight from `registry.listCapabilities()` after the
+ * enable/disable mutation so the stored value always mirrors the live
+ * registry state.
+ */
+export function persistCollectionDisabled(
+  configService: ConfigService,
+  capability: string,
+  disabled: readonly string[],
+): void {
+  configService.set(
+    collectionPreferenceKey(capability),
+    JSON.stringify({ disabled: [...disabled] }),
+  )
+}

package/src/api/core/event-bus-proxy.router.ts

@@ -0,0 +1,45 @@
+/**
+ * EventBus proxy router — allows forked workers to emit events to the
+ * hub's EventBus via tRPC.
+ *
+ * Workers call `trpc.eventBusProxy.emit.mutate(event)` from their
+ * `context.eventBus.emit()` implementation. The hub-side router
+ * deserializes the event and emits it on the real EventBus.
+ *
+ * Subscribe/getRecent are routed through the existing `live.onEvent`
+ * subscription and `events` query routers — no duplication needed here.
+ *
+ * Introduced in session 7 (EventBus wiring for forked addons).
+ */
+import { z } from 'zod'
+import type { IEventBus } from '@camstack/types'
+import { trpcRouter, protectedProcedure } from '../trpc/trpc.middleware.js'
+
+const SystemEventInputSchema = z.object({
+  id: z.string(),
+  timestamp: z.string(), // ISO 8601 — converted to Date on emit
+  source: z.object({
+    type: z.string(),
+    id: z.string(),
+  }),
+  category: z.string(),
+  data: z.record(z.string(), z.unknown()),
+})
+
+export function createEventBusProxyRouter(eventBus: IEventBus) {
+  return trpcRouter({
+    emit: protectedProcedure
+      .input(SystemEventInputSchema)
+      .output(z.object({ ok: z.literal(true) }))
+      .mutation(({ input }) => {
+        eventBus.emit({
+          id: input.id,
+          timestamp: new Date(input.timestamp),
+          source: { type: input.source.type, id: input.source.id },
+          category: input.category,
+          data: input.data,
+        })
+        return { ok: true as const }
+      }),
+  })
+}

package/src/api/core/hwaccel.router.ts

@@ -0,0 +1,81 @@
+/**
+ * Hwaccel router — fixed core API (not a capability).
+ *
+ * Thin wrapper around the per-node `$hwaccel.resolve` Moleculer
+ * service. The hub-local instance (same process) serves the default
+ * `resolve` call; the per-node `resolveForNode` action targets any
+ * node in the cluster — used by the admin UI pipeline / NodeDetail
+ * pages to show the hwaccel backends available on each agent.
+ *
+ * Cross-node behaviour: `resolveForNode({ nodeId })` forwards via
+ * `broker.call('$hwaccel.resolve', params, { nodeID })`. Every node
+ * (hub + forked worker + remote agent) registers `$hwaccel` at
+ * bootstrap, so any reachable nodeId works.
+ */
+import { z } from 'zod'
+import type { ServiceBroker } from 'moleculer'
+import type { HwAccelResolution } from '@camstack/types'
+import { trpcRouter, adminProcedure } from '../trpc/trpc.middleware.js'
+
+const HwAccelBackendSchema = z.enum([
+  'videotoolbox', 'cuda', 'nvdec', 'vaapi', 'qsv',
+  'd3d11va', 'dxva2', 'amf', 'vdpau', 'drm',
+])
+
+const HwAccelPreferSchema = z.union([HwAccelBackendSchema, z.literal('none')]).nullable().optional()
+
+const HwAccelResolutionSchema = z.object({
+  preferred: z.array(HwAccelBackendSchema).readonly(),
+  rationale: z.string(),
+})
+
+export function createHwAccelRouter(broker: ServiceBroker | null) {
+  return trpcRouter({
+    /** Probe the current hub process. */
+    resolve: adminProcedure
+      .input(z.object({ prefer: HwAccelPreferSchema }).optional())
+      .output(HwAccelResolutionSchema)
+      .query(async ({ input }) => {
+        if (!broker) throw new Error('Moleculer broker not available')
+        const params = { prefer: input?.prefer ?? null }
+        return broker.call('$hwaccel.resolve', params) as Promise<HwAccelResolution>
+      }),
+
+    /** Probe a specific node in the cluster — used by per-agent UI cards. */
+    resolveForNode: adminProcedure
+      .input(z.object({ nodeId: z.string(), prefer: HwAccelPreferSchema }))
+      .output(HwAccelResolutionSchema)
+      .query(async ({ input }) => {
+        if (!broker) throw new Error('Moleculer broker not available')
+        const params = { prefer: input.prefer ?? null }
+        return broker.call('$hwaccel.resolve', params, { nodeID: input.nodeId }) as Promise<HwAccelResolution>
+      }),
+
+    /** List every node currently reachable and the hwaccel each resolves to. */
+    resolveAll: adminProcedure
+      .output(z.array(z.object({
+        nodeId: z.string(),
+        resolution: HwAccelResolutionSchema,
+      })))
+      .query(async () => {
+        if (!broker) throw new Error('Moleculer broker not available')
+        const registry = (broker as unknown as { registry: { getNodeList: (opts: { onlyAvailable: boolean }) => readonly { id: string }[] } }).registry
+        const nodes = registry.getNodeList({ onlyAvailable: true })
+        const results = await Promise.all(
+          nodes.map(async (n) => {
+            try {
+              const resolution = await broker.call('$hwaccel.resolve', { prefer: null }, { nodeID: n.id }) as HwAccelResolution
+              return { nodeId: n.id, resolution }
+            } catch (err) {
+              const msg = err instanceof Error ? err.message : String(err)
+              return {
+                nodeId: n.id,
+                resolution: { preferred: [] as const, rationale: `resolve failed: ${msg}` },
+              }
+            }
+          }),
+        )
+        return results
+      }),
+  })
+}

package/src/api/core/live-events.router.ts

@@ -0,0 +1,60 @@
+/**
+ * Live events router — fixed core API (not a capability).
+ *
+ * Higher-level live-subscription API consumed by the admin UI dashboard.
+ * Wraps `EventBusService` with per-device permission enforcement.
+ */
+import { z } from 'zod'
+import type { EventBusService } from '../../core/events/event-bus.service.js'
+import type { AddonRegistryService } from '../../core/addon/addon-registry.service.js'
+import { trpcRouter, protectedProcedure, iterableSubscription } from '../trpc/trpc.middleware.js'
+
+export function createLiveEventsRouter(
+  eb: EventBusService,
+  ar: AddonRegistryService,
+) {
+  return trpcRouter({
+    recentSystemEvents: protectedProcedure
+      .input(z.object({
+        category: z.string().optional(),
+        limit: z.number().optional(),
+      }).optional())
+      .query(({ input }) => eb.getRecent(input ?? {}, input?.limit ?? 50)),
+
+    onEvent: protectedProcedure
+      .input(z.object({ category: z.string().optional() }))
+      .subscription(({ input }) => {
+        return iterableSubscription<{ id: string; timestamp: Date; source: { type: string; id: string | number }; category: string; data: Record<string, unknown> }>((push) => {
+          const filter: Record<string, unknown> = {}
+          if (input.category) filter.category = input.category
+          return eb.subscribe(filter, push)
+        })
+      }),
+
+    onDeviceEvent: protectedProcedure
+      .input(z.object({ deviceId: z.number() }))
+      .subscription(({ input, ctx }) => {
+        return iterableSubscription<unknown>((push) => {
+          const deviceRegistry = ar.getDeviceRegistry()
+          const device = deviceRegistry.getById(input.deviceId)
+          if (!device) throw new Error(`Device id=${input.deviceId} not found`)
+          // Permission check — new IDevice has no providerId; admin bypass only
+          if (!ctx.user.isAdmin) {
+            const ad = ctx.user.permissions?.allowedDevices
+            if (!ad) throw new Error('Access denied')
+            // Find which addon owns this device to determine the provider key
+            const ownerAddonId = deviceRegistry.getAddonId(input.deviceId)
+            if (!ownerAddonId) throw new Error('Access denied')
+            const pd = ad[ownerAddonId]
+            // Permission lists are still keyed by stableId — that's the
+            // external admin-facing identifier. Resolve the device's
+            // stableId for the membership check.
+            if (!pd || (pd !== '*' && !pd.includes(device.stableId))) {
+              throw new Error('Access denied')
+            }
+          }
+          return eb.subscribe({ source: { type: 'device', id: input.deviceId } }, push)
+        })
+      }),
+  })
+}

package/src/api/core/logs.router.ts

@@ -0,0 +1,162 @@
+/**
+ * Logs router — fixed core API (not a capability).
+ *
+ * Queries and streams log entries via `LoggingService` (thin NestJS DI
+ * wrapper over `LogManager` from `@camstack/core`). Admin can read
+ * everything; viewers/protected users only see entries matching their
+ * allowed providers scope (filtered in `query`).
+ */
+import { z } from 'zod'
+import type { LoggingService } from '../../core/logging/logging.service.js'
+import { trpcRouter, protectedProcedure, adminProcedure, iterableSubscription } from '../trpc/trpc.middleware.js'
+import type { LogEntry } from '@camstack/types'
+
+const LogLevelSchema = z.enum(['debug', 'info', 'warn', 'error'])
+
+const LogTagsSchema = z.object({
+  agentId: z.string().optional(),
+  nodeId: z.string().optional(),
+  /** Numeric progressive id (or its string form for legacy callers). */
+  deviceId: z.union([z.string(), z.number()]).optional(),
+  deviceName: z.string().optional(),
+  integrationId: z.string().optional(),
+  addonId: z.string().optional(),
+  streamId: z.string().optional(),
+  streamName: z.string().optional(),
+  sessionId: z.string().optional(),
+  /**
+   * Correlation id used to scope a single short-lived operation
+   * (e.g. a `testCreationField` probe). The Add-Device modal generates
+   * one per dialog open and providers tag their loggers with it so the
+   * modal can stream test logs without a deviceId (the device doesn't
+   * exist yet).
+   */
+  requestId: z.string().optional(),
+})
+
+/** Wire shape of a log entry — timestamp is serialised to ISO string by tRPC. */
+const LogEntrySchema = z.object({
+  timestamp: z.string(),
+  level: z.string(),
+  scope: z.string().optional(),
+  message: z.string(),
+  tags: z.record(z.string(), z.string().optional()).optional(),
+  /**
+   * Ad-hoc structured payload attached to the log call (e.g.
+   * `{error, brokerId, sourceType, url}` for stream-broker errors).
+   * Tags are filterable structural fields; meta is the per-call
+   * payload operators read in the expanded LogStream row.
+   */
+  meta: z.record(z.string(), z.unknown()).optional(),
+})
+
+const LogEntryArraySchema = z.array(LogEntrySchema)
+
+export function createLogsRouter(logging: LoggingService) {
+  return trpcRouter({
+    query: adminProcedure
+      .input(z.object({
+        level: LogLevelSchema.optional(),
+        since: z.number().optional(),
+        until: z.number().optional(),
+        limit: z.number().optional(),
+        tags: LogTagsSchema.optional(),
+      }))
+      .output(LogEntryArraySchema)
+      .query(({ input, ctx }) => {
+        const filter: Record<string, unknown> = { limit: input.limit ?? 100 }
+        if (input.level) filter.level = input.level
+        if (input.since !== undefined) filter.since = new Date(input.since)
+        if (input.until !== undefined) filter.until = new Date(input.until)
+        if (input.tags) filter.tags = input.tags
+        const entries: LogEntry[] = logging.query(filter)
+        const filtered = (() => {
+          if (!ctx.user.isAdmin) {
+            const ap = ctx.user.permissions?.allowedProviders
+            if (ap && ap !== '*') {
+              const allowed = ap as string[]
+              return entries.filter(e => {
+                const addonId = e.tags?.addonId
+                if (typeof addonId !== 'string') return false
+                return allowed.some(p => {
+                  const bare = p.startsWith('addon:') ? p.slice('addon:'.length) : p
+                  return addonId === bare || addonId.startsWith(bare)
+                })
+              })
+            }
+          }
+          return entries
+        })()
+        return filtered.map(e => ({
+          timestamp: e.timestamp instanceof Date ? e.timestamp.toISOString() : String(e.timestamp),
+          level: e.level,
+          ...(e.scope !== undefined ? { scope: e.scope } : {}),
+          message: e.message,
+          // Tags carry mixed primitive types (numeric deviceId is common —
+          // see kernel/capability-registry.ts logging calls). The wire
+          // schema is Record<string,string>, so stringify here. Mirrors
+          // the same normalisation applied in `subscribe` below.
+          tags: e.tags
+            ? Object.fromEntries(
+                Object.entries(e.tags).map(([k, v]) => [k, v === undefined ? undefined : String(v)]),
+              )
+            : undefined,
+          ...(e.meta !== undefined ? { meta: e.meta } : {}),
+        }))
+      }),
+
+    /**
+     * Drop matching entries from the in-memory ring buffer. Powers
+     * the UI's "Clear logs" button — without server-side purge, the
+     * cleared rows reappear on the next page open from the historical
+     * `query`. Admin-only so a viewer can't wipe context other ops
+     * are reading.
+     */
+    clear: adminProcedure
+      .input(z.object({
+        level: LogLevelSchema.optional(),
+        since: z.number().optional(),
+        until: z.number().optional(),
+        tags: LogTagsSchema.optional(),
+      }))
+      .output(z.object({ removed: z.number().int().nonnegative() }))
+      .mutation(({ input }) => {
+        const filter: Record<string, unknown> = {}
+        if (input.level) filter.level = input.level
+        if (input.since !== undefined) filter.since = new Date(input.since)
+        if (input.until !== undefined) filter.until = new Date(input.until)
+        if (input.tags) filter.tags = input.tags
+        const removed = logging.clear(filter)
+        return { removed }
+      }),
+
+    subscribe: protectedProcedure
+      .input(z.object({
+        level: LogLevelSchema.optional(),
+        tags: LogTagsSchema.optional(),
+      }))
+      .subscription(({ input }) => {
+        return iterableSubscription<unknown>((push) => {
+          return logging.subscribe(
+            {
+              level: input.level,
+              tags: input.tags as Record<string, string> | undefined,
+            },
+            (entry: { timestamp: Date | string | number; level: string; message: string; scope?: string; tags?: Record<string, string | number | undefined>; meta?: Record<string, unknown> }) => {
+              const stringifiedTags = entry.tags
+                ? Object.fromEntries(Object.entries(entry.tags).map(([k, v]) => [k, v === undefined ? undefined : String(v)]))
+                : undefined
+              push({
+                timestamp: entry.timestamp instanceof Date ? entry.timestamp.toISOString() : String(entry.timestamp),
+                level: entry.level,
+                message: entry.message,
+                scope: entry.scope,
+                tags: stringifiedTags,
+                meta: entry.meta,
+              })
+            },
+          )
+        })
+      }),
+  })
+}

package/src/api/core/notifications.router.ts

@@ -0,0 +1,65 @@
+/**
+ * Notifications router — fixed core API (not a capability).
+ *
+ * Routes events by category to registered outputs. The NotificationService
+ * is a singleton from @camstack/core; individual outputs are still provided
+ * by addons via the `notification-output` capability collection.
+ */
+import { z } from 'zod'
+import type { NotificationService } from '@camstack/core'
+import { trpcRouter, protectedProcedure, adminProcedure } from '../trpc/trpc.middleware.js'
+
+const NotificationOutputSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  icon: z.string(),
+})
+
+const SendTestResultSchema = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+})
+
+export function createNotificationsRouter(ns: NotificationService | null) {
+  return trpcRouter({
+    listOutputs: protectedProcedure
+      .input(z.void())
+      .output(z.array(NotificationOutputSchema).readonly())
+      .query(() => {
+        if (!ns) return []
+        return ns.getOutputs()
+      }),
+
+    getRouting: protectedProcedure
+      .input(z.void())
+      .output(z.record(z.string(), z.array(z.string())))
+      .query(() => {
+        if (!ns) return {}
+        const routing = ns.getRouting()
+        const result: Record<string, string[]> = {}
+        for (const [category, outputIds] of routing) {
+          result[category] = [...outputIds]
+        }
+        return result
+      }),
+
+    setRouting: adminProcedure
+      .input(z.object({ category: z.string(), outputIds: z.array(z.string()) }))
+      .output(z.void())
+      .mutation(({ input }) => {
+        if (!ns) throw new Error('Notification service unavailable')
+        ns.setRouting(input.category, input.outputIds)
+      }),
+
+    sendTest: adminProcedure
+      .input(z.object({ outputId: z.string() }))
+      .output(SendTestResultSchema)
+      .mutation(async ({ input }) => {
+        if (!ns) return { success: false, error: 'Notification service unavailable' }
+        const output = ns.getOutput(input.outputId)
+        if (!output) return { success: false, error: `Output "${input.outputId}" not found` }
+        if (!output.sendTest) return { success: false, error: 'Output does not support test notifications' }
+        return output.sendTest()
+      }),
+  })
+}

package/src/api/core/repl.router.ts

@@ -0,0 +1,41 @@
+/**
+ * REPL router — fixed core API (not a capability).
+ *
+ * The REPL engine is a single NestJS-backed service in the backend
+ * (`ReplEngineService` extends `ReplEngine` from `@camstack/core`).
+ * Only super_admin can execute code.
+ */
+import { z } from 'zod'
+import type { ReplEngineService } from '../../core/repl/repl-engine.service.js'
+import { trpcRouter, adminProcedure } from '../trpc/trpc.middleware.js'
+
+const ReplScopeSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('system') }),
+  z.object({ type: z.literal('device'), deviceId: z.number() }),
+  z.object({ type: z.literal('provider'), providerId: z.string() }),
+  z.object({ type: z.literal('addon'), addonId: z.string() }),
+])
+
+const ReplResultSchema = z.object({
+  output: z.string(),
+  error: z.string().optional(),
+  duration: z.number().optional(),
+})
+
+export function createReplRouter(repl: ReplEngineService) {
+  return trpcRouter({
+    execute: adminProcedure
+      .input(z.object({ code: z.string().max(10000), scope: ReplScopeSchema }))
+      .output(ReplResultSchema)
+      .mutation(({ input }) =>
+        repl.execute(input.code, { scope: input.scope, variables: {} }),
+      ),
+
+    completions: adminProcedure
+      .input(z.object({ partial: z.string(), scope: ReplScopeSchema }))
+      .output(z.array(z.string()).readonly())
+      .query(({ input }) =>
+        repl.getCompletions(input.partial, { scope: input.scope, variables: {} }),
+      ),
+  })
+}