@checkstack/healthcheck-common 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @checkstack/healthcheck-common
 
+## 0.1.0
+
+### Minor Changes
+
+- f5b1f49: Extended health check system with per-collector assertion support.
+
+  - Added `collectors` column to `healthCheckConfigurations` schema for storing collector configs
+  - Updated queue-executor to run configured collectors and evaluate per-collector assertions
+  - Added `CollectorAssertionSchema` to healthcheck-common for assertion validation
+  - Results now stored with `metadata.collectors` containing per-collector result data
+
+- f5b1f49: Added JSONPath assertions for response body validation and fully qualified strategy IDs.
+
+  **JSONPath Assertions:**
+
+  - Added `healthResultJSONPath()` factory in healthcheck-common for fields supporting JSONPath queries
+  - Extended AssertionBuilder with jsonpath field type showing path input (e.g., `$.data.status`)
+  - Added `jsonPath` field to `CollectorAssertionSchema` for persistence
+  - HTTP Request collector body field now supports JSONPath assertions
+
+  **Fully Qualified Strategy IDs:**
+
+  - HealthCheckRegistry now uses scoped factories like CollectorRegistry
+  - Strategies are stored with `pluginId.strategyId` format
+  - Added `getStrategiesWithMeta()` method to HealthCheckRegistry interface
+  - Router returns qualified IDs so frontend can correctly fetch collectors
+
+  **UI Improvements:**
+
+  - Save button disabled when collector configs have invalid required fields
+  - Fixed nested button warning in CollectorList accordion
+
+### Patch Changes
+
+- Updated dependencies [f5b1f49]
+  - @checkstack/common@0.0.3
+  - @checkstack/signal-common@0.0.3
+
+## 0.0.3
+
+### Patch Changes
+
+- cb82e4d: Improved `counter` and `pie` auto-chart types to show frequency distributions instead of just the latest value. Both chart types now count occurrences of each unique value across all runs/buckets, making them more intuitive for visualizing data like HTTP status codes.
+
+  Changed HTTP health check chart annotations: `statusCode` now uses `pie` chart (distribution view), `contentType` now uses `counter` chart (frequency count).
+
+  Fixed scrollbar hopping when health check signals update the accordion content. All charts now update silently without layout shift or loading state flicker.
+
+  Refactored health check visualization architecture:
+
+  - `HealthCheckStatusTimeline` and `HealthCheckLatencyChart` now accept `HealthCheckDiagramSlotContext` directly, handling data transformation internally
+  - `HealthCheckDiagram` refactored to accept context from parent, ensuring all visualizations share the same data source and update together on signals
+  - `HealthCheckSystemOverview` simplified to use `useHealthCheckData` hook for consolidated data fetching with automatic signal-driven refresh
+
+  Added `silentRefetch()` method to `usePagination` hook for background data refreshes without showing loading indicators.
+
+  Fixed `useSignal` hook to use a ref pattern internally, preventing stale closure issues. Callbacks now always access the latest values without requiring manual memoization or refs in consumer components.
+
+  Added signal handling to `useHealthCheckData` hook for automatic chart refresh when health check runs complete.
+
 ## 0.0.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-common",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -15,6 +15,8 @@ export interface HealthCheckStrategyDto {
   configSchema: Record<string, unknown>;
 }
 
+import type { CollectorConfigEntry } from "./schemas";
+
 /**
  * Represents a Health Check Configuration (the check definition/template).
  * NOTE: This is derived from Zod schema but kept as interface for explicit type documentation.
@@ -25,6 +27,7 @@ export interface HealthCheckConfiguration {
   strategyId: string;
   config: Record<string, unknown>;
   intervalSeconds: number;
+  collectors?: CollectorConfigEntry[];
   createdAt: Date;
   updatedAt: Date;
 }

package/src/rpc-contract.ts

@@ -8,6 +8,7 @@ import { z } from "zod";
 import { permissions } from "./permissions";
 import {
   HealthCheckStrategyDtoSchema,
+  CollectorDtoSchema,
   HealthCheckConfigurationSchema,
   CreateHealthCheckConfigurationSchema,
   UpdateHealthCheckConfigurationSchema,
@@ -53,6 +54,18 @@ export const healthCheckContract = {
     })
     .output(z.array(HealthCheckStrategyDtoSchema)),
 
+  /**
+   * Get available collectors for a specific strategy.
+   * Returns collectors that support the given strategy's transport.
+   */
+  getCollectors: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.healthCheckRead.id],
+    })
+    .input(z.object({ strategyId: z.string() }))
+    .output(z.array(CollectorDtoSchema)),
+
   // ==========================================================================
   // CONFIGURATION MANAGEMENT (userType: "authenticated")
   // ==========================================================================

package/src/schemas.ts

@@ -13,21 +13,85 @@ export const HealthCheckStrategyDtoSchema = z.object({
   aggregatedResultSchema: z.record(z.string(), z.unknown()).optional(),
 });
 
+export type HealthCheckStrategyDto = z.infer<
+  typeof HealthCheckStrategyDtoSchema
+>;
+
+/**
+ * Collector DTO for frontend discovery.
+ * ID is fully-qualified: `pluginId.collectorId` (e.g., `collector-hardware.cpu`)
+ */
+export const CollectorDtoSchema = z.object({
+  /** Fully-qualified ID: pluginId.collectorId */
+  id: z.string(),
+  /** Human-readable name */
+  displayName: z.string(),
+  /** Optional description */
+  description: z.string().optional(),
+  /** JSON Schema for collector configuration */
+  configSchema: z.record(z.string(), z.unknown()),
+  /** JSON Schema for per-run result metadata (with chart annotations) */
+  resultSchema: z.record(z.string(), z.unknown()),
+  /** Whether multiple instances of this collector are allowed per config */
+  allowMultiple: z.boolean(),
+});
+
+export type CollectorDto = z.infer<typeof CollectorDtoSchema>;
+
+/**
+ * A single collector assertion with field, operator, and optional value.
+ */
+export const CollectorAssertionSchema = z.object({
+  /** Field path to assert on (from collector result schema) */
+  field: z.string(),
+  /** JSONPath expression for jsonpath-type assertions (e.g., $.status) */
+  jsonPath: z.string().optional(),
+  /** Comparison operator */
+  operator: z.string(),
+  /** Expected value (not needed for some operators like exists, isTrue) */
+  value: z.unknown().optional(),
+});
+
+export type CollectorAssertion = z.infer<typeof CollectorAssertionSchema>;
+
+/**
+ * A collector configuration entry within a health check.
+ * Each entry includes the collector ID, its config, and per-collector assertions.
+ */
+export const CollectorConfigEntrySchema = z.object({
+  /** Fully-qualified collector ID (e.g., collector-hardware.cpu) */
+  collectorId: z.string(),
+  /** Collector-specific configuration */
+  config: z.record(z.string(), z.unknown()),
+  /** Per-collector assertions (schema derived from collector's resultSchema) */
+  assertions: z.array(CollectorAssertionSchema).optional(),
+});
+
+export type CollectorConfigEntry = z.infer<typeof CollectorConfigEntrySchema>;
+
 export const HealthCheckConfigurationSchema = z.object({
   id: z.string(),
   name: z.string(),
   strategyId: z.string(),
   config: z.record(z.string(), z.unknown()),
   intervalSeconds: z.number(),
+  /** Optional collector configurations */
+  collectors: z.array(CollectorConfigEntrySchema).optional(),
   createdAt: z.date(),
   updatedAt: z.date(),
 });
 
+export type HealthCheckConfiguration = z.infer<
+  typeof HealthCheckConfigurationSchema
+>;
+
 export const CreateHealthCheckConfigurationSchema = z.object({
   name: z.string().min(1),
   strategyId: z.string().min(1),
   config: z.record(z.string(), z.unknown()),
   intervalSeconds: z.number().min(1),
+  /** Optional collector configurations */
+  collectors: z.array(CollectorConfigEntrySchema).optional(),
 });
 
 export type CreateHealthCheckConfiguration = z.infer<

package/src/zod-health-result.ts

@@ -10,6 +10,7 @@ import { z } from "zod";
  * Numeric types:
  * - line: Time series line chart for numeric metrics over time
  * - bar: Bar chart for distributions (record of string to number)
+ * - pie: Pie chart for category distributions (record of string to number)
  * - counter: Simple count display with trend indicator
  * - gauge: Percentage gauge for rates/percentages (0-100)
  *
@@ -21,6 +22,7 @@ import { z } from "zod";
 export type ChartType =
   | "line"
   | "bar"
+  | "pie"
   | "counter"
   | "gauge"
   | "boolean"
@@ -38,6 +40,8 @@ export interface HealthResultMeta {
   "x-chart-label"?: string;
   /** Unit suffix for values (e.g., 'ms', '%', 'req/s') */
   "x-chart-unit"?: string;
+  /** Whether this field supports JSONPath assertions */
+  "x-jsonpath"?: boolean;
 }
 
 /**
@@ -50,6 +54,9 @@ export const healthResultRegistry = z.registry<HealthResultMeta>();
 // TYPED HEALTH RESULT FACTORIES
 // ============================================================================
 
+/** Chart metadata (excludes x-jsonpath, use healthResultJSONPath for that) */
+type ChartMeta = Omit<HealthResultMeta, "x-jsonpath">;
+
 /**
  * Create a health result string field with typed chart metadata.
  *
@@ -62,7 +69,7 @@ export const healthResultRegistry = z.registry<HealthResultMeta>();
  * });
  * ```
  */
-export function healthResultString(meta: HealthResultMeta) {
+export function healthResultString(meta: ChartMeta) {
   const schema = z.string();
   schema.register(healthResultRegistry, meta);
   return schema;
@@ -71,7 +78,7 @@ export function healthResultString(meta: HealthResultMeta) {
 /**
  * Create a health result number field with typed chart metadata.
  */
-export function healthResultNumber(meta: HealthResultMeta) {
+export function healthResultNumber(meta: ChartMeta) {
   const schema = z.number();
   schema.register(healthResultRegistry, meta);
   return schema;
@@ -80,8 +87,65 @@ export function healthResultNumber(meta: HealthResultMeta) {
 /**
  * Create a health result boolean field with typed chart metadata.
  */
-export function healthResultBoolean(meta: HealthResultMeta) {
+export function healthResultBoolean(meta: ChartMeta) {
   const schema = z.boolean();
   schema.register(healthResultRegistry, meta);
   return schema;
 }
+
+/**
+ * Create a health result string field with JSONPath assertion support.
+ * The UI will show a JSONPath input field for this result.
+ *
+ * @example
+ * ```typescript
+ * import { healthResultJSONPath } from "@checkstack/healthcheck-common";
+ *
+ * const resultSchema = z.object({
+ *   body: healthResultJSONPath(),
+ * });
+ * ```
+ */
+export function healthResultJSONPath(meta: ChartMeta) {
+  const schema = z.string();
+  schema.register(healthResultRegistry, { ...meta, "x-jsonpath": true });
+  return schema;
+}
+
+// ============================================================================
+// METADATA RETRIEVAL - For toJsonSchema integration
+// ============================================================================
+
+/**
+ * Unwraps a Zod schema to get the inner schema, handling:
+ * - ZodOptional
+ * - ZodDefault
+ * - ZodNullable
+ */
+function unwrapSchema(schema: z.ZodTypeAny): z.ZodTypeAny {
+  let unwrapped = schema;
+
+  if (unwrapped instanceof z.ZodOptional) {
+    unwrapped = unwrapped.unwrap() as z.ZodTypeAny;
+  }
+
+  if (unwrapped instanceof z.ZodDefault) {
+    unwrapped = unwrapped.def.innerType as z.ZodTypeAny;
+  }
+
+  if (unwrapped instanceof z.ZodNullable) {
+    unwrapped = unwrapped.unwrap() as z.ZodTypeAny;
+  }
+
+  return unwrapped;
+}
+
+/**
+ * Get health result metadata for a schema.
+ * Automatically unwraps Optional/Default/Nullable wrappers.
+ */
+export function getHealthResultMeta(
+  schema: z.ZodTypeAny
+): HealthResultMeta | undefined {
+  return healthResultRegistry.get(unwrapSchema(schema));
+}