@camstack/server 0.1.3

package/src/core/addon/addon-search.service.ts

@@ -0,0 +1,90 @@
+import { LoggingService } from '../logging/logging.service'
+import { errMsg } from '@camstack/types'
+
+interface NpmSearchResult {
+  name: string
+  version: string
+  description: string
+  keywords: string[]
+  date: string
+  publisher: { username: string }
+}
+
+interface AddonSearchResult {
+  name: string
+  version: string
+  description: string
+  keywords: string[]
+  publishedAt: string
+  author: string
+  installed: boolean
+  installedVersion?: string
+}
+
+export class AddonSearchService {
+  private cache: { results: NpmSearchResult[]; timestamp: number } | null = null
+  private readonly CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
+
+  constructor(private readonly loggingService: LoggingService) {}
+
+  async searchAddons(query?: string): Promise<AddonSearchResult[]> {
+    const npmResults = await this.fetchFromNpm()
+
+    // Filter by additional query if provided
+    let filtered = npmResults
+    if (query) {
+      const q = query.toLowerCase()
+      filtered = npmResults.filter(
+        (r) =>
+          r.name.toLowerCase().includes(q) ||
+          r.description?.toLowerCase().includes(q) ||
+          r.keywords?.some((k) => k.toLowerCase().includes(q)),
+      )
+    }
+
+    // Return without install status — the caller can merge with installed list
+    return filtered.map((r) => ({
+      name: r.name,
+      version: r.version,
+      description: r.description ?? '',
+      keywords: r.keywords ?? [],
+      publishedAt: r.date ?? '',
+      author: r.publisher?.username ?? '',
+      installed: false, // caller will enrich this
+      installedVersion: undefined,
+    }))
+  }
+
+  private async fetchFromNpm(): Promise<NpmSearchResult[]> {
+    // Return from cache if still fresh
+    if (this.cache && Date.now() - this.cache.timestamp < this.CACHE_TTL_MS) {
+      return this.cache.results
+    }
+
+    // npm registry v1 search: packages with BOTH "camstack" and "addon" keywords
+    const url = 'https://registry.npmjs.org/-/v1/search?text=keywords:camstack+keywords:addon&size=250'
+
+    try {
+      const response = await fetch(url, {
+        headers: { Accept: 'application/json' },
+        signal: AbortSignal.timeout(10000),
+      })
+
+      if (!response.ok) {
+        throw new Error(`npm search failed: ${response.status}`)
+      }
+
+      const data = (await response.json()) as { objects: Array<{ package: NpmSearchResult }> }
+      const results = data.objects.map((o) => o.package)
+
+      this.cache = { results, timestamp: Date.now() }
+
+      return results
+    } catch (err) {
+      const logger = this.loggingService.createLogger('addon-search')
+      logger.warn('npm search failed', { meta: { error: errMsg(err) } })
+      // Stale cache is better than nothing on transient network failure
+      return this.cache?.results ?? []
+    }
+  }
+}

package/src/core/addon/addon-settings-provider.ts

@@ -0,0 +1,276 @@
+/**
+ * Hub-side singleton provider for the `addon-settings` capability.
+ *
+ * Acts as a gateway: resolves `addonId` to the target addon and
+ * delegates the settings call. For hub-local addons, calls the
+ * addon instance directly. For remote agents, proxies via the
+ * per-addon Moleculer service (`<addonId>.settings.<method>`).
+ *
+ * Replaces the `$addonHost` Moleculer service.
+ */
+import type { ICamstackAddon, ConfigUISchemaWithValues } from '@camstack/types'
+import type { IAddonSettingsProvider } from '@camstack/types'
+
+/**
+ * Minimal structural view of the Moleculer broker this provider needs
+ * (`call` + `registry`). Typed locally — mirroring the
+ * `ReconcileBrokerLike` pattern in `agent-registry.service.ts` —
+ * because the lint type-checker cannot resolve Moleculer's
+ * `ServiceBroker` type, which left every `broker.*` access `any`-typed.
+ */
+interface SettingsBroker {
+  readonly registry: unknown
+  call(
+    action: string,
+    params: Record<string, unknown>,
+    opts?: { readonly nodeID?: string; readonly timeout?: number },
+  ): Promise<unknown>
+}
+
+// ── Dependency interfaces ────────────────────────────────────────────
+
+/** Resolve an addon by id. Returns null if not loaded on this node. */
+type AddonLookup = (addonId: string) => ICamstackAddon | null
+
+/** Resolve which node hosts a given addon. Returns 'hub' for local. */
+type NodeResolver = (addonId: string) => string
+
+// ── Input types (match the cap definition's z.infer) ─────────────────
+
+interface AddonIdInput {
+  readonly addonId: string
+  readonly nodeId?: string
+  readonly overlay?: Record<string, unknown>
+}
+
+interface AddonPatchInput {
+  readonly addonId: string
+  readonly nodeId?: string
+  readonly patch: Record<string, unknown>
+}
+
+interface DeviceGetInput {
+  readonly addonId: string
+  readonly deviceId: number
+  readonly nodeId?: string
+}
+
+interface DeviceUpdateInput {
+  readonly addonId: string
+  readonly deviceId: number
+  readonly nodeId?: string
+  readonly patch: Record<string, unknown>
+}
+
+interface SettingsUpdateResult {
+  readonly success: true
+}
+
+// ── Reshape helper ───────────────────────────────────────────────────
+
+/**
+ * Deep-copy a `ConfigUISchemaWithValues` into mutable-array shape for
+ * Zod output. The domain type uses `readonly` arrays; Zod's inferred
+ * output uses mutable arrays. Structurally identical at runtime.
+ */
+interface ReshapedSchema {
+  tabs?: Array<{ id: string; label: string; icon: string; order?: number }>
+  sections: Array<{
+    id: string
+    title: string
+    description?: string
+    style?: 'card' | 'accordion'
+    defaultCollapsed?: boolean
+    columns?: 1 | 2 | 3 | 4
+    tab?: string
+    order?: number
+    fields: unknown[]
+  }>
+}
+
+function reshapeForOutput(schema: ConfigUISchemaWithValues): ReshapedSchema {
+  return {
+    tabs: schema.tabs
+      ? schema.tabs.map((t) => ({ id: t.id, label: t.label, icon: t.icon, order: t.order }))
+      : undefined,
+    sections: schema.sections.map((s) => ({
+      id: s.id,
+      title: s.title,
+      description: s.description,
+      style: s.style,
+      defaultCollapsed: s.defaultCollapsed,
+      columns: s.columns,
+      tab: s.tab,
+      order: s.order,
+      fields: [...s.fields],
+    })),
+  }
+}
+
+/**
+ * True for Moleculer's `ServiceNotFoundError` — raised when a
+ * `<addonId>.settings.*` action is called before the owning forked
+ * addon has registered its service (still booting, or wedged in
+ * `onInitialize`). Matched by `name` so we don't depend on Moleculer's
+ * error class being importable here.
+ */
+function isServiceNotFoundError(err: unknown): boolean {
+  return err instanceof Error && err.name === 'ServiceNotFoundError'
+}
+
+// ── Provider factory ─────────────────────────────────────────────────
+
+interface AddonSettingsProviderDeps {
+  /** Look up a loaded addon by id on this hub node. */
+  readonly getAddon: AddonLookup
+  /** Resolve which node hosts a given addon. Defaults to 'hub'. */
+  readonly resolveNode: NodeResolver
+  /** Moleculer broker for remote calls. */
+  readonly broker: SettingsBroker
+  /** This hub's node ID (for local short-circuit). */
+  readonly hubNodeId: string
+}
+
+function createAddonSettingsProvider(deps: AddonSettingsProviderDeps): IAddonSettingsProvider {
+  const { getAddon, resolveNode, broker, hubNodeId } = deps
+
+  function isLocal(addonId: string, explicitNodeId?: string): boolean {
+    // `resolveNode` is consulted FIRST: it knows whether the addon
+    // runs in-process on the hub or as a forkable worker. An explicit
+    // `nodeId: 'hub'` from the caller is treated as "target the hub
+    // cluster" — NOT "force local dispatch" — so for forkable addons
+    // we still route via Moleculer to `hub/<addonId>`. Without this
+    // check the hub-side stub (which never had `initialize()` run and
+    // has no `_ctx.settings`) would respond with defaults only and
+    // silently drop every `updateGlobalSettings` patch.
+    const resolved = resolveNode(addonId)
+    if (resolved !== 'hub' && resolved !== hubNodeId) return false
+    const nodeId = explicitNodeId ?? resolved
+    return nodeId === 'hub' || nodeId === hubNodeId
+  }
+
+  // ── Remote call helpers ──────────────────────────────────────────
+
+  // Resolve the Moleculer nodeID that actually hosts an addon's
+  // `<addonId>.settings.*` service. Forkable addons register under
+  // `${baseNodeId}/${addonId}`; in-process addons register under the
+  // base nodeId itself. Walk the Moleculer registry and pick the
+  // first node whose id matches either convention.
+  function resolveWorkerNodeId(addonId: string, baseNodeId: string): string | null {
+    const registry = broker.registry
+    const services = (registry as unknown as {
+      getServiceList: (opts: { onlyAvailable: boolean }) => readonly { name: string; nodeID: string }[]
+    }).getServiceList({ onlyAvailable: true })
+    // Find the node that actually hosts the `<addonId>` service (the
+    // moleculer service factory registers addons under their id). The
+    // baseNodeId is a hint — we trust the registry's ground truth
+    // instead. Forkable addons live at `<parent>/<addonId>`;
+    // in-process addons live at `<parent>`.
+    const exactNode = `${baseNodeId}/${addonId}`
+    const preferred = services.find((s) => s.name === addonId && s.nodeID === exactNode)
+    if (preferred) return preferred.nodeID
+    const anyForBase = services.find((s) => s.name === addonId && s.nodeID === baseNodeId)
+    if (anyForBase) return anyForBase.nodeID
+    const anyWithName = services.find((s) => s.name === addonId)
+    return anyWithName?.nodeID ?? null
+  }
+
+  async function remoteGet(
+    addonId: string,
+    nodeId: string,
+    action: string,
+    extraParams?: Record<string, unknown>,
+  ): Promise<ReshapedSchema | null> {
+    const params = { ...extraParams }
+    const workerNodeId = resolveWorkerNodeId(addonId, nodeId)
+    try {
+      const result: unknown = await broker.call(
+        `${addonId}.settings.${action}`,
+        params,
+        workerNodeId ? { nodeID: workerNodeId, timeout: 10_000 } : { timeout: 10_000 },
+      )
+      return result ? reshapeForOutput(result as ConfigUISchemaWithValues) : null
+    } catch (err) {
+      // A forked addon that is still booting (or wedged in
+      // `onInitialize`) has not yet registered its
+      // `<addonId>.settings.*` Moleculer service. A settings READ
+      // against a missing service should degrade to "no schema" so the
+      // panel shows its empty state — NOT bubble a 500 to the operator.
+      if (isServiceNotFoundError(err)) return null
+      throw err
+    }
+  }
+
+  async function remoteUpdate(
+    addonId: string,
+    nodeId: string,
+    action: string,
+    extraParams: Record<string, unknown>,
+  ): Promise<SettingsUpdateResult> {
+    const workerNodeId = resolveWorkerNodeId(addonId, nodeId)
+    await broker.call(
+      `${addonId}.settings.${action}`,
+      extraParams,
+      workerNodeId ? { nodeID: workerNodeId, timeout: 10_000 } : { timeout: 10_000 },
+    )
+    return { success: true as const }
+  }
+
+  // ── Provider implementation ──────────────────────────────────────
+
+  return {
+    async getGlobalSettings(input: AddonIdInput) {
+      if (isLocal(input.addonId, input.nodeId)) {
+        const addon = getAddon(input.addonId)
+        if (!addon || typeof addon.getGlobalSettings !== 'function') return null
+        const result = await addon.getGlobalSettings(input.overlay)
+        return result ? reshapeForOutput(result) : null
+      }
+      const nodeId = input.nodeId ?? resolveNode(input.addonId)
+      return remoteGet(input.addonId, nodeId, 'getGlobalSettings', { ...(input.overlay ? { overlay: input.overlay } : {}) })
+    },
+
+    async updateGlobalSettings(input: AddonPatchInput) {
+      if (isLocal(input.addonId, input.nodeId)) {
+        const addon = getAddon(input.addonId)
+        if (!addon || typeof addon.updateGlobalSettings !== 'function') {
+          throw new Error(`Addon "${input.addonId}" does not implement updateGlobalSettings`)
+        }
+        await addon.updateGlobalSettings(input.patch)
+        return { success: true as const }
+      }
+      const nodeId = input.nodeId ?? resolveNode(input.addonId)
+      return remoteUpdate(input.addonId, nodeId, 'updateGlobalSettings', { patch: input.patch })
+    },
+
+    async getDeviceSettings(input: DeviceGetInput) {
+      if (isLocal(input.addonId, input.nodeId)) {
+        const addon = getAddon(input.addonId)
+        if (!addon || typeof addon.getDeviceSettings !== 'function') return null
+        const result = await addon.getDeviceSettings(input.deviceId)
+        return result ? reshapeForOutput(result) : null
+      }
+      const nodeId = input.nodeId ?? resolveNode(input.addonId)
+      return remoteGet(input.addonId, nodeId, 'getDeviceSettings', { deviceId: input.deviceId })
+    },
+
+    async updateDeviceSettings(input: DeviceUpdateInput) {
+      if (isLocal(input.addonId, input.nodeId)) {
+        const addon = getAddon(input.addonId)
+        if (!addon || typeof addon.updateDeviceSettings !== 'function') {
+          throw new Error(`Addon "${input.addonId}" does not implement updateDeviceSettings`)
+        }
+        await addon.updateDeviceSettings(input.deviceId, input.patch)
+        return { success: true as const }
+      }
+      const nodeId = input.nodeId ?? resolveNode(input.addonId)
+      return remoteUpdate(input.addonId, nodeId, 'updateDeviceSettings', {
+        deviceId: input.deviceId,
+        patch: input.patch,
+      })
+    },
+  }
+}
+
+export { createAddonSettingsProvider }
+export type { AddonSettingsProviderDeps }

package/src/core/addon/addon.tokens.ts

@@ -0,0 +1,2 @@
+export const ADDON_REGISTRY = Symbol('ADDON_REGISTRY')
+export const BUILTIN_ADDONS = Symbol('BUILTIN_ADDONS')

package/src/core/addon-bridge/addon-bridge.service.ts

@@ -0,0 +1,125 @@
+import * as path from 'node:path'
+import { LoggingService } from '../logging/logging.service'
+import type { IScopedLogger } from '@camstack/types'
+import { errMsg } from '@camstack/types'
+
+// Dynamically imported to tolerate missing / unbuilt packages at startup
+type AddonLoader = import('@camstack/kernel').AddonLoader
+type AddonInstaller = import('@camstack/kernel').AddonInstaller
+type RegisteredAddon = import('@camstack/kernel').RegisteredAddon
+
+/**
+ * AddonBridgeService — slim package-management surface.
+ *
+ * Historically this service also cached per-camera pipeline configs + per-
+ * addon config records + hosted an in-process `PipelineRunner` that consumers
+ * called via `processFrame` / `processMotionFrame`. Every piece of that
+ * plumbing was dead post commit 2c (the runtime scheduler moved to
+ * `addon-pipeline-runner`) and the pipeline page redesign finishes the job
+ * by deleting the cache, the AddonEngineManager wiring, the bridge-pipeline
+ * tRPC router, and the PipelineWiringModule that bolted the legacy addon
+ * resolver onto this service.
+ *
+ * What's left is ONLY the addon package management surface: the installer
+ * + the loader + `reloadPackages` + `listAvailableAddons`. These are still
+ * used by:
+ *  - `server/backend/src/api/addon-upload.ts` (multipart upload → install
+ *    → loader reload)
+ *  - `server/backend/src/api/bridge-addons.router.ts` (install/uninstall
+ *    package lifecycle, addon list via the loader)
+ */
+export class AddonBridgeService {
+  private readonly logger: IScopedLogger
+
+  private loader!: AddonLoader
+  private installer: AddonInstaller | null = null
+
+  /** Whether the bridge initialised successfully */
+  private available = false
+
+  constructor(
+    private readonly loggingService: LoggingService,
+  ) {
+    this.logger = this.loggingService.createLogger('AddonBridge')
+
+    // Initialize installer eagerly in constructor (no async needed).
+    // This ensures install/uninstall works even before onModuleInit completes.
+    try {
+      const kernel = require('@camstack/kernel') as typeof import('@camstack/kernel')
+      const dataDir = process.env.CAMSTACK_DATA ?? 'camstack-data'
+      const addonsDir = path.resolve(dataDir, 'addons')
+      const workspacePackagesDir = kernel.detectWorkspacePackagesDir(__dirname)
+      this.installer = new kernel.AddonInstaller({ addonsDir, workspacePackagesDir: workspacePackagesDir ?? undefined })
+      kernel.ensureDir(addonsDir)
+    } catch (error: unknown) {
+      const msg = errMsg(error)
+      this.logger.warn('Installer init failed', { meta: { error: msg } })
+    }
+  }
+
+  async onModuleInit(): Promise<void> {
+    this.logger.info('Initializing addon bridge (package management only)...')
+
+    try {
+      const kernel = await import('@camstack/kernel')
+
+      this.loader = new kernel.AddonLoader(this.logger.child('AddonLoader'))
+
+      const dataDir = process.env.CAMSTACK_DATA ?? 'camstack-data'
+      const addonsDir = path.resolve(dataDir, 'addons')
+      await this.loader.loadFromDirectory(addonsDir)
+
+      this.available = true
+      this.logger.info('Addon bridge initialized', { meta: { count: this.loader.listAddons().length } })
+    } catch (error: unknown) {
+      const msg = errMsg(error)
+      this.logger.warn('Addon bridge loader failed — install/uninstall still available', { meta: { error: msg } })
+    }
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    this.logger.info('Addon bridge shut down')
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /** Whether the bridge is ready for use */
+  isAvailable(): boolean {
+    return this.available
+  }
+
+  /** Return the underlying AddonLoader (for querying / introspection) */
+  getLoader(): AddonLoader {
+    return this.loader
+  }
+
+  /** List IDs of all successfully loaded addons */
+  listAvailableAddons(): string[] {
+    if (!this.available) return []
+    return this.loader.listAddons().map((a: RegisteredAddon) => a.declaration.id)
+  }
+
+  /** Return the AddonInstaller instance (may be null if bridge failed to init) */
+  getInstaller(): AddonInstaller | null {
+    return this.installer
+  }
+
+  /** Re-discover addons from the addons directory (call after install/uninstall) */
+  async reloadPackages(): Promise<void> {
+    if (!this.available) {
+      this.logger.warn('reloadPackages called but bridge is unavailable — skipping')
+      return
+    }
+
+    const kernel = await import('@camstack/kernel')
+    this.loader = new kernel.AddonLoader(this.logger.child('AddonLoader'))
+
+    const dataDir = process.env.CAMSTACK_DATA ?? 'camstack-data'
+    const addonsDir = path.resolve(dataDir, 'addons')
+    await this.loader.loadFromDirectory(addonsDir)
+
+    this.logger.info('Reloaded', { meta: { count: this.loader.listAddons().length } })
+  }
+}

package/src/core/addon-pages/addon-pages.service.spec.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, vi } from 'vitest'
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+}))
+
+import * as fs from 'node:fs'
+import { AddonPagesService } from './addon-pages.service'
+import type { CapabilityService } from '../capability/capability.service'
+import type { LoggingService } from '../logging/logging.service'
+import type { ConfigService } from '../config/config.service'
+import type { IAddonPageProvider, AddonPageDeclaration, IScopedLogger } from '@camstack/types'
+
+function createMockLogger(): IScopedLogger {
+  return {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    child: vi.fn().mockReturnThis(),
+  }
+}
+
+function createMockLoggingService(): LoggingService {
+  return {
+    createLogger: vi.fn().mockReturnValue(createMockLogger()),
+  } as unknown as LoggingService
+}
+
+function createMockConfigService(): ConfigService {
+  return {
+    get: vi.fn().mockReturnValue('./data'),
+  } as unknown as ConfigService
+}
+
+function createMockPageProvider(
+  id: string,
+  pages: readonly AddonPageDeclaration[],
+): IAddonPageProvider {
+  return {
+    id,
+    listPages: () => pages,
+  }
+}
+
+/**
+ * AddonPagesService now resolves bundles via the `addon-pages-source`
+ * collection cap (split from the public `addon-pages` singleton cap
+ * earlier this session).
+ */
+function createMockCapabilityService(providers: IAddonPageProvider[] = []): CapabilityService {
+  return {
+    getSingleton: vi.fn(() => null),
+    getCollection: vi.fn((capability: string) => {
+      if (capability === 'addon-pages-source') return providers
+      return []
+    }),
+    resolveForDevice: vi.fn(() => null),
+    resolveCollectionForDevice: vi.fn(() => []),
+    setRegistry: vi.fn(),
+    getRegistry: vi.fn(() => null),
+  } as unknown as CapabilityService
+}
+
+function buildService(providers: IAddonPageProvider[] = []): AddonPagesService {
+  return new AddonPagesService(
+    createMockLoggingService(),
+    createMockConfigService(),
+    createMockCapabilityService(providers),
+  )
+}
+
+describe('AddonPagesService.resolveBundle', () => {
+  it('should return null for unregistered addon', () => {
+    const service = buildService([])
+    const result = service.resolveBundle('nonexistent', 'dist/pages/main.js')
+    expect(result).toBeNull()
+  })
+
+  it('should return null when file does not exist', () => {
+    const provider = createMockPageProvider('benchmark', [])
+    const service = buildService([provider])
+
+    const existsMock = fs.existsSync as unknown as ReturnType<typeof vi.fn>
+    existsMock.mockReturnValue(false)
+
+    const result = service.resolveBundle('benchmark', 'dist/pages/benchmark.js')
+    expect(result).toBeNull()
+  })
+
+  it('should return resolved path when file exists', () => {
+    const provider = createMockPageProvider('benchmark', [])
+    const service = buildService([provider])
+
+    const existsMock = fs.existsSync as unknown as ReturnType<typeof vi.fn>
+    existsMock.mockReturnValue(true)
+
+    const result = service.resolveBundle('benchmark', 'dist/pages/benchmark.js')
+    expect(result).not.toBeNull()
+    expect(result).toContain('addon-benchmark')
+    expect(result).toContain('dist/pages/benchmark.js')
+  })
+
+  it('should deny path traversal attempts', () => {
+    const provider = createMockPageProvider('benchmark', [])
+    const service = buildService([provider])
+    const result = service.resolveBundle('benchmark', '../../etc/passwd')
+    expect(result).toBeNull()
+  })
+
+  it('should deny absolute path traversal', () => {
+    const provider = createMockPageProvider('benchmark', [])
+    const service = buildService([provider])
+    const result = service.resolveBundle('benchmark', '../../../etc/passwd')
+    expect(result).toBeNull()
+  })
+})

package/src/core/addon-pages/addon-pages.service.ts

@@ -0,0 +1,80 @@
+import * as path from 'node:path'
+import * as fs from 'node:fs'
+import { LoggingService } from '../logging/logging.service'
+import { ConfigService } from '../config/config.service'
+import { CapabilityService } from '../capability/capability.service'
+import type { IScopedLogger } from '@camstack/types'
+import type { IAddonPageProvider } from '@camstack/types'
+
+/**
+ * AddonPagesService — server-side helper that backs the static file
+ * route `/api/addon-pages/:addonId/*` (registered in `main.ts`).
+ *
+ * The public listing surface (`addonPages.listPages` on the AppRouter)
+ * has been split out of this class — it now lives in the
+ * `addon-pages-aggregator` builtin (`@camstack/core/builtins/...`)
+ * which walks every `addon-pages-source` collection provider and
+ * stamps versioned `bundleUrl`s. The split lets both ends flow through
+ * codegen instead of relying on a hand-written wrapper.
+ *
+ * What stays here: filesystem path resolution + traversal protection
+ * for the static file route. Both rely on `CapabilityService` to
+ * enumerate registered page providers (so unknown / unregistered
+ * addons can't be probed via path traversal tricks) and on
+ * `ConfigService` to locate the addons directory.
+ */
+export class AddonPagesService {
+  private readonly logger: IScopedLogger
+
+  constructor(
+    private readonly loggingService: LoggingService,
+    private readonly configService: ConfigService,
+    private readonly caps: CapabilityService,
+  ) {
+    this.logger = this.loggingService.createLogger('AddonPagesService')
+  }
+
+  /**
+   * Resolve the filesystem path to an addon's page bundle file.
+   * Returns null if the addon is not registered, the file doesn't exist,
+   * or the path would escape the addon directory (path traversal protection).
+   */
+  resolveBundle(addonId: string, filePath: string): string | null {
+    // Check if the addon is a registered page provider via the
+    // collection cap. `addon-pages-source` is the new home for the raw
+    // per-provider declarations (the public `addon-pages` cap is the
+    // aggregated singleton — different shape, different surface).
+    const providers = this.caps.getCollection<IAddonPageProvider>('addon-pages-source')
+    const isRegistered = providers.some((p) => p.id === addonId)
+    if (!isRegistered) {
+      this.logger.warn('Bundle resolve failed: addon not registered as page provider', { tags: { addonId } })
+      return null
+    }
+
+    const addonsDir = this.resolveAddonsDir()
+    // Addon packages are at addons/@camstack/addon-<id>/dist/
+    const addonDistPath = path.join(addonsDir, '@camstack', `addon-${addonId}`, 'dist')
+
+    const resolvedBase = path.resolve(addonDistPath)
+    const resolvedFile = path.resolve(addonDistPath, filePath)
+
+    // Path traversal protection
+    if (!resolvedFile.startsWith(resolvedBase + path.sep) && resolvedFile !== resolvedBase) {
+      this.logger.warn('Path traversal denied for addon', { tags: { addonId }, meta: { filePath } })
+      return null
+    }
+
+    if (!fs.existsSync(resolvedFile)) {
+      this.logger.debug('Bundle file not found', { meta: { resolvedFile } })
+      return null
+    }
+
+    return resolvedFile
+  }
+
+  /** Resolve the addons directory from config */
+  private resolveAddonsDir(): string {
+    const dataPath = this.configService.get<string>('server.dataPath') ?? 'camstack-data'
+    return path.resolve(dataPath, 'addons')
+  }
+}