@checkstack/healthcheck-common 0.0.3 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,130 @@
 # @checkstack/healthcheck-common
 
+## 0.2.0
+
+### Minor Changes
+
+- 8e43507: # Teams and Resource-Level Access Control
+
+  This release introduces a comprehensive Teams system for organizing users and controlling access to resources at a granular level.
+
+  ## Features
+
+  ### Team Management
+
+  - Create, update, and delete teams with name and description
+  - Add/remove users from teams
+  - Designate team managers with elevated privileges
+  - View team membership and manager status
+
+  ### Resource-Level Access Control
+
+  - Grant teams access to specific resources (systems, health checks, incidents, maintenances)
+  - Configure read-only or manage permissions per team
+  - Resource-level "Team Only" mode that restricts access exclusively to team members
+  - Separate `resourceAccessSettings` table for resource-level settings (not per-grant)
+  - Automatic cleanup of grants when teams are deleted (database cascade)
+
+  ### Middleware Integration
+
+  - Extended `autoAuthMiddleware` to support resource access checks
+  - Single-resource pre-handler validation for detail endpoints
+  - Automatic list filtering for collection endpoints
+  - S2S endpoints for access verification
+
+  ### Frontend Components
+
+  - `TeamsTab` component for managing teams in Auth Settings
+  - `TeamAccessEditor` component for assigning team access to resources
+  - Resource-level "Team Only" toggle in `TeamAccessEditor`
+  - Integration into System, Health Check, Incident, and Maintenance editors
+
+  ## Breaking Changes
+
+  ### API Response Format Changes
+
+  List endpoints now return objects with named keys instead of arrays directly:
+
+  ```typescript
+  // Before
+  const systems = await catalogApi.getSystems();
+
+  // After
+  const { systems } = await catalogApi.getSystems();
+  ```
+
+  Affected endpoints:
+
+  - `catalog.getSystems` → `{ systems: [...] }`
+  - `healthcheck.getConfigurations` → `{ configurations: [...] }`
+  - `incident.listIncidents` → `{ incidents: [...] }`
+  - `maintenance.listMaintenances` → `{ maintenances: [...] }`
+
+  ### User Identity Enrichment
+
+  `RealUser` and `ApplicationUser` types now include `teamIds: string[]` field with team memberships.
+
+  ## Documentation
+
+  See `docs/backend/teams.md` for complete API reference and integration guide.
+
+- 97c5a6b: Add UUID-based collector identification for better multiple collector support
+
+  **Breaking Change**: Existing health check configurations with collectors need to be recreated.
+
+  - Each collector instance now has a unique UUID assigned on creation
+  - Collector results are stored under the UUID key with `_collectorId` and `_assertionFailed` metadata
+  - Auto-charts correctly display separate charts for each collector instance
+  - Charts are now grouped by collector instance with clear headings
+  - Assertion status card shows pass/fail for each collector
+  - Renamed "Success" to "HTTP Success" to clarify it's about HTTP request success
+  - Fixed deletion of collectors not persisting to database
+  - Fixed duplicate React key warnings in auto-chart grid
+
+### Patch Changes
+
+- Updated dependencies [8e43507]
+  - @checkstack/common@0.1.0
+  - @checkstack/signal-common@0.0.4
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-common",
-  "version": "0.0.3",
+  "version": "0.2.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

@@ -1,6 +1,7 @@
 import { oc } from "@orpc/contract";
 import {
   createClientDefinition,
+  createResourceAccessList,
   type ProcedureMetadata,
 } from "@checkstack/common";
 import { pluginMetadata } from "./plugin-metadata";
@@ -8,6 +9,7 @@ import { z } from "zod";
 import { permissions } from "./permissions";
 import {
   HealthCheckStrategyDtoSchema,
+  CollectorDtoSchema,
   HealthCheckConfigurationSchema,
   CreateHealthCheckConfigurationSchema,
   UpdateHealthCheckConfigurationSchema,
@@ -24,6 +26,12 @@ import {
 // Base builder with full metadata support
 const _base = oc.$meta<ProcedureMetadata>({});
 
+// Resource access configurations for team-based access control
+const configListAccess = createResourceAccessList(
+  "configuration",
+  "configurations"
+);
+
 // --- Response Schemas for Evaluated Status ---
 
 const SystemCheckStatusSchema = z.object({
@@ -53,6 +61,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")
   // ==========================================================================
@@ -61,8 +81,11 @@ export const healthCheckContract = {
     .meta({
       userType: "authenticated",
       permissions: [permissions.healthCheckRead.id],
+      resourceAccess: [configListAccess],
     })
-    .output(z.array(HealthCheckConfigurationSchema)),
+    .output(
+      z.object({ configurations: z.array(HealthCheckConfigurationSchema) })
+    ),
 
   createConfiguration: _base
     .meta({

package/src/schemas.ts

@@ -13,21 +13,87 @@ 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 a unique ID, the collector type ID, its config, and per-collector assertions.
+ */
+export const CollectorConfigEntrySchema = z.object({
+  /** Unique ID for this collector instance (UUID) */
+  id: z.string(),
+  /** 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

@@ -40,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;
 }
 
 /**
@@ -52,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.
  *
@@ -64,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;
@@ -73,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;
@@ -82,12 +87,31 @@ 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
 // ============================================================================