@checkstack/healthcheck-common 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @checkstack/healthcheck-common
 
+## 0.3.0
+
+### Minor Changes
+
+- 9faec1f: # Unified AccessRule Terminology Refactoring
+
+  This release completes a comprehensive terminology refactoring from "permission" to "accessRule" across the entire codebase, establishing a consistent and modern access control vocabulary.
+
+  ## Changes
+
+  ### Core Infrastructure (`@checkstack/common`)
+
+  - Introduced `AccessRule` interface as the primary access control type
+  - Added `accessPair()` helper for creating read/manage access rule pairs
+  - Added `access()` builder for individual access rules
+  - Replaced `Permission` type with `AccessRule` throughout
+
+  ### API Changes
+
+  - `env.registerPermissions()` → `env.registerAccessRules()`
+  - `meta.permissions` → `meta.access` in RPC contracts
+  - `usePermission()` → `useAccess()` in frontend hooks
+  - Route `permission:` field → `accessRule:` field
+
+  ### UI Changes
+
+  - "Roles & Permissions" tab → "Roles & Access Rules"
+  - "You don't have permission..." → "You don't have access..."
+  - All permission-related UI text updated
+
+  ### Documentation & Templates
+
+  - Updated 18 documentation files with AccessRule terminology
+  - Updated 7 scaffolding templates with `accessPair()` pattern
+  - All code examples use new AccessRule API
+
+  ## Migration Guide
+
+  ### Backend Plugins
+
+  ```diff
+  - import { permissionList } from "./permissions";
+  - env.registerPermissions(permissionList);
+  + import { accessRules } from "./access";
+  + env.registerAccessRules(accessRules);
+  ```
+
+  ### RPC Contracts
+
+  ```diff
+  - .meta({ userType: "user", permissions: [permissions.read.id] })
+  + .meta({ userType: "user", access: [access.read] })
+  ```
+
+  ### Frontend Hooks
+
+  ```diff
+  - const canRead = accessApi.usePermission(permissions.read.id);
+  + const canRead = accessApi.useAccess(access.read);
+  ```
+
+  ### Routes
+
+  ```diff
+  - permission: permissions.entityRead.id,
+  + accessRule: access.read,
+  ```
+
+- f533141: Enforce health result factory function usage via branded types
+
+  - Added `healthResultSchema()` builder that enforces the use of factory functions at compile-time
+  - Added `healthResultArray()` factory for array fields (e.g., DNS resolved values)
+  - Added branded `HealthResultField<T>` type to mark schemas created by factory functions
+  - Consolidated `ChartType` and `HealthResultMeta` into `@checkstack/common` as single source of truth
+  - Updated all 12 health check strategies and 11 collectors to use `healthResultSchema()`
+  - Using raw `z.number()` etc. inside `healthResultSchema()` now causes a TypeScript error
+
+### Patch Changes
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [f533141]
+  - @checkstack/common@0.2.0
+  - @checkstack/signal-common@0.1.0
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

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

package/src/access.ts

@@ -0,0 +1,43 @@
+import { access, accessPair } from "@checkstack/common";
+
+/**
+ * Access rules for the Health Check plugin.
+ */
+export const healthCheckAccess = {
+  /**
+   * Status-only access for viewing health check status.
+   * Enabled by default for anonymous and authenticated users.
+   */
+  status: access("healthcheck.status", "read", "View Health Check Status", {
+    isDefault: true,
+    isPublic: true,
+  }),
+
+  /**
+   * Configuration access for viewing and managing health check configurations.
+   */
+  configuration: accessPair("healthcheck", {
+    read: "Read Health Check Configurations",
+    manage: "Full management of Health Check Configurations",
+  }),
+
+  /**
+   * Access for viewing detailed health check run data including metadata.
+   * Allows access to extended visualizations without full management access.
+   */
+  details: access(
+    "healthcheck.details",
+    "read",
+    "View Detailed Health Check Run Data (Warning: This may expose sensitive data, depending on the health check strategy)"
+  ),
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const healthCheckAccessRules = [
+  healthCheckAccess.status,
+  healthCheckAccess.configuration.read,
+  healthCheckAccess.configuration.manage,
+  healthCheckAccess.details,
+];

package/src/index.ts

@@ -1,4 +1,4 @@
-export * from "./permissions";
+export * from "./access";
 export * from "./schemas";
 export * from "./zod-health-result";
 

package/src/rpc-contract.ts

@@ -1,12 +1,11 @@
 import { oc } from "@orpc/contract";
 import {
   createClientDefinition,
-  createResourceAccessList,
   type ProcedureMetadata,
 } from "@checkstack/common";
 import { pluginMetadata } from "./plugin-metadata";
 import { z } from "zod";
-import { permissions } from "./permissions";
+import { healthCheckAccess } from "./access";
 import {
   HealthCheckStrategyDtoSchema,
   CollectorDtoSchema,
@@ -26,12 +25,6 @@ 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({
@@ -51,13 +44,13 @@ const SystemHealthStatusResponseSchema = z.object({
 // Health Check RPC Contract using oRPC's contract-first pattern
 export const healthCheckContract = {
   // ==========================================================================
-  // STRATEGY MANAGEMENT (userType: "authenticated" with read permission)
+  // STRATEGY MANAGEMENT (userType: "authenticated" with read access)
   // ==========================================================================
 
   getStrategies: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
     .output(z.array(HealthCheckStrategyDtoSchema)),
 
@@ -68,7 +61,7 @@ export const healthCheckContract = {
   getCollectors: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
     .input(z.object({ strategyId: z.string() }))
     .output(z.array(CollectorDtoSchema)),
@@ -80,8 +73,7 @@ export const healthCheckContract = {
   getConfigurations: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
-      resourceAccess: [configListAccess],
+      access: [healthCheckAccess.configuration.read],
     })
     .output(
       z.object({ configurations: z.array(HealthCheckConfigurationSchema) })
@@ -90,7 +82,7 @@ export const healthCheckContract = {
   createConfiguration: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(CreateHealthCheckConfigurationSchema)
     .output(HealthCheckConfigurationSchema),
@@ -98,7 +90,7 @@ export const healthCheckContract = {
   updateConfiguration: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(
       z.object({
@@ -111,7 +103,7 @@ export const healthCheckContract = {
   deleteConfiguration: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(z.string())
     .output(z.void()),
@@ -123,7 +115,7 @@ export const healthCheckContract = {
   getSystemConfigurations: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
     .input(z.string())
     .output(z.array(HealthCheckConfigurationSchema)),
@@ -135,7 +127,7 @@ export const healthCheckContract = {
   getSystemAssociations: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
     .input(z.object({ systemId: z.string() }))
     .output(
@@ -152,7 +144,7 @@ export const healthCheckContract = {
   associateSystem: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(
       z.object({
@@ -165,7 +157,7 @@ export const healthCheckContract = {
   disassociateSystem: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(
       z.object({
@@ -176,13 +168,13 @@ export const healthCheckContract = {
     .output(z.void()),
 
   // ==========================================================================
-  // RETENTION CONFIGURATION (userType: "authenticated" with manage permission)
+  // RETENTION CONFIGURATION (userType: "authenticated" with manage access)
   // ==========================================================================
 
   getRetentionConfig: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckRead.id],
+      access: [healthCheckAccess.configuration.read],
     })
     .input(
       z.object({
@@ -199,7 +191,7 @@ export const healthCheckContract = {
   updateRetentionConfig: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckManage.id],
+      access: [healthCheckAccess.configuration.manage],
     })
     .input(
       z.object({
@@ -211,13 +203,13 @@ export const healthCheckContract = {
     .output(z.void()),
 
   // ==========================================================================
-  // HISTORY & STATUS (userType: "user" with read permission)
+  // HISTORY & STATUS (userType: "user" with read access)
   // ==========================================================================
 
   getHistory: _base
     .meta({
       userType: "public",
-      permissions: [permissions.healthCheckStatusRead.id],
+      access: [healthCheckAccess.status],
     })
     .input(
       z.object({
@@ -238,12 +230,12 @@ export const healthCheckContract = {
 
   /**
    * Get detailed health check run history with full result data.
-   * Requires permission to view detailed run data including metadata.
+   * Requires access to view detailed run data including metadata.
    */
   getDetailedHistory: _base
     .meta({
       userType: "authenticated",
-      permissions: [permissions.healthCheckDetailsRead.id],
+      access: [healthCheckAccess.details],
     })
     .input(
       z.object({
@@ -270,7 +262,7 @@ export const healthCheckContract = {
   getAggregatedHistory: _base
     .meta({
       userType: "public",
-      permissions: [permissions.healthCheckStatusRead.id],
+      access: [healthCheckAccess.status],
     })
     .input(
       z.object({
@@ -290,12 +282,12 @@ export const healthCheckContract = {
   /**
    * Get detailed aggregated health check history including strategy-specific data.
    * Returns buckets with core metrics AND aggregatedResult from strategy.
-   * Requires healthCheckDetailsRead permission.
+   * Requires healthCheckDetailsRead access rule.
    */
   getDetailedAggregatedHistory: _base
     .meta({
       userType: "public",
-      permissions: [permissions.healthCheckDetailsRead.id],
+      access: [healthCheckAccess.details],
     })
     .input(
       z.object({
@@ -319,7 +311,7 @@ export const healthCheckContract = {
   getSystemHealthStatus: _base
     .meta({
       userType: "public",
-      permissions: [permissions.healthCheckStatusRead.id],
+      access: [healthCheckAccess.status],
     })
     .input(z.object({ systemId: z.string() }))
     .output(SystemHealthStatusResponseSchema),
@@ -331,7 +323,7 @@ export const healthCheckContract = {
   getSystemHealthOverview: _base
     .meta({
       userType: "public",
-      permissions: [permissions.healthCheckStatusRead.id],
+      access: [healthCheckAccess.status],
     })
     .input(z.object({ systemId: z.string() }))
     .output(

package/src/schemas.ts

@@ -272,7 +272,7 @@ export const DEFAULT_RETENTION_CONFIG: RetentionConfig = {
 /**
  * Base schema for aggregated health check data buckets.
  * Contains core metrics only (no strategy-specific data).
- * Used by getAggregatedHistory endpoint (healthCheckStatusRead permission).
+ * Used by getAggregatedHistory endpoint (healthCheckStatusRead access).
  */
 export const AggregatedBucketBaseSchema = z.object({
   bucketStart: z.date(),
@@ -292,7 +292,7 @@ export type AggregatedBucketBase = z.infer<typeof AggregatedBucketBaseSchema>;
 
 /**
  * Extended schema with strategy-specific aggregated result.
- * Used by getDetailedAggregatedHistory endpoint (healthCheckDetailsRead permission).
+ * Used by getDetailedAggregatedHistory endpoint (healthCheckDetailsRead access).
  */
 export const AggregatedBucketSchema = AggregatedBucketBaseSchema.extend({
   aggregatedResult: z.record(z.string(), z.unknown()).optional(),

package/src/zod-health-result.ts

@@ -1,54 +1,95 @@
 import { z } from "zod";
+import type { HealthResultMeta } from "@checkstack/common";
 
 // ============================================================================
 // HEALTH RESULT REGISTRY - Typed metadata for chart annotations
 // ============================================================================
 
 /**
- * Chart types for auto-generated health check visualizations.
- *
- * 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)
- *
- * Non-numeric types:
- * - boolean: Boolean indicator (success/failure, connected/disconnected)
- * - text: Text display for string values
- * - status: Status badge for error/warning states
+ * Registry for health result schema metadata.
+ * Used by auto-chart components for visualization inference.
  */
-export type ChartType =
-  | "line"
-  | "bar"
-  | "pie"
-  | "counter"
-  | "gauge"
-  | "boolean"
-  | "text"
-  | "status";
+export const healthResultRegistry = z.registry<HealthResultMeta>();
+
+// ============================================================================
+// BRANDED TYPES FOR COMPILE-TIME ENFORCEMENT
+// ============================================================================
 
 /**
- * Metadata type for health check result schemas.
- * Provides autocompletion for `.meta()` calls on result fields.
+ * Unique symbol for branding health result fields.
+ * This enables compile-time enforcement that developers use factory functions.
  */
-export interface HealthResultMeta {
-  /** The type of chart to render for this field */
-  "x-chart-type"?: ChartType;
-  /** Human-readable label for the chart (defaults to field name) */
-  "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;
-}
+declare const HealthResultBrand: unique symbol;
 
 /**
- * Registry for health result schema metadata.
- * Used by auto-chart components for visualization inference.
+ * A branded Zod schema type that marks it as a health result field.
+ * Only schemas created via factory functions (healthResultNumber, healthResultString, etc.)
+ * carry this brand.
  */
-export const healthResultRegistry = z.registry<HealthResultMeta>();
+export type HealthResultField<T extends z.ZodTypeAny> = T & {
+  [HealthResultBrand]: true;
+};
+
+/**
+ * Allowed field types in a health result schema.
+ * Supports direct fields, optional fields, and fields with defaults.
+ */
+export type HealthResultFieldType =
+  | HealthResultField<z.ZodTypeAny>
+  | z.ZodOptional<HealthResultField<z.ZodTypeAny>>
+  | z.ZodDefault<HealthResultField<z.ZodTypeAny>>
+  | z.ZodNullable<HealthResultField<z.ZodTypeAny>>;
+
+/**
+ * Constraint for health result schema shapes.
+ * All fields must use factory functions (healthResultNumber, healthResultString, etc.)
+ *
+ * @example
+ * ```typescript
+ * // ✅ Valid - uses factory functions
+ * const validSchema = z.object({
+ *   value: healthResultNumber({ "x-chart-type": "line" }),
+ *   error: healthResultString({ "x-chart-type": "status" }).optional(),
+ * });
+ *
+ * // ❌ Invalid - uses raw z.number()
+ * const invalidSchema = z.object({
+ *   value: z.number(), // Type error!
+ * });
+ * ```
+ */
+export type HealthResultShape = Record<string, HealthResultFieldType>;
+
+// ============================================================================
+// HEALTH RESULT SCHEMA BUILDER
+// ============================================================================
+
+/**
+ * Create a health result schema that enforces the use of factory functions.
+ *
+ * This builder ensures all fields use healthResultNumber(), healthResultString(),
+ * healthResultBoolean(), or healthResultJSONPath() - raw Zod schemas like z.number()
+ * will cause a compile-time error.
+ *
+ * @example
+ * ```typescript
+ * // ✅ Valid - all fields use factory functions
+ * const schema = healthResultSchema({
+ *   responseTime: healthResultNumber({ "x-chart-type": "line", "x-chart-label": "Response Time" }),
+ *   error: healthResultString({ "x-chart-type": "status" }).optional(),
+ * });
+ *
+ * // ❌ Invalid - raw z.number() causes type error
+ * const schema = healthResultSchema({
+ *   value: z.number(), // Type error: not assignable to HealthResultFieldType
+ * });
+ * ```
+ */
+export function healthResultSchema<T extends HealthResultShape>(
+  shape: T
+): z.ZodObject<T> {
+  return z.object(shape);
+}
 
 // ============================================================================
 // TYPED HEALTH RESULT FACTORIES
@@ -69,28 +110,53 @@ type ChartMeta = Omit<HealthResultMeta, "x-jsonpath">;
  * });
  * ```
  */
-export function healthResultString(meta: ChartMeta) {
+export function healthResultString(
+  meta: ChartMeta
+): HealthResultField<z.ZodString> {
   const schema = z.string();
   schema.register(healthResultRegistry, meta);
-  return schema;
+  return schema as HealthResultField<z.ZodString>;
 }
 
 /**
  * Create a health result number field with typed chart metadata.
  */
-export function healthResultNumber(meta: ChartMeta) {
+export function healthResultNumber(
+  meta: ChartMeta
+): HealthResultField<z.ZodNumber> {
   const schema = z.number();
   schema.register(healthResultRegistry, meta);
-  return schema;
+  return schema as HealthResultField<z.ZodNumber>;
 }
 
 /**
  * Create a health result boolean field with typed chart metadata.
  */
-export function healthResultBoolean(meta: ChartMeta) {
+export function healthResultBoolean(
+  meta: ChartMeta
+): HealthResultField<z.ZodBoolean> {
   const schema = z.boolean();
   schema.register(healthResultRegistry, meta);
-  return schema;
+  return schema as HealthResultField<z.ZodBoolean>;
+}
+
+/**
+ * Create a health result array field with typed chart metadata.
+ * For arrays of strings (e.g., DNS resolved values, list of hosts).
+ *
+ * @example
+ * ```typescript
+ * const resultSchema = healthResultSchema({
+ *   resolvedValues: healthResultArray({ "x-chart-type": "text", "x-chart-label": "Values" }),
+ * });
+ * ```
+ */
+export function healthResultArray(
+  meta: ChartMeta
+): HealthResultField<z.ZodArray<z.ZodString>> {
+  const schema = z.array(z.string());
+  schema.register(healthResultRegistry, meta);
+  return schema as HealthResultField<z.ZodArray<z.ZodString>>;
 }
 
 /**
@@ -106,10 +172,12 @@ export function healthResultBoolean(meta: ChartMeta) {
  * });
  * ```
  */
-export function healthResultJSONPath(meta: ChartMeta) {
+export function healthResultJSONPath(
+  meta: ChartMeta
+): HealthResultField<z.ZodString> {
   const schema = z.string();
   schema.register(healthResultRegistry, { ...meta, "x-jsonpath": true });
-  return schema;
+  return schema as HealthResultField<z.ZodString>;
 }
 
 // ============================================================================

package/src/permissions.ts

@@ -1,39 +0,0 @@
-import { createPermission } from "@checkstack/common";
-
-export const permissions = {
-  /**
-   * Status-only permission for viewing health check status.
-   * Enabled by default for anonymous and authenticated users.
-   */
-  healthCheckStatusRead: createPermission(
-    "healthcheck.status",
-    "read",
-    "View Health Check Status",
-    { isAuthenticatedDefault: true, isPublicDefault: true }
-  ),
-  /**
-   * Configuration read permission for viewing health check configurations.
-   * Restricted to users with explicit grant.
-   */
-  healthCheckRead: createPermission(
-    "healthcheck",
-    "read",
-    "Read Health Check Configurations"
-  ),
-  /**
-   * Permission for viewing detailed health check run data including metadata.
-   * Allows access to extended visualizations without full management access.
-   */
-  healthCheckDetailsRead: createPermission(
-    "healthcheck.details",
-    "read",
-    "View Detailed Health Check Run Data (Warning: This may expose sensitive data, depending on the health check strategy)"
-  ),
-  healthCheckManage: createPermission(
-    "healthcheck",
-    "manage",
-    "Full management of Health Check Configurations"
-  ),
-};
-
-export const permissionList = Object.values(permissions);