@checkstack/healthcheck-frontend 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # @checkstack/healthcheck-frontend
 
+## 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,
+  ```
+
+- 827b286: Add array assertion operators for string array fields
+
+  New operators for asserting on array fields (e.g., playerNames in RCON collectors):
+
+  - **includes** - Check if array contains a specific value
+  - **notIncludes** - Check if array does NOT contain a specific value
+  - **lengthEquals** - Check if array length equals a value
+  - **lengthGreaterThan** - Check if array length is greater than a value
+  - **lengthLessThan** - Check if array length is less than a value
+  - **isEmpty** - Check if array is empty
+  - **isNotEmpty** - Check if array has at least one element
+
+  Also exports a new `arrayField()` schema factory for creating array assertion schemas.
+
+### Patch Changes
+
+- 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
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [95eeec7]
+- Updated dependencies [f533141]
+  - @checkstack/auth-frontend@0.2.0
+  - @checkstack/catalog-common@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/healthcheck-common@0.3.0
+  - @checkstack/ui@0.2.0
+  - @checkstack/signal-frontend@0.0.6
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-frontend",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.tsx",
   "scripts": {

package/src/auto-charts/schema-parser.ts

@@ -7,8 +7,8 @@
  * Supports nested schemas under `collectors.*` for per-collector metrics.
  */
 
-import type { ChartType } from "@checkstack/healthcheck-common";
 import type {
+  ChartType,
   JsonSchemaPropertyCore,
   JsonSchemaBase,
 } from "@checkstack/common";

package/src/components/AssertionBuilder.tsx

@@ -81,6 +81,13 @@ const OPERATORS: Record<FieldType, { value: string; label: string }[]> = {
   ],
   enum: [{ value: "equals", label: "Equals" }],
   array: [
+    { value: "includes", label: "Includes" },
+    { value: "notIncludes", label: "Not Includes" },
+    { value: "lengthEquals", label: "Length Equals" },
+    { value: "lengthGreaterThan", label: "Length Greater Than" },
+    { value: "lengthLessThan", label: "Length Less Than" },
+    { value: "isEmpty", label: "Is Empty" },
+    { value: "isNotEmpty", label: "Is Not Empty" },
     { value: "exists", label: "Exists" },
     { value: "notExists", label: "Not Exists" },
   ],
@@ -98,6 +105,7 @@ const OPERATORS: Record<FieldType, { value: string; label: string }[]> = {
 // Operators that don't need a value input
 const VALUE_LESS_OPERATORS = new Set([
   "isEmpty",
+  "isNotEmpty",
   "isTrue",
   "isFalse",
   "exists",

package/src/components/HealthCheckDiagram.tsx

@@ -44,20 +44,20 @@ export function HealthCheckDiagram({
 }
 
 /**
- * Wrapper that shows permission message when user lacks access.
+ * Wrapper that shows access message when user lacks access.
  */
-export function HealthCheckDiagramPermissionGate({
-  hasPermission,
+export function HealthCheckDiagramAccessGate({
+  hasAccess,
   children,
 }: {
-  hasPermission: boolean;
+  hasAccess: boolean;
   children: React.ReactNode;
 }) {
-  if (!hasPermission) {
+  if (!hasAccess) {
     return (
       <InfoBanner variant="info">
         Additional strategy-specific visualizations are available with the
-        &quot;Read Health Check Details&quot; permission.
+        &quot;Read Health Check Details&quot; access rule.
       </InfoBanner>
     );
   }

package/src/components/HealthCheckMenuItems.tsx

@@ -3,20 +3,17 @@ import { Link } from "react-router-dom";
 import { Activity } from "lucide-react";
 import type { UserMenuItemsContext } from "@checkstack/frontend-api";
 import { DropdownMenuItem } from "@checkstack/ui";
-import { qualifyPermissionId, resolveRoute } from "@checkstack/common";
+import { resolveRoute } from "@checkstack/common";
 import {
   healthcheckRoutes,
-  permissions,
+  healthCheckAccess,
   pluginMetadata,
 } from "@checkstack/healthcheck-common";
 
 export const HealthCheckMenuItems = ({
-  permissions: userPerms,
+  accessRules: userPerms,
 }: UserMenuItemsContext) => {
-  const qualifiedId = qualifyPermissionId(
-    pluginMetadata,
-    permissions.healthCheckRead
-  );
+  const qualifiedId = `${pluginMetadata.pluginId}.${healthCheckAccess.configuration.read.id}`;
   const canRead = userPerms.includes("*") || userPerms.includes(qualifiedId);
 
   if (!canRead) {

package/src/components/SystemHealthCheckAssignment.tsx

@@ -2,7 +2,7 @@ import React, { useEffect, useState } from "react";
 import {
   useApi,
   type SlotContext,
-  permissionApiRef,
+  accessApiRef,
 } from "@checkstack/frontend-api";
 import { healthCheckApiRef, HealthCheckConfiguration } from "../api";
 import {
@@ -32,6 +32,7 @@ import type { StateThresholds } from "@checkstack/healthcheck-common";
 import {
   DEFAULT_STATE_THRESHOLDS,
   healthcheckRoutes,
+  healthCheckAccess,
 } from "@checkstack/healthcheck-common";
 import { resolveRoute } from "@checkstack/common";
 import { DEFAULT_RETENTION_CONFIG } from "@checkstack/healthcheck-common";
@@ -52,10 +53,9 @@ export const SystemHealthCheckAssignment: React.FC<Props> = ({
   systemName: _systemName,
 }) => {
   const api = useApi(healthCheckApiRef);
-  const permissionApi = useApi(permissionApiRef);
-  const { allowed: canManage } = permissionApi.useResourcePermission(
-    "healthcheck",
-    "manage"
+  const accessApi = useApi(accessApiRef);
+  const { allowed: canManage } = accessApi.useAccess(
+    healthCheckAccess.configuration.manage
   );
   const [configs, setConfigs] = useState<HealthCheckConfiguration[]>([]);
   const [associations, setAssociations] = useState<AssociationState[]>([]);

package/src/hooks/useHealthCheckData.ts

@@ -1,8 +1,8 @@
 import { useEffect, useState, useMemo, useCallback } from "react";
-import { useApi, permissionApiRef } from "@checkstack/frontend-api";
+import { useApi, accessApiRef } from "@checkstack/frontend-api";
 import { healthCheckApiRef } from "../api";
 import {
-  permissions,
+  healthCheckAccess,
   DEFAULT_RETENTION_CONFIG,
   type RetentionConfig,
   HEALTH_CHECK_RUN_COMPLETED,
@@ -36,10 +36,10 @@ interface UseHealthCheckDataResult {
   isAggregated: boolean;
   /** The resolved retention config */
   retentionConfig: RetentionConfig;
-  /** Whether user has permission to view detailed data */
-  hasPermission: boolean;
-  /** Whether permission is still loading */
-  permissionLoading: boolean;
+  /** Whether user has access to view detailed data */
+  hasAccess: boolean;
+  /** Whether access is still loading */
+  accessLoading: boolean;
 }
 
 /**
@@ -52,14 +52,14 @@ interface UseHealthCheckDataResult {
  *
  * @example
  * ```tsx
- * const { context, loading, hasPermission } = useHealthCheckData({
+ * const { context, loading, hasAccess } = useHealthCheckData({
  *   systemId,
  *   configurationId,
  *   strategyId,
  *   dateRange: { startDate, endDate },
  * });
  *
- * if (!hasPermission) return <NoPermissionMessage />;
+ * if (!hasAccess) return <NoAccessMessage />;
  * if (loading) return <LoadingSpinner />;
  * if (!context) return null;
  *
@@ -75,11 +75,11 @@ export function useHealthCheckData({
   offset = 0,
 }: UseHealthCheckDataProps): UseHealthCheckDataResult {
   const api = useApi(healthCheckApiRef);
-  const permissionApi = useApi(permissionApiRef);
+  const accessApi = useApi(accessApiRef);
 
-  // Permission state
-  const { allowed: hasPermission, loading: permissionLoading } =
-    permissionApi.usePermission(permissions.healthCheckDetailsRead.id);
+  // Access state
+  const { allowed: hasAccess, loading: accessLoading } =
+    accessApi.useAccess(healthCheckAccess.details);
 
   // Retention config state
   const [retentionConfig, setRetentionConfig] = useState<RetentionConfig>(
@@ -160,24 +160,24 @@ export function useHealthCheckData({
 
   // Fetch raw data when in raw mode
   useEffect(() => {
-    if (!hasPermission || permissionLoading || retentionLoading || isAggregated)
+    if (!hasAccess || accessLoading || retentionLoading || isAggregated)
       return;
     fetchRawData(true);
   }, [
     fetchRawData,
-    hasPermission,
-    permissionLoading,
+    hasAccess,
+    accessLoading,
     retentionLoading,
     isAggregated,
   ]);
 
   // Listen for realtime health check updates to refresh data silently
   useSignal(HEALTH_CHECK_RUN_COMPLETED, ({ systemId: changedId }) => {
-    // Only refresh if we're in raw mode (not aggregated) and have permission
+    // Only refresh if we're in raw mode (not aggregated) and have access
     if (
       changedId === systemId &&
-      hasPermission &&
-      !permissionLoading &&
+      hasAccess &&
+      !accessLoading &&
       !retentionLoading &&
       !isAggregated
     ) {
@@ -188,8 +188,8 @@ export function useHealthCheckData({
   // Fetch aggregated data when in aggregated mode
   useEffect(() => {
     if (
-      !hasPermission ||
-      permissionLoading ||
+      !hasAccess ||
+      accessLoading ||
       retentionLoading ||
       !isAggregated
     )
@@ -198,7 +198,7 @@ export function useHealthCheckData({
     setAggregatedLoading(true);
     // Use daily buckets for ranges > 30 days, hourly otherwise
     const bucketSize = dateRangeDays > 30 ? "daily" : "hourly";
-    // Use detailed endpoint to get aggregatedResult since we have permission
+    // Use detailed endpoint to get aggregatedResult since we have access
     api
       .getDetailedAggregatedHistory({
         systemId,
@@ -217,8 +217,8 @@ export function useHealthCheckData({
     api,
     systemId,
     configurationId,
-    hasPermission,
-    permissionLoading,
+    hasAccess,
+    accessLoading,
     retentionLoading,
     isAggregated,
     dateRangeDays,
@@ -227,7 +227,7 @@ export function useHealthCheckData({
   ]);
 
   const context = useMemo((): HealthCheckDiagramSlotContext | undefined => {
-    if (!hasPermission || permissionLoading || retentionLoading) {
+    if (!hasAccess || accessLoading || retentionLoading) {
       return undefined;
     }
 
@@ -249,8 +249,8 @@ export function useHealthCheckData({
       runs: rawRuns,
     };
   }, [
-    hasPermission,
-    permissionLoading,
+    hasAccess,
+    accessLoading,
     retentionLoading,
     isAggregated,
     systemId,
@@ -261,7 +261,7 @@ export function useHealthCheckData({
   ]);
 
   const loading =
-    permissionLoading ||
+    accessLoading ||
     retentionLoading ||
     (isAggregated ? aggregatedLoading : rawLoading);
 
@@ -270,7 +270,7 @@ export function useHealthCheckData({
     loading,
     isAggregated,
     retentionConfig,
-    hasPermission,
-    permissionLoading,
+    hasAccess,
+    accessLoading,
   };
 }

package/src/index.tsx

@@ -13,7 +13,7 @@ import { HealthCheckMenuItems } from "./components/HealthCheckMenuItems";
 import { HealthCheckSystemOverview } from "./components/HealthCheckSystemOverview";
 import { SystemHealthCheckAssignment } from "./components/SystemHealthCheckAssignment";
 import { SystemHealthBadge } from "./components/SystemHealthBadge";
-import { permissions } from "@checkstack/healthcheck-common";
+import { healthCheckAccess } from "@checkstack/healthcheck-common";
 import { autoChartExtension } from "./auto-charts";
 
 import {
@@ -49,19 +49,19 @@ export default createFrontendPlugin({
       route: healthcheckRoutes.routes.config,
       element: <HealthCheckConfigPage />,
       title: "Health Checks",
-      permission: permissions.healthCheckManage,
+      accessRule: healthCheckAccess.configuration.manage,
     },
     {
       route: healthcheckRoutes.routes.history,
       element: <HealthCheckHistoryPage />,
       title: "Health Check History",
-      permission: permissions.healthCheckRead,
+      accessRule: healthCheckAccess.configuration.read,
     },
     {
       route: healthcheckRoutes.routes.historyDetail,
       element: <HealthCheckHistoryDetailPage />,
       title: "Health Check Detail",
-      permission: permissions.healthCheckDetailsRead,
+      accessRule: healthCheckAccess.details,
     },
   ],
   apis: [

package/src/pages/HealthCheckConfigPage.tsx

@@ -3,7 +3,7 @@ import { useSearchParams } from "react-router-dom";
 import {
   useApi,
   wrapInSuspense,
-  permissionApiRef,
+  accessApiRef,
 } from "@checkstack/frontend-api";
 import { healthCheckApiRef } from "../api";
 import {
@@ -11,6 +11,7 @@ import {
   HealthCheckStrategyDto,
   CreateHealthCheckConfiguration,
   healthcheckRoutes,
+  healthCheckAccess,
 } from "@checkstack/healthcheck-common";
 import { HealthCheckList } from "../components/HealthCheckList";
 import { HealthCheckEditor } from "../components/HealthCheckEditor";
@@ -21,13 +22,12 @@ import { resolveRoute } from "@checkstack/common";
 
 const HealthCheckConfigPageContent = () => {
   const api = useApi(healthCheckApiRef);
-  const permissionApi = useApi(permissionApiRef);
+  const accessApi = useApi(accessApiRef);
   const [searchParams, setSearchParams] = useSearchParams();
-  const { allowed: canRead, loading: permissionLoading } =
-    permissionApi.useResourcePermission("healthcheck", "read");
-  const { allowed: canManage } = permissionApi.useResourcePermission(
-    "healthcheck",
-    "manage"
+  const { allowed: canRead, loading: accessLoading } =
+    accessApi.useAccess(healthCheckAccess.configuration.read);
+  const { allowed: canManage } = accessApi.useAccess(
+    healthCheckAccess.configuration.manage
   );
 
   const [configurations, setConfigurations] = useState<
@@ -113,7 +113,7 @@ const HealthCheckConfigPageContent = () => {
     <PageLayout
       title="Health Checks"
       subtitle="Manage health check configurations"
-      loading={permissionLoading}
+      loading={accessLoading}
       allowed={canRead}
       actions={
         <div className="flex gap-2">

package/src/pages/HealthCheckHistoryDetailPage.tsx

@@ -2,10 +2,13 @@ import { useState } from "react";
 import {
   useApi,
   wrapInSuspense,
-  permissionApiRef,
+  accessApiRef,
 } from "@checkstack/frontend-api";
 import { healthCheckApiRef } from "../api";
-import { healthcheckRoutes } from "@checkstack/healthcheck-common";
+import {
+  healthcheckRoutes,
+  healthCheckAccess,
+} from "@checkstack/healthcheck-common";
 import { resolveRoute } from "@checkstack/common";
 import {
   PageLayout,
@@ -32,9 +35,9 @@ const HealthCheckHistoryDetailPageContent = () => {
   }>();
 
   const api = useApi(healthCheckApiRef);
-  const permissionApi = useApi(permissionApiRef);
-  const { allowed: canManage, loading: permissionLoading } =
-    permissionApi.useResourcePermission("healthcheck", "manage");
+  const accessApi = useApi(accessApiRef);
+  const { allowed: canManage, loading: accessLoading } =
+    accessApi.useAccess(healthCheckAccess.configuration.manage);
 
   const [dateRange, setDateRange] = useState<DateRange>(getDefaultDateRange);
 
@@ -65,7 +68,7 @@ const HealthCheckHistoryDetailPageContent = () => {
         0,
         8
       )}...`}
-      loading={permissionLoading}
+      loading={accessLoading}
       allowed={canManage}
       actions={
         <BackLink to={resolveRoute(healthcheckRoutes.routes.history)}>

package/src/pages/HealthCheckHistoryPage.tsx

@@ -1,7 +1,7 @@
 import {
   useApi,
   wrapInSuspense,
-  permissionApiRef,
+  accessApiRef,
 } from "@checkstack/frontend-api";
 import { healthCheckApiRef } from "../api";
 import {
@@ -16,12 +16,13 @@ import {
   HealthCheckRunsTable,
   type HealthCheckRunDetailed,
 } from "../components/HealthCheckRunsTable";
+import { healthCheckAccess } from "@checkstack/healthcheck-common";
 
 const HealthCheckHistoryPageContent = () => {
   const api = useApi(healthCheckApiRef);
-  const permissionApi = useApi(permissionApiRef);
-  const { allowed: canManage, loading: permissionLoading } =
-    permissionApi.useResourcePermission("healthcheck", "manage");
+  const accessApi = useApi(accessApiRef);
+  const { allowed: canManage, loading: accessLoading } =
+    accessApi.useAccess(healthCheckAccess.configuration.manage);
 
   const {
     items: runs,
@@ -42,7 +43,7 @@ const HealthCheckHistoryPageContent = () => {
     <PageLayout
       title="Health Check History"
       subtitle="Detailed run history with full result data"
-      loading={permissionLoading}
+      loading={accessLoading}
       allowed={canManage}
     >
       <Card>