@affectively/slash-commands 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,390 @@
+import { z } from 'zod';
+
+/**
+ * Slash Command Types
+ *
+ * Shared type definitions for slash commands across CLI, web, and chat interfaces.
+ * These types enable auto-generation of commands from Zod schemas.
+ */
+
+/**
+ * Subscription tier (can be extended by consumers)
+ */
+type SubscriptionTier = 'free' | 'premium' | 'ultra-premium' | 'enterprise' | string;
+/**
+ * Parameter definition extracted from Zod schema
+ */
+interface SlashCommandParameter {
+    /** Parameter name */
+    name: string;
+    /** Parameter type (string, number, boolean, enum, array, object) */
+    type: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object';
+    /** Human-readable description from Zod .describe() */
+    description: string;
+    /** Whether this parameter is required */
+    required: boolean;
+    /** Default value if any */
+    defaultValue?: unknown;
+    /** Enum values if type is 'enum' */
+    enumValues?: string[];
+    /** CLI flag aliases (e.g., ['-c', '--category']) */
+    aliases?: string[];
+}
+/**
+ * Slash command definition generated from tool definition
+ */
+interface SlashCommandDefinition {
+    /** Command name without slash (e.g., 'behaviors_list') */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Zod schema for input validation */
+    schema: z.ZodType;
+    /** Category for grouping (extracted from name prefix, e.g., 'behaviors') */
+    category: string;
+    /** Subscription tier required */
+    requiredTier: SubscriptionTier;
+    /** Parsed parameters from schema */
+    parameters: SlashCommandParameter[];
+    /** Optional command aliases (e.g., ['bl', 'list-behaviors']) */
+    aliases?: string[];
+    /** Generated help text from schema and description */
+    helpText: string;
+    /** Example usage strings */
+    examples: string[];
+    /** Whether this command is hidden from help/autocomplete */
+    hidden?: boolean;
+}
+/**
+ * Parsed slash command from user input
+ */
+interface SlashCommandParsed {
+    /** Resolved command name */
+    command: string;
+    /** Parsed and validated arguments */
+    args: Record<string, unknown>;
+    /** Original raw input string */
+    raw: string;
+    /** Whether the command was found in registry */
+    found: boolean;
+    /** Validation errors if any */
+    errors?: string[];
+    /** Matched command definition (if found) */
+    definition?: SlashCommandDefinition;
+}
+/**
+ * Result from executing a slash command
+ */
+interface SlashCommandResult {
+    /** Whether execution succeeded */
+    success: boolean;
+    /** Result data (JSON-serializable) */
+    data?: unknown;
+    /** Error message if failed */
+    error?: string;
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+    /** Command that was executed */
+    command: string;
+    /** Arguments that were used */
+    args: Record<string, unknown>;
+}
+/**
+ * Autocomplete suggestion for slash commands
+ */
+interface SlashCommandSuggestion {
+    /** Full command name */
+    command: string;
+    /** Display text for UI (may include formatting) */
+    displayText: string;
+    /** Short description */
+    description: string;
+    /** Match score (0-100, higher is better match) */
+    matchScore?: number;
+    /** Category for grouping in UI */
+    category: string;
+    /** Whether user has access based on subscription */
+    hasAccess: boolean;
+    /** Required subscription tier for this command */
+    requiredTier?: SubscriptionTier;
+}
+/**
+ * Tool definition (input to generator)
+ */
+interface ToolDefinition {
+    /** Tool name (snake_case) */
+    name: string;
+    /** Tool description */
+    description: string;
+    /** Zod schema or JSON schema for input */
+    inputSchema: z.ZodType | Record<string, unknown>;
+    /** Required subscription tier */
+    requiredTier?: SubscriptionTier;
+}
+/**
+ * Options for the slash command parser
+ */
+interface SlashCommandParserOptions {
+    /** Whether to allow unknown arguments (default: false) */
+    allowUnknownArgs?: boolean;
+    /** Whether to coerce types (default: true) */
+    coerceTypes?: boolean;
+    /** Custom argument separator (default: ' ') */
+    argSeparator?: string;
+}
+/**
+ * Options for autocomplete
+ */
+interface SlashCommandAutocompleteOptions {
+    /** Maximum suggestions to return (default: 10) */
+    maxSuggestions?: number;
+    /** User's subscription tier for filtering */
+    userTier?: SubscriptionTier;
+    /** Include hidden commands */
+    includeHidden?: boolean;
+    /** Minimum match score threshold (0-100, default: 0) */
+    minScore?: number;
+}
+/**
+ * Execution context for slash commands
+ */
+interface SlashCommandContext {
+    /** User ID (for auth/tracking) */
+    userId?: string;
+    /** User's subscription tier */
+    userTier: SubscriptionTier;
+    /** API base URL for remote execution */
+    apiBaseUrl: string;
+    /** Auth token for API calls */
+    authToken?: string;
+    /** Conversation ID (for chat context) */
+    conversationId?: string;
+    /** Whether running in CLI mode */
+    isCLI?: boolean;
+}
+
+/**
+ * Slash Command Generator
+ *
+ * Converts tool definitions with Zod schemas into SlashCommandDefinitions.
+ * This enables auto-generation of CLI commands and web slash commands from
+ * a single source of truth (tool definitions).
+ */
+
+/**
+ * Extract category from tool name (prefix before first underscore)
+ */
+declare function extractCategory(toolName: string): string;
+/**
+ * Extract parameters from a Zod schema
+ */
+declare function extractParametersFromZod(schema: z.ZodType): SlashCommandParameter[];
+/**
+ * Generate help text from command definition
+ */
+declare function generateHelpText(name: string, description: string, parameters: SlashCommandParameter[]): string;
+/**
+ * Generate example usage strings
+ */
+declare function generateExamples(name: string, parameters: SlashCommandParameter[]): string[];
+/**
+ * Generate a SlashCommandDefinition from a tool definition
+ */
+declare function generateSlashCommand(tool: ToolDefinition, tierOverride?: SubscriptionTier): SlashCommandDefinition;
+/**
+ * Extract parameters from JSON Schema (for tools using inline schema instead of Zod)
+ */
+declare function extractParametersFromJsonSchema(jsonSchema: Record<string, unknown>): SlashCommandParameter[];
+/**
+ * Generate multiple SlashCommandDefinitions from an array of tools
+ */
+declare function generateSlashCommands(tools: ToolDefinition[]): SlashCommandDefinition[];
+/**
+ * Generate command aliases (shorter versions of command names)
+ */
+declare function generateAliases(name: string): string[];
+
+/**
+ * Slash Command Parser
+ *
+ * Parses user input in the form `/command arg1=value1 arg2=value2`
+ * Supports both snake_case commands and hierarchical syntax (e.g., `/behaviors list`)
+ */
+
+/**
+ * Check if input starts with a slash command
+ */
+declare function isSlashCommand(input: string): boolean;
+/**
+ * Extract the command name from input (before arguments)
+ */
+declare function extractCommandName(input: string): string;
+/**
+ * Parse slash command input into structured form
+ *
+ * Supports:
+ * - `/command` - command with no args
+ * - `/command arg1=value1` - command with named args
+ * - `/command arg1="value with spaces"` - quoted values
+ * - `/command arg1='value with spaces'` - single-quoted values
+ * - `/command --arg1=value1` - CLI-style flags
+ * - `/command -a value1` - Short flags with space
+ * - `/domain subcommand` - Hierarchical commands (converted to domain_subcommand)
+ */
+declare function parseSlashCommand(input: string, registry?: Map<string, SlashCommandDefinition>, options?: SlashCommandParserOptions): SlashCommandParsed;
+/**
+ * Format a command invocation for display
+ */
+declare function formatCommand(command: string, args: Record<string, unknown>): string;
+/**
+ * Get partial command info for autocomplete (before user finishes typing)
+ */
+declare function getPartialCommand(input: string): {
+    command: string;
+    isComplete: boolean;
+    partialArg?: string;
+};
+
+/**
+ * Slash Command Registry
+ *
+ * Central registry for all slash commands. Commands are generated from tool
+ * definitions and can be registered either statically or dynamically.
+ *
+ * Usage:
+ * - CLI: Import and use the singleton registry
+ * - Web: Build registry from fetched tool definitions
+ */
+
+/**
+ * Slash Command Registry
+ *
+ * Stores and manages all registered slash commands with support for:
+ * - Command lookup by name or alias
+ * - Category-based filtering
+ * - Subscription tier filtering
+ * - Alias resolution
+ */
+declare class SlashCommandRegistry {
+    private commands;
+    private aliases;
+    private categories;
+    /**
+     * Register a single slash command
+     */
+    register(command: SlashCommandDefinition): void;
+    /**
+     * Register multiple commands at once
+     */
+    registerAll(commands: SlashCommandDefinition[]): void;
+    /**
+     * Register commands from tool definitions
+     */
+    registerFromTools(tools: ToolDefinition[]): void;
+    /**
+     * Get a command by name or alias
+     */
+    get(nameOrAlias: string): SlashCommandDefinition | undefined;
+    /**
+     * Check if a command exists
+     */
+    has(nameOrAlias: string): boolean;
+    /**
+     * Get all registered commands
+     */
+    getAll(): SlashCommandDefinition[];
+    /**
+     * Get commands filtered by category
+     */
+    getByCategory(category: string): SlashCommandDefinition[];
+    /**
+     * Get commands available for a subscription tier
+     */
+    getForTier(tier: SubscriptionTier): SlashCommandDefinition[];
+    /**
+     * Get all categories
+     */
+    getCategories(): string[];
+    /**
+     * Get command count by category
+     */
+    getCountByCategory(): Record<string, number>;
+    /**
+     * Resolve an alias to the canonical command name
+     */
+    resolveAlias(alias: string): string | undefined;
+    /**
+     * Get the underlying Map for direct access
+     */
+    getMap(): Map<string, SlashCommandDefinition>;
+    /**
+     * Clear all registered commands
+     */
+    clear(): void;
+    /**
+     * Get total command count
+     */
+    get size(): number;
+}
+/**
+ * Global singleton registry instance
+ */
+declare const slashCommandRegistry: SlashCommandRegistry;
+/**
+ * Execute a slash command
+ *
+ * @param input - Raw input string (e.g., "/behaviors_list limit=10")
+ * @param context - Execution context with auth and API info
+ * @param executor - Function to execute the command (API call, local handler, etc.)
+ */
+declare function executeSlashCommand(input: string, context: SlashCommandContext, executor: (command: string, args: Record<string, unknown>, context: SlashCommandContext) => Promise<unknown>): Promise<SlashCommandResult>;
+/**
+ * Create an API-based command executor
+ */
+declare function createAPIExecutor(apiBaseUrl: string, authToken?: string): (command: string, args: Record<string, unknown>, context: SlashCommandContext) => Promise<unknown>;
+/**
+ * Export helper to get all commands as an array (useful for CLI help)
+ */
+declare function getAllSlashCommands(): SlashCommandDefinition[];
+/**
+ * Export helper to get a specific command
+ */
+declare function getSlashCommand(name: string): SlashCommandDefinition | undefined;
+/**
+ * Export helper to check if a command exists
+ */
+declare function hasSlashCommand(name: string): boolean;
+
+/**
+ * Slash Command Autocomplete
+ *
+ * Provides fuzzy matching and suggestion generation for slash commands.
+ * Used by both CLI tab-completion and web chat autocomplete UI.
+ */
+
+/**
+ * Calculate fuzzy match score between query and target
+ * Returns 0-100, higher is better match
+ */
+declare function fuzzyMatch(query: string, target: string): number;
+/**
+ * Get autocomplete suggestions for a partial input
+ */
+declare function getAutocompleteSuggestions(input: string, options?: SlashCommandAutocompleteOptions, registry?: SlashCommandRegistry): SlashCommandSuggestion[];
+/**
+ * Get suggestions grouped by category
+ */
+declare function getSuggestionsGroupedByCategory(input: string, options?: SlashCommandAutocompleteOptions, registry?: SlashCommandRegistry): Record<string, SlashCommandSuggestion[]>;
+/**
+ * Check if input should trigger autocomplete
+ */
+declare function shouldShowAutocomplete(input: string): boolean;
+/**
+ * Get the text to replace when selecting a suggestion
+ */
+declare function getReplacementRange(input: string): {
+    start: number;
+    end: number;
+};
+
+export { type SlashCommandAutocompleteOptions, type SlashCommandContext, type SlashCommandDefinition, type SlashCommandParameter, type SlashCommandParsed, type SlashCommandParserOptions, SlashCommandRegistry, type SlashCommandResult, type SlashCommandSuggestion, type SubscriptionTier, type ToolDefinition, createAPIExecutor, executeSlashCommand, extractCategory, extractCommandName, extractParametersFromJsonSchema, extractParametersFromZod, formatCommand, fuzzyMatch, generateAliases, generateExamples, generateHelpText, generateSlashCommand, generateSlashCommands, getAllSlashCommands, getAutocompleteSuggestions, getPartialCommand, getReplacementRange, getSlashCommand, getSuggestionsGroupedByCategory, hasSlashCommand, isSlashCommand, parseSlashCommand, shouldShowAutocomplete, slashCommandRegistry };