@checkstack/common 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,136 @@
 # @checkstack/common
 
+## 0.3.0
+
+### Minor Changes
+
+- 7a23261: ## TanStack Query Integration
+
+  Migrated all frontend components to use `usePluginClient` hook with TanStack Query integration, replacing the legacy `forPlugin()` pattern.
+
+  ### New Features
+
+  - **`usePluginClient` hook**: Provides type-safe access to plugin APIs with `.useQuery()` and `.useMutation()` methods
+  - **Automatic request deduplication**: Multiple components requesting the same data share a single network request
+  - **Built-in caching**: Configurable stale time and cache duration per query
+  - **Loading/error states**: TanStack Query provides `isLoading`, `error`, `isRefetching` states automatically
+  - **Background refetching**: Stale data is automatically refreshed when components mount
+
+  ### Contract Changes
+
+  All RPC contracts now require `operationType: "query"` or `operationType: "mutation"` metadata:
+
+  ```typescript
+  const getItems = proc()
+    .meta({ operationType: "query", access: [access.read] })
+    .output(z.array(itemSchema))
+    .query();
+
+  const createItem = proc()
+    .meta({ operationType: "mutation", access: [access.manage] })
+    .input(createItemSchema)
+    .output(itemSchema)
+    .mutation();
+  ```
+
+  ### Migration
+
+  ```typescript
+  // Before (forPlugin pattern)
+  const api = useApi(myPluginApiRef);
+  const [items, setItems] = useState<Item[]>([]);
+  useEffect(() => {
+    api.getItems().then(setItems);
+  }, [api]);
+
+  // After (usePluginClient pattern)
+  const client = usePluginClient(MyPluginApi);
+  const { data: items, isLoading } = client.getItems.useQuery({});
+  ```
+
+  ### Bug Fixes
+
+  - Fixed `rpc.test.ts` test setup for middleware type inference
+  - Fixed `SearchDialog` to use `setQuery` instead of deprecated `search` method
+  - Fixed null→undefined warnings in notification and queue frontends
+
+## 0.2.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
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/common",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/access-utils.ts

@@ -0,0 +1,240 @@
+import type { PluginMetadata } from "./plugin-metadata";
+
+// =============================================================================
+// UNIFIED ACCESS CONTROL
+// =============================================================================
+
+/**
+ * The two fundamental access levels.
+ */
+export type AccessLevel = "read" | "manage";
+
+/**
+ * Configuration for instance-level (team-based) access control.
+ * Specifies how to extract resource IDs from requests or responses.
+ */
+export interface InstanceAccessConfig {
+  /**
+   * For single-resource endpoints: parameter path in request input to extract resource ID.
+   * Uses dot notation for nested params (e.g., "params.systemId").
+   */
+  idParam?: string;
+
+  /**
+   * For list endpoints: key in response object containing the array to filter.
+   * When set, post-filters results based on team grants.
+   * Example: "systems" for response { systems: [...] }
+   */
+  listKey?: string;
+
+  /**
+   * For bulk record endpoints: key in response containing a Record<resourceId, data>.
+   * When set, post-filters the record keys based on team grants.
+   * Example: "statuses" for response { statuses: { [systemId]: {...} } }
+   */
+  recordKey?: string;
+}
+
+/**
+ * An Access Rule defines WHO can do WHAT to WHICH resources.
+ * This is the fundamental building block of the unified access control system.
+ *
+ * @example
+ * ```typescript
+ * // Simple access rule (no instance-level checks)
+ * const teamsRead = access("teams", "read", "View teams");
+ *
+ * // With instance-level access (single resource)
+ * const systemRead = access("system", "read", "View systems", {
+ *   idParam: "systemId",
+ * });
+ *
+ * // With instance-level access (list filtering)
+ * const systemListRead = access("system", "read", "View systems", {
+ *   listKey: "systems",
+ * });
+ * ```
+ */
+export interface AccessRule {
+  /**
+   * Unique identifier for this rule (e.g., "system.read").
+   * Auto-generated from resource + level.
+   * This is used as the access rule ID when checking user access rules.
+   */
+  readonly id: string;
+
+  /**
+   * The resource domain (e.g., "system", "healthcheck", "incident").
+   * Combined with pluginId to create fully-qualified type for team access checks.
+   */
+  readonly resource: string;
+
+  /**
+   * The access level this rule grants: "read" or "manage".
+   * Directly maps to canRead/canManage in team grants.
+   */
+  readonly level: AccessLevel;
+
+  /**
+   * Human-readable description of what this rule allows.
+   */
+  readonly description: string;
+
+  /**
+   * Whether this rule is granted by default to authenticated users ("users" role).
+   */
+  readonly isDefault?: boolean;
+
+  /**
+   * Whether this rule is granted to anonymous/public users ("anonymous" role).
+   */
+  readonly isPublic?: boolean;
+
+  /**
+   * Instance-level (team-based) access configuration.
+   * If defined, the middleware will check team grants for specific resource instances.
+   * If undefined, only global access is checked.
+   */
+  readonly instanceAccess?: InstanceAccessConfig;
+}
+
+/**
+ * Creates a fully-qualified access rule ID by prefixing the rule's ID with the plugin ID.
+ *
+ * This is the canonical way to construct namespaced access rule IDs for authorization checks.
+ * The function ensures consistent formatting across all access-related operations.
+ *
+ * @param pluginMetadata - The plugin metadata containing the pluginId
+ * @param rule - The access rule object containing the local access rule ID
+ * @returns The fully-qualified access rule ID (e.g., "catalog.system.read")
+ *
+ * @example
+ * ```typescript
+ * import { qualifyAccessRuleId } from "@checkstack/common";
+ * import { pluginMetadata } from "./plugin-metadata";
+ * import { catalogAccess } from "./access";
+ *
+ * const qualifiedId = qualifyAccessRuleId(pluginMetadata, catalogAccess.systems.read);
+ * // Returns: "catalog.system.read"
+ * ```
+ */
+export function qualifyAccessRuleId(
+  pluginMetadata: Pick<PluginMetadata, "pluginId">,
+  rule: Pick<AccessRule, "id">
+): string {
+  return `${pluginMetadata.pluginId}.${rule.id}`;
+}
+
+/**
+ * Creates an access rule for a resource.
+ *
+ * @param resource - The resource name (e.g., "system", "incident")
+ * @param level - The access level ("read" or "manage")
+ * @param description - Human-readable description
+ * @param options - Optional configuration for defaults and instance-level access
+ * @returns An AccessRule object
+ *
+ * @example
+ * ```typescript
+ * // Simple access rule
+ * const teamsRead = access("teams", "read", "View teams");
+ *
+ * // With defaults for public access
+ * const statusRead = access("status", "read", "View status", {
+ *   isDefault: true,
+ *   isPublic: true,
+ * });
+ *
+ * // With instance-level access
+ * const systemRead = access("system", "read", "View systems", {
+ *   idParam: "systemId",
+ *   listKey: "systems",
+ *   isDefault: true,
+ *   isPublic: true,
+ * });
+ * ```
+ */
+export function access(
+  resource: string,
+  level: AccessLevel,
+  description: string,
+  options?: {
+    idParam?: string;
+    listKey?: string;
+    recordKey?: string;
+    isDefault?: boolean;
+    isPublic?: boolean;
+  }
+): AccessRule {
+  const hasInstanceAccess =
+    options?.idParam || options?.listKey || options?.recordKey;
+
+  return {
+    id: `${resource}.${level}`,
+    resource,
+    level,
+    description,
+    isDefault: options?.isDefault,
+    isPublic: options?.isPublic,
+    instanceAccess: hasInstanceAccess
+      ? {
+          idParam: options?.idParam,
+          listKey: options?.listKey,
+          recordKey: options?.recordKey,
+        }
+      : undefined,
+  };
+}
+
+/**
+ * Creates a read/manage pair for a resource.
+ * Most resources need both access levels, so this reduces boilerplate.
+ *
+ * @param resource - The resource name (e.g., "system", "incident")
+ * @param descriptions - Descriptions for read and manage levels
+ * @param options - Optional configuration for defaults and instance-level access
+ * @returns An object with `read` and `manage` AccessRule properties
+ *
+ * @example
+ * ```typescript
+ * const systemAccess = accessPair("system", {
+ *   read: "View systems",
+ *   manage: "Create, update, and delete systems",
+ * }, {
+ *   idParam: "systemId",
+ *   listKey: "systems",
+ *   readIsDefault: true,
+ *   readIsPublic: true,
+ * });
+ *
+ * // Usage in contract:
+ * getSystem: _base.meta({ access: [systemAccess.read] }),
+ * updateSystem: _base.meta({ access: [systemAccess.manage] }),
+ * ```
+ */
+export function accessPair(
+  resource: string,
+  descriptions: { read: string; manage: string },
+  options?: {
+    idParam?: string;
+    listKey?: string;
+    recordKey?: string;
+    readIsDefault?: boolean;
+    readIsPublic?: boolean;
+  }
+): { read: AccessRule; manage: AccessRule } {
+  return {
+    read: access(resource, "read", descriptions.read, {
+      idParam: options?.idParam,
+      listKey: options?.listKey,
+      recordKey: options?.recordKey,
+      isDefault: options?.readIsDefault,
+      isPublic: options?.readIsPublic,
+    }),
+    manage: access(resource, "manage", descriptions.manage, {
+      idParam: options?.idParam,
+      // Note: manage doesn't typically use listKey (you don't "manage" a list in bulk)
+      // but we include idParam for single-resource manage checks
+    }),
+  };
+}

package/src/chart-types.ts

@@ -0,0 +1,38 @@
+/**
+ * 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)
+ * - 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
+ */
+export type ChartType =
+  | "line"
+  | "bar"
+  | "pie"
+  | "counter"
+  | "gauge"
+  | "boolean"
+  | "text"
+  | "status";
+
+/**
+ * Metadata type for health check result schemas.
+ * Provides autocompletion for chart-related metadata on result fields.
+ */
+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;
+}

package/src/client-definition.ts

@@ -1,23 +1,26 @@
 import type { ContractRouterClient, AnyContractRouter } from "@orpc/contract";
 import type { PluginMetadata } from "./plugin-metadata";
+import type { ProcedureMetadata } from "./types";
 
 /**
- * A client definition that bundles an RPC contract type with its plugin metadata.
- * Used for type-safe plugin RPC consumption.
+ * A client definition that bundles an RPC contract with its plugin metadata.
+ * Used for type-safe plugin RPC consumption and TanStack Query integration.
  *
  * @example
  * ```typescript
  * // Define in auth-common
  * export const AuthApi = createClientDefinition(authContract, pluginMetadata);
  *
- * // Use in frontend/backend
- * const authClient = rpcApi.forPlugin(AuthApi);  // Fully typed!
+ * // Use in frontend with TanStack Query hooks
+ * const authClient = usePluginClient(AuthApi);
+ * const { data } = authClient.getUser.useQuery({ id });
  * ```
  */
 export interface ClientDefinition<
   TContract extends AnyContractRouter = AnyContractRouter
 > {
   readonly pluginId: string;
+  readonly contract: TContract;
   /**
    * Phantom type for contract type inference.
    * This property doesn't exist at runtime - it's only used by TypeScript
@@ -38,15 +41,37 @@ export interface ClientDefinition<
 export type InferClient<T extends ClientDefinition> =
   T extends ClientDefinition<infer C> ? ContractRouterClient<C> : never;
 
+/**
+ * Type helper to extract operationType from a procedure's metadata.
+ */
+export type ExtractOperationType<TProcedure> = TProcedure extends {
+  "~orpc": { meta: { operationType: infer T } };
+}
+  ? T
+  : "query"; // Default to query if not specified
+
+/**
+ * Extracts the contract's metadata for a specific procedure path.
+ */
+export type InferProcedureMetadata<
+  TContract extends AnyContractRouter,
+  TPath extends keyof TContract
+> = TContract[TPath] extends { "~orpc": { meta: infer M } }
+  ? M extends ProcedureMetadata
+    ? M
+    : never
+  : never;
+
 /**
  * Create a typed client definition for a plugin's RPC contract.
  *
- * This bundles the contract type with the plugin metadata, enabling type-safe
- * forPlugin() calls without manual type annotations.
+ * This bundles the contract with the plugin metadata, enabling type-safe
+ * TanStack Query hooks that expose only .useQuery() or .useMutation() based
+ * on the procedure's operationType.
  *
- * @param _contract - The RPC contract object (used only for type inference)
+ * @param contract - The RPC contract object
  * @param metadata - The plugin metadata from the plugin's plugin-metadata.ts
- * @returns A ClientDefinition object that can be passed to forPlugin()
+ * @returns A ClientDefinition object that can be passed to usePluginClient()
  *
  * @example
  * ```typescript
@@ -56,16 +81,18 @@ export type InferClient<T extends ClientDefinition> =
  *
  * export const AuthApi = createClientDefinition(authContract, pluginMetadata);
  *
- * // In consumer (frontend or backend)
- * const authClient = rpcApi.forPlugin(AuthApi);
- * await authClient.getUsers(); // Fully typed!
+ * // In consumer (frontend)
+ * const authClient = usePluginClient(AuthApi);
+ * const { data } = authClient.getUsers.useQuery({}); // Type-safe!
+ * const mutation = authClient.deleteUser.useMutation(); // Type-safe!
  * ```
  */
 export function createClientDefinition<TContract extends AnyContractRouter>(
-  _contract: TContract,
+  contract: TContract,
   metadata: PluginMetadata
 ): ClientDefinition<TContract> {
   return {
     pluginId: metadata.pluginId,
+    contract,
   } as ClientDefinition<TContract>;
 }

package/src/index.ts

@@ -3,7 +3,9 @@ export * from "./pagination";
 export * from "./routes";
 export * from "./plugin-metadata";
 export * from "./client-definition";
-export * from "./permission-utils";
+export * from "./access-utils";
 export * from "./icons";
 export * from "./transport-client";
 export * from "./json-schema";
+export * from "./chart-types";
+export * from "./procedure-builder";

package/src/procedure-builder.ts

@@ -0,0 +1,52 @@
+import { oc } from "@orpc/contract";
+import type { ContractProcedureBuilder } from "@orpc/contract";
+import type { Schema, ErrorMap } from "@orpc/contract";
+import type { ProcedureMetadata } from "./types";
+
+/**
+ * Return type of proc() that preserves the operationType in the type system.
+ * This extends ContractProcedureBuilder but with our specific ProcedureMetadata.
+ */
+export type TypedContractProcedureBuilder<TMeta extends ProcedureMetadata> =
+  ContractProcedureBuilder<
+    Schema<unknown, unknown>,
+    Schema<unknown, unknown>,
+    ErrorMap,
+    TMeta
+  >;
+
+/**
+ * Creates an oRPC procedure builder with required metadata.
+ * All procedures MUST provide userType, operationType, and access.
+ *
+ * The return type preserves the operationType in the generic parameter,
+ * enabling type-safe hook selection (useQuery vs useMutation) in usePluginClient.
+ *
+ * @example
+ * ```typescript
+ * import { proc } from "@checkstack/common";
+ *
+ * export const myContract = {
+ *   // Returns TypedContractProcedureBuilder<{ operationType: "query", ... }>
+ *   getItems: proc({
+ *     operationType: "query",
+ *     userType: "public",
+ *     access: [myAccess.items.read],
+ *   }).output(z.array(ItemSchema)),
+ *
+ *   // Returns TypedContractProcedureBuilder<{ operationType: "mutation", ... }>
+ *   createItem: proc({
+ *     operationType: "mutation",
+ *     userType: "authenticated",
+ *     access: [myAccess.items.manage],
+ *   })
+ *     .input(CreateItemSchema)
+ *     .output(ItemSchema),
+ * };
+ * ```
+ */
+export function proc<TMeta extends ProcedureMetadata>(
+  meta: TMeta
+): TypedContractProcedureBuilder<TMeta> {
+  return oc.$meta<TMeta>(meta) as TypedContractProcedureBuilder<TMeta>;
+}

package/src/types.ts

@@ -2,64 +2,7 @@
 // RPC PROCEDURE METADATA
 // =============================================================================
 
-/**
- * Configuration for resource-level access control.
- * Used to enforce fine-grained permissions based on team grants.
- */
-export interface ResourceAccessConfig {
-  /**
-   * The resource type identifier (e.g., "system", "healthcheck").
-   * Will be auto-prefixed with pluginId in middleware (e.g., "catalog.system").
-   */
-  resourceType: string;
-
-  /**
-   * Parameter name in request input to extract resource ID from.
-   * Uses dot notation for nested params (e.g., "params.id").
-   * Required for single-resource access checks.
-   */
-  idParam?: string;
-
-  /**
-   * Filter mode for list endpoints.
-   * - "single": Check access to a single resource (default)
-   * - "list": Post-filter result array based on team access
-   */
-  filterMode?: "single" | "list";
-
-  /**
-   * Key in response object containing the array to filter.
-   * Required when filterMode is "list".
-   * Example: "systems" for response { systems: [...] }
-   */
-  outputKey?: string;
-}
-
-/**
- * Creates a ResourceAccessConfig for single-resource access checks.
- *
- * @param resourceType - The resource type (auto-prefixed with pluginId)
- * @param idParam - Parameter path in input to extract resource ID from
- */
-export function createResourceAccess(
-  resourceType: string,
-  idParam: string
-): ResourceAccessConfig {
-  return { resourceType, idParam, filterMode: "single" };
-}
-
-/**
- * Creates a ResourceAccessConfig for list filtering.
- *
- * @param resourceType - The resource type (auto-prefixed with pluginId)
- * @param outputKey - Key in response object containing the array to filter
- */
-export function createResourceAccessList(
-  resourceType: string,
-  outputKey: string
-): ResourceAccessConfig {
-  return { resourceType, filterMode: "list", outputKey };
-}
+import type { AccessRule } from "./access-utils";
 
 /**
  * Qualifies a resource type with the plugin namespace.
@@ -85,7 +28,7 @@ export function qualifyResourceType(
  *   getItems: baseContractBuilder
  *     .meta({
  *       userType: "user",
- *       permissions: [permissions.myPluginRead.id]
+ *       access: [myPluginAccess.items.read]
  *     })
  *     .output(z.array(ItemSchema)),
  * };
@@ -93,25 +36,35 @@ export function qualifyResourceType(
 export interface ProcedureMetadata {
   /**
    * Which type of caller can access this endpoint.
-   * - "anonymous": No authentication required, no permission checks (fully public)
-   * - "public": Anyone can attempt, but permissions are checked (uses anonymous role for guests)
+   * - "anonymous": No authentication required, no access checks (fully public)
+   * - "public": Anyone can attempt, but access rules are checked (uses anonymous role for guests)
    * - "user": Only real users (frontend authenticated)
    * - "service": Only services (backend-to-backend)
    * - "authenticated": Either users or services, but must be authenticated (default)
    */
-  userType?: "anonymous" | "public" | "user" | "service" | "authenticated";
+  userType: "anonymous" | "public" | "user" | "service" | "authenticated";
 
   /**
-   * Permissions required to access this endpoint.
-   * Only enforced for real users - services are trusted.
-   * For "public" userType, permissions are checked against the anonymous role if not authenticated.
-   * User must have at least one of the listed permissions, or "*" (wildcard).
+   * Operation type for TanStack Query integration.
+   * - "query": Read-only operation, uses useQuery hook
+   * - "mutation": Write operation, uses useMutation hook
+   *
+   * This is REQUIRED for all procedures to enable type-safe frontend hooks.
    */
-  permissions?: string[];
+  operationType: "query" | "mutation";
 
   /**
-   * Resource-level access control configurations.
-   * When specified, middleware checks team-based grants for the resources.
+   * Unified access rules combining access rules and resource-level access control.
+   * Each rule specifies the access rule ID, access level, and optional instance-level checks.
+   *
+   * User must satisfy ALL rules (AND logic).
+   *
+   * @example
+   * ```typescript
+   * access: [catalogAccess.systems.read]
+   * access: [catalogAccess.systems.manage]
+   * access: [catalogAccess.groups.manage, catalogAccess.systems.manage] // Both required
+   * ```
    */
-  resourceAccess?: ResourceAccessConfig[];
+  access: AccessRule[];
 }

package/src/permission-utils.ts

@@ -1,81 +0,0 @@
-import type { PluginMetadata } from "./plugin-metadata";
-
-/**
- * Supported actions for permissions.
- */
-export type PermissionAction = "read" | "manage";
-
-/**
- * Represents a permission that can be assigned to roles.
- */
-export interface Permission {
-  /** Permission identifier (e.g., "catalog.read") */
-  id: string;
-  /** Human-readable description of what this permission allows */
-  description?: string;
-  /** Whether this permission is assigned to the default "users" role (authenticated users) */
-  isAuthenticatedDefault?: boolean;
-  /** Whether this permission is assigned to the "anonymous" role (public access) */
-  isPublicDefault?: boolean;
-}
-
-/**
- * Represents a permission tied to a specific resource and action.
- */
-export interface ResourcePermission extends Permission {
-  /** The resource this permission applies to */
-  resource: string;
-  /** The action allowed on the resource */
-  action: PermissionAction;
-}
-
-/**
- * Helper to create a standardized resource permission.
- *
- * @param resource The resource name (e.g., "catalog", "healthcheck")
- * @param action The action (e.g., "read", "manage")
- * @param description Optional human-readable description
- * @param options Additional options like isAuthenticatedDefault and isPublicDefault
- */
-export function createPermission(
-  resource: string,
-  action: PermissionAction,
-  description?: string,
-  options?: { isAuthenticatedDefault?: boolean; isPublicDefault?: boolean }
-): ResourcePermission {
-  return {
-    id: `${resource}.${action}`,
-    resource,
-    action,
-    description,
-    isAuthenticatedDefault: options?.isAuthenticatedDefault,
-    isPublicDefault: options?.isPublicDefault,
-  };
-}
-
-/**
- * Creates a fully-qualified permission ID by prefixing the permission's ID with the plugin ID.
- *
- * This is the canonical way to construct namespaced permission IDs for authorization checks.
- * The function ensures consistent formatting across all permission-related operations.
- *
- * @param pluginMetadata - The plugin metadata containing the pluginId
- * @param permission - The permission object containing the local permission ID
- * @returns The fully-qualified permission ID (e.g., "catalog.catalog.read")
- *
- * @example
- * ```typescript
- * import { qualifyPermissionId } from "@checkstack/common";
- * import { pluginMetadata } from "./plugin-metadata";
- * import { permissions } from "./permissions";
- *
- * const qualifiedId = qualifyPermissionId(pluginMetadata, permissions.catalogRead);
- * // Returns: "catalog.catalog.read"
- * ```
- */
-export function qualifyPermissionId(
-  pluginMetadata: Pick<PluginMetadata, "pluginId">,
-  permission: Pick<Permission, "id">
-): string {
-  return `${pluginMetadata.pluginId}.${permission.id}`;
-}