@checkstack/satellite 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# @checkstack/satellite
+
+## 0.2.0
+
+### Minor Changes
+
+- 26d8bae: Distributed satellite health checks and Assignment IDE page
+
+  **Satellite System**
+
+  - New `satellite-backend`, `satellite-common`, `satellite-frontend`, and `satellite` agent packages for distributed health check execution
+  - WebSocket-based satellite connectivity with authentication, heartbeats, and live configuration push
+  - Satellite management UI with create dialog, status badges, and list page
+
+  **Live Configuration Updates**
+
+  - Added `assignmentChanged` hook to `healthcheck-backend` for cross-plugin communication
+  - `satellite-backend` subscribes to assignment changes and pushes config updates to connected satellites in real-time
+
+  **Assignment IDE Page**
+
+  - Replaced the 1028-line modal-based `SystemHealthCheckAssignment` component with a full-page IDE layout
+  - New modular components: `AssignmentTree`, `GeneralPanel`, `ThresholdsPanel`, `RetentionPanel`, `ExecutionPanel`
+  - Added unassign capability and sorted assignment lists for stable ordering
+
+  **Shared IDE Primitives**
+
+  - Extracted `IDETreeNode`, `IDETreeSection`, `IDEStatusBar`, `IDELayout` to `@checkstack/ui` for cross-plugin reuse
+  - Migrated existing health check IDE editor to use shared primitives
+
+  **Infrastructure**
+
+  - Added `Dockerfile.satellite` for containerized satellite deployment
+  - WebSocket route registry in `@checkstack/backend` and `@checkstack/backend-api`
+
+### Patch Changes
+
+- Updated dependencies [26d8bae]
+  - @checkstack/satellite-common@0.2.0
+  - @checkstack/backend-api@0.12.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@checkstack/satellite",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "start": "bun run src/index.ts",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/satellite-common": "0.1.0",
+    "@checkstack/backend-api": "0.11.1",
+    "@checkstack/common": "0.6.5"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/scripts": "0.1.2",
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,298 @@
+import type {
+  SatelliteAssignment,
+  ResultMessage,
+} from "@checkstack/satellite-common";
+import type {
+  ConnectedClient,
+  TransportClient,
+} from "@checkstack/backend-api";
+import { SatelliteClient } from "./satellite-client";
+import { Scheduler } from "./scheduler";
+import { loadStrategies } from "./strategy-loader";
+
+// =============================================================================
+// Environment validation — fail fast if required vars are missing
+// =============================================================================
+
+const CORE_URL = process.env["CHECKSTACK_CORE_URL"];
+const CLIENT_ID = process.env["CHECKSTACK_SATELLITE_CLIENT_ID"];
+const TOKEN = process.env["CHECKSTACK_SATELLITE_TOKEN"];
+
+if (!CORE_URL) {
+  throw new Error("CHECKSTACK_CORE_URL environment variable is required");
+}
+if (!CLIENT_ID) {
+  throw new Error(
+    "CHECKSTACK_SATELLITE_CLIENT_ID environment variable is required",
+  );
+}
+if (!TOKEN) {
+  throw new Error("CHECKSTACK_SATELLITE_TOKEN environment variable is required");
+}
+
+// Read version from package.json
+const pkg = await import("../package.json");
+const VERSION = (pkg as { version?: string }).version ?? "unknown";
+
+// =============================================================================
+// Logger
+// =============================================================================
+
+const logger = {
+  info: (msg: string) => console.log(`[satellite] ${msg}`),
+  warn: (msg: string) => console.warn(`[satellite] ${msg}`),
+  error: (msg: string) => console.error(`[satellite] ${msg}`),
+  debug: (msg: string) => {
+    if (process.env["DEBUG"]) {
+      console.log(`[satellite:debug] ${msg}`);
+    }
+  },
+};
+
+// =============================================================================
+// Strategy loading — dynamically discovers healthcheck-*-backend plugins
+// =============================================================================
+
+logger.info(`Starting Checkstack Satellite v${VERSION}`);
+logger.info("Loading health check strategies...");
+
+const { healthCheckRegistry, collectorRegistry } = await loadStrategies({
+  logger,
+});
+
+// =============================================================================
+// Health check executor — mirrors core queue-executor pattern:
+// 1. Look up strategy by ID
+// 2. createClient(config) to establish connection + measure latency
+// 3. Execute collectors against the connected client
+// 4. Close client and report result
+// =============================================================================
+
+async function executeAssignment(
+  assignment: SatelliteAssignment,
+): Promise<ResultMessage> {
+  const strategy = healthCheckRegistry.getStrategy(assignment.strategyId);
+  if (!strategy) {
+    return {
+      type: "result",
+      configId: assignment.configId,
+      systemId: assignment.systemId,
+      status: "unhealthy",
+      latencyMs: 0,
+      executedAt: new Date().toISOString(),
+      result: {
+        status: "unhealthy",
+        latencyMs: 0,
+        message: `Strategy ${assignment.strategyId} not found in satellite`,
+        metadata: {
+          connected: false,
+          error: `Strategy ${assignment.strategyId} not found in satellite`,
+        },
+      },
+    };
+  }
+
+  const start = performance.now();
+  let connectedClient:
+    | ConnectedClient<TransportClient<never, unknown>>
+    | undefined;
+
+  try {
+    // 1. Establish connection (measures connectivity + latency)
+    connectedClient = await strategy.createClient(assignment.config);
+    const connectionTimeMs = Math.round(performance.now() - start);
+
+    // 2. Execute collectors if configured
+    const collectors = assignment.collectors ?? [];
+    const collectorResults: Record<string, unknown> = {};
+    let hasCollectorError = false;
+    let errorMessage: string | undefined;
+
+    if (collectors.length > 0) {
+      const collectorPromises = collectors.map(async (collectorEntry) => {
+        const registered = collectorRegistry.getCollector(
+          collectorEntry.collectorId,
+        );
+        if (!registered) {
+          logger.warn(
+            `Collector ${collectorEntry.collectorId} not found, skipping`,
+          );
+          return { storageKey: collectorEntry.id, skipped: true };
+        }
+
+        try {
+          const collectorResult = await registered.collector.execute({
+            config: collectorEntry.config,
+            client: connectedClient!.client,
+            pluginId: assignment.strategyId,
+          });
+
+          return {
+            storageKey: collectorEntry.id,
+            skipped: false,
+            success: !collectorResult.error,
+            error: collectorResult.error,
+            result: {
+              _collectorId: collectorEntry.collectorId,
+              ...collectorResult.result,
+            },
+          };
+        } catch (error) {
+          return {
+            storageKey: collectorEntry.id,
+            skipped: false,
+            success: false,
+            error: String(error),
+            result: {
+              _collectorId: collectorEntry.collectorId,
+              error: String(error),
+            },
+          };
+        }
+      });
+
+      const settledResults = await Promise.allSettled(collectorPromises);
+
+      for (const settled of settledResults) {
+        if (settled.status === "rejected") {
+          hasCollectorError = true;
+          if (!errorMessage) errorMessage = String(settled.reason);
+          continue;
+        }
+
+        const result = settled.value;
+        if (result.skipped) continue;
+
+        collectorResults[result.storageKey] = result.result;
+
+        if (!result.success) {
+          hasCollectorError = true;
+          if (!errorMessage) errorMessage = result.error;
+        }
+      }
+    }
+
+    const latencyMs = Math.round(performance.now() - start);
+
+    // 3. Build result — matches local queue-executor structure so
+    //    frontend auto-charts and history detail page work identically.
+    const status = hasCollectorError ? "unhealthy" : "healthy";
+    const result: ResultMessage = {
+      type: "result",
+      configId: assignment.configId,
+      systemId: assignment.systemId,
+      status,
+      latencyMs,
+      executedAt: new Date().toISOString(),
+      result: {
+        status,
+        latencyMs,
+        message: errorMessage
+          ? `Check failed: ${errorMessage}`
+          : `Completed in ${latencyMs}ms`,
+        metadata: {
+          connected: true,
+          connectionTimeMs,
+          collectors: collectorResults,
+        },
+      },
+    };
+
+    return result;
+  } catch (error) {
+    const latencyMs = Math.round(performance.now() - start);
+    return {
+      type: "result",
+      configId: assignment.configId,
+      systemId: assignment.systemId,
+      status: "unhealthy",
+      latencyMs,
+      executedAt: new Date().toISOString(),
+      result: {
+        status: "unhealthy",
+        latencyMs,
+        message: String(error),
+        metadata: {
+          connected: !!connectedClient,
+          error: String(error),
+        },
+      },
+    };
+  } finally {
+    try {
+      connectedClient?.close();
+    } catch {
+      // Ignore close errors
+    }
+  }
+}
+
+// =============================================================================
+// Bootstrap
+// =============================================================================
+
+logger.info(`Core URL: ${CORE_URL}`);
+logger.info(`Client ID: ${CLIENT_ID}`);
+
+const client = new SatelliteClient({
+  coreUrl: CORE_URL,
+  clientId: CLIENT_ID,
+  token: TOKEN,
+  version: VERSION,
+  logger,
+  onAssignments: (assignments: SatelliteAssignment[]) => {
+    scheduler.updateAssignments(assignments);
+  },
+  onDisconnect: () => {
+    scheduler.stop();
+  },
+});
+
+const scheduler = new Scheduler({
+  logger,
+  onExecute: async (assignment: SatelliteAssignment) => {
+    try {
+      const result = await executeAssignment(assignment);
+      client.sendResult(result);
+    } catch (error) {
+      logger.error(
+        `Failed to execute ${assignment.configId}: ${String(error)}`,
+      );
+      client.sendResult({
+        type: "result",
+        configId: assignment.configId,
+        systemId: assignment.systemId,
+        status: "unhealthy",
+        latencyMs: 0,
+        executedAt: new Date().toISOString(),
+        result: {
+          status: "unhealthy",
+          latencyMs: 0,
+          message: String(error),
+          metadata: {
+            connected: false,
+            error: String(error),
+          },
+        },
+      });
+    }
+  },
+});
+
+// Start the connection
+void client.connect();
+
+// Graceful shutdown
+process.on("SIGTERM", () => {
+  logger.info("Received SIGTERM, shutting down...");
+  scheduler.stop();
+  client.disconnect();
+  process.exit(0);
+});
+
+process.on("SIGINT", () => {
+  logger.info("Received SIGINT, shutting down...");
+  scheduler.stop();
+  client.disconnect();
+  process.exit(0);
+});

package/src/result-buffer.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect } from "bun:test";
+import { ResultBuffer } from "./result-buffer";
+import type { ResultMessage } from "@checkstack/satellite-common";
+
+function makeResult(overrides?: Partial<ResultMessage>): ResultMessage {
+  return {
+    type: "result",
+    configId: "config-1",
+    systemId: "system-1",
+    status: "healthy",
+    latencyMs: 42,
+    executedAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+describe("ResultBuffer", () => {
+  test("starts empty", () => {
+    const buffer = new ResultBuffer();
+    expect(buffer.size).toBe(0);
+    expect(buffer.isEmpty).toBe(true);
+  });
+
+  test("push adds results", () => {
+    const buffer = new ResultBuffer();
+    buffer.push(makeResult());
+    expect(buffer.size).toBe(1);
+    expect(buffer.isEmpty).toBe(false);
+  });
+
+  test("flush returns all results and clears buffer", () => {
+    const buffer = new ResultBuffer();
+    const r1 = makeResult({ configId: "a" });
+    const r2 = makeResult({ configId: "b" });
+    buffer.push(r1);
+    buffer.push(r2);
+
+    const flushed = buffer.flush();
+    expect(flushed).toHaveLength(2);
+    expect(flushed[0].configId).toBe("a");
+    expect(flushed[1].configId).toBe("b");
+    expect(buffer.size).toBe(0);
+    expect(buffer.isEmpty).toBe(true);
+  });
+
+  test("flush returns empty array when buffer is empty", () => {
+    const buffer = new ResultBuffer();
+    expect(buffer.flush()).toEqual([]);
+  });
+
+  test("drops oldest when capacity is exceeded", () => {
+    const buffer = new ResultBuffer(3);
+    buffer.push(makeResult({ configId: "1" }));
+    buffer.push(makeResult({ configId: "2" }));
+    buffer.push(makeResult({ configId: "3" }));
+
+    // Buffer is full, next push should drop "1"
+    buffer.push(makeResult({ configId: "4" }));
+    expect(buffer.size).toBe(3);
+
+    const flushed = buffer.flush();
+    expect(flushed.map((r) => r.configId)).toEqual(["2", "3", "4"]);
+  });
+
+  test("respects custom capacity", () => {
+    const buffer = new ResultBuffer(1);
+    buffer.push(makeResult({ configId: "first" }));
+    buffer.push(makeResult({ configId: "second" }));
+
+    expect(buffer.size).toBe(1);
+    const flushed = buffer.flush();
+    expect(flushed[0].configId).toBe("second");
+  });
+});

package/src/result-buffer.ts

@@ -0,0 +1,49 @@
+import { RESULT_BUFFER_CAPACITY } from "@checkstack/satellite-common";
+import type { ResultMessage } from "@checkstack/satellite-common";
+
+/**
+ * In-memory FIFO ring buffer for health check results.
+ * When the WebSocket connection is lost, results are queued here.
+ * On reconnection, all buffered results are flushed to the core.
+ * Oldest results are dropped when the buffer is full.
+ */
+export class ResultBuffer {
+  private buffer: ResultMessage[] = [];
+  private readonly capacity: number;
+
+  constructor(capacity = RESULT_BUFFER_CAPACITY) {
+    this.capacity = capacity;
+  }
+
+  /**
+   * Push a result into the buffer.
+   * If the buffer is full, the oldest result is dropped.
+   */
+  push(result: ResultMessage): void {
+    if (this.buffer.length >= this.capacity) {
+      // Drop oldest (FIFO)
+      this.buffer.shift();
+    }
+    this.buffer.push(result);
+  }
+
+  /**
+   * Flush all buffered results and clear the buffer.
+   * Returns the results in chronological order (oldest first).
+   */
+  flush(): ResultMessage[] {
+    const results = [...this.buffer];
+    this.buffer = [];
+    return results;
+  }
+
+  /** Current number of buffered results */
+  get size(): number {
+    return this.buffer.length;
+  }
+
+  /** Whether the buffer is empty */
+  get isEmpty(): boolean {
+    return this.buffer.length === 0;
+  }
+}

package/src/satellite-client.ts

@@ -0,0 +1,224 @@
+import {
+  HEARTBEAT_INTERVAL_MS,
+  RECONNECT_BASE_MS,
+  RECONNECT_MAX_MS,
+} from "@checkstack/satellite-common";
+import type {
+  SatelliteAssignment,
+  CoreToSatelliteMessage,
+  SatelliteToCoreMessage,
+  ResultMessage,
+} from "@checkstack/satellite-common";
+import { ResultBuffer } from "./result-buffer";
+
+interface SatelliteClientConfig {
+  coreUrl: string;
+  clientId: string;
+  token: string;
+  version: string;
+  onAssignments: (assignments: SatelliteAssignment[]) => void;
+  onDisconnect?: () => void;
+  logger?: {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    debug: (msg: string) => void;
+  };
+}
+
+/**
+ * WebSocket client for connecting a satellite to the core.
+ * Handles authentication, heartbeats, result delivery, and reconnection.
+ */
+export class SatelliteClient {
+  private ws: WebSocket | undefined;
+  private heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+  private reconnectAttempt = 0;
+  private startTime = Date.now();
+  private connected = false;
+  private readonly resultBuffer = new ResultBuffer();
+  private readonly config: SatelliteClientConfig;
+
+  constructor(config: SatelliteClientConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Start the connection loop. Connects and automatically reconnects on failure.
+   */
+  async connect(): Promise<void> {
+    const wsUrl = this.buildWsUrl();
+    this.config.logger?.info(`Connecting to core at ${wsUrl}...`);
+
+    try {
+      this.ws = new WebSocket(wsUrl);
+
+      this.ws.addEventListener("open", () => {
+        this.config.logger?.info("WebSocket connection established");
+        this.sendMessage({
+          type: "authenticate",
+          clientId: this.config.clientId,
+          token: this.config.token,
+        });
+      });
+
+      this.ws.addEventListener("message", (event) => {
+        this.handleMessage(String(event.data));
+      });
+
+      this.ws.addEventListener("close", (event) => {
+        this.config.logger?.warn(
+          `WebSocket closed: ${event.code} ${event.reason}`,
+        );
+        this.handleDisconnect();
+      });
+
+      this.ws.addEventListener("error", () => {
+        this.config.logger?.error("WebSocket error");
+      });
+    } catch (error) {
+      this.config.logger?.error(`Connection failed: ${String(error)}`);
+      this.scheduleReconnect();
+    }
+  }
+
+  /**
+   * Send a health check result to the core.
+   * If disconnected, the result is buffered for later delivery.
+   */
+  sendResult(result: ResultMessage): void {
+    if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
+      this.sendMessage(result);
+    } else {
+      this.resultBuffer.push(result);
+      this.config.logger?.debug(
+        `Buffered result (${this.resultBuffer.size} total)`,
+      );
+    }
+  }
+
+  /** Gracefully disconnect */
+  disconnect(): void {
+    this.stopHeartbeat();
+    this.connected = false;
+    this.ws?.close(1000, "Client shutdown");
+  }
+
+  private handleMessage(raw: string): void {
+    let msg: CoreToSatelliteMessage;
+    try {
+      msg = JSON.parse(raw) as CoreToSatelliteMessage;
+    } catch {
+      this.config.logger?.warn(`Invalid message from core: ${raw}`);
+      return;
+    }
+
+    switch (msg.type) {
+      case "authenticated": {
+        this.config.logger?.info(
+          `Authenticated as ${msg.satelliteId}, received ${msg.assignments.length} assignments`,
+        );
+        this.connected = true;
+        this.reconnectAttempt = 0;
+        this.startHeartbeat();
+        this.flushBuffer();
+        this.config.onAssignments(msg.assignments);
+        break;
+      }
+
+      case "auth_failed": {
+        this.config.logger?.error(`Authentication failed: ${msg.reason}`);
+        // Don't reconnect on auth failure — credentials are wrong
+        this.ws?.close(4001, "Auth failed");
+        break;
+      }
+
+      case "config_updated": {
+        this.config.logger?.info(
+          `Config updated: ${msg.assignments.length} assignments`,
+        );
+        this.config.onAssignments(msg.assignments);
+        break;
+      }
+
+      case "shutdown": {
+        this.config.logger?.warn(`Shutdown requested: ${msg.reason}`);
+        this.disconnect();
+        break;
+      }
+    }
+  }
+
+  private handleDisconnect(): void {
+    this.connected = false;
+    this.stopHeartbeat();
+    this.config.onDisconnect?.();
+    this.scheduleReconnect();
+  }
+
+  private scheduleReconnect(): void {
+    const delay = this.calculateBackoff();
+    this.reconnectAttempt++;
+    this.config.logger?.info(
+      `Reconnecting in ${delay}ms (attempt ${this.reconnectAttempt})...`,
+    );
+    setTimeout(() => void this.connect(), delay);
+  }
+
+  /**
+   * Exponential backoff with jitter.
+   * Delay = min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2^attempt) ± jitter
+   */
+  private calculateBackoff(): number {
+    const exponential = RECONNECT_BASE_MS * 2 ** this.reconnectAttempt;
+    const capped = Math.min(exponential, RECONNECT_MAX_MS);
+    // Add ±25% jitter
+    const jitter = capped * 0.25 * (Math.random() * 2 - 1);
+    return Math.round(capped + jitter);
+  }
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
+        this.sendMessage({
+          type: "heartbeat",
+          version: this.config.version,
+          uptimeSeconds: Math.round((Date.now() - this.startTime) / 1000),
+        });
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = undefined;
+    }
+  }
+
+  private flushBuffer(): void {
+    if (this.resultBuffer.isEmpty) return;
+
+    const buffered = this.resultBuffer.flush();
+    this.config.logger?.info(
+      `Flushing ${buffered.length} buffered results to core`,
+    );
+    for (const result of buffered) {
+      this.sendMessage(result);
+    }
+  }
+
+  private sendMessage(msg: SatelliteToCoreMessage): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+
+  private buildWsUrl(): string {
+    const base = this.config.coreUrl
+      .replace(/^http:/, "ws:")
+      .replace(/^https:/, "wss:");
+    return `${base.replace(/\/$/, "")}/api/ws/satellite`;
+  }
+}

package/src/scheduler.ts

@@ -0,0 +1,88 @@
+import type { SatelliteAssignment } from "@checkstack/satellite-common";
+
+interface SchedulerConfig {
+  onExecute: (assignment: SatelliteAssignment) => Promise<void>;
+  logger?: {
+    info: (msg: string) => void;
+    debug: (msg: string) => void;
+  };
+}
+
+/**
+ * Local scheduler for satellite health check execution.
+ * Manages interval timers for each assignment. When assignments are updated,
+ * existing timers are reconciled: unchanged assignments keep running,
+ * removed assignments are stopped, and new assignments are started.
+ */
+export class Scheduler {
+  private timers = new Map<string, ReturnType<typeof setInterval>>();
+  private readonly config: SchedulerConfig;
+
+  constructor(config: SchedulerConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Update the set of assignments. Reconciles timers with the new set.
+   */
+  updateAssignments(assignments: SatelliteAssignment[]): void {
+    // Build a set of current assignment keys
+    const newKeys = new Set(
+      assignments.map((a) => this.makeKey(a)),
+    );
+
+    // Stop timers for removed assignments
+    for (const [key, timer] of this.timers) {
+      if (!newKeys.has(key)) {
+        clearInterval(timer);
+        this.timers.delete(key);
+        this.config.logger?.debug(`Stopped scheduler for ${key}`);
+      }
+    }
+
+    // Start timers for new/updated assignments
+    for (const assignment of assignments) {
+      const key = this.makeKey(assignment);
+      if (this.timers.has(key)) {
+        // Already running — keep existing timer
+        continue;
+      }
+
+      this.config.logger?.debug(
+        `Starting scheduler for ${key} (every ${assignment.intervalSeconds}s)`,
+      );
+
+      // Execute immediately, then at interval
+      void this.config.onExecute(assignment);
+
+      const timer = setInterval(
+        () => void this.config.onExecute(assignment),
+        assignment.intervalSeconds * 1000,
+      );
+      this.timers.set(key, timer);
+    }
+
+    this.config.logger?.info(
+      `Scheduler updated: ${this.timers.size} active check(s)`,
+    );
+  }
+
+  /** Stop all timers */
+  stop(): void {
+    for (const [key, timer] of this.timers) {
+      clearInterval(timer);
+      this.config.logger?.debug(`Stopped scheduler for ${key}`);
+    }
+    this.timers.clear();
+  }
+
+  /** Number of active timers */
+  get activeCount(): number {
+    return this.timers.size;
+  }
+
+  /** Unique key for an assignment (config+system, since a satellite only runs each once) */
+  private makeKey(assignment: SatelliteAssignment): string {
+    return `${assignment.configId}:${assignment.systemId}`;
+  }
+}

package/src/strategy-loader.ts

@@ -0,0 +1,215 @@
+import type {
+  HealthCheckStrategy,
+  HealthCheckRegistry,
+  CollectorRegistry,
+  RegisteredCollector,
+  CollectorStrategy,
+  TransportClient,
+  BackendPluginRegistry,
+} from "@checkstack/backend-api";
+import type { PluginMetadata } from "@checkstack/common";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Simple in-memory HealthCheckRegistry for the satellite.
+ * Captures strategy registrations from plugins without needing the full backend.
+ */
+class SatelliteHealthCheckRegistry implements HealthCheckRegistry {
+  private strategies = new Map<string, HealthCheckStrategy>();
+  private pluginId = "";
+
+  setPluginId(id: string) {
+    this.pluginId = id;
+  }
+
+  register<S extends HealthCheckStrategy>(strategy: S): void {
+    const qualifiedId = `${this.pluginId}.${strategy.id}`;
+    this.strategies.set(qualifiedId, strategy);
+  }
+
+  getStrategy(id: string): HealthCheckStrategy | undefined {
+    return this.strategies.get(id);
+  }
+
+  getStrategies(): HealthCheckStrategy[] {
+    return [...this.strategies.values()];
+  }
+
+  getStrategiesWithMeta() {
+    return [...this.strategies.entries()].map(([qualifiedId, strategy]) => ({
+      qualifiedId,
+      strategy,
+      ownerPluginId: qualifiedId.split(".")[0] ?? qualifiedId,
+    }));
+  }
+}
+
+/**
+ * Simple in-memory CollectorRegistry for the satellite.
+ */
+class SatelliteCollectorRegistry implements CollectorRegistry {
+  private collectors = new Map<string, RegisteredCollector>();
+  private pluginMeta: PluginMetadata = { pluginId: "" };
+
+  setPlugin(meta: PluginMetadata) {
+    this.pluginMeta = meta;
+  }
+
+  register(
+    collector: CollectorStrategy<TransportClient<unknown, unknown>>,
+  ): void {
+    const qualifiedId = `${this.pluginMeta.pluginId}.${collector.id}`;
+    this.collectors.set(qualifiedId, {
+      qualifiedId,
+      collector,
+      ownerPlugin: this.pluginMeta,
+    });
+  }
+
+  getCollector(id: string): RegisteredCollector | undefined {
+    return this.collectors.get(id);
+  }
+
+  getCollectorsForPlugin(meta: PluginMetadata): RegisteredCollector[] {
+    return [...this.collectors.values()].filter(
+      (c) => c.ownerPlugin.pluginId === meta.pluginId,
+    );
+  }
+
+  getCollectors(): RegisteredCollector[] {
+    return [...this.collectors.values()];
+  }
+}
+
+/**
+ * Discovers and loads all healthcheck strategy plugins from the plugins directory.
+ * Returns in-memory registries populated with the strategies and collectors.
+ */
+export async function loadStrategies(opts: {
+  logger: { info: (msg: string) => void; debug: (msg: string) => void; warn: (msg: string) => void };
+}): Promise<{
+  healthCheckRegistry: SatelliteHealthCheckRegistry;
+  collectorRegistry: SatelliteCollectorRegistry;
+}> {
+  const { logger } = opts;
+  const healthCheckRegistry = new SatelliteHealthCheckRegistry();
+  const collectorRegistry = new SatelliteCollectorRegistry();
+
+  // Discover plugins by scanning for healthcheck-*-backend directories
+  // In Docker, plugins are at /app/plugins/; locally, relative to this file
+  const pluginsDir = path.resolve(import.meta.dir, "../../../plugins");
+  let entries: string[];
+  try {
+    entries = await readdir(pluginsDir);
+  } catch {
+    // Try Docker path
+    try {
+      const dockerPluginsDir = "/app/plugins";
+      entries = await readdir(dockerPluginsDir);
+      return loadPluginsFromDir({
+        pluginsDir: dockerPluginsDir,
+        entries,
+        healthCheckRegistry,
+        collectorRegistry,
+        logger,
+      });
+    } catch {
+      logger.warn("No plugins directory found, no strategies loaded");
+      return { healthCheckRegistry, collectorRegistry };
+    }
+  }
+
+  return loadPluginsFromDir({
+    pluginsDir,
+    entries,
+    healthCheckRegistry,
+    collectorRegistry,
+    logger,
+  });
+}
+
+async function loadPluginsFromDir(opts: {
+  pluginsDir: string;
+  entries: string[];
+  healthCheckRegistry: SatelliteHealthCheckRegistry;
+  collectorRegistry: SatelliteCollectorRegistry;
+  logger: { info: (msg: string) => void; debug: (msg: string) => void; warn: (msg: string) => void };
+}): Promise<{
+  healthCheckRegistry: SatelliteHealthCheckRegistry;
+  collectorRegistry: SatelliteCollectorRegistry;
+}> {
+  const { pluginsDir, entries, healthCheckRegistry, collectorRegistry, logger } = opts;
+
+  // Include both healthcheck strategy plugins and standalone collector plugins
+  const pluginDirs = entries.filter(
+    (e) =>
+      (e.startsWith("healthcheck-") && e.endsWith("-backend")) ||
+      (e.startsWith("collector-") && e.endsWith("-backend")),
+  );
+
+  logger.info(`Discovered ${pluginDirs.length} strategy plugins`);
+
+  for (const dir of pluginDirs) {
+    try {
+      const pluginPath = path.join(pluginsDir, dir, "src", "index.ts");
+      const mod = await import(pluginPath);
+      const plugin = mod.default;
+
+      if (!plugin?.metadata?.pluginId || !plugin?.register) {
+        logger.warn(`Plugin ${dir} has no valid default export, skipping`);
+        continue;
+      }
+
+      const pluginId = plugin.metadata.pluginId as string;
+
+
+
+      // Create a mock env that captures registrations
+      healthCheckRegistry.setPluginId(pluginId);
+      collectorRegistry.setPlugin(plugin.metadata as PluginMetadata);
+
+      const mockEnv: Partial<BackendPluginRegistry> = {
+        registerInit: ({ init }) => {
+          // We'll call init synchronously after register
+          // Store it for deferred execution
+          (mockEnv as Record<string, unknown>)._init = init;
+        },
+        registerAccessRules: () => {
+          // No-op in satellite
+        },
+      };
+
+      plugin.register(mockEnv);
+
+      // Call the stored init function with our registries
+      const storedInit = (mockEnv as Record<string, unknown>)._init as (
+        deps: Record<string, unknown>,
+      ) => Promise<void>;
+
+      if (storedInit) {
+        await storedInit({
+          healthCheckRegistry,
+          collectorRegistry,
+          logger: {
+            debug: (msg: string) => logger.debug(`[${pluginId}] ${msg}`),
+            info: (msg: string) => logger.info(`[${pluginId}] ${msg}`),
+            warn: (msg: string) => logger.warn(`[${pluginId}] ${msg}`),
+            error: (msg: string) => logger.warn(`[${pluginId}] ${msg}`),
+          },
+        });
+      }
+
+      logger.info(`✓ Loaded strategy plugin: ${pluginId}`);
+    } catch (error) {
+      logger.warn(`Failed to load plugin ${dir}: ${String(error)}`);
+    }
+  }
+
+  logger.info(
+    `Loaded ${healthCheckRegistry.getStrategies().length} strategies, ` +
+    `${collectorRegistry.getCollectors().length} collectors`,
+  );
+
+  return { healthCheckRegistry, collectorRegistry };
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}