@checkstack/command-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# @checkstack/command-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/command-common@0.0.2
+  - @checkstack/common@0.0.2
+
+## 0.1.0
+
+### Minor Changes
+
+- a65e002: Add command palette commands and deep-linking support
+
+  **Backend Changes:**
+
+  - `healthcheck-backend`: Add "Manage Health Checks" (⇧⌘H) and "Create Health Check" commands
+  - `catalog-backend`: Add "Manage Systems" (⇧⌘S) and "Create System" commands
+  - `integration-backend`: Add "Manage Integrations" (⇧⌘G), "Create Integration Subscription", and "View Integration Logs" commands
+  - `auth-backend`: Add "Manage Users" (⇧⌘U), "Create User", "Manage Roles", and "Manage Applications" commands
+  - `command-backend`: Auto-cleanup command registrations when plugins are deregistered
+
+  **Frontend Changes:**
+
+  - `HealthCheckConfigPage`: Handle `?action=create` URL parameter
+  - `CatalogConfigPage`: Handle `?action=create` URL parameter
+  - `IntegrationsPage`: Handle `?action=create` URL parameter
+  - `AuthSettingsPage`: Handle `?tab=` and `?action=create` URL parameters
+
+### Patch Changes
+
+- a65e002: Add compile-time type safety for Lucide icon names
+
+  - Add `LucideIconName` type and `lucideIconSchema` Zod schema to `@checkstack/common`
+  - Update backend interfaces (`AuthStrategy`, `NotificationStrategy`, `IntegrationProvider`, `CommandDefinition`) to use `LucideIconName`
+  - Update RPC contracts to use `lucideIconSchema` for proper type inference across RPC boundaries
+  - Simplify `SocialProviderButton` to use `DynamicIcon` directly (removes 30+ lines of pascalCase conversion)
+  - Replace static `iconMap` in `SearchDialog` with `DynamicIcon` for dynamic icon rendering
+  - Add fallback handling in `DynamicIcon` when icon name isn't found
+  - Fix legacy kebab-case icon names to PascalCase: `mail`→`Mail`, `send`→`Send`, `github`→`Github`, `key-round`→`KeyRound`, `network`→`Network`, `AlertCircle`→`CircleAlert`
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/command-common@0.0.3
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/command-common@0.0.2

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@checkstack/command-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/command-common": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@orpc/server": "^1.13.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@checkstack/scripts": "workspace:*",
+    "@checkstack/tsconfig": "workspace:*",
+    "@types/bun": "^1.3.5",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+import {
+  createBackendPlugin,
+  coreServices,
+  coreHooks,
+} from "@checkstack/backend-api";
+import {
+  pluginMetadata,
+  commandContract,
+} from "@checkstack/command-common";
+import { createCommandRouter } from "./router";
+import { unregisterProvidersByPluginId } from "./registry";
+
+// Re-export registry functions for other plugins to use
+export {
+  registerSearchProvider,
+  unregisterSearchProvider,
+  clearRegistry,
+  type BackendSearchProvider,
+  type SearchContext,
+  type CommandDefinition,
+  type RegisterSearchProviderOptions,
+} from "./registry";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerInit({
+      deps: {
+        rpc: coreServices.rpc,
+        logger: coreServices.logger,
+      },
+      init: async ({ rpc, logger }) => {
+        logger.debug("Initializing Command Backend...");
+
+        // Register oRPC router
+        const commandRouter = createCommandRouter();
+        rpc.registerRouter(commandRouter, commandContract);
+
+        logger.debug("✅ Command Backend initialized.");
+      },
+      afterPluginsReady: async ({ logger, onHook }) => {
+        // Subscribe to plugin deregistration to clean up their commands
+        onHook(
+          coreHooks.pluginDeregistering,
+          async ({ pluginId }) => {
+            const removed = unregisterProvidersByPluginId(pluginId);
+            if (removed > 0) {
+              logger.debug(
+                `[command-backend] Unregistered ${removed} search provider(s) for plugin: ${pluginId}`
+              );
+            }
+          },
+          { mode: "instance-local" }
+        );
+      },
+    });
+  },
+});

package/src/registry.ts

@@ -0,0 +1,274 @@
+import type { SearchResult } from "@checkstack/command-common";
+import {
+  qualifyPermissionId,
+  type PluginMetadata,
+  type Permission,
+  type LucideIconName,
+} from "@checkstack/common";
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Context provided to search providers during search operations.
+ */
+export interface SearchContext {
+  /** The user's permission IDs for filtering results */
+  userPermissions: string[];
+}
+
+/**
+ * A command definition for simple registration.
+ * Permissions will be automatically qualified using the plugin's metadata.
+ */
+export interface CommandDefinition {
+  /** Unique command ID (will be prefixed with plugin ID) */
+  id: string;
+  title: string;
+  subtitle?: string;
+  /** Icon name (Lucide PascalCase, e.g., 'AlertCircle') */
+  iconName?: LucideIconName;
+  /** Keyboard shortcuts, e.g. ["meta+shift+i", "ctrl+shift+i"] */
+  shortcuts?: string[];
+  /** Route to navigate to when executed */
+  route: string;
+  /** Permissions required (will be auto-qualified with plugin ID) */
+  requiredPermissions?: Permission[];
+}
+
+/**
+ * A backend search provider that contributes results to the command palette.
+ */
+export interface BackendSearchProvider {
+  /** Unique identifier for this provider */
+  id: string;
+  /** Display name for the provider category */
+  name: string;
+  /** Higher priority = appears first in results (default: 0) */
+  priority?: number;
+  /**
+   * Search function that returns results matching the query.
+   * Results should NOT be pre-filtered by permissions - the registry handles that.
+   */
+  search: (
+    query: string,
+    context: SearchContext
+  ) => Promise<SearchResult[]> | SearchResult[];
+}
+
+/**
+ * Options for registering a search provider.
+ */
+export interface RegisterSearchProviderOptions {
+  /** The plugin's metadata - used to qualify permission IDs */
+  pluginMetadata: PluginMetadata;
+
+  /**
+   * Simple command definitions. These will be automatically:
+   * - Converted to a search provider
+   * - Have permissions qualified with pluginId
+   * - Be searchable by title, subtitle, and category
+   */
+  commands?: CommandDefinition[];
+
+  /**
+   * 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.
+   */
+  provider?: Omit<BackendSearchProvider, "id"> & {
+    /** Provider ID (will be prefixed with plugin ID) */
+    id: string;
+  };
+}
+
+// =============================================================================
+// INTERNAL REGISTRY
+// =============================================================================
+
+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.
+ *
+ * @example Simple command registration:
+ * ```ts
+ * registerSearchProvider({
+ *   pluginMetadata,
+ *   commands: [
+ *     {
+ *       id: "create",
+ *       title: "Create Incident",
+ *       subtitle: "Report a new incident",
+ *       iconName: "AlertCircle",
+ *       shortcuts: ["meta+shift+i", "ctrl+shift+i"],
+ *       route: "/incidents?action=create",
+ *       requiredPermissions: [permissions.incidentManage],
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Custom entity provider:
+ * ```ts
+ * registerSearchProvider({
+ *   pluginMetadata,
+ *   provider: {
+ *     id: "systems",
+ *     name: "Systems",
+ *     priority: 100,
+ *     search: async (query) => {
+ *       const systems = await db.select().from(schema.systems);
+ *       return systems.filter(s => s.name.includes(query)).map(s => ({
+ *         id: s.id,
+ *         type: "entity",
+ *         title: s.name,
+ *         category: "Systems",
+ *         route: `/catalog/systems/${s.id}`,
+ *       }));
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function registerSearchProvider(
+  options: RegisterSearchProviderOptions
+): void {
+  const { pluginMetadata, commands, provider } = options;
+
+  // Register commands as a search provider
+  if (commands && commands.length > 0) {
+    const commandProvider = createCommandProvider(pluginMetadata, commands);
+    searchProviders.set(commandProvider.id, commandProvider);
+  }
+
+  // Register custom provider with auto-qualified permissions
+  if (provider) {
+    const qualifiedProvider = createQualifiedProvider(pluginMetadata, provider);
+    searchProviders.set(qualifiedProvider.id, qualifiedProvider);
+  }
+}
+
+/**
+ * Create a search provider from command definitions.
+ */
+function createCommandProvider(
+  pluginMetadata: PluginMetadata,
+  commands: CommandDefinition[]
+): BackendSearchProvider {
+  // Pre-qualify all permissions and build SearchResult objects
+  const searchableCommands: SearchResult[] = commands.map((cmd) => ({
+    id: `${pluginMetadata.pluginId}.${cmd.id}`,
+    type: "command" as const,
+    title: cmd.title,
+    subtitle: cmd.subtitle,
+    iconName: cmd.iconName,
+    category: capitalize(pluginMetadata.pluginId),
+    shortcuts: cmd.shortcuts,
+    route: cmd.route,
+    requiredPermissions: cmd.requiredPermissions?.map((perm) =>
+      qualifyPermissionId(pluginMetadata, perm)
+    ),
+  }));
+
+  return {
+    id: `${pluginMetadata.pluginId}.commands`,
+    name: `${capitalize(pluginMetadata.pluginId)} Commands`,
+    priority: 80, // Commands have medium-high priority
+    search: (query) => {
+      const q = query.toLowerCase();
+
+      // Return all if no query
+      if (!q) return searchableCommands;
+
+      // Filter by title, subtitle, or category
+      return searchableCommands.filter(
+        (cmd) =>
+          cmd.title.toLowerCase().includes(q) ||
+          cmd.subtitle?.toLowerCase().includes(q) ||
+          cmd.category.toLowerCase().includes(q)
+      );
+    },
+  };
+}
+
+/**
+ * Wrap a custom provider to auto-qualify permissions in results.
+ */
+function createQualifiedProvider(
+  pluginMetadata: PluginMetadata,
+  provider: BackendSearchProvider
+): BackendSearchProvider {
+  return {
+    ...provider,
+    id: `${pluginMetadata.pluginId}.${provider.id}`,
+    search: async (query, context) => {
+      const results = await provider.search(query, context);
+
+      // Auto-qualify permission IDs in results
+      return results.map((result) => ({
+        ...result,
+        id: result.id.includes(".")
+          ? result.id
+          : `${pluginMetadata.pluginId}.${result.id}`,
+        requiredPermissions: result.requiredPermissions?.map((permId) =>
+          // If already qualified (contains the plugin ID prefix), leave it
+          permId.startsWith(`${pluginMetadata.pluginId}.`)
+            ? permId
+            : `${pluginMetadata.pluginId}.${permId}`
+        ),
+      }));
+    },
+  };
+}
+
+/**
+ * Capitalize first letter of a string.
+ */
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Unregister a search provider.
+ */
+export function unregisterSearchProvider(providerId: string): void {
+  searchProviders.delete(providerId);
+}
+
+/**
+ * Unregister all search providers for a given plugin ID.
+ * Called automatically when a plugin is deregistered.
+ * @returns The number of providers removed
+ */
+export function unregisterProvidersByPluginId(pluginId: string): number {
+  let removed = 0;
+  for (const [id] of searchProviders) {
+    if (id.startsWith(`${pluginId}.`)) {
+      searchProviders.delete(id);
+      removed++;
+    }
+  }
+  return removed;
+}
+
+/**
+ * Get all registered search providers, sorted by priority (descending).
+ * @internal Used by the command router
+ */
+export function getSearchProviders(): BackendSearchProvider[] {
+  return [...searchProviders.values()].toSorted(
+    (a, b) => (b.priority ?? 0) - (a.priority ?? 0)
+  );
+}
+
+/**
+ * Clear all registrations. Useful for testing.
+ */
+export function clearRegistry(): void {
+  searchProviders.clear();
+}

package/src/router.ts

@@ -0,0 +1,105 @@
+import { implement } from "@orpc/server";
+import {
+  autoAuthMiddleware,
+  type RpcContext,
+} from "@checkstack/backend-api";
+import {
+  commandContract,
+  filterByPermissions,
+  type SearchResult,
+} from "@checkstack/command-common";
+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.
+ */
+const os = implement(commandContract)
+  .$context<RpcContext>()
+  .use(autoAuthMiddleware);
+
+/**
+ * Extract permissions from the context user.
+ * Only RealUser and ApplicationUser have permissions; ServiceUser doesn't.
+ */
+function getUserPermissions(context: RpcContext): string[] {
+  const user = context.user;
+  if (!user) return [];
+  if (user.type === "user" || user.type === "application") {
+    return user.permissions ?? [];
+  }
+  // ServiceUser has no permissions array - treated as having all permissions
+  // but for search filtering, return empty (no filtering applied)
+  return [];
+}
+
+export const createCommandRouter = () => {
+  /**
+   * Search across all registered search providers.
+   * Results are aggregated from all providers, filtered by permissions,
+   * 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);
+
+    // Execute all provider searches in parallel
+    const providerResults = await Promise.all(
+      providers.map(async (provider) => {
+        try {
+          const results = await provider.search(query, { userPermissions });
+          return results;
+        } catch (error) {
+          // Log but don't fail - one failing provider shouldn't break search
+          console.error(`Search provider ${provider.id} failed:`, error);
+          return [];
+        }
+      })
+    );
+
+    // Flatten and filter by permissions
+    const allResults = providerResults.flat();
+    return filterByPermissions(allResults, userPermissions);
+  });
+
+  /**
+   * Get all registered commands for browsing.
+   * Returns commands filtered by user permissions.
+   */
+  const getCommands = os.getCommands.handler(async ({ context }) => {
+    const providers = getSearchProviders();
+    const userPermissions = getUserPermissions(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 });
+          // Filter to only commands for this endpoint
+          return results.filter(
+            (r): r is SearchResult & { type: "command" } => r.type === "command"
+          );
+        } catch (error) {
+          console.error(`Search provider ${provider.id} failed:`, error);
+          return [];
+        }
+      })
+    );
+
+    const allCommands = providerResults.flat();
+    return filterByPermissions(allCommands, userPermissions);
+  });
+
+  return os.router({
+    search,
+    getCommands,
+  });
+};
+
+export type CommandRouter = ReturnType<typeof createCommandRouter>;

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}