@checkstack/command-common 0.0.4 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # @checkstack/command-common
 
+## 0.2.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
+
+### Patch Changes
+
+- Updated dependencies [7a23261]
+  - @checkstack/common@0.3.0
+
+## 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 [f533141]
+  - @checkstack/common@0.2.0
+
 ## 0.0.4
 
 ### Patch Changes

package/package.json

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

package/src/index.ts

@@ -1,9 +1,8 @@
-import { oc } from "@orpc/contract";
 import { z } from "zod";
 import {
   createClientDefinition,
   definePluginMetadata,
-  type ProcedureMetadata,
+  proc,
 } from "@checkstack/common";
 
 // =============================================================================
@@ -33,8 +32,8 @@ export const SearchResultSchema = z.object({
   route: z.string().optional(),
   /** For commands: keyboard shortcuts */
   shortcuts: z.array(z.string()).optional(),
-  /** Permission IDs required to see this result */
-  requiredPermissions: z.array(z.string()).optional(),
+  /** Access rule IDs required to see this result */
+  requiredAccessRules: z.array(z.string()).optional(),
 });
 
 export type SearchResult = z.infer<typeof SearchResultSchema>;
@@ -54,8 +53,8 @@ export const CommandSchema = z.object({
   iconName: z.string().optional(),
   /** Route to navigate to when the command is executed */
   route: z.string(),
-  /** Permission IDs required to see/execute this command */
-  requiredPermissions: z.array(z.string()).optional(),
+  /** Access rule IDs required to see/execute this command */
+  requiredAccessRules: z.array(z.string()).optional(),
 });
 
 export type Command = z.infer<typeof CommandSchema>;
@@ -64,8 +63,6 @@ export type Command = z.infer<typeof CommandSchema>;
 // RPC CONTRACT
 // =============================================================================
 
-const _base = oc.$meta<ProcedureMetadata>({});
-
 /**
  * Command palette RPC contract.
  * Provides search functionality across all registered providers.
@@ -73,20 +70,25 @@ const _base = oc.$meta<ProcedureMetadata>({});
 export const commandContract = {
   /**
    * Search across all registered search providers.
-   * Returns results filtered by user permissions.
+   * Returns results filtered by user access rules.
    */
-  search: _base
-    .meta({ userType: "public" })
+  search: proc({
+    operationType: "query",
+    userType: "public",
+    access: [],
+  })
     .input(z.object({ query: z.string() }))
     .output(z.array(SearchResultSchema)),
 
   /**
    * Get all registered commands (for browsing without a query).
-   * Returns commands filtered by user permissions.
+   * Returns commands filtered by user access rules.
    */
-  getCommands: _base
-    .meta({ userType: "public" })
-    .output(z.array(SearchResultSchema)),
+  getCommands: proc({
+    operationType: "query",
+    userType: "public",
+    access: [],
+  }).output(z.array(SearchResultSchema)),
 };
 
 export type CommandContract = typeof commandContract;
@@ -101,32 +103,32 @@ export const CommandApi = createClientDefinition(
 );
 
 // =============================================================================
-// PERMISSION UTILITIES (shared between frontend and backend)
+// ACCESS RULE UTILITIES (shared between frontend and backend)
 // =============================================================================
 
 /**
- * Filter items by user permissions.
- * Items without requiredPermissions are always included.
- * Users with the wildcard "*" permission can see all items.
+ * Filter items by user access rules.
+ * Items without requiredAccessRules are always included.
+ * Users with the wildcard "*" access rule can see all items.
  */
-export function filterByPermissions<
-  T extends { requiredPermissions?: string[] }
->(items: T[], userPermissions: string[]): T[] {
-  // Wildcard permission means access to everything
-  const hasWildcard = userPermissions.includes("*");
+export function filterByAccessRules<
+  T extends { requiredAccessRules?: string[] }
+>(items: T[], userAccessRules: string[]): T[] {
+  // Wildcard access rule means access to everything
+  const hasWildcard = userAccessRules.includes("*");
 
   return items.filter((item) => {
-    // No permissions required - always visible
-    if (!item.requiredPermissions || item.requiredPermissions.length === 0) {
+    // No access rules required - always visible
+    if (!item.requiredAccessRules || item.requiredAccessRules.length === 0) {
       return true;
     }
     // Wildcard user can see everything
     if (hasWildcard) {
       return true;
     }
-    // Check if user has all required permissions
-    return item.requiredPermissions.every((perm) =>
-      userPermissions.includes(perm)
+    // Check if user has all required access rules
+    return item.requiredAccessRules.every((rule) =>
+      userAccessRules.includes(rule)
     );
   });
 }