@checkstack/backend 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # @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
+
+- d1a2796: Enforce stricter code quality standards and eliminate AI slop anti-patterns.
+
+  **New utility**
+
+  - `extractErrorMessage(error, fallback?)` in `@checkstack/common` for consistent error extraction
+
+  **ESLint rules**
+
+  - `react-hooks/rules-of-hooks` and `exhaustive-deps` for hook correctness
+  - `no-console` in frontend packages — forces `toast` over silent `console.error`
+  - `no-restricted-syntax` banning `instanceof Error` — forces `extractErrorMessage`
+  - Custom `no-eslint-disable-any` rule preventing `@typescript-eslint/no-explicit-any` circumvention
+
+  **Refactoring**
+
+  - Replace 141 `instanceof Error` boilerplate patterns across the codebase
+  - Replace swallowed `console.error` with user-visible `toast.error()` feedback
+  - Remove 15 redundant `as` type casts in IntegrationsPage and ProviderConnectionsPage
+  - Consolidate 3 identical callback handlers into `handleDialogClose`
+  - Fix conditional React hook call in `FormField.tsx`
+  - Fix unstable useMemo deps in `Dashboard.tsx`
+  - Replace `useEffect`→`setState` with derived `useMemo` in `RegisterPage.tsx`
+  - Rewrite `keystore.test.ts` with typed `DrizzleMockChain` (eliminating 7 `any` suppressions)
+  - Delete obvious comments in `encryption.ts` and Teams `provider.ts`
+
+- Updated dependencies [d1a2796]
+  - @checkstack/common@0.6.5
+  - @checkstack/backend-api@0.11.1
+  - @checkstack/api-docs-common@0.1.9
+  - @checkstack/auth-common@0.6.1
+  - @checkstack/signal-backend@0.1.18
+  - @checkstack/signal-common@0.1.9
+  - @checkstack/queue-api@0.2.12
+
 ## 0.5.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.5.2",
+  "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.10.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.9",
-    "@checkstack/signal-backend": "0.1.15",
-    "@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",
@@ -38,8 +38,8 @@
   "devDependencies": {
     "@types/pg": "^8.11.0",
     "@types/bun": "latest",
-    "@checkstack/tsconfig": "0.0.4",
+    "@checkstack/tsconfig": "0.0.5",
     "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.15"
+    "@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/api-router.ts

@@ -68,11 +68,15 @@ export function createApiRouteHandler({
               return await next(rest);
             } catch (error) {
               if (logger) {
-                (logger as Logger).error(
-                  `RPC procedure error: ${String(error)}`,
-                );
-                if (error instanceof Error && error.stack) {
-                  (logger as Logger).error(`Stack trace: ${error.stack}`);
+                logger.error(`RPC procedure error: ${String(error)}`);
+                const stack =
+                  error !== null &&
+                  typeof error === "object" &&
+                  "stack" in error
+                    ? (error as { stack: string }).stack
+                    : undefined;
+                if (stack) {
+                  logger.error(`Stack trace: ${stack}`);
                 }
               }
               throw error;

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/keystore.test.ts

@@ -1,76 +1,74 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
 import { KeyStore } from "./keystore";
 
-// 1. Mock the DB module
-const mockDb = {
-  insert: mock(() => ({
+/**
+ * Drizzle fluent-chain mock factory.
+ *
+ * Drizzle's API returns `this` from every query-builder method (select, from,
+ * where, …). The final object is thenable — awaiting it resolves the query.
+ * This factory builds a single object that satisfies that pattern without
+ * resorting to `any`.
+ */
+interface DrizzleMockChain {
+  insert: ReturnType<typeof mock>;
+  values: ReturnType<typeof mock>;
+  update: ReturnType<typeof mock>;
+  set: ReturnType<typeof mock>;
+  delete: ReturnType<typeof mock>;
+  select: ReturnType<typeof mock>;
+  from: ReturnType<typeof mock>;
+  where: ReturnType<typeof mock>;
+  orderBy: ReturnType<typeof mock>;
+  limit: ReturnType<typeof mock>;
+  // eslint-disable-next-line unicorn/no-thenable -- Required: Drizzle chains are awaitable via a custom .then()
+  then: (resolve: (rows: unknown[]) => void) => void;
+}
+
+function createDrizzleMockChain(): DrizzleMockChain {
+  const chain: DrizzleMockChain = {
+    insert: mock(() => chain),
     values: mock(() => Promise.resolve()),
-  })),
-  select: mock(() => mockDb),
-  from: mock(() => mockDb),
-  where: mock(() => mockDb),
-  orderBy: mock(() => mockDb),
-  limit: mock(() => mockDb),
-};
-
-// Return empty list by default for selects
-// We will override implementation per test if needed
-// But since the chain returns `mockDb` (itself), the final await needs to return data.
-// Wait, `await db.select()...` means the object must be thenable or the last method returns a Promise.
-// Drizzle: .execute() or await directly.
-// In the code: `const validKeys = await db.select()...`
-// So the object returned by `limit()` must be thenable.
-
-const mockChain = () => {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const chain: any = {};
-  chain.insert = mock(() => chain);
-  chain.values = mock(() => Promise.resolve());
-  chain.update = mock(() => chain);
-  chain.set = mock(() => chain);
-  chain.delete = mock(() => chain);
-
-  chain.select = mock(() => chain);
-  chain.from = mock(() => chain);
-  chain.where = mock(() => chain);
-  chain.orderBy = mock(() => chain);
-  chain.limit = mock(() => chain); // limit is the last one called in getSigningKey
-
-  // Make it thenable to simulate 'await'
-  // eslint-disable-next-line unicorn/no-thenable, @typescript-eslint/no-explicit-any
-  chain.then = (resolve: any) => resolve([]); // Default empty array
+    update: mock(() => chain),
+    set: mock(() => chain),
+    delete: mock(() => chain),
+    select: mock(() => chain),
+    from: mock(() => chain),
+    where: mock(() => chain),
+    orderBy: mock(() => chain),
+    limit: mock(() => chain),
+    // eslint-disable-next-line unicorn/no-thenable -- Required: Drizzle chains are awaitable via a custom .then()
+    then: (resolve) => resolve([]),
+  };
 
   return chain;
-};
+}
 
-const dbMockInstance = mockChain();
+const dbMock = createDrizzleMockChain();
 
-mock.module("../db", () => {
-  return {
-    db: dbMockInstance,
-  };
-});
+mock.module("../db", () => ({
+  db: dbMock,
+}));
 
 describe("KeyStore", () => {
   let store: KeyStore;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let mockKeyForGeneration: any;
+  let mockKeyForGeneration: Record<string, unknown>;
 
   beforeEach(async () => {
     store = new KeyStore();
+
     // Reset mocks
-    dbMockInstance.select.mockClear();
-    dbMockInstance.insert.mockClear();
-    dbMockInstance.update.mockClear();
-    dbMockInstance.set.mockClear();
-    dbMockInstance.delete.mockClear();
-    dbMockInstance.where.mockClear();
-
-    // Reset default behavior
-    // eslint-disable-next-line unicorn/no-thenable, @typescript-eslint/no-explicit-any
-    dbMockInstance.then = (resolve: any) => resolve([]);
-
-    // Pre-generate a valid key for mocking responses
+    dbMock.select.mockClear();
+    dbMock.insert.mockClear();
+    dbMock.update.mockClear();
+    dbMock.set.mockClear();
+    dbMock.delete.mockClear();
+    dbMock.where.mockClear();
+
+    // Reset default behavior — empty result set
+    // eslint-disable-next-line unicorn/no-thenable -- Required: Drizzle chains are awaitable via a custom .then()
+    dbMock.then = (resolve) => resolve([]);
+
+    // Pre-generate a valid RSA keypair for mock responses
     const { generateKeyPair, exportJWK } = await import("jose");
     const { publicKey, privateKey } = await generateKeyPair("RS256", {
       extractable: true,
@@ -90,10 +88,9 @@ describe("KeyStore", () => {
   });
 
   it("should generate a new key if no active key exists", async () => {
-    // Mock DB returning empty array for existing keys first, then the new key
     let callCount = 0;
-    // eslint-disable-next-line unicorn/no-thenable, @typescript-eslint/no-explicit-any
-    dbMockInstance.then = (resolve: any) => {
+    // eslint-disable-next-line unicorn/no-thenable -- Required: Drizzle chains are awaitable via a custom .then()
+    dbMock.then = (resolve) => {
       callCount++;
       if (callCount === 1) {
         return resolve([]); // First call: no active key
@@ -103,9 +100,9 @@ describe("KeyStore", () => {
 
     const result = await store.getSigningKey();
 
-    expect(result.kid).toBe("generated-kid"); // The mock key ID
+    expect(result.kid).toBe("generated-kid");
     expect(result.key).toBeTruthy();
-    expect(dbMockInstance.insert).toHaveBeenCalled();
+    expect(dbMock.insert).toHaveBeenCalled();
   });
 
   it("should return the existing key if it is valid", async () => {
@@ -122,24 +119,21 @@ describe("KeyStore", () => {
       publicKey: JSON.stringify(publicJwk),
       privateKey: JSON.stringify(privateJwk),
       algorithm: "RS256",
-      createdAt: new Date().toISOString(), // Fresh
+      createdAt: new Date().toISOString(),
       expiresAt: undefined,
       revokedAt: undefined,
     };
 
-    // Mock DB return
-    // eslint-disable-next-line unicorn/no-thenable, @typescript-eslint/no-explicit-any
-    dbMockInstance.then = (resolve: any) => resolve([mockKeyRow]);
+    // eslint-disable-next-line unicorn/no-thenable -- Required: Drizzle chains are awaitable via a custom .then()
+    dbMock.then = (resolve) => resolve([mockKeyRow]);
 
     const result = await store.getSigningKey();
 
     expect(result.kid).toBe(kid);
-    // Should NOT have called insert (no rotation)
-    expect(dbMockInstance.insert).not.toHaveBeenCalled();
+    expect(dbMock.insert).not.toHaveBeenCalled();
   });
 
   it("should rotate key if the existing one is too old", async () => {
-    // Generate a real key
     const { generateKeyPair, exportJWK } = await import("jose");
     const { publicKey, privateKey } = await generateKeyPair("RS256", {
       extractable: true,
@@ -148,7 +142,6 @@ describe("KeyStore", () => {
     const privateJwk = await exportJWK(privateKey);
     const kid = "old-kid";
 
-    // Create an OLD date > 1 hour ago
     const oldDate = new Date(Date.now() - 1000 * 60 * 60 * 2).toISOString();
 
     const mockKeyRow = {
@@ -162,14 +155,12 @@ describe("KeyStore", () => {
     };
 
     let callCount = 0;
-    // eslint-disable-next-line unicorn/no-thenable, @typescript-eslint/no-explicit-any
-    dbMockInstance.then = (resolve: any) => {
+    // eslint-disable-next-line unicorn/no-thenable -- Required: Drizzle chains are awaitable via a custom .then()
+    dbMock.then = (resolve) => {
       callCount++;
       if (callCount === 1) {
-        return resolve([mockKeyRow]); // First call: check active
+        return resolve([mockKeyRow]);
       }
-      // Second call: fetch new key (in rotate logic)
-      // We need to return a valid new key so it doesn't crash
       return resolve([
         {
           ...mockKeyRow,
@@ -181,10 +172,10 @@ describe("KeyStore", () => {
 
     const result = await store.getSigningKey();
 
-    expect(result.kid).toBe("new-kid"); // Should return the NEW key
-    expect(dbMockInstance.insert).toHaveBeenCalled();
-    expect(dbMockInstance.update).toHaveBeenCalled(); // Should set expiresAt on old key
-    expect(dbMockInstance.set).toHaveBeenCalledWith(
+    expect(result.kid).toBe("new-kid");
+    expect(dbMock.insert).toHaveBeenCalled();
+    expect(dbMock.update).toHaveBeenCalled();
+    expect(dbMock.set).toHaveBeenCalledWith(
       expect.objectContaining({ expiresAt: expect.any(String) })
     );
   });
@@ -192,7 +183,7 @@ describe("KeyStore", () => {
   it("should delete expired keys in cleanupKeys", async () => {
     await store.cleanupKeys();
 
-    expect(dbMockInstance.delete).toHaveBeenCalled();
-    expect(dbMockInstance.where).toHaveBeenCalled();
+    expect(dbMock.delete).toHaveBeenCalled();
+    expect(dbMock.where).toHaveBeenCalled();
   });
 });

package/src/services/queue-manager.ts

@@ -9,6 +9,7 @@ import type { QueuePluginRegistryImpl } from "./queue-plugin-registry";
 import type { Logger, ConfigService } from "@checkstack/backend-api";
 import { z } from "zod";
 import { QueueProxy } from "./queue-proxy";
+import { extractErrorMessage } from "@checkstack/common";
 
 // Schema for active plugin pointer with version for multi-instance coordination
 const activePluginPointerSchema = z.object({
@@ -151,7 +152,7 @@ export class QueueManagerImpl implements QueueManager {
       await testQueue.stop();
       this.logger.info("✅ Connection test successful");
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = extractErrorMessage(error);
       this.logger.error(`❌ Connection test failed: ${message}`);
       throw new Error(`Failed to connect to queue: ${message}`);
     }

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);
+    },
+  };
+}