@camstack/server 1.0.0 → 1.0.1

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

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

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