@checkstack/command-backend 0.0.3 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # @checkstack/command-backend
 
+## 0.1.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,
+  ```
+
+### Patch Changes
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [827b286]
+- Updated dependencies [f533141]
+- Updated dependencies [aa4a8ab]
+  - @checkstack/backend-api@0.3.0
+  - @checkstack/command-common@0.1.0
+  - @checkstack/common@0.2.0
+
+## 0.0.4
+
+### Patch Changes
+
+- Updated dependencies [97c5a6b]
+- Updated dependencies [8e43507]
+  - @checkstack/backend-api@0.2.0
+  - @checkstack/common@0.1.0
+  - @checkstack/command-common@0.0.4
+
 ## 0.0.3
 
 ### Patch Changes

package/package.json

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

package/src/registry.ts

@@ -1,8 +1,8 @@
 import type { SearchResult } from "@checkstack/command-common";
 import {
-  qualifyPermissionId,
+  qualifyAccessRuleId,
   type PluginMetadata,
-  type Permission,
+  type AccessRule,
   type LucideIconName,
 } from "@checkstack/common";
 
@@ -14,13 +14,13 @@ import {
  * Context provided to search providers during search operations.
  */
 export interface SearchContext {
-  /** The user's permission IDs for filtering results */
-  userPermissions: string[];
+  /** The user's access rule IDs for filtering results */
+  userAccessRules: string[];
 }
 
 /**
  * A command definition for simple registration.
- * Permissions will be automatically qualified using the plugin's metadata.
+ * Access rules will be automatically qualified using the plugin's metadata.
  */
 export interface CommandDefinition {
   /** Unique command ID (will be prefixed with plugin ID) */
@@ -33,8 +33,8 @@ export interface CommandDefinition {
   shortcuts?: string[];
   /** Route to navigate to when executed */
   route: string;
-  /** Permissions required (will be auto-qualified with plugin ID) */
-  requiredPermissions?: Permission[];
+  /** Access rules required (will be auto-qualified with plugin ID) */
+  requiredAccessRules?: AccessRule[];
 }
 
 /**
@@ -49,7 +49,7 @@ export interface BackendSearchProvider {
   priority?: number;
   /**
    * Search function that returns results matching the query.
-   * Results should NOT be pre-filtered by permissions - the registry handles that.
+   * Results should NOT be pre-filtered by access rules - the registry handles that.
    */
   search: (
     query: string,
@@ -61,13 +61,13 @@ export interface BackendSearchProvider {
  * Options for registering a search provider.
  */
 export interface RegisterSearchProviderOptions {
-  /** The plugin's metadata - used to qualify permission IDs */
+  /** The plugin's metadata - used to qualify access rule IDs */
   pluginMetadata: PluginMetadata;
 
   /**
    * Simple command definitions. These will be automatically:
    * - Converted to a search provider
-   * - Have permissions qualified with pluginId
+   * - Have access rules qualified with pluginId
    * - Be searchable by title, subtitle, and category
    */
   commands?: CommandDefinition[];
@@ -75,7 +75,7 @@ export interface RegisterSearchProviderOptions {
   /**
    * Custom search provider for more complex search logic.
    * Use this for entity search (e.g., catalog systems).
-   * Permissions in returned results will be auto-qualified.
+   * Access rules in returned results will be auto-qualified.
    */
   provider?: Omit<BackendSearchProvider, "id"> & {
     /** Provider ID (will be prefixed with plugin ID) */
@@ -93,7 +93,7 @@ const searchProviders = new Map<string, BackendSearchProvider>();
  * Register a search provider with the command palette.
  *
  * This is the main API for plugins to contribute to command palette search.
- * Permissions are automatically qualified with the plugin's ID.
+ * Access rules are automatically qualified with the plugin's ID.
  *
  * @example Simple command registration:
  * ```ts
@@ -107,7 +107,7 @@ const searchProviders = new Map<string, BackendSearchProvider>();
  *       iconName: "AlertCircle",
  *       shortcuts: ["meta+shift+i", "ctrl+shift+i"],
  *       route: "/incidents?action=create",
- *       requiredPermissions: [permissions.incidentManage],
+ *       requiredAccessRules: [access.incidentManage],
  *     },
  *   ],
  * });
@@ -146,7 +146,7 @@ export function registerSearchProvider(
     searchProviders.set(commandProvider.id, commandProvider);
   }
 
-  // Register custom provider with auto-qualified permissions
+  // Register custom provider with auto-qualified access rules
   if (provider) {
     const qualifiedProvider = createQualifiedProvider(pluginMetadata, provider);
     searchProviders.set(qualifiedProvider.id, qualifiedProvider);
@@ -160,7 +160,7 @@ function createCommandProvider(
   pluginMetadata: PluginMetadata,
   commands: CommandDefinition[]
 ): BackendSearchProvider {
-  // Pre-qualify all permissions and build SearchResult objects
+  // Pre-qualify all access rules and build SearchResult objects
   const searchableCommands: SearchResult[] = commands.map((cmd) => ({
     id: `${pluginMetadata.pluginId}.${cmd.id}`,
     type: "command" as const,
@@ -170,8 +170,8 @@ function createCommandProvider(
     category: capitalize(pluginMetadata.pluginId),
     shortcuts: cmd.shortcuts,
     route: cmd.route,
-    requiredPermissions: cmd.requiredPermissions?.map((perm) =>
-      qualifyPermissionId(pluginMetadata, perm)
+    requiredAccessRules: cmd.requiredAccessRules?.map((rule) =>
+      qualifyAccessRuleId(pluginMetadata, rule)
     ),
   }));
 
@@ -197,7 +197,7 @@ function createCommandProvider(
 }
 
 /**
- * Wrap a custom provider to auto-qualify permissions in results.
+ * Wrap a custom provider to auto-qualify access rules in results.
  */
 function createQualifiedProvider(
   pluginMetadata: PluginMetadata,
@@ -209,17 +209,17 @@ function createQualifiedProvider(
     search: async (query, context) => {
       const results = await provider.search(query, context);
 
-      // Auto-qualify permission IDs in results
+      // Auto-qualify access rule IDs in results
       return results.map((result) => ({
         ...result,
         id: result.id.includes(".")
           ? result.id
           : `${pluginMetadata.pluginId}.${result.id}`,
-        requiredPermissions: result.requiredPermissions?.map((permId) =>
+        requiredAccessRules: result.requiredAccessRules?.map((ruleId) =>
           // If already qualified (contains the plugin ID prefix), leave it
-          permId.startsWith(`${pluginMetadata.pluginId}.`)
-            ? permId
-            : `${pluginMetadata.pluginId}.${permId}`
+          ruleId.startsWith(`${pluginMetadata.pluginId}.`)
+            ? ruleId
+            : `${pluginMetadata.pluginId}.${ruleId}`
         ),
       }));
     },

package/src/router.ts

@@ -1,11 +1,8 @@
 import { implement } from "@orpc/server";
-import {
-  autoAuthMiddleware,
-  type RpcContext,
-} from "@checkstack/backend-api";
+import { autoAuthMiddleware, type RpcContext } from "@checkstack/backend-api";
 import {
   commandContract,
-  filterByPermissions,
+  filterByAccessRules,
   type SearchResult,
 } from "@checkstack/command-common";
 import { getSearchProviders } from "./registry";
@@ -13,24 +10,24 @@ import { getSearchProviders } from "./registry";
 /**
  * Creates the command router using contract-based implementation.
  *
- * Auth and permissions are automatically enforced via autoAuthMiddleware
- * based on the contract's meta.userType and meta.permissions.
+ * Auth and access rules are automatically enforced via autoAuthMiddleware
+ * based on the contract's meta.userType and meta.access.
  */
 const os = implement(commandContract)
   .$context<RpcContext>()
   .use(autoAuthMiddleware);
 
 /**
- * Extract permissions from the context user.
- * Only RealUser and ApplicationUser have permissions; ServiceUser doesn't.
+ * Extract access rules from the context user.
+ * Only RealUser and ApplicationUser have access rules; ServiceUser doesn't.
  */
-function getUserPermissions(context: RpcContext): string[] {
+function getUserAccessRules(context: RpcContext): string[] {
   const user = context.user;
   if (!user) return [];
   if (user.type === "user" || user.type === "application") {
-    return user.permissions ?? [];
+    return user.accessRules ?? [];
   }
-  // ServiceUser has no permissions array - treated as having all permissions
+  // ServiceUser has no accesss array - treated as having all access
   // but for search filtering, return empty (no filtering applied)
   return [];
 }
@@ -38,21 +35,23 @@ function getUserPermissions(context: RpcContext): string[] {
 export const createCommandRouter = () => {
   /**
    * Search across all registered search providers.
-   * Results are aggregated from all providers, filtered by permissions,
+   * Results are aggregated from all providers, filtered by access rules,
    * and returned in priority order.
    */
   const search = os.search.handler(async ({ input, context }) => {
     const providers = getSearchProviders();
     const query = input.query.toLowerCase().trim();
 
-    // Get user permissions for filtering
-    const userPermissions = getUserPermissions(context);
+    // Get user access rules for filtering
+    const userAccessRules = getUserAccessRules(context);
 
     // Execute all provider searches in parallel
     const providerResults = await Promise.all(
       providers.map(async (provider) => {
         try {
-          const results = await provider.search(query, { userPermissions });
+          const results = await provider.search(query, {
+            userAccessRules: userAccessRules,
+          });
           return results;
         } catch (error) {
           // Log but don't fail - one failing provider shouldn't break search
@@ -62,25 +61,27 @@ export const createCommandRouter = () => {
       })
     );
 
-    // Flatten and filter by permissions
+    // Flatten and filter by access rules
     const allResults = providerResults.flat();
-    return filterByPermissions(allResults, userPermissions);
+    return filterByAccessRules(allResults, userAccessRules);
   });
 
   /**
    * Get all registered commands for browsing.
-   * Returns commands filtered by user permissions.
+   * Returns commands filtered by user access rules.
    */
   const getCommands = os.getCommands.handler(async ({ context }) => {
     const providers = getSearchProviders();
-    const userPermissions = getUserPermissions(context);
+    const userAccessRules = getUserAccessRules(context);
 
     // Get all results with empty query (commands return all when query is empty)
     const providerResults = await Promise.all(
       providers.map(async (provider) => {
         try {
           // Empty query = return all items
-          const results = await provider.search("", { userPermissions });
+          const results = await provider.search("", {
+            userAccessRules: userAccessRules,
+          });
           // Filter to only commands for this endpoint
           return results.filter(
             (r): r is SearchResult & { type: "command" } => r.type === "command"
@@ -93,7 +94,7 @@ export const createCommandRouter = () => {
     );
 
     const allCommands = providerResults.flat();
-    return filterByPermissions(allCommands, userPermissions);
+    return filterByAccessRules(allCommands, userAccessRules);
   });
 
   return os.router({