@checkstack/satellite-common 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# @checkstack/satellite-common
+
+## 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]
+- Updated dependencies [26d8bae]
+  - @checkstack/healthcheck-common@0.11.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@checkstack/satellite-common",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "0.6.5",
+    "@checkstack/healthcheck-common": "0.10.1",
+    "@checkstack/signal-common": "0.1.9",
+    "@orpc/contract": "^1.13.14",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/scripts": "0.1.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/access.ts

@@ -0,0 +1,29 @@
+import { accessPair } from "@checkstack/common";
+
+/**
+ * Access rules for the Satellite plugin.
+ */
+export const satelliteAccess = {
+  /**
+   * Satellite management access with read and manage levels.
+   * Read allows viewing satellite list and status.
+   * Manage allows creating, deleting, and managing satellites.
+   */
+  satellite: accessPair("satellite", {
+    read: {
+      description: "View satellite list and status",
+    },
+    manage: {
+      description:
+        "Manage satellites - create, delete, and configure satellite nodes",
+    },
+  }),
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const satelliteAccessRules = [
+  satelliteAccess.satellite.read,
+  satelliteAccess.satellite.manage,
+];

package/src/constants.ts

@@ -0,0 +1,28 @@
+/**
+ * How often satellites send heartbeats to the core (in milliseconds).
+ */
+export const HEARTBEAT_INTERVAL_MS = 15_000;
+
+/**
+ * How long the core waits before considering a satellite offline (in milliseconds).
+ * Set to 3× the heartbeat interval to tolerate brief network hiccups.
+ */
+export const OFFLINE_THRESHOLD_MS = 45_000;
+
+/**
+ * Maximum number of health check results to buffer in-memory
+ * on the satellite when the WebSocket connection is lost.
+ * Oldest results are dropped when the buffer is full (FIFO ring buffer).
+ */
+export const RESULT_BUFFER_CAPACITY = 100;
+
+/**
+ * Base delay for reconnection backoff (in milliseconds).
+ * Actual delay uses exponential backoff with jitter.
+ */
+export const RECONNECT_BASE_MS = 1000;
+
+/**
+ * Maximum delay between reconnection attempts (in milliseconds).
+ */
+export const RECONNECT_MAX_MS = 30_000;

package/src/index.ts

@@ -0,0 +1,45 @@
+export { satelliteAccess, satelliteAccessRules } from "./access";
+export {
+  satelliteContract,
+  SatelliteApi,
+  type SatelliteContract,
+} from "./rpc-contract";
+export {
+  SatelliteStatusSchema,
+  SatelliteSchema,
+  SatelliteWithStatusSchema,
+  CreateSatelliteSchema,
+  type SatelliteStatus,
+  type Satellite,
+  type SatelliteWithStatus,
+  type CreateSatellite,
+} from "./schemas";
+export {
+  SatelliteAssignmentSchema,
+  SatelliteToCoreMessageSchema,
+  CoreToSatelliteMessageSchema,
+  type SatelliteAssignment,
+  type SatelliteToCoreMessage,
+  type CoreToSatelliteMessage,
+  type AuthenticateMessage,
+  type HeartbeatMessage,
+  type ResultMessage,
+  type StrategyErrorMessage,
+  type AuthenticatedMessage,
+  type AuthFailedMessage,
+  type ConfigUpdatedMessage,
+  type ShutdownMessage,
+} from "./protocol";
+export {
+  SATELLITE_STATUS_CHANGED,
+  SATELLITE_CONFIG_CHANGED,
+} from "./signals";
+export {
+  HEARTBEAT_INTERVAL_MS,
+  OFFLINE_THRESHOLD_MS,
+  RESULT_BUFFER_CAPACITY,
+  RECONNECT_BASE_MS,
+  RECONNECT_MAX_MS,
+} from "./constants";
+export * from "./plugin-metadata";
+export { satelliteRoutes } from "./routes";

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the satellite plugin.
+ * Exported from the common package so both backend and frontend can reference it.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "satellite",
+});

package/src/protocol.ts

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import {
+  HealthCheckStatusSchema,
+  HealthCheckRunResultSchema,
+} from "@checkstack/healthcheck-common";
+
+// =============================================================================
+// SATELLITE ASSIGNMENT (Core → Satellite configuration payload)
+// =============================================================================
+
+/**
+ * A single collector configuration sent to the satellite for execution.
+ */
+const SatelliteCollectorConfigSchema = z.object({
+  id: z.string(),
+  collectorId: z.string(),
+  config: z.record(z.string(), z.unknown()),
+  assertions: z
+    .array(
+      z.object({
+        field: z.string(),
+        jsonPath: z.string().optional(),
+        operator: z.string(),
+        value: z.unknown().optional(),
+      }),
+    )
+    .optional(),
+});
+
+/**
+ * A health check assignment sent from the core to a satellite.
+ * Contains everything the satellite needs to execute the check.
+ */
+export const SatelliteAssignmentSchema = z.object({
+  configId: z.string(),
+  systemId: z.string(),
+  strategyId: z.string(),
+  config: z.record(z.string(), z.unknown()),
+  collectors: z.array(SatelliteCollectorConfigSchema).optional(),
+  intervalSeconds: z.number(),
+});
+
+export type SatelliteAssignment = z.infer<typeof SatelliteAssignmentSchema>;
+
+// =============================================================================
+// SATELLITE → CORE MESSAGES
+// =============================================================================
+
+const AuthenticateMessageSchema = z.object({
+  type: z.literal("authenticate"),
+  clientId: z.string(),
+  token: z.string(),
+});
+
+const HeartbeatMessageSchema = z.object({
+  type: z.literal("heartbeat"),
+  version: z.string(),
+  uptimeSeconds: z.number(),
+});
+
+const ResultMessageSchema = z.object({
+  type: z.literal("result"),
+  configId: z.string(),
+  systemId: z.string(),
+  status: HealthCheckStatusSchema,
+  latencyMs: z.number().optional(),
+  /** Structured run result — typed to enforce parity with the local executor */
+  result: HealthCheckRunResultSchema.optional(),
+  executedAt: z.string(),
+});
+
+const StrategyErrorMessageSchema = z.object({
+  type: z.literal("strategy_error"),
+  strategyId: z.string(),
+  message: z.string(),
+});
+
+/**
+ * Discriminated union of all messages that a satellite can send to the core.
+ */
+export const SatelliteToCoreMessageSchema = z.discriminatedUnion("type", [
+  AuthenticateMessageSchema,
+  HeartbeatMessageSchema,
+  ResultMessageSchema,
+  StrategyErrorMessageSchema,
+]);
+
+export type SatelliteToCoreMessage = z.infer<
+  typeof SatelliteToCoreMessageSchema
+>;
+
+// Re-export individual message types for use in handler type narrowing
+export type AuthenticateMessage = z.infer<typeof AuthenticateMessageSchema>;
+export type HeartbeatMessage = z.infer<typeof HeartbeatMessageSchema>;
+export type ResultMessage = z.infer<typeof ResultMessageSchema>;
+export type StrategyErrorMessage = z.infer<typeof StrategyErrorMessageSchema>;
+
+// =============================================================================
+// CORE → SATELLITE MESSAGES
+// =============================================================================
+
+const AuthenticatedMessageSchema = z.object({
+  type: z.literal("authenticated"),
+  satelliteId: z.string(),
+  assignments: z.array(SatelliteAssignmentSchema),
+});
+
+const AuthFailedMessageSchema = z.object({
+  type: z.literal("auth_failed"),
+  reason: z.string(),
+});
+
+const ConfigUpdatedMessageSchema = z.object({
+  type: z.literal("config_updated"),
+  assignments: z.array(SatelliteAssignmentSchema),
+});
+
+const ShutdownMessageSchema = z.object({
+  type: z.literal("shutdown"),
+  reason: z.string(),
+});
+
+/**
+ * Discriminated union of all messages that the core can send to a satellite.
+ */
+export const CoreToSatelliteMessageSchema = z.discriminatedUnion("type", [
+  AuthenticatedMessageSchema,
+  AuthFailedMessageSchema,
+  ConfigUpdatedMessageSchema,
+  ShutdownMessageSchema,
+]);
+
+export type CoreToSatelliteMessage = z.infer<
+  typeof CoreToSatelliteMessageSchema
+>;
+
+// Re-export individual message types
+export type AuthenticatedMessage = z.infer<typeof AuthenticatedMessageSchema>;
+export type AuthFailedMessage = z.infer<typeof AuthFailedMessageSchema>;
+export type ConfigUpdatedMessage = z.infer<typeof ConfigUpdatedMessageSchema>;
+export type ShutdownMessage = z.infer<typeof ShutdownMessageSchema>;

package/src/routes.ts

@@ -0,0 +1,20 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the satellite plugin.
+ * Import and use these routes in both frontend plugins and for link generation.
+ *
+ * @example Frontend plugin usage
+ * ```tsx
+ * import { satelliteRoutes } from "@checkstack/satellite-common";
+ *
+ * createFrontendPlugin({
+ *   routes: [
+ *     { route: satelliteRoutes.routes.list, element: <SatelliteListPage /> },
+ *   ],
+ * });
+ * ```
+ */
+export const satelliteRoutes = createRoutes("satellite", {
+  list: "/",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { createClientDefinition, proc } from "@checkstack/common";
+import { satelliteAccess } from "./access";
+import { pluginMetadata } from "./plugin-metadata";
+import { SatelliteWithStatusSchema, CreateSatelliteSchema } from "./schemas";
+
+/**
+ * RPC contract for satellite management.
+ * Consumed by satellite-frontend for the management UI.
+ */
+export const satelliteContract = {
+  /** List all satellites with computed online/offline status */
+  listSatellites: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [satelliteAccess.satellite.read],
+  }).output(
+    z.object({ satellites: z.array(SatelliteWithStatusSchema) }),
+  ),
+
+  /** Get a single satellite by ID */
+  getSatellite: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [satelliteAccess.satellite.read],
+  })
+    .input(z.object({ id: z.string() }))
+    .output(SatelliteWithStatusSchema.nullable()),
+
+  /**
+   * Create a new satellite.
+   * Returns the satellite record AND the plaintext token (shown once).
+   * The clientId is the satellite's UUID (satellite.id).
+   */
+  createSatellite: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [satelliteAccess.satellite.manage],
+  })
+    .input(CreateSatelliteSchema)
+    .output(
+      z.object({
+        satellite: SatelliteWithStatusSchema,
+        /** Plaintext token — shown once, never stored */
+        token: z.string(),
+      }),
+    ),
+
+  /** Delete a satellite by ID */
+  deleteSatellite: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [satelliteAccess.satellite.manage],
+  })
+    .input(z.object({ id: z.string() }))
+    .output(z.void()),
+
+  /**
+   * Get the list of online satellite IDs.
+   * Used internally by healthcheck-backend for stale source exclusion
+   * during health state evaluation.
+   */
+  getOnlineSatelliteIds: proc({
+    operationType: "query",
+    userType: "service",
+    access: [],
+  }).output(z.object({ satelliteIds: z.array(z.string()) })),
+};
+
+// Export contract type
+export type SatelliteContract = typeof satelliteContract;
+
+// Export client definition for type-safe forPlugin usage
+// Use: const client = rpcApi.forPlugin(SatelliteApi);
+export const SatelliteApi = createClientDefinition(
+  satelliteContract,
+  pluginMetadata,
+);

package/src/schemas.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+
+// =============================================================================
+// SATELLITE ENTITY SCHEMAS
+// =============================================================================
+
+/**
+ * Satellite status derived from lastHeartbeatAt vs OFFLINE_THRESHOLD_MS.
+ */
+export const SatelliteStatusSchema = z.enum(["online", "offline"]);
+
+export type SatelliteStatus = z.infer<typeof SatelliteStatusSchema>;
+
+/**
+ * Full satellite record as stored in the database.
+ * tokenHash is intentionally excluded from the schema —
+ * it should never leave the backend.
+ */
+export const SatelliteSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  region: z.string(),
+  tags: z.record(z.string(), z.string()),
+  lastHeartbeatAt: z.date().optional(),
+  version: z.string().optional(),
+  createdAt: z.date(),
+});
+
+export type Satellite = z.infer<typeof SatelliteSchema>;
+
+/**
+ * Satellite with computed online/offline status.
+ * Used in API responses — the status is derived from lastHeartbeatAt.
+ */
+export const SatelliteWithStatusSchema = SatelliteSchema.extend({
+  status: SatelliteStatusSchema,
+});
+
+export type SatelliteWithStatus = z.infer<typeof SatelliteWithStatusSchema>;
+
+/**
+ * Input schema for creating a new satellite.
+ */
+export const CreateSatelliteSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  region: z.string().min(1, "Region is required"),
+  tags: z.record(z.string(), z.string()).default({}),
+});
+
+export type CreateSatellite = z.infer<typeof CreateSatelliteSchema>;

package/src/signals.ts

@@ -0,0 +1,28 @@
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+import { SatelliteStatusSchema } from "./schemas";
+
+/**
+ * Broadcast when a satellite's connection status changes (online ↔ offline).
+ * Frontend components listening to this signal can update status badges in real-time.
+ */
+export const SATELLITE_STATUS_CHANGED = createSignal(
+  "satellite.status.changed",
+  z.object({
+    satelliteId: z.string(),
+    status: SatelliteStatusSchema,
+    name: z.string(),
+    region: z.string(),
+  }),
+);
+
+/**
+ * Broadcast when satellite configuration changes (assignments updated).
+ * Frontend components listening to this signal can refetch satellite data.
+ */
+export const SATELLITE_CONFIG_CHANGED = createSignal(
+  "satellite.config.changed",
+  z.object({
+    satelliteId: z.string(),
+  }),
+);

package/tsconfig.json

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