@camstack/server 0.1.3

package/src/core/streaming/stream-probe.service.ts

@@ -0,0 +1,212 @@
+import { execFile } from 'child_process'
+import { promisify } from 'util'
+
+import { LoggingService } from '../logging/logging.service'
+import type { StreamMetadata, StreamAudioMetadata } from '@camstack/types'
+import type { IScopedLogger } from '@camstack/types'
+import { errMsg } from '@camstack/types'
+
+const execFileAsync = promisify(execFile)
+
+const CACHE_TTL_MS = 3_600_000 // 1 hour
+const PROBE_TIMEOUT_MS = 5_000
+
+/** Codec aliases normalised to canonical names. */
+const CODEC_ALIASES: Readonly<Record<string, string>> = {
+  hevc: 'h265',
+}
+
+interface CacheEntry {
+  readonly metadata: StreamMetadata
+  readonly timestamp: number
+}
+
+export class StreamProbeService {
+  private readonly logger: IScopedLogger
+  private readonly cache = new Map<string, CacheEntry>()
+
+  constructor(
+    loggingService: LoggingService,
+  ) {
+    this.logger = loggingService.createLogger('StreamProbeService')
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /** Probe a stream URL and return its metadata (cached for 1 hour). */
+  async probe(url: string, options?: { force?: boolean }): Promise<StreamMetadata> {
+    const force = options?.force ?? false
+
+    if (!force) {
+      const cached = this.cache.get(url)
+      if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+        return cached.metadata
+      }
+    }
+
+    const metadata = await this.runProbe(url)
+    this.cache.set(url, { metadata, timestamp: Date.now() })
+    return metadata
+  }
+
+  /**
+   * Generic field probe: given a field key and value, decides how to probe.
+   * Stream fields (stream_*) → ffprobe, other URLs → HTTP HEAD check.
+   */
+  async probeField(key: string, value: unknown): Promise<{ status: 'ok' | 'error'; labels?: string[]; error?: string }> {
+    const url = String(value ?? '').trim()
+    if (!url) {
+      return { status: 'error', error: 'No URL provided' }
+    }
+
+    // Stream fields: use ffprobe
+    if (key.startsWith('stream')) {
+      const meta = await this.probe(url, { force: true })
+      const labels: string[] = []
+      if (meta.width && meta.height) labels.push(`${meta.width}\u00d7${meta.height}`)
+      if (meta.codec) {
+        const codecDisplay: Record<string, string> = { h265: 'H.265', h264: 'H.264', hevc: 'H.265' }
+        labels.push(codecDisplay[meta.codec] ?? meta.codec.toUpperCase())
+      }
+      if (meta.fps) labels.push(`${Math.round(meta.fps)}fps`)
+      if (meta.audio?.codec) {
+        const audioCodec = meta.audio.codec.toUpperCase()
+        const audioBits: string[] = [audioCodec]
+        if (meta.audio.sampleRate) audioBits.push(`${Math.round(meta.audio.sampleRate / 1000)}kHz`)
+        if (meta.audio.channels === 1) audioBits.push('mono')
+        else if (meta.audio.channels === 2) audioBits.push('stereo')
+        else if (meta.audio.channels) audioBits.push(`${meta.audio.channels}ch`)
+        labels.push(`audio: ${audioBits.join(' ')}`)
+      }
+      if (labels.length === 0) {
+        return { status: 'error', error: 'No video streams found at URL' }
+      }
+      return { status: 'ok', labels }
+    }
+
+    // Other URL fields (snapshot, etc.): GET with early abort to check reachability + content-type
+    try {
+      const controller = new AbortController()
+      const timeout = AbortSignal.timeout(5000)
+      timeout.addEventListener('abort', () => controller.abort(timeout.reason))
+      const response = await fetch(url, { method: 'GET', signal: controller.signal })
+      if (!response.ok) {
+        controller.abort()
+        return { status: 'error', error: `HTTP ${response.status} ${response.statusText}` }
+      }
+      const contentType = response.headers.get('content-type') ?? ''
+      controller.abort() // Don't download the full body
+      const labels: string[] = ['Reachable']
+      if (contentType.startsWith('image/')) {
+        labels.push(contentType.replace('image/', '').toUpperCase())
+      }
+      return { status: 'ok', labels }
+    } catch (err) {
+      if (err instanceof Error && err.name === 'AbortError') {
+        // We aborted intentionally after reading headers — that's success
+        return { status: 'ok', labels: ['Reachable'] }
+      }
+      const msg = errMsg(err)
+      return { status: 'error', error: `Unreachable: ${msg}` }
+    }
+  }
+
+  /** Clear cached metadata for a single URL or all URLs. */
+  clearCache(url?: string): void {
+    if (url) {
+      this.cache.delete(url)
+    } else {
+      this.cache.clear()
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private async runProbe(url: string): Promise<StreamMetadata> {
+    try {
+      // Query first video + first audio stream in one ffprobe pass.
+      // `-show_streams` returns every stream in the container; we filter
+      // by codec_type when parsing. Fields cover both kinds.
+      const { stdout } = await execFileAsync('ffprobe', [
+        '-v', 'error',
+        '-rtsp_transport', 'tcp',
+        '-timeout', '5000000',
+        '-show_entries',
+        'stream=codec_type,codec_name,profile,width,height,r_frame_rate,bit_rate,sample_rate,channels',
+        '-of', 'json',
+        url,
+      ], { timeout: PROBE_TIMEOUT_MS })
+
+      return this.parseOutput(stdout)
+    } catch (err) {
+      this.logger.error('ffprobe failed', { meta: { url, error: String(err) } })
+      return {}
+    }
+  }
+
+  private parseOutput(stdout: string): StreamMetadata {
+    const parsed: unknown = JSON.parse(stdout)
+    const streams = (parsed as { streams?: unknown[] }).streams
+    if (!Array.isArray(streams) || streams.length === 0) {
+      return {}
+    }
+
+    const meta: StreamMetadata = {}
+
+    for (const raw of streams) {
+      const stream = raw as Record<string, unknown>
+      const codecType = typeof stream.codec_type === 'string' ? stream.codec_type : undefined
+
+      if (codecType === 'video' && meta.codec === undefined) {
+        const rawCodec = typeof stream.codec_name === 'string' ? stream.codec_name : undefined
+        meta.codec = rawCodec ? (CODEC_ALIASES[rawCodec] ?? rawCodec) : undefined
+        if (typeof stream.width === 'number') meta.width = stream.width
+        if (typeof stream.height === 'number') meta.height = stream.height
+        const fps = this.parseFps(stream.r_frame_rate)
+        if (fps !== undefined) meta.fps = fps
+        const bitrateKbps = this.parseBitrateKbps(stream.bit_rate)
+        if (bitrateKbps !== undefined) meta.bitrateKbps = bitrateKbps
+      } else if (codecType === 'audio' && meta.audio === undefined) {
+        const audio: StreamAudioMetadata = {}
+        if (typeof stream.codec_name === 'string') audio.codec = stream.codec_name
+        if (typeof stream.profile === 'string') audio.profile = stream.profile
+        const sampleRate = this.parseIntField(stream.sample_rate)
+        if (sampleRate !== undefined) audio.sampleRate = sampleRate
+        if (typeof stream.channels === 'number') audio.channels = stream.channels
+        const audioBitrateKbps = this.parseBitrateKbps(stream.bit_rate)
+        if (audioBitrateKbps !== undefined) audio.bitrateKbps = audioBitrateKbps
+        meta.audio = audio
+      }
+    }
+
+    return meta
+  }
+
+  private parseIntField(value: unknown): number | undefined {
+    const n = typeof value === 'string' ? Number(value) : typeof value === 'number' ? value : NaN
+    if (!Number.isFinite(n) || n <= 0) return undefined
+    return Math.round(n)
+  }
+
+  /** Parse fractional frame rate string like "25/1" → 25. */
+  private parseFps(value: unknown): number | undefined {
+    if (typeof value !== 'string') return undefined
+    const parts = value.split('/')
+    if (parts.length !== 2) return undefined
+    const num = Number(parts[0])
+    const den = Number(parts[1])
+    if (!Number.isFinite(num) || !Number.isFinite(den) || den === 0) return undefined
+    return Math.round((num / den) * 100) / 100
+  }
+
+  /** Parse bit_rate string (bps) → kbps. */
+  private parseBitrateKbps(value: unknown): number | undefined {
+    const n = typeof value === 'string' ? Number(value) : typeof value === 'number' ? value : NaN
+    if (!Number.isFinite(n) || n <= 0) return undefined
+    return Math.round(n / 1000)
+  }
+}

package/src/core/topology/topology-emitter.service.ts

@@ -0,0 +1,101 @@
+/**
+ * TopologyEmitterService — push the cluster topology over the event bus.
+ *
+ * Subscribes to agent connect/disconnect + addon lifecycle events,
+ * recomputes the topology snapshot on each change (debounced), and
+ * emits `cluster.topology-snapshot`. Also fires a periodic safety-net
+ * snapshot every TOPOLOGY_HEARTBEAT_MS so consumers that boot mid-
+ * stream get a fresh payload without waiting for the next lifecycle
+ * change.
+ *
+ * Replaces UI polling on `nodes.topology`. Admin-ui dashboards
+ * subscribe to the snapshot category and read state directly from the
+ * payload — zero round-trip.
+ */
+import { randomUUID } from 'node:crypto'
+import { EventCategory } from '@camstack/types'
+
+type Unsubscribe = () => void
+import type { EventBusService } from '../events/event-bus.service'
+import type { AgentRegistryService } from '../agent/agent-registry.service'
+import type { AddonRegistryService } from '../addon/addon-registry.service'
+import { computeTopology } from '../../api/core/cap-providers'
+
+const DEBOUNCE_MS = 200
+const HEARTBEAT_MS = 30_000
+
+const LIFECYCLE_CATEGORIES: readonly EventCategory[] = [
+  EventCategory.AgentOnline,
+  EventCategory.AgentOffline,
+  EventCategory.WorkerOnline,
+  EventCategory.WorkerOffline,
+  EventCategory.AgentUnregistered,
+  EventCategory.AddonStarted,
+  EventCategory.AddonStopped,
+  EventCategory.AddonRestarted,
+  EventCategory.AddonInstalled,
+  EventCategory.AddonUninstalled,
+  EventCategory.AddonUpdated,
+  EventCategory.AddonCrashed,
+]
+
+export class TopologyEmitterService {
+  private readonly unsubscribers: Unsubscribe[] = []
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null
+  private emitting = false
+
+  constructor(
+    private readonly eventBus: EventBusService,
+    private readonly agentRegistry: AgentRegistryService,
+    private readonly addonRegistry: AddonRegistryService,
+  ) {}
+
+  onModuleInit(): void {
+    for (const category of LIFECYCLE_CATEGORIES) {
+      const unsub = this.eventBus.subscribe({ category }, () => this.scheduleEmit())
+      this.unsubscribers.push(unsub)
+    }
+    // Heartbeat fires the first emit ~immediately so consumers that
+    // mount before any lifecycle change still see a snapshot.
+    void this.emitNow()
+    this.heartbeatTimer = setInterval(() => this.scheduleEmit(), HEARTBEAT_MS)
+  }
+
+  onModuleDestroy(): void {
+    if (this.debounceTimer) clearTimeout(this.debounceTimer)
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
+    for (const unsub of this.unsubscribers) {
+      try { unsub() } catch { /* idempotent */ }
+    }
+    this.unsubscribers.length = 0
+  }
+
+  private scheduleEmit(): void {
+    if (this.debounceTimer) clearTimeout(this.debounceTimer)
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null
+      void this.emitNow()
+    }, DEBOUNCE_MS)
+  }
+
+  private async emitNow(): Promise<void> {
+    if (this.emitting) return
+    this.emitting = true
+    try {
+      const nodes = await computeTopology(this.agentRegistry, this.addonRegistry)
+      this.eventBus.emit({
+        id: randomUUID(),
+        timestamp: new Date(),
+        source: { type: 'core', id: 'topology-emitter' },
+        category: EventCategory.ClusterTopologySnapshot,
+        data: { nodes, timestamp: Date.now() },
+      })
+    } catch {
+      // Best-effort observability path. Next lifecycle event or the
+      // heartbeat will retry — no need to log here.
+    } finally {
+      this.emitting = false
+    }
+  }
+}

package/src/launcher.ts

@@ -0,0 +1,309 @@
+/**
+ * Launcher -- entry point that ensures required addons are installed
+ * before main.ts loads. This solves the chicken-and-egg problem:
+ * main.ts has static imports from @camstack/core, but core lives in
+ * data/addons/ and may not exist on first boot.
+ *
+ * 1. Run AddonInstaller.ensureRequiredPackages (zero core dependencies)
+ * 2. Create symlinks so @camstack/core resolves from data/addons/
+ * 3. Dynamically import main.ts (which has static @camstack/core imports)
+ */
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as tar from 'tar'
+import * as yaml from 'js-yaml'
+import { AddonInstaller, bootstrapSchema, detectWorkspacePackagesDir } from '@camstack/kernel'
+
+/** Path of the manifest file embedded inside every archive. */
+const ARCHIVE_MANIFEST_NAME = '.camstack-backup-manifest.json'
+
+/** Resolve the data directory from env or default */
+const DATA_DIR = process.env['CAMSTACK_DATA'] ?? 'camstack-data'
+
+const RESTORE_MARKER_FILE = '.pending-restore.json'
+
+/**
+ * Apply a pending system-restore archive over `dataDir` if a marker is
+ * present. Runs BEFORE the addon installer so the restored snapshot's
+ * `addons/` folder is what `ensureRequiredPackages` picks up.
+ *
+ * Marker contract is owned by `SystemBackupService.scheduleRestoreMarker`
+ * (packages/core/src/builtins/system-backup) — kept inline here so the
+ * launcher remains zero-core-deps. Schema:
+ *   { archivePath: string, requestedAt: number, source: string }
+ *
+ * Failure modes:
+ *   - marker malformed → log + leave it in place (operator visibility)
+ *   - archive missing  → log + clear marker (auto-recover from stale)
+ *   - tar fails        → throw → launcher exits non-zero, marker preserved
+ */
+async function applyPendingRestore(dataDir: string): Promise<void> {
+  const markerPath = path.join(dataDir, RESTORE_MARKER_FILE)
+  if (!fs.existsSync(markerPath)) return
+
+  console.log(`[launcher] Pending restore marker found at ${markerPath}`)
+  let archivePath: string | null = null
+  let locations: string[] | null = null
+  try {
+    const raw = fs.readFileSync(markerPath, 'utf-8')
+    const parsed: unknown = JSON.parse(raw)
+    if (
+      typeof parsed === 'object' &&
+      parsed != null &&
+      typeof (parsed as { archivePath?: unknown }).archivePath === 'string'
+    ) {
+      archivePath = (parsed as { archivePath: string }).archivePath
+    }
+    const locField = (parsed as { locations?: unknown }).locations
+    if (Array.isArray(locField) && locField.every((l) => typeof l === 'string')) {
+      locations = locField as string[]
+    }
+  } catch (err) {
+    console.error('[launcher] Restore marker malformed — leaving in place:', err)
+    return
+  }
+
+  if (archivePath == null) {
+    console.error('[launcher] Restore marker missing archivePath — clearing')
+    fs.rmSync(markerPath, { force: true })
+    return
+  }
+
+  if (!fs.existsSync(archivePath)) {
+    console.error(`[launcher] Restore archive ${archivePath} missing — clearing marker`)
+    fs.rmSync(markerPath, { force: true })
+    return
+  }
+
+  const scope = locations ? ` (only: ${locations.join(', ')})` : ''
+  console.log(`[launcher] Restoring snapshot from ${archivePath} into ${dataDir}${scope}`)
+  fs.mkdirSync(dataDir, { recursive: true })
+
+  // Same filter logic SystemBackupService.extractArchive uses — kept
+  // inline here so the launcher stays zero-core-deps. The shape is
+  // straightforward enough to duplicate.
+  const allowedPrefixes = locations
+    ? locations.map((loc) => loc.replace(/^\.\//, '').replace(/\/+$/, ''))
+    : null
+  await tar.extract({
+    file: archivePath,
+    cwd: dataDir,
+    filter: (p) => {
+      if (p === ARCHIVE_MANIFEST_NAME || p === `./${ARCHIVE_MANIFEST_NAME}`) return false
+      if (!allowedPrefixes) return true
+      const normalized = p.replace(/^\.\//, '')
+      return allowedPrefixes.some((prefix) =>
+        normalized === prefix || normalized.startsWith(`${prefix}/`),
+      )
+    },
+  })
+  fs.rmSync(markerPath, { force: true })
+  console.log('[launcher] Restore complete; marker cleared')
+}
+
+/** Narrow `CAMSTACK_INSTALL_SOURCE` env into the typed union. */
+function parseInstallSource(value: string | undefined): 'npm' | 'local' | 'symlink' | undefined {
+  if (value === 'npm' || value === 'local' || value === 'symlink') return value
+  return undefined
+}
+
+/**
+ * Locate + parse `config.yaml` relative to the data dir. Returns the
+ * raw object on success, `null` when missing or unparseable. The
+ * launcher uses this BEFORE @camstack/core is imported so it must stay
+ * free of core deps — just js-yaml + the kernel's bootstrapSchema for
+ * shape validation by the call site.
+ */
+function readConfigYaml(dataDir: string): unknown {
+  const candidates = [
+    path.resolve(dataDir, '..', 'config.yaml'),
+    path.resolve(dataDir, 'config.yaml'),
+    path.resolve(process.cwd(), 'config.yaml'),
+  ]
+  const found = candidates.find((p) => fs.existsSync(p))
+  if (!found) return null
+  try {
+    return yaml.load(fs.readFileSync(found, 'utf-8')) ?? {}
+  } catch (err) {
+    console.warn(`[launcher] Could not parse ${found}: ${err instanceof Error ? err.message : String(err)}`)
+    return null
+  }
+}
+
+/**
+ * Read `bootstrap.installSource` from `<dataDir>/config.yaml` if present.
+ * Returns the configured value or `null` when absent.
+ *
+ * Production deployments should leave this unset (defaults to 'npm');
+ * `symlink` is a dev-time convenience that points data/addons/<pkg>
+ * directly at the workspace source dir — never set in shipped
+ * containers or Electron bundles.
+ */
+function readBootstrapInstallSource(dataDir: string): 'npm' | 'local' | 'symlink' | undefined {
+  const raw = readConfigYaml(dataDir)
+  if (raw === null) return undefined
+  const validation = bootstrapSchema.safeParse(raw)
+  if (!validation.success) return undefined
+  return parseInstallSource(validation.data.bootstrap.installSource)
+}
+
+/**
+ * Read `bootstrap.requiredAddons` from `<dataDir>/config.yaml` if present.
+ * Returns the parsed array, an empty array when explicitly set to `[]`,
+ * or `null` when the field is absent (caller should fall back to the
+ * kernel's REQUIRED_PACKAGES constant).
+ *
+ * Inline YAML parse rather than going through ConfigManager: the
+ * launcher runs before @camstack/core is imported and must stay free of
+ * core dependencies. Just yaml.load + bootstrapSchema (kernel) for
+ * shape validation.
+ */
+function readBootstrapRequiredAddons(dataDir: string): readonly string[] | null {
+  const raw = readConfigYaml(dataDir)
+  if (raw === null) return null
+
+  const validation = bootstrapSchema.safeParse(raw)
+  if (!validation.success) {
+    console.warn(`[launcher] config.yaml failed bootstrapSchema validation: ${validation.error.message}`)
+    return null
+  }
+
+  return validation.data.bootstrap.requiredAddons ?? null
+}
+
+async function launch(): Promise<void> {
+  const dataDir = DATA_DIR
+  const addonsDir = path.resolve(dataDir, 'addons')
+
+  // Restore must happen first so the snapshot's `addons/` is what the
+  // installer + symlink step pick up — otherwise we'd install a stale
+  // set and overwrite it a step later.
+  await applyPendingRestore(dataDir)
+
+  // Install source resolution:
+  //   1. CAMSTACK_BUNDLED_ADDONS_DIR — set by Electron-packaged builds
+  //      to <resourcesPath>/addons. Pre-built addons ship with the
+  //      bundle, copied at first launch (`'local'` mode).
+  //   2. CAMSTACK_INSTALL_SOURCE=local — explicit opt-in to copy from
+  //      the monorepo workspace (used by e2e + dev bootstrap). Hub
+  //      auto-detects `packages/` via detectWorkspacePackagesDir.
+  //   3. Otherwise: 'npm' from the registry. Local development pushes
+  //      via `camstack deploy` (CLI tarball upload), bypassing this
+  //      bootstrap entirely.
+  console.log('[launcher] Checking required packages...')
+  // Install source resolution:
+  //   CAMSTACK_INSTALL_SOURCE env: 'npm' | 'local' | 'symlink' | undefined.
+  //   CAMSTACK_BUNDLED_ADDONS_DIR: Electron path, forces 'local'.
+  //   bootstrap.installSource (config.yaml): same set as env. Env wins.
+  const rawEnvSource = process.env['CAMSTACK_INSTALL_SOURCE']
+  const yamlSource = readBootstrapInstallSource(dataDir)
+  const explicitSource = parseInstallSource(rawEnvSource) ?? yamlSource
+  const bundledDir = process.env['CAMSTACK_BUNDLED_ADDONS_DIR']
+  let workspaceDir: string | null = null
+  let resolvedSource: 'npm' | 'local' | 'symlink' | undefined = explicitSource
+  if (bundledDir && fs.existsSync(bundledDir)) {
+    workspaceDir = bundledDir
+    resolvedSource = 'local'
+    console.log(`[launcher] Using bundled addons from ${bundledDir}`)
+  } else if (explicitSource === 'local' || explicitSource === 'symlink') {
+    workspaceDir = detectWorkspacePackagesDir(__dirname)
+    if (workspaceDir === null) {
+      console.warn(
+        `[launcher] installSource=${explicitSource} requested but no workspace `
+          + `packages/ dir found from ${__dirname} — falling back to 'npm'`,
+      )
+      resolvedSource = 'npm'
+    }
+  }
+  const installer = new AddonInstaller({
+    addonsDir,
+    workspacePackagesDir: workspaceDir ?? undefined,
+    installSource: resolvedSource,
+  })
+
+  // bootstrap.requiredAddons from config.yaml — if set, REPLACES the
+  // kernel's hard-coded REQUIRED_PACKAGES. The kernel never reaches into
+  // SQL before this list is installed; everything here must be a known
+  // package name that can be resolved from the workspace, the bundle, or
+  // npm. Default (undefined) → fall back to the in-kernel constant.
+  const bootstrapRequired = readBootstrapRequiredAddons(dataDir)
+  if (bootstrapRequired !== null) {
+    console.log(`[launcher] bootstrap.requiredAddons from config.yaml: ${bootstrapRequired.length} packages`)
+    await installer.ensureRequiredPackages(bootstrapRequired)
+  } else {
+    await installer.ensureRequiredPackages()
+  }
+
+  // Self-contained addon bundles (build preset `self-contained`) inline
+  // @camstack/types + zod + @camstack/sdk into each addon's dist. The
+  // hub no longer plants peer-dep symlinks under
+  // addonsDir/node_modules/@camstack/ — addons resolve everything from
+  // their own bundle. Kept the serverDir derivation in case future
+  // tooling needs it (NODE_PATH extension below still uses it).
+  const serverDir = path.resolve(__dirname, '..')
+  const nodeModulesDir = path.join(serverDir, 'node_modules')
+
+  // Extend Node's module resolution so addons in `data/addons/`
+  // (which sit outside the server tree on packaged builds — e.g.
+  // `~/Library/Application Support/.../data/addons/`) can resolve
+  // third-party peer deps from the hub's own `node_modules`.
+  //
+  // Why: an addon's runtime file `data/addons/@scope/<x>/dist/x.js`
+  // walks UP looking for `node_modules/<pkg>`. With user-data
+  // outside the workspace, the walk dead-ends well before hitting
+  // the hub's tree. NODE_PATH instructs Node to ALSO check the
+  // listed dirs after the regular walk fails.
+  //
+  // The workspace-root node_modules holds hoisted deps (zod, werift,
+  // etc); the server-local node_modules has direct deps. Listing
+  // both covers every realistic resolution.
+  const workspaceRootNodeModules = path.resolve(serverDir, '..', '..', 'node_modules')
+  const extraNodePaths = [nodeModulesDir, workspaceRootNodeModules]
+    .filter((p) => fs.existsSync(p))
+  if (extraNodePaths.length > 0) {
+    const sep = process.platform === 'win32' ? ';' : ':'
+    process.env['NODE_PATH'] = process.env['NODE_PATH']
+      ? `${process.env['NODE_PATH']}${sep}${extraNodePaths.join(sep)}`
+      : extraNodePaths.join(sep)
+    // Re-init Node's module path cache so the change takes effect for
+    // subsequent require()/import() calls. Without this the resolver
+    // already cached the empty list at startup.
+    const Module = require('node:module') as { _initPaths: () => void }
+    Module._initPaths()
+    console.log(`[launcher] NODE_PATH extended with: ${extraNodePaths.join(sep)}`)
+  }
+
+  // Now safe to load main.ts (which has static imports from @camstack/core)
+  console.log('[launcher] Starting server...')
+  await import('./main')
+}
+
+// Signal handlers — forward to default exit so NestJS shutdown hooks
+// (Moleculer broker stopped() → kills spawned workers) run cleanly.
+// Without these, TTY close / `npm run serve` kill leaves workers orphaned.
+let shuttingDown = false
+const handleSignal = (signal: NodeJS.Signals) => {
+  if (shuttingDown) return
+  shuttingDown = true
+  console.log(`[launcher] Received ${signal} — shutting down`)
+  process.exit(0)
+}
+process.on('SIGHUP', handleSignal)
+process.on('SIGTERM', handleSignal)
+process.on('SIGINT', handleSignal)
+
+// Parent-death watchdog (macOS: no PR_SET_PDEATHSIG). If tsx watch / npm
+// get orphaned to init, self-destruct so NestJS shutdown hooks fire before
+// the process tree turns into a zombie.
+const initialPpid = process.ppid
+setInterval(() => {
+  if (process.ppid === 1 && initialPpid !== 1) {
+    console.error('[launcher] Parent died (reparented to init) — exiting')
+    process.exit(0)
+  }
+}, 2000).unref()
+
+launch().catch((err) => {
+  console.error('[launcher] FATAL:', err)
+  process.exit(1)
+})