@checkstack/backend-api 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @checkstack/backend-api
 
+## 0.1.0
+
+### Minor Changes
+
+- f5b1f49: Added collector registry lifecycle cleanup during plugin unloading.
+
+  - Added `unregisterByOwner(pluginId)` to remove collectors owned by unloading plugins
+  - Added `unregisterByMissingStrategies(loadedPluginIds)` for dependency-based pruning
+  - Integrated registry cleanup into `PluginManager.deregisterPlugin()`
+  - Updated `registerCoreServices` to return global registries for lifecycle management
+
+### Patch Changes
+
+- 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
+
+- Updated dependencies [f5b1f49]
+  - @checkstack/common@0.0.3
+  - @checkstack/queue-api@0.0.3
+  - @checkstack/signal-common@0.0.3
+
 ## 0.0.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {

package/src/collector-registry.ts

@@ -0,0 +1,42 @@
+import type { PluginMetadata } from "@checkstack/common";
+import type { CollectorStrategy } from "./collector-strategy";
+import type { TransportClient } from "./transport-client";
+
+/**
+ * A registered collector with its owning plugin metadata.
+ */
+export interface RegisteredCollector {
+  /** The collector strategy */
+  collector: CollectorStrategy<TransportClient<unknown, unknown>>;
+  /** The plugin that registered this collector */
+  ownerPlugin: PluginMetadata;
+}
+
+/**
+ * Scoped collector registry interface.
+ * The owning plugin metadata is automatically injected via factory.
+ */
+export interface CollectorRegistry {
+  /**
+   * Register a collector strategy.
+   * The owning plugin metadata is automatically captured from the scoped context.
+   */
+  register(
+    collector: CollectorStrategy<TransportClient<unknown, unknown>>
+  ): void;
+
+  /**
+   * Get a collector by ID.
+   */
+  getCollector(id: string): RegisteredCollector | undefined;
+
+  /**
+   * Get all collectors that support a specific transport plugin.
+   */
+  getCollectorsForPlugin(pluginMetadata: PluginMetadata): RegisteredCollector[];
+
+  /**
+   * Get all registered collectors.
+   */
+  getCollectors(): RegisteredCollector[];
+}

package/src/collector-strategy.ts

@@ -0,0 +1,83 @@
+import type { PluginMetadata } from "@checkstack/common";
+import type { TransportClient } from "./transport-client";
+import type { Versioned } from "./config-versioning";
+import type { HealthCheckRunForAggregation } from "./health-check";
+
+/**
+ * Result from a collector execution.
+ */
+export interface CollectorResult<TResult> {
+  /** Collector-specific result data */
+  result: TResult;
+  /** Optional error message if collection partially failed */
+  error?: string;
+}
+
+/**
+ * Generic collector strategy interface.
+ *
+ * Collectors extend health check strategies by providing additional metrics
+ * collection capabilities. They receive a connected transport client and
+ * produce typed results with chart metadata.
+ *
+ * @template TClient - Transport client type (e.g., SshTransportClient)
+ * @template TConfig - Collector configuration schema
+ * @template TResult - Per-execution result type
+ * @template TAggregated - Aggregated result for buckets
+ */
+export interface CollectorStrategy<
+  TClient extends TransportClient<unknown, unknown>,
+  TConfig = unknown,
+  TResult = Record<string, unknown>,
+  TAggregated = Record<string, unknown>
+> {
+  /** Unique identifier for this collector */
+  id: string;
+
+  /** Human-readable name */
+  displayName: string;
+
+  /** Optional description */
+  description?: string;
+
+  /**
+   * PluginMetadata of transport strategies this collector supports.
+   * The registry uses this to match collectors to compatible strategies.
+   */
+  supportedPlugins: PluginMetadata[];
+
+  /**
+   * Whether multiple instances of this collector can be added to one config.
+   * Default: false (one instance per collector type)
+   */
+  allowMultiple?: boolean;
+
+  /** Collector configuration schema with versioning */
+  config: Versioned<TConfig>;
+
+  /** Per-execution result schema (with x-chart-* metadata) */
+  result: Versioned<TResult>;
+
+  /** Aggregated result schema for bucket storage */
+  aggregatedResult: Versioned<TAggregated>;
+
+  /**
+   * Execute the collector using the provided transport client.
+   *
+   * @param params.config - Validated collector configuration
+   * @param params.client - Connected transport client
+   * @param params.pluginId - ID of the transport strategy invoking this collector
+   * @returns Collector result with typed metadata
+   */
+  execute(params: {
+    config: TConfig;
+    client: TClient;
+    pluginId: string;
+  }): Promise<CollectorResult<TResult>>;
+
+  /**
+   * Aggregate results from multiple runs into a summary.
+   * Called during retention processing.
+   */
+  aggregateResult(runs: HealthCheckRunForAggregation<TResult>[]): TAggregated;
+}

package/src/core-services.ts

@@ -1,10 +1,8 @@
 import { createServiceRef } from "./service-ref";
 import type { RpcService } from "./rpc";
 import type { HealthCheckRegistry } from "./health-check";
-import type {
-  QueuePluginRegistry,
-  QueueManager,
-} from "@checkstack/queue-api";
+import type { CollectorRegistry } from "./collector-registry";
+import type { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
 import type { ConfigService } from "./config-service";
 import type { SignalService } from "@checkstack/signal-common";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
@@ -32,6 +30,9 @@ export const coreServices = {
   healthCheckRegistry: createServiceRef<HealthCheckRegistry>(
     "core.healthCheckRegistry"
   ),
+  collectorRegistry: createServiceRef<CollectorRegistry>(
+    "core.collectorRegistry"
+  ),
   pluginInstaller: createServiceRef<PluginInstaller>("core.pluginInstaller"),
   rpc: createServiceRef<RpcService>("core.rpc"),
   rpcClient: createServiceRef<RpcClient>("core.rpcClient"),

package/src/health-check.ts

@@ -1,4 +1,5 @@
 import { Versioned } from "./config-versioning";
+import type { TransportClient } from "./transport-client";
 
 /**
  * Health check result with typed metadata.
@@ -23,13 +24,35 @@ export interface HealthCheckRunForAggregation<
 }
 
 /**
- * Health check strategy definition with typed config and result.
+ * Connected transport client with cleanup capability.
+ */
+export interface ConnectedClient<
+  TClient extends TransportClient<unknown, unknown>
+> {
+  /** The connected transport client */
+  client: TClient;
+  /** Close the connection and release resources */
+  close(): void;
+}
+
+/**
+ * Health check strategy definition with typed config and transport client.
+ *
+ * Strategies provide a `createClient` function that establishes a connection
+ * and returns a transport client. The platform executor handles running
+ * collectors and basic health check logic (connectivity test, latency measurement).
+ *
  * @template TConfig - Configuration type for this strategy
- * @template TResult - Per-run result type
+ * @template TClient - Transport client type (e.g., SshTransportClient)
+ * @template TResult - Per-run result type (for aggregation)
  * @template TAggregatedResult - Aggregated result type for buckets
  */
 export interface HealthCheckStrategy<
   TConfig = unknown,
+  TClient extends TransportClient<unknown, unknown> = TransportClient<
+    unknown,
+    unknown
+  >,
   TResult = Record<string, unknown>,
   TAggregatedResult = Record<string, unknown>
 > {
@@ -46,7 +69,15 @@ export interface HealthCheckStrategy<
   /** Aggregated result schema for long-term bucket storage */
   aggregatedResult: Versioned<TAggregatedResult>;
 
-  execute(config: TConfig): Promise<HealthCheckResult<TResult>>;
+  /**
+   * Create a connected transport client from the configuration.
+   * The platform will use this client to execute collectors.
+   *
+   * @param config - Validated strategy configuration
+   * @returns Connected client wrapper with close() method
+   * @throws Error if connection fails (will be caught by executor)
+   */
+  createClient(config: TConfig): Promise<ConnectedClient<TClient>>;
 
   /**
    * Aggregate results from multiple runs into a summary for bucket storage.
@@ -59,10 +90,47 @@ export interface HealthCheckStrategy<
   ): TAggregatedResult;
 }
 
+/**
+ * A registered strategy with its owning plugin metadata and qualified ID.
+ */
+export interface RegisteredStrategy {
+  strategy: HealthCheckStrategy<
+    unknown,
+    TransportClient<unknown, unknown>,
+    unknown,
+    unknown
+  >;
+  ownerPluginId: string;
+  qualifiedId: string;
+}
+
 export interface HealthCheckRegistry {
-  register(strategy: HealthCheckStrategy<unknown, unknown, unknown>): void;
+  register(
+    strategy: HealthCheckStrategy<
+      unknown,
+      TransportClient<unknown, unknown>,
+      unknown,
+      unknown
+    >
+  ): void;
   getStrategy(
     id: string
-  ): HealthCheckStrategy<unknown, unknown, unknown> | undefined;
-  getStrategies(): HealthCheckStrategy<unknown, unknown, unknown>[];
+  ):
+    | HealthCheckStrategy<
+        unknown,
+        TransportClient<unknown, unknown>,
+        unknown,
+        unknown
+      >
+    | undefined;
+  getStrategies(): HealthCheckStrategy<
+    unknown,
+    TransportClient<unknown, unknown>,
+    unknown,
+    unknown
+  >[];
+  /**
+   * Get all registered strategies with their metadata (qualified ID, owner plugin).
+   */
+  getStrategiesWithMeta(): RegisteredStrategy[];
 }

package/src/index.ts

@@ -21,3 +21,6 @@ export * from "./markdown";
 export * from "./email-layout";
 export * from "./assertions";
 export * from "./chart-metadata";
+export * from "./transport-client";
+export * from "./collector-strategy";
+export * from "./collector-registry";

package/src/rpc.ts

@@ -1,14 +1,9 @@
 import { os as baseOs, ORPCError, Router } from "@orpc/server";
 import { AnyContractRouter } from "@orpc/contract";
 import { HealthCheckRegistry } from "./health-check";
-import {
-  QueuePluginRegistry,
-  QueueManager,
-} from "@checkstack/queue-api";
-import {
-  ProcedureMetadata,
-  qualifyPermissionId,
-} from "@checkstack/common";
+import { CollectorRegistry } from "./collector-registry";
+import { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
+import { ProcedureMetadata, qualifyPermissionId } from "@checkstack/common";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import {
   Logger,
@@ -43,6 +38,7 @@ export interface RpcContext {
   auth: AuthService;
   user?: AuthUser;
   healthCheckRegistry: HealthCheckRegistry;
+  collectorRegistry: CollectorRegistry;
   queuePluginRegistry: QueuePluginRegistry;
   queueManager: QueueManager;
   /** Emit a hook event for cross-plugin communication */

package/src/test-utils.ts

@@ -2,10 +2,8 @@ import { mock } from "bun:test";
 import { RpcContext, EmitHookFn } from "./rpc";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { HealthCheckRegistry } from "./health-check";
-import {
-  QueuePluginRegistry,
-  QueueManager,
-} from "@checkstack/queue-api";
+import { CollectorRegistry } from "./collector-registry";
+import { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
 
 /**
  * Creates a mocked oRPC context for testing.
@@ -39,10 +37,17 @@ export function createMockRpcContext(
       getAnonymousPermissions: mock().mockResolvedValue([]),
     },
     healthCheckRegistry: {
-      registerStrategy: mock(),
+      register: mock(),
       getStrategies: mock().mockReturnValue([]),
       getStrategy: mock(),
+      getStrategiesWithMeta: mock().mockReturnValue([]),
     } as unknown as HealthCheckRegistry,
+    collectorRegistry: {
+      register: mock(),
+      getCollector: mock(),
+      getCollectors: mock().mockReturnValue([]),
+      getCollectorsForPlugin: mock().mockReturnValue([]),
+    } as unknown as CollectorRegistry,
     queuePluginRegistry: {
       register: mock(),
       getPlugin: mock(),

package/src/transport-client.ts

@@ -0,0 +1,2 @@
+// Re-export TransportClient from common for convenience
+export type { TransportClient } from "@checkstack/common";