@checkstack/backend 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @checkstack/backend
 
+## 0.6.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/backend-api@0.12.0
+  - @checkstack/queue-api@0.2.13
+  - @checkstack/signal-backend@0.1.19
+
 ## 0.5.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "checkstack": {
     "type": "backend"
   },
@@ -13,14 +13,14 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/api-docs-common": "0.1.8",
-    "@checkstack/auth-common": "0.6.0",
-    "@checkstack/backend-api": "0.11.0",
-    "@checkstack/common": "0.6.4",
+    "@checkstack/api-docs-common": "0.1.9",
+    "@checkstack/auth-common": "0.6.1",
+    "@checkstack/backend-api": "0.11.1",
+    "@checkstack/common": "0.6.5",
     "@checkstack/drizzle-helper": "0.0.4",
-    "@checkstack/queue-api": "0.2.11",
-    "@checkstack/signal-backend": "0.1.17",
-    "@checkstack/signal-common": "0.1.8",
+    "@checkstack/queue-api": "0.2.12",
+    "@checkstack/signal-backend": "0.1.18",
+    "@checkstack/signal-common": "0.1.9",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
@@ -40,6 +40,6 @@
     "@types/bun": "latest",
     "@checkstack/tsconfig": "0.0.5",
     "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.17"
+    "@checkstack/test-utils-backend": "0.1.18"
   }
 }

package/src/index.ts

@@ -18,6 +18,26 @@ import {
   SignalServiceImpl,
   type WebSocketData,
 } from "@checkstack/signal-backend";
+import type { WsConnectionHandlers } from "@checkstack/backend-api";
+
+// =============================================================================
+// SERVER-LEVEL WEBSOCKET DATA
+// =============================================================================
+
+/**
+ * Discriminated union for all WebSocket connection types.
+ * Signal connections are handled by signal-backend.
+ * Plugin WS connections are routed via the generic WebSocket route registry.
+ */
+type ServerWsData =
+  | ({ connectionType: "signal" } & WebSocketData)
+  | {
+      connectionType: "plugin";
+      createdAt: number;
+      pluginHandlers: WsConnectionHandlers;
+      /** Mutable proxy — patched in open() to the real Bun WS */
+      wsProxy: { send: (data: string) => void; close: () => void };
+    };
 import {
   PLUGIN_INSTALLED,
   PLUGIN_DEREGISTERED,
@@ -398,7 +418,7 @@ void init();
 // Custom fetch handler that handles WebSocket upgrades
 const fetch = async (
   req: Request,
-  server: Server<WebSocketData>
+  server: Server<ServerWsData>
 ): Promise<Response | undefined> => {
   // Set the server reference for WebSocket pub/sub after startup
   if (wsHandler && !server.upgrade) {
@@ -407,7 +427,8 @@ const fetch = async (
   }
 
   // Give the WebSocket handler the server reference if needed
-  wsHandler?.setServer(server);
+  // Cast is safe: signal handler only reads its own fields via connectionType guard
+  wsHandler?.setServer(server as unknown as Server<WebSocketData>);
 
   const url = new URL(req.url);
 
@@ -427,6 +448,7 @@ const fetch = async (
 
     const success = server.upgrade(req, {
       data: {
+        connectionType: "signal" as const,
         userId, // undefined for anonymous, set for authenticated users
         createdAt: Date.now(),
       },
@@ -437,6 +459,37 @@ const fetch = async (
       : new Response("WebSocket upgrade failed", { status: 500 });
   }
 
+  // Handle WebSocket upgrade for plugin-registered routes (/api/ws/*)
+  const WS_PREFIX = "/api/ws/";
+  if (url.pathname.startsWith(WS_PREFIX)) {
+    const pluginPath = url.pathname.slice(WS_PREFIX.length);
+    const handler = pluginManager.getWsStore().getHandler(pluginPath);
+    if (!handler) {
+      return new Response("Not Found", { status: 404 });
+    }
+
+    // Mutable WsConnection proxy — starts as no-op, patched in open() to the real Bun WS.
+    // The handler captures this object reference, so patching its methods works.
+    const wsProxy = {
+      send: (_: string) => {},
+      close: () => {},
+    };
+    const pluginHandlers = handler.onConnection(wsProxy);
+
+    const success = server.upgrade(req, {
+      data: {
+        connectionType: "plugin" as const,
+        createdAt: Date.now(),
+        pluginHandlers,
+        wsProxy,
+      },
+    });
+
+    return success
+      ? undefined
+      : new Response("WebSocket upgrade failed", { status: 500 });
+  }
+
   // Handle regular HTTP requests with Hono
   return app.fetch(req, server);
 };
@@ -446,25 +499,49 @@ export default {
   fetch,
   websocket: {
     // Type template for ws.data
-    data: {} as WebSocketData,
+    data: {} as ServerWsData,
 
-    open(ws: import("bun").ServerWebSocket<WebSocketData>) {
-      wsHandler?.websocket.open(ws);
+    open(ws: import("bun").ServerWebSocket<ServerWsData>) {
+      if (ws.data.connectionType === "plugin") {
+        // Patch the mutable proxy to wire through to the real Bun WebSocket
+        ws.data.wsProxy.send = (data: string) => ws.send(data);
+        ws.data.wsProxy.close = () => ws.close();
+        return;
+      }
+      // Signal connection
+      wsHandler?.websocket.open(
+        ws as unknown as import("bun").ServerWebSocket<WebSocketData>,
+      );
     },
 
     message(
-      ws: import("bun").ServerWebSocket<WebSocketData>,
-      message: string | Buffer
+      ws: import("bun").ServerWebSocket<ServerWsData>,
+      message: string | Buffer,
     ) {
-      wsHandler?.websocket.message(ws, message);
+      if (ws.data.connectionType === "plugin") {
+        void ws.data.pluginHandlers.onMessage(message.toString());
+        return;
+      }
+      wsHandler?.websocket.message(
+        ws as unknown as import("bun").ServerWebSocket<WebSocketData>,
+        message,
+      );
     },
 
     close(
-      ws: import("bun").ServerWebSocket<WebSocketData>,
+      ws: import("bun").ServerWebSocket<ServerWsData>,
       code: number,
-      reason: string
+      reason: string,
     ) {
-      wsHandler?.websocket.close(ws, code, reason);
+      if (ws.data.connectionType === "plugin") {
+        ws.data.pluginHandlers.onClose();
+        return;
+      }
+      wsHandler?.websocket.close(
+        ws as unknown as import("bun").ServerWebSocket<WebSocketData>,
+        code,
+        reason,
+      );
     },
   },
 };

package/src/plugin-manager/core-services.ts

@@ -26,6 +26,10 @@ import {
 import { EventBus } from "../services/event-bus.js";
 import { getPluginSchemaName } from "@checkstack/drizzle-helper";
 import { createScopedDb } from "../utils/scoped-db.js";
+import {
+  WebSocketRouteStoreImpl,
+  createScopedWsRegistry,
+} from "../services/ws-route-registry";
 
 /**
  * Check if a PostgreSQL schema exists.
@@ -55,7 +59,7 @@ export function registerCoreServices({
   pluginRpcRouters: Map<string, unknown>;
   pluginHttpHandlers: Map<string, (req: Request) => Promise<Response>>;
   pluginContractRegistry: Map<string, unknown>;
-}): { collectorRegistry: CoreCollectorRegistry } {
+}): { collectorRegistry: CoreCollectorRegistry; wsStore: WebSocketRouteStoreImpl } {
   // 1. Database Factory (Scoped)
   registry.registerFactory(coreServices.database, async (metadata) => {
     const { pluginId, previousPluginIds } = metadata;
@@ -346,6 +350,12 @@ export function registerCoreServices({
     return eventBusInstance;
   });
 
+  // 10. WebSocket Route Registry (Scoped Factory - auto-prefixes with pluginId)
+  const globalWsStore = new WebSocketRouteStoreImpl();
+  registry.registerFactory(coreServices.wsRegistry, (metadata) =>
+    createScopedWsRegistry(globalWsStore, metadata.pluginId),
+  );
+
   // Return global registries for lifecycle cleanup
-  return { collectorRegistry: globalCollectorRegistry };
+  return { collectorRegistry: globalCollectorRegistry, wsStore: globalWsStore };
 }

package/src/plugin-manager.ts

@@ -2,6 +2,7 @@ import type { Hono } from "hono";
 import { adminPool, db } from "./db";
 import { ServiceRegistry } from "./services/service-registry";
 import type { CoreCollectorRegistry } from "./services/collector-registry";
+import type { WebSocketRouteStoreImpl } from "./services/ws-route-registry";
 import {
   BackendPlugin,
   ServiceRef,
@@ -50,6 +51,9 @@ export class PluginManager {
   // Global collector registry reference for cleanup
   private collectorRegistry: CoreCollectorRegistry;
 
+  // Global WebSocket route store for server-level routing
+  private wsStore: WebSocketRouteStoreImpl;
+
   constructor() {
     const registries = registerCoreServices({
       registry: this.registry,
@@ -59,6 +63,15 @@ export class PluginManager {
       pluginContractRegistry: this.pluginContractRegistry,
     });
     this.collectorRegistry = registries.collectorRegistry;
+    this.wsStore = registries.wsStore;
+  }
+
+  /**
+   * Get the global WebSocket route store for the backend server to use
+   * during WebSocket upgrade routing.
+   */
+  getWsStore(): WebSocketRouteStoreImpl {
+    return this.wsStore;
   }
 
   registerExtensionPoint<T>(ref: ExtensionPoint<T>, impl: T) {

package/src/services/ws-route-registry.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "bun:test";
+import {
+  WebSocketRouteStoreImpl,
+  createScopedWsRegistry,
+} from "./ws-route-registry";
+import type { WebSocketRouteHandler } from "@checkstack/backend-api";
+
+function createMockHandler(): WebSocketRouteHandler {
+  return {
+    onConnection: () => ({
+      onMessage: () => {},
+      onClose: () => {},
+    }),
+  };
+}
+
+describe("WebSocketRouteStoreImpl", () => {
+  it("should register and retrieve a handler by full path", () => {
+    const store = new WebSocketRouteStoreImpl();
+    const handler = createMockHandler();
+
+    store.registerHandler("satellite", handler);
+
+    expect(store.getHandler("satellite")).toBe(handler);
+  });
+
+  it("should return undefined for unregistered paths", () => {
+    const store = new WebSocketRouteStoreImpl();
+
+    expect(store.getHandler("nonexistent")).toBeUndefined();
+  });
+
+  it("should reject duplicate registrations", () => {
+    const store = new WebSocketRouteStoreImpl();
+    const handler = createMockHandler();
+
+    store.registerHandler("satellite", handler);
+
+    expect(() => store.registerHandler("satellite", handler)).toThrow(
+      "WebSocket route already registered: /api/ws/satellite",
+    );
+  });
+});
+
+describe("createScopedWsRegistry", () => {
+  it('should auto-prefix pluginId when path is "/"', () => {
+    const store = new WebSocketRouteStoreImpl();
+    const scoped = createScopedWsRegistry(store, "satellite");
+    const handler = createMockHandler();
+
+    scoped.register("/", handler);
+
+    expect(store.getHandler("satellite")).toBe(handler);
+  });
+
+  it("should auto-prefix pluginId with sub-path", () => {
+    const store = new WebSocketRouteStoreImpl();
+    const scoped = createScopedWsRegistry(store, "my-plugin");
+    const handler = createMockHandler();
+
+    scoped.register("/connect", handler);
+
+    expect(store.getHandler("my-plugin/connect")).toBe(handler);
+  });
+
+  it("should namespace different plugins independently", () => {
+    const store = new WebSocketRouteStoreImpl();
+    const scopedA = createScopedWsRegistry(store, "plugin-a");
+    const scopedB = createScopedWsRegistry(store, "plugin-b");
+    const handlerA = createMockHandler();
+    const handlerB = createMockHandler();
+
+    scopedA.register("/", handlerA);
+    scopedB.register("/", handlerB);
+
+    expect(store.getHandler("plugin-a")).toBe(handlerA);
+    expect(store.getHandler("plugin-b")).toBe(handlerB);
+  });
+
+  it("should prevent cross-plugin path collisions", () => {
+    const store = new WebSocketRouteStoreImpl();
+    const scopedA = createScopedWsRegistry(store, "plugin-a");
+    const scopedB = createScopedWsRegistry(store, "plugin-a");
+    const handler = createMockHandler();
+
+    scopedA.register("/", handler);
+
+    // Same pluginId + same path = collision
+    expect(() => scopedB.register("/", handler)).toThrow(
+      "WebSocket route already registered",
+    );
+  });
+});

package/src/services/ws-route-registry.ts

@@ -0,0 +1,46 @@
+import type {
+  WebSocketRouteRegistry,
+  WebSocketRouteHandler,
+  WebSocketRouteStore,
+} from "@checkstack/backend-api";
+
+/**
+ * Global store for all registered WebSocket route handlers.
+ * Plugins don't interact with this directly — they use a scoped
+ * `WebSocketRouteRegistry` that auto-prefixes the pluginId.
+ */
+export class WebSocketRouteStoreImpl implements WebSocketRouteStore {
+  private handlers = new Map<string, WebSocketRouteHandler>();
+
+  /** Register a handler at a fully-qualified path (e.g., "satellite" or "satellite/connect"). */
+  registerHandler(fullPath: string, handler: WebSocketRouteHandler): void {
+    if (this.handlers.has(fullPath)) {
+      throw new Error(
+        `WebSocket route already registered: /api/ws/${fullPath}`,
+      );
+    }
+    this.handlers.set(fullPath, handler);
+  }
+
+  getHandler(fullPath: string): WebSocketRouteHandler | undefined {
+    return this.handlers.get(fullPath);
+  }
+}
+
+/**
+ * Create a scoped WebSocket route registry for a specific plugin.
+ * Auto-prefixes all paths with the plugin's ID.
+ */
+export function createScopedWsRegistry(
+  store: WebSocketRouteStoreImpl,
+  pluginId: string,
+): WebSocketRouteRegistry {
+  return {
+    register(path: string, handler: WebSocketRouteHandler): void {
+      // Normalize: "/" maps to just the pluginId, "/foo" maps to "pluginId/foo"
+      const suffix = path === "/" ? "" : path.replace(/^\//, "/");
+      const fullPath = `${pluginId}${suffix}`;
+      store.registerHandler(fullPath, handler);
+    },
+  };
+}