@affectively/slash-commands 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-01-25
+
+### Added
+
+- Initial release
+- Zod schema integration for command generation
+- Flexible syntax parsing (key=value, --key=value, -k, etc.)
+- Automatic type coercion (numbers, booleans, arrays, objects)
+- Fuzzy autocomplete with scoring
+- Subscription tier support
+- Auto-generated aliases (kebab-case, acronyms)
+- Command registry with category filtering
+- API executor for remote command execution
+- Full TypeScript support

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AFFECTIVELY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+# @affectively/slash-commands
+
+Slash command parser with Zod schema integration. Auto-generates commands from Zod schemas with autocomplete, validation, and type coercion for CLI and chat interfaces.
+
+## Features
+
+- **Zod Integration** - Generate commands directly from Zod schemas
+- **Type Coercion** - Automatically convert strings to numbers, booleans, arrays
+- **Autocomplete** - Fuzzy matching suggestions for commands and arguments
+- **Validation** - Validate arguments against schema with detailed errors
+- **Subscription Tiers** - Built-in support for tiered command access
+- **Aliases** - Auto-generated aliases (kebab-case, acronyms)
+- **Flexible Syntax** - Supports `key=value`, `--key=value`, `--key value`, `-k`
+
+## Installation
+
+```bash
+npm install @affectively/slash-commands zod
+# or
+bun add @affectively/slash-commands zod
+# or
+yarn add @affectively/slash-commands zod
+```
+
+## Quick Start
+
+```typescript
+import {
+  slashCommandRegistry,
+  parseSlashCommand,
+  getAutocompleteSuggestions,
+} from '@affectively/slash-commands';
+import { z } from 'zod';
+
+// Register commands from tool definitions
+slashCommandRegistry.registerFromTools([
+  {
+    name: 'users_list',
+    description: 'List users with optional filtering',
+    inputSchema: z.object({
+      role: z.enum(['admin', 'user', 'guest']).optional().describe('Filter by role'),
+      limit: z.number().default(10).describe('Maximum results'),
+      active: z.boolean().optional().describe('Only active users'),
+    }),
+    requiredTier: 'free',
+  },
+  {
+    name: 'users_create',
+    description: 'Create a new user',
+    inputSchema: z.object({
+      email: z.string().describe('User email address'),
+      name: z.string().describe('Display name'),
+      role: z.enum(['admin', 'user', 'guest']).default('user'),
+    }),
+    requiredTier: 'premium',
+  },
+]);
+
+// Parse user input
+const parsed = parseSlashCommand('/users_list limit=20 role=admin');
+console.log(parsed);
+// {
+//   command: 'users_list',
+//   args: { limit: 20, role: 'admin' },
+//   found: true,
+//   errors: undefined
+// }
+
+// Get autocomplete suggestions
+const suggestions = getAutocompleteSuggestions('/us', { userTier: 'premium' });
+console.log(suggestions);
+// [
+//   { command: 'users_list', displayText: '/users_list', ... },
+//   { command: 'users_create', displayText: '/users_create', ... }
+// ]
+```
+
+## Supported Syntax
+
+```bash
+# Basic command
+/command
+
+# Named arguments
+/command arg1=value1 arg2=value2
+
+# Quoted values (for spaces)
+/command name="John Doe"
+
+# CLI-style flags
+/command --limit=10 --active
+
+# Short flags
+/command -l 10 -a
+
+# Boolean flags
+/command --active
+
+# Hierarchical commands (auto-converted)
+/users list  →  users_list
+```
+
+## Type Coercion
+
+Arguments are automatically coerced to appropriate types:
+
+```typescript
+parseSlashCommand('/cmd num=42');        // { num: 42 } (number)
+parseSlashCommand('/cmd flag=true');     // { flag: true } (boolean)
+parseSlashCommand('/cmd arr=[1,2,3]');   // { arr: [1,2,3] } (array)
+parseSlashCommand('/cmd obj={"a":1}');   // { obj: { a: 1 } } (object)
+```
+
+## Registry API
+
+```typescript
+import { slashCommandRegistry } from '@affectively/slash-commands';
+
+// Register a single command
+slashCommandRegistry.register(commandDefinition);
+
+// Register multiple commands
+slashCommandRegistry.registerAll([cmd1, cmd2]);
+
+// Register from tool definitions (with Zod schemas)
+slashCommandRegistry.registerFromTools(tools);
+
+// Get command by name or alias
+const cmd = slashCommandRegistry.get('users_list');
+const cmd = slashCommandRegistry.get('ul'); // Auto-generated alias
+
+// Filter by category
+const userCommands = slashCommandRegistry.getByCategory('users');
+
+// Filter by subscription tier
+const freeCommands = slashCommandRegistry.getForTier('free');
+
+// Get all categories
+const categories = slashCommandRegistry.getCategories();
+```
+
+## Autocomplete
+
+```typescript
+import {
+  getAutocompleteSuggestions,
+  getSuggestionsGroupedByCategory,
+  shouldShowAutocomplete,
+  fuzzyMatch,
+} from '@affectively/slash-commands';
+
+// Get suggestions for partial input
+const suggestions = getAutocompleteSuggestions('/us', {
+  userTier: 'premium',
+  maxSuggestions: 10,
+  includeHidden: false,
+  minScore: 30,
+});
+
+// Group by category for UI
+const grouped = getSuggestionsGroupedByCategory('/us', { userTier: 'premium' });
+// { users: [...], utilities: [...] }
+
+// Check if autocomplete should show
+if (shouldShowAutocomplete(input)) {
+  // Show autocomplete UI
+}
+
+// Test fuzzy match score
+const score = fuzzyMatch('ul', 'users_list'); // 80+ (initials match)
+```
+
+## Command Execution
+
+```typescript
+import { executeSlashCommand, createAPIExecutor } from '@affectively/slash-commands';
+
+// Execute with custom executor
+const result = await executeSlashCommand(
+  '/users_list limit=10',
+  {
+    userTier: 'premium',
+    apiBaseUrl: 'https://api.example.com',
+    authToken: 'bearer-token',
+  },
+  async (command, args, context) => {
+    // Your execution logic here
+    return await fetch(`/api/${command}`, {
+      method: 'POST',
+      body: JSON.stringify(args),
+    });
+  }
+);
+
+// Or use the built-in API executor
+const apiExecutor = createAPIExecutor('https://api.example.com', 'auth-token');
+const result = await executeSlashCommand('/users_list', context, apiExecutor);
+```
+
+## Generating Commands
+
+```typescript
+import { generateSlashCommand, generateSlashCommands } from '@affectively/slash-commands';
+import { z } from 'zod';
+
+const command = generateSlashCommand({
+  name: 'search',
+  description: 'Search for items',
+  inputSchema: z.object({
+    query: z.string().describe('Search query'),
+    page: z.number().default(1),
+  }),
+});
+
+console.log(command.helpText);
+// /search
+//
+// Search for items
+//
+// Parameters:
+//   query <string> (required)
+//     Search query
+//   page <number> (optional) (default: 1)
+
+console.log(command.examples);
+// ['/search', '/search query="example"']
+```
+
+## Subscription Tiers
+
+```typescript
+// Commands can require specific subscription tiers
+const command = generateSlashCommand({
+  name: 'premium_feature',
+  description: 'A premium feature',
+  inputSchema: z.object({}),
+  requiredTier: 'premium',
+});
+
+// Filter available commands by tier
+const available = slashCommandRegistry.getForTier('free');
+
+// Autocomplete respects tiers (shows but marks inaccessible)
+const suggestions = getAutocompleteSuggestions('/pre', { userTier: 'free' });
+// Returns suggestion with hasAccess: false
+```
+
+## API Reference
+
+### Parser
+
+- `parseSlashCommand(input, registry?, options?)` - Parse input into command and args
+- `isSlashCommand(input)` - Check if input starts with /
+- `extractCommandName(input)` - Get command name from input
+- `formatCommand(command, args)` - Format command for display
+- `getPartialCommand(input)` - Get partial command info for autocomplete
+
+### Registry
+
+- `SlashCommandRegistry` - Main registry class
+- `slashCommandRegistry` - Global singleton instance
+- `executeSlashCommand(input, context, executor)` - Execute a command
+- `createAPIExecutor(baseUrl, token?)` - Create API-based executor
+
+### Generator
+
+- `generateSlashCommand(tool)` - Generate command from tool definition
+- `generateSlashCommands(tools)` - Generate multiple commands
+- `extractParametersFromZod(schema)` - Extract params from Zod schema
+- `extractParametersFromJsonSchema(schema)` - Extract params from JSON schema
+
+### Autocomplete
+
+- `getAutocompleteSuggestions(input, options?, registry?)` - Get suggestions
+- `getSuggestionsGroupedByCategory(input, options?, registry?)` - Grouped suggestions
+- `shouldShowAutocomplete(input)` - Check if autocomplete should show
+- `fuzzyMatch(query, target)` - Calculate match score (0-100)
+
+## License
+
+MIT © AFFECTIVELY

package/dist/index.d.mts

@@ -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 };