@checkstack/command-frontend 0.0.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,144 @@
 # @checkstack/command-frontend
 
+## 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/frontend-api@0.2.0
+  - @checkstack/common@0.3.0
+  - @checkstack/command-common@0.2.0
+  - @checkstack/ui@0.2.1
+
+## 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/command-common@0.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/ui@0.2.0
+
 ## 0.0.5
 
 ### Patch Changes

package/package.json

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

package/src/components/SearchDialog.tsx

@@ -24,7 +24,12 @@ export const SearchDialog: React.FC<SearchDialogProps> = ({
 }) => {
   const navigate = useNavigate();
   const formatShortcut = useFormatShortcut();
-  const { results, loading, search, reset } = useDebouncedSearch(300);
+  const {
+    results,
+    loading,
+    setQuery: setSearchQuery,
+    reset,
+  } = useDebouncedSearch(300);
 
   const [query, setQuery] = useState("");
   const [selectedIndex, setSelectedIndex] = useState(0);
@@ -34,7 +39,7 @@ export const SearchDialog: React.FC<SearchDialogProps> = ({
   // Trigger search when dialog opens or query changes
   useEffect(() => {
     if (open) {
-      search(query);
+      setSearchQuery(query);
       // Focus input after dialog opens
       setTimeout(() => inputRef.current?.focus(), 50);
     } else {
@@ -43,7 +48,7 @@ export const SearchDialog: React.FC<SearchDialogProps> = ({
       setSelectedIndex(0);
       reset();
     }
-  }, [open, query, search, reset]);
+  }, [open, query, setSearchQuery, reset]);
 
   // Group results by category
   const groupedResults: Record<string, SearchResult[]> = {};

package/src/index.tsx

@@ -1,17 +1,14 @@
-import { useEffect, useCallback, useMemo, useState, useRef } from "react";
+import { useEffect, useCallback, useMemo, useState } from "react";
 import {
-  useApi,
-  rpcApiRef,
-  createApiRef,
   createFrontendPlugin,
   NavbarCenterSlot,
+  usePluginClient,
 } from "@checkstack/frontend-api";
 import {
   CommandApi,
   pluginMetadata,
   type SearchResult,
 } from "@checkstack/command-common";
-import type { InferClient } from "@checkstack/common";
 import { NavbarSearch } from "./components/NavbarSearch";
 
 // =============================================================================
@@ -30,15 +27,6 @@ export const commandPlugin = createFrontendPlugin({
   ],
 });
 
-// =============================================================================
-// API REF
-// =============================================================================
-
-export type CommandApiClient = InferClient<typeof CommandApi>;
-
-export const commandApiRef =
-  createApiRef<CommandApiClient>("plugin.command.api");
-
 // =============================================================================
 // SHORTCUT UTILITIES (Frontend-only - requires DOM types)
 // =============================================================================
@@ -107,6 +95,27 @@ export function formatShortcut(shortcut: string, isMac: boolean): string {
   return isMac ? parts.join("") : parts.join("+");
 }
 
+// =============================================================================
+// DEBOUNCE HOOK
+// =============================================================================
+
+/**
+ * Hook to debounce a value by the specified delay.
+ */
+function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delayMs);
+
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+
+  return debouncedValue;
+}
+
 // =============================================================================
 // HOOKS
 // =============================================================================
@@ -118,16 +127,16 @@ export function formatShortcut(shortcut: string, isMac: boolean): string {
  *
  * @param commands - Array of commands with shortcuts
  * @param navigate - Navigation function to call when a command is triggered
- * @param userPermissions - Array of permission IDs the user has
+ * @param userAccessRules - Array of access rule IDs the user has
  */
 export function useGlobalShortcuts(
   commands: SearchResult[],
   navigate: (route: string) => void,
-  userPermissions: string[]
+  userAccessRules: string[]
 ): void {
   useEffect(() => {
-    // Check if user has wildcard permission (admin)
-    const hasWildcard = userPermissions.includes("*");
+    // Check if user has wildcard access rule (admin)
+    const hasWildcard = userAccessRules.includes("*");
 
     const handleKeyDown = (event: KeyboardEvent) => {
       // Don't trigger in input fields
@@ -144,12 +153,12 @@ export function useGlobalShortcuts(
       for (const command of commands) {
         if (!command.shortcuts || !command.route) continue;
 
-        // Check permissions (skip if user has wildcard)
-        if (!hasWildcard && command.requiredPermissions?.length) {
-          const hasPermission = command.requiredPermissions.every((perm) =>
-            userPermissions.includes(perm)
+        // Check access rules (skip if user has wildcard)
+        if (!hasWildcard && command.requiredAccessRules?.length) {
+          const hasAccess = command.requiredAccessRules.every((rule) =>
+            userAccessRules.includes(rule)
           );
-          if (!hasPermission) continue;
+          if (!hasAccess) continue;
         }
 
         for (const shortcut of command.shortcuts) {
@@ -165,7 +174,7 @@ export function useGlobalShortcuts(
 
     globalThis.addEventListener("keydown", handleKeyDown);
     return () => globalThis.removeEventListener("keydown", handleKeyDown);
-  }, [commands, navigate, userPermissions]);
+  }, [commands, navigate, userAccessRules]);
 }
 
 /**
@@ -185,105 +194,36 @@ export function useFormatShortcut(): (shortcut: string) => string {
   );
 }
 
-/**
- * Hook to search across all providers via backend RPC.
- * Returns search function and loading state.
- */
-export function useCommandPaletteSearch(): {
-  search: (query: string) => Promise<SearchResult[]>;
-  getCommands: () => Promise<SearchResult[]>;
-  loading: boolean;
-} {
-  const rpcApi = useApi(rpcApiRef);
-  const commandApi = useMemo(() => rpcApi.forPlugin(CommandApi), [rpcApi]);
-  const [loading, setLoading] = useState(false);
-
-  const search = useCallback(
-    async (query: string): Promise<SearchResult[]> => {
-      setLoading(true);
-      try {
-        return await commandApi.search({ query });
-      } finally {
-        setLoading(false);
-      }
-    },
-    [commandApi]
-  );
-
-  const getCommands = useCallback(async (): Promise<SearchResult[]> => {
-    setLoading(true);
-    try {
-      return await commandApi.getCommands();
-    } finally {
-      setLoading(false);
-    }
-  }, [commandApi]);
-
-  return { search, getCommands, loading };
-}
-
 /**
  * Hook for debounced search in the command palette.
- * Automatically debounces the search query by the specified delay.
+ * Uses TanStack Query with a debounced query state.
  */
 export function useDebouncedSearch(delayMs: number = 300): {
   results: SearchResult[];
   loading: boolean;
-  search: (query: string) => void;
+  setQuery: (query: string) => void;
   reset: () => void;
 } {
-  const { search: doSearch, getCommands } = useCommandPaletteSearch();
-  const [results, setResults] = useState<SearchResult[]>([]);
-  const [loading, setLoading] = useState(false);
-  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  const search = useCallback(
-    (query: string) => {
-      // Clear any pending search
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current);
-      }
-
-      // If empty query, fetch all results immediately (commands + entities)
-      if (!query.trim()) {
-        setLoading(true);
-        doSearch("")
-          .then(setResults)
-          .catch(() => setResults([]))
-          .finally(() => setLoading(false));
-        return;
-      }
-
-      // Debounce non-empty queries
-      setLoading(true);
-      timeoutRef.current = setTimeout(() => {
-        doSearch(query)
-          .then(setResults)
-          .catch(() => setResults([]))
-          .finally(() => setLoading(false));
-      }, delayMs);
-    },
-    [doSearch, getCommands, delayMs]
+  const commandClient = usePluginClient(CommandApi);
+  const [query, setQuery] = useState("");
+  const debouncedQuery = useDebouncedValue(query, delayMs);
+
+  // useQuery automatically refetches when debouncedQuery changes
+  const { data, isLoading } = commandClient.search.useQuery(
+    { query: debouncedQuery },
+    { staleTime: 30_000 } // Cache results for 30 seconds
   );
 
   const reset = useCallback(() => {
-    if (timeoutRef.current) {
-      clearTimeout(timeoutRef.current);
-    }
-    setResults([]);
-    setLoading(false);
-  }, []);
-
-  // Cleanup on unmount
-  useEffect(() => {
-    return () => {
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current);
-      }
-    };
+    setQuery("");
   }, []);
 
-  return { results, loading, search, reset };
+  return {
+    results: data ?? [],
+    loading: isLoading,
+    setQuery,
+    reset,
+  };
 }
 
 // =============================================================================
@@ -298,40 +238,20 @@ export function useCommands(): {
   commands: SearchResult[];
   loading: boolean;
 } {
-  const rpcApi = useApi(rpcApiRef);
-  const commandApi = useMemo(() => rpcApi.forPlugin(CommandApi), [rpcApi]);
-  const [commands, setCommands] = useState<SearchResult[]>([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    async function fetchCommands() {
-      try {
-        const results = await commandApi.getCommands();
-        if (!cancelled) {
-          // Filter to only commands with shortcuts
-          setCommands(
-            results.filter((r) => r.shortcuts && r.shortcuts.length > 0)
-          );
-        }
-      } catch {
-        // Ignore errors - commands just won't be available
-      } finally {
-        if (!cancelled) {
-          setLoading(false);
-        }
-      }
-    }
+  const commandClient = usePluginClient(CommandApi);
 
-    fetchCommands();
+  // Fetch all commands (empty query returns all)
+  const { data, isLoading } = commandClient.getCommands.useQuery(undefined, {
+    staleTime: 60_000, // Cache for 1 minute
+  });
 
-    return () => {
-      cancelled = true;
-    };
-  }, [commandApi]);
+  // Filter to only commands with shortcuts
+  const commandsWithShortcuts = useMemo(
+    () => (data ?? []).filter((r) => r.shortcuts && r.shortcuts.length > 0),
+    [data]
+  );
 
-  return { commands, loading };
+  return { commands: commandsWithShortcuts, loading: isLoading };
 }
 
 /**
@@ -359,7 +279,7 @@ export function GlobalShortcuts(): React.ReactNode {
     globalThis.location.href = route;
   }, []);
 
-  // For now, pass "*" as permission since the backend already filters by permission
+  // For now, pass "*" as access rule since the backend already filters
   // The commands returned from getCommands are already filtered
   useGlobalShortcuts(commands, navigate, ["*"]);