@checkstack/healthcheck-common 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @checkstack/healthcheck-common
 
+## 0.12.0
+
+### Minor Changes
+
+- 8d1ef12: ## Downstream consumer bumps for the anomaly detection + cache system rollout
+
+  Packages on this branch were updated as part of the anomaly detection feature (schema annotations on result fields, plugin metadata for the modular cache system) but were not listed in the upstream changesets.
+
+  - **`@checkstack/healthcheck-common`** (minor) — new RPC contract additions and schema changes supporting per-field anomaly metadata.
+  - **`@checkstack/cache-memory-common`** (minor) — new package providing access rules + plugin metadata for the in-memory cache backend.
+  - **healthcheck plugins** (patch) — adopt the new `x-anomaly-*` schema annotations on their result fields so anomaly detection works automatically against their checks. No public API changes.
+  - **integration / notification / auth / queue / collector plugins** (patch) — minor internal updates as consumers of upstream API changes (cache plugin registry, schema additions). No public API changes.
+
+### Patch Changes
+
+- Updated dependencies [8d1ef12]
+  - @checkstack/common@0.7.0
+  - @checkstack/signal-common@0.1.10
+
+## 0.11.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`
+
+- 26d8bae: Source attribution and filtering for satellite health checks
+
+  **Source Attribution**
+
+  - Fixed satellite result attribution: runs from satellites now correctly display their source instead of defaulting to "Local"
+  - Added `sourceId` and `sourceLabel` to both public and detailed history API responses
+
+  **Source Filtering**
+
+  - Added `sourceFilter` parameter to `getHistory`, `getDetailedHistory`, and `getDetailedAggregatedHistory` RPC endpoints
+  - Source filter supports "local" (core-only), specific satellite UUID, or all sources
+  - Filter applies to all three aggregation tiers (raw, hourly, daily)
+
+  **Frontend**
+
+  - System detail accordion shows source filter buttons (All / Local / per-satellite) next to date range filter
+  - Filter applies to both charts and recent runs table
+  - Source column added to the recent runs table with Local/Remote badges
+  - Health check history detail page includes per-satellite source filter buttons
+
 ## 0.10.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-common",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "type": "module",
   "exports": {
     ".": {
@@ -8,8 +8,8 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.6.4",
-    "@checkstack/signal-common": "0.1.8",
+    "@checkstack/common": "0.6.5",
+    "@checkstack/signal-common": "0.1.9",
     "zod": "^4.2.1"
   },
   "devDependencies": {

package/src/routes.ts

@@ -7,6 +7,7 @@ export const healthcheckRoutes = createRoutes("healthcheck", {
   config: "/config",
   create: "/config/create",
   edit: "/config/:configId/edit",
+  assignments: "/assignments/:systemId",
   history: "/history",
   historyDetail: "/history/:systemId/:configurationId",
   historyRun: "/history/:systemId/:configurationId/:runId",

package/src/rpc-contract.ts

@@ -12,6 +12,7 @@ import {
   HealthCheckRunSchema,
   HealthCheckRunPublicSchema,
   HealthCheckStatusSchema,
+  HealthCheckRunResultSchema,
   StateThresholdsSchema,
   RetentionConfigSchema,
   AggregatedBucketBaseSchema,
@@ -148,6 +149,10 @@ export const healthCheckContract = {
           configurationName: z.string(),
           enabled: z.boolean(),
           stateThresholds: StateThresholdsSchema.optional(),
+          /** IDs of satellites assigned to execute this health check */
+          satelliteIds: z.array(z.string()).optional(),
+          /** Whether to also run this check locally on the core (default: true) */
+          includeLocal: z.boolean(),
         }),
       ),
     ),
@@ -228,6 +233,8 @@ export const healthCheckContract = {
         configurationId: z.string().optional(),
         startDate: z.date().optional(),
         endDate: z.date().optional(),
+        /** Filter by source: "local" = core only, satellite UUID = specific satellite, undefined = all */
+        sourceFilter: z.string().optional(),
         limit: z.number().optional().default(10),
         offset: z.number().optional().default(0),
         sortOrder: z.enum(["asc", "desc"]),
@@ -251,6 +258,8 @@ export const healthCheckContract = {
         configurationId: z.string().optional(),
         startDate: z.date().optional(),
         endDate: z.date().optional(),
+        /** Filter by source: "local" = core only, satellite UUID = specific satellite, undefined = all */
+        sourceFilter: z.string().optional(),
         limit: z.number().optional().default(10),
         offset: z.number().optional().default(0),
         sortOrder: z.enum(["asc", "desc"]),
@@ -309,6 +318,8 @@ export const healthCheckContract = {
         configurationId: z.string(),
         startDate: z.date(),
         endDate: z.date(),
+        /** Filter by source: "local" = core only, satellite UUID = specific satellite, undefined = all */
+        sourceFilter: z.string().optional(),
         /** Target number of data points (default: 500). Bucket interval is calculated as (endDate - startDate) / targetPoints */
         targetPoints: z.number().min(10).max(2000).default(500),
       }),
@@ -371,6 +382,92 @@ export const healthCheckContract = {
         ),
       }),
     ),
+
+  // ==========================================================================
+  // SERVICE INTERFACE (userType: "service" — backend-to-backend only)
+  // Used by satellite-backend to fetch assignments and submit results.
+  // ==========================================================================
+
+  getAssignmentsForSatellite: proc({
+    operationType: "query",
+    userType: "service",
+    access: [],
+  })
+    .input(z.object({ satelliteId: z.string() }))
+    .output(
+      z.array(
+        z.object({
+          configId: z.string(),
+          systemId: z.string(),
+          strategyId: z.string(),
+          config: z.record(z.string(), z.unknown()),
+          collectors: z
+            .array(
+              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(),
+              }),
+            )
+            .optional(),
+          intervalSeconds: z.number(),
+        }),
+      ),
+    ),
+
+  ingestSatelliteResult: proc({
+    operationType: "mutation",
+    userType: "service",
+    access: [],
+  })
+    .input(
+      z.object({
+        configId: z.string(),
+        systemId: z.string(),
+        status: HealthCheckStatusSchema,
+        latencyMs: z.number().optional(),
+        result: HealthCheckRunResultSchema.optional(),
+        executedAt: z.string(),
+        sourceId: z.string(),
+        sourceLabel: z.string(),
+      }),
+    )
+    .output(z.void()),
+
+  getRunsForAnalysis: proc({
+    operationType: "query",
+    userType: "service",
+    access: [],
+  })
+    .input(
+      z.object({
+        startDate: z.date(),
+        limitPerAssignment: z.number().optional().default(200),
+      }),
+    )
+    .output(
+      z.array(
+        z.object({
+          systemId: z.string(),
+          configurationId: z.string(),
+          runs: z.array(
+            z.object({
+              result: z.record(z.string(), z.unknown()).nullable().optional(),
+            }),
+          ),
+        }),
+      ),
+    ),
 };
 // Export contract type
 export type HealthCheckContract = typeof healthCheckContract;

package/src/schemas.ts

@@ -124,6 +124,25 @@ export const HealthCheckStatusSchema = z.enum([
 
 export type HealthCheckStatus = z.infer<typeof HealthCheckStatusSchema>;
 
+/**
+ * Canonical shape for a single health check run result.
+ * Both the local queue-executor and satellite agent MUST produce this shape
+ * to ensure the frontend (auto-charts, history detail) renders correctly.
+ */
+export const HealthCheckRunResultSchema = z.object({
+  status: HealthCheckStatusSchema,
+  latencyMs: z.number(),
+  message: z.string().optional(),
+  metadata: z.object({
+    connected: z.boolean(),
+    connectionTimeMs: z.number().optional(),
+    collectors: z.record(z.string(), z.unknown()).optional(),
+    error: z.string().optional(),
+  }),
+});
+
+export type HealthCheckRunResult = z.infer<typeof HealthCheckRunResultSchema>;
+
 // --- State Threshold Schemas ---
 
 /**
@@ -192,6 +211,10 @@ export const AssociateHealthCheckSchema = z.object({
   configurationId: z.string().uuid(),
   enabled: z.boolean().default(true),
   stateThresholds: StateThresholdsSchema.optional(),
+  /** IDs of satellites assigned to execute this health check */
+  satelliteIds: z.array(z.string()).optional(),
+  /** Whether to also run this check locally on the core instance (default: true) */
+  includeLocal: z.boolean().default(true),
 });
 
 export type AssociateHealthCheck = z.infer<typeof AssociateHealthCheckSchema>;
@@ -210,6 +233,10 @@ export const HealthCheckRunSchema = z.object({
   result: z.record(z.string(), z.unknown()),
   timestamp: z.date(),
   latencyMs: z.number().optional(),
+  /** Source ID for result attribution (null = local core, UUID = satellite) */
+  sourceId: z.string().optional(),
+  /** Human-readable source label (e.g. "Local" or "EU West (eu-west-1)") */
+  sourceLabel: z.string().optional(),
 });
 
 export type HealthCheckRun = z.infer<typeof HealthCheckRunSchema>;
@@ -246,6 +273,10 @@ export const HealthCheckRunPublicSchema = z.object({
   status: HealthCheckStatusSchema,
   timestamp: z.date(),
   latencyMs: z.number().optional(),
+  /** Source ID for result attribution (null = local core, UUID = satellite) */
+  sourceId: z.string().optional(),
+  /** Human-readable source label (e.g. "Local" or "EU West (eu-west-1)") */
+  sourceLabel: z.string().optional(),
 });
 
 export type HealthCheckRunPublic = z.infer<typeof HealthCheckRunPublicSchema>;

package/src/zod-health-result.test.ts

@@ -12,7 +12,7 @@ import {
 describe("stripEphemeralFields", () => {
   it("should strip fields marked with x-ephemeral", () => {
     const schema = healthResultSchema({
-      statusCode: healthResultNumber({ "x-chart-type": "counter" }),
+      statusCode: healthResultNumber({ "x-chart-type": "counter", "x-anomaly-enabled": false }),
       body: healthResultJSONPath({ "x-ephemeral": true }), // Explicitly marked ephemeral
     });
 
@@ -29,8 +29,8 @@ describe("stripEphemeralFields", () => {
 
   it("should preserve non-ephemeral fields", () => {
     const schema = healthResultSchema({
-      responseTimeMs: healthResultNumber({ "x-chart-type": "line" }),
-      statusText: healthResultString({ "x-chart-type": "text" }),
+      responseTimeMs: healthResultNumber({ "x-chart-type": "line", "x-anomaly-enabled": false }),
+      statusText: healthResultString({ "x-chart-type": "text", "x-anomaly-enabled": false }),
     });
 
     const result = {
@@ -45,7 +45,7 @@ describe("stripEphemeralFields", () => {
 
   it("should preserve unknown fields like _collectorId", () => {
     const schema = healthResultSchema({
-      value: healthResultNumber({ "x-chart-type": "counter" }),
+      value: healthResultNumber({ "x-chart-type": "counter", "x-anomaly-enabled": false }),
       body: healthResultJSONPath({ "x-ephemeral": true }),
     });
 

package/src/zod-health-result.ts

@@ -96,7 +96,8 @@ export function healthResultSchema<T extends HealthResultShape>(
 // ============================================================================
 
 /** Chart metadata (excludes x-jsonpath, use healthResultJSONPath for that) */
-type ChartMeta = Omit<HealthResultMeta, "x-jsonpath">;
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+type ChartMeta = DistributiveOmit<HealthResultMeta, "x-jsonpath">;
 
 /**
  * Create a health result string field with typed chart metadata.
@@ -114,7 +115,8 @@ export function healthResultString(
   meta: ChartMeta,
 ): HealthResultField<z.ZodString> {
   const schema = z.string();
-  schema.register(healthResultRegistry, meta);
+  const finalMeta = (meta["x-ephemeral"] ? { ...meta, "x-anomaly-enabled": false as const } : meta) as HealthResultMeta;
+  schema.register(healthResultRegistry, finalMeta);
   return schema as HealthResultField<z.ZodString>;
 }
 
@@ -125,7 +127,8 @@ export function healthResultNumber(
   meta: ChartMeta,
 ): HealthResultField<z.ZodNumber> {
   const schema = z.number();
-  schema.register(healthResultRegistry, meta);
+  const finalMeta = (meta["x-ephemeral"] ? { ...meta, "x-anomaly-enabled": false as const } : meta) as HealthResultMeta;
+  schema.register(healthResultRegistry, finalMeta);
   return schema as HealthResultField<z.ZodNumber>;
 }
 
@@ -136,7 +139,8 @@ export function healthResultBoolean(
   meta: ChartMeta,
 ): HealthResultField<z.ZodBoolean> {
   const schema = z.boolean();
-  schema.register(healthResultRegistry, meta);
+  const finalMeta = (meta["x-ephemeral"] ? { ...meta, "x-anomaly-enabled": false as const } : meta) as HealthResultMeta;
+  schema.register(healthResultRegistry, finalMeta);
   return schema as HealthResultField<z.ZodBoolean>;
 }
 
@@ -155,7 +159,8 @@ export function healthResultArray(
   meta: ChartMeta,
 ): HealthResultField<z.ZodArray<z.ZodString>> {
   const schema = z.array(z.string());
-  schema.register(healthResultRegistry, meta);
+  const finalMeta = (meta["x-ephemeral"] ? { ...meta, "x-anomaly-enabled": false as const } : meta) as HealthResultMeta;
+  schema.register(healthResultRegistry, finalMeta);
   return schema as HealthResultField<z.ZodArray<z.ZodString>>;
 }
 
@@ -176,7 +181,11 @@ export function healthResultJSONPath(
   meta: ChartMeta,
 ): HealthResultField<z.ZodString> {
   const schema = z.string();
-  schema.register(healthResultRegistry, { ...meta, "x-jsonpath": true });
+  schema.register(healthResultRegistry, { 
+    ...meta, 
+    "x-jsonpath": true,
+    "x-anomaly-enabled": false as const // Always disable anomaly detection for raw body payloads
+  } as HealthResultMeta);
   return schema as HealthResultField<z.ZodString>;
 }