@butlerw/vellum 0.1.0

package/src/commands/registry.ts

@@ -0,0 +1,374 @@
+/**
+ * Command Registry
+ *
+ * Central registry for slash commands with support for:
+ * - Priority-based conflict resolution
+ * - Alias resolution
+ * - Category indexing
+ * - Fuzzy search
+ *
+ * @module cli/commands/registry
+ */
+
+import type { CommandCategory, CommandKind, SlashCommand } from "./types.js";
+
+// =============================================================================
+// T008: CommandConflictError
+// =============================================================================
+
+/**
+ * Error thrown when two commands with the same priority conflict
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   registry.register(commandA);
+ *   registry.register(commandB); // Same name and priority as A
+ * } catch (e) {
+ *   if (e instanceof CommandConflictError) {
+ *     console.error(`Conflict: ${e.existingCommand} vs ${e.incomingCommand}`);
+ *   }
+ * }
+ * ```
+ */
+export class CommandConflictError extends Error {
+  /** Name of the command that already exists */
+  readonly existingCommand: string;
+  /** Name of the command attempting to register */
+  readonly incomingCommand: string;
+  /** Priority level of the conflicting commands */
+  readonly priority: CommandKind;
+
+  constructor(existingCommand: string, incomingCommand: string, priority: CommandKind) {
+    super(
+      `Command conflict: "${incomingCommand}" cannot be registered. ` +
+        `"${existingCommand}" already exists with same priority (${priority}).`
+    );
+    this.name = "CommandConflictError";
+    this.existingCommand = existingCommand;
+    this.incomingCommand = incomingCommand;
+    this.priority = priority;
+  }
+}
+
+// =============================================================================
+// Priority Constants
+// =============================================================================
+
+/**
+ * Priority values for command kinds
+ *
+ * Lower number = higher priority.
+ * Builtin commands always win over plugin commands, etc.
+ */
+const KIND_PRIORITY: Record<CommandKind, number> = {
+  builtin: 0,
+  plugin: 1,
+  mcp: 2,
+  user: 3,
+};
+
+// =============================================================================
+// T008: CommandRegistry Class
+// =============================================================================
+
+/**
+ * Central registry for slash commands
+ *
+ * Manages command registration, lookup, and search with:
+ * - Priority-based conflict resolution (lower priority number wins)
+ * - Alias resolution for alternative command names
+ * - Category indexing for grouped retrieval
+ * - Fuzzy search by command name
+ *
+ * @example
+ * ```typescript
+ * const registry = new CommandRegistry();
+ *
+ * // Register a builtin command
+ * registry.register(helpCommand);
+ *
+ * // Get by name or alias
+ * const cmd = registry.get('help'); // or registry.get('h')
+ *
+ * // Search commands
+ * const matches = registry.search('hel'); // returns [helpCommand]
+ *
+ * // Get by category
+ * const systemCmds = registry.getByCategory('system');
+ * ```
+ */
+export class CommandRegistry {
+  /** Primary command storage: name → command */
+  private readonly commands: Map<string, SlashCommand> = new Map();
+
+  /** Category index: category → set of command names */
+  private readonly categoryIndex: Map<CommandCategory, Set<string>> = new Map();
+
+  /** Alias index: alias → command name */
+  private readonly aliasIndex: Map<string, string> = new Map();
+
+  /**
+   * Create a new CommandRegistry
+   */
+  constructor() {
+    // Initialize category index with empty sets for all categories
+    const categories: CommandCategory[] = [
+      "system",
+      "auth",
+      "session",
+      "navigation",
+      "tools",
+      "config",
+      "debug",
+    ];
+    for (const category of categories) {
+      this.categoryIndex.set(category, new Set());
+    }
+  }
+
+  /**
+   * Number of registered commands
+   */
+  get size(): number {
+    return this.commands.size;
+  }
+
+  // ===========================================================================
+  // T009: Registration with Priority Conflict Resolution
+  // ===========================================================================
+
+  /**
+   * Register a command
+   *
+   * Priority rules:
+   * - builtin (0) > plugin (1) > mcp (2) > user (3)
+   * - Higher priority (lower number) wins silently
+   * - Same priority throws CommandConflictError
+   *
+   * @param command - Command to register
+   * @throws CommandConflictError if same-priority conflict occurs
+   *
+   * @example
+   * ```typescript
+   * registry.register({
+   *   name: 'help',
+   *   kind: 'builtin',
+   *   category: 'system',
+   *   description: 'Show help',
+   *   execute: async () => ({ kind: 'success' }),
+   * });
+   * ```
+   */
+  register(command: SlashCommand): void {
+    const existing = this.commands.get(command.name);
+
+    if (existing) {
+      const existingPriority = KIND_PRIORITY[existing.kind];
+      const incomingPriority = KIND_PRIORITY[command.kind];
+
+      // Same priority = conflict error
+      if (existingPriority === incomingPriority) {
+        throw new CommandConflictError(existing.name, command.name, command.kind);
+      }
+
+      // Incoming has lower priority (higher number) = ignore silently
+      if (incomingPriority > existingPriority) {
+        return;
+      }
+
+      // Incoming has higher priority (lower number) = replace
+      // First, clean up old command's indexes
+      this.removeFromIndexes(existing);
+    }
+
+    // Register the command
+    this.commands.set(command.name, command);
+
+    // Update category index
+    const categorySet = this.categoryIndex.get(command.category);
+    if (categorySet) {
+      categorySet.add(command.name);
+    }
+
+    // Update alias index
+    if (command.aliases) {
+      for (const alias of command.aliases) {
+        this.aliasIndex.set(alias, command.name);
+      }
+    }
+  }
+
+  // ===========================================================================
+  // T010: Get and Unregister
+  // ===========================================================================
+
+  /**
+   * Get a command by name or alias
+   *
+   * @param name - Command name or alias
+   * @returns Command if found, undefined otherwise
+   *
+   * @example
+   * ```typescript
+   * const cmd = registry.get('help'); // by name
+   * const cmd2 = registry.get('h');   // by alias
+   * ```
+   */
+  get(name: string): SlashCommand | undefined {
+    // Direct lookup first
+    const direct = this.commands.get(name);
+    if (direct) {
+      return direct;
+    }
+
+    // Try alias lookup
+    const resolvedName = this.aliasIndex.get(name);
+    if (resolvedName) {
+      return this.commands.get(resolvedName);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Unregister a command
+   *
+   * Removes the command from all indexes (commands, category, aliases).
+   *
+   * @param name - Command name to unregister
+   * @returns true if command was removed, false if not found
+   *
+   * @example
+   * ```typescript
+   * registry.unregister('help'); // removes help command and its aliases
+   * ```
+   */
+  unregister(name: string): boolean {
+    const command = this.commands.get(name);
+    if (!command) {
+      return false;
+    }
+
+    this.removeFromIndexes(command);
+    this.commands.delete(name);
+
+    return true;
+  }
+
+  /**
+   * Remove a command from category and alias indexes
+   */
+  private removeFromIndexes(command: SlashCommand): void {
+    // Remove from category index
+    const categorySet = this.categoryIndex.get(command.category);
+    if (categorySet) {
+      categorySet.delete(command.name);
+    }
+
+    // Remove from alias index
+    if (command.aliases) {
+      for (const alias of command.aliases) {
+        this.aliasIndex.delete(alias);
+      }
+    }
+  }
+
+  // ===========================================================================
+  // T011: Search, GetByCategory, List
+  // ===========================================================================
+
+  /**
+   * Search commands by name (fuzzy match)
+   *
+   * Returns commands where the name includes the query string.
+   *
+   * @param query - Search query
+   * @returns Array of matching commands
+   *
+   * @example
+   * ```typescript
+   * const matches = registry.search('log'); // returns login, logout
+   * ```
+   */
+  search(query: string): SlashCommand[] {
+    const normalizedQuery = query.toLowerCase();
+    const results: SlashCommand[] = [];
+
+    for (const command of this.commands.values()) {
+      if (command.name.toLowerCase().includes(normalizedQuery)) {
+        results.push(command);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Get all commands in a category
+   *
+   * @param category - Category to filter by
+   * @returns Set of commands in the category
+   *
+   * @example
+   * ```typescript
+   * const authCmds = registry.getByCategory('auth');
+   * for (const cmd of authCmds) {
+   *   console.log(cmd.name);
+   * }
+   * ```
+   */
+  getByCategory(category: CommandCategory): Set<SlashCommand> {
+    const names = this.categoryIndex.get(category);
+    const result = new Set<SlashCommand>();
+
+    if (names) {
+      for (const name of names) {
+        const command = this.commands.get(name);
+        if (command) {
+          result.add(command);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * List all registered commands
+   *
+   * @returns Array of all commands
+   *
+   * @example
+   * ```typescript
+   * const allCommands = registry.list();
+   * console.log(`${allCommands.length} commands registered`);
+   * ```
+   */
+  list(): SlashCommand[] {
+    return Array.from(this.commands.values());
+  }
+
+  /**
+   * Check if a command or alias exists
+   *
+   * @param name - Command name or alias
+   * @returns true if command exists
+   */
+  has(name: string): boolean {
+    return this.commands.has(name) || this.aliasIndex.has(name);
+  }
+
+  /**
+   * Clear all registered commands
+   *
+   * Useful for testing or resetting state.
+   */
+  clear(): void {
+    this.commands.clear();
+    this.aliasIndex.clear();
+    for (const categorySet of this.categoryIndex.values()) {
+      categorySet.clear();
+    }
+  }
+}

package/src/commands/sandbox/index.ts

@@ -0,0 +1,131 @@
+/**
+ * Sandbox Commands
+ * @module cli/commands/sandbox
+ */
+
+import type { CommandResult, SlashCommand } from "../types.js";
+import { success } from "../types.js";
+
+export type SandboxSubcommand = "enable" | "disable" | "status";
+
+export interface SandboxStatusJson {
+  enabled: boolean;
+  mode?: string;
+}
+
+export interface StatusOptions {
+  json?: boolean;
+}
+
+export type EnableableBackend = "subprocess" | "platform" | "container";
+
+export interface EnableOptions {
+  backend?: EnableableBackend;
+  force?: boolean;
+}
+
+export interface EnableResult {
+  success: boolean;
+  message?: string;
+  backend?: EnableableBackend;
+}
+
+/**
+ * Sandbox command
+ */
+export const sandboxCommand: SlashCommand = {
+  name: "sandbox",
+  description: "Manage sandbox mode",
+  kind: "builtin",
+  category: "system",
+  execute: async (): Promise<CommandResult> => success("Sandbox command not yet implemented"),
+};
+
+/**
+ * Sandbox enable command
+ */
+export const sandboxEnableCommand: SlashCommand = {
+  name: "enable",
+  description: "Enable sandbox mode",
+  kind: "builtin",
+  category: "system",
+  execute: async (): Promise<CommandResult> => success("Sandbox enable not yet implemented"),
+};
+
+/**
+ * Sandbox status command
+ */
+export const sandboxStatusCommand: SlashCommand = {
+  name: "status",
+  description: "Show sandbox status",
+  kind: "builtin",
+  category: "system",
+  execute: async (): Promise<CommandResult> => success("Sandbox status not yet implemented"),
+};
+
+/**
+ * Create sandbox command
+ */
+export function createSandboxCommand(): SlashCommand {
+  return sandboxCommand;
+}
+
+/**
+ * Handle sandbox enable
+ */
+export async function handleSandboxEnable(): Promise<void> {
+  // Placeholder
+}
+
+/**
+ * Handle sandbox status
+ */
+export async function handleSandboxStatus(_options?: StatusOptions): Promise<void> {
+  // Placeholder
+}
+
+/**
+ * Execute sandbox command
+ */
+export async function executeSandbox(
+  subcommand: SandboxSubcommand,
+  options?: EnableOptions | StatusOptions
+): Promise<EnableResult | SandboxStatusJson> {
+  switch (subcommand) {
+    case "enable":
+      return executeSandboxEnable(options as EnableOptions);
+    case "status":
+      return executeSandboxStatus(options as StatusOptions);
+    case "disable":
+      return { success: true, message: "Sandbox disable not yet implemented" };
+    default:
+      return { success: false, message: `Unknown sandbox subcommand: ${subcommand}` };
+  }
+}
+
+/**
+ * Execute sandbox enable command
+ */
+export async function executeSandboxEnable(_options?: EnableOptions): Promise<EnableResult> {
+  return { success: true, message: "Sandbox enable not yet implemented" };
+}
+
+/**
+ * Execute sandbox status command
+ */
+export async function executeSandboxStatus(_options?: StatusOptions): Promise<SandboxStatusJson> {
+  return { enabled: false };
+}
+
+/**
+ * Get help text for sandbox commands
+ */
+export function getSandboxHelp(): string {
+  return [
+    "Sandbox Commands",
+    "",
+    "  /sandbox status   Show sandbox status",
+    "  /sandbox enable   Enable sandbox mode",
+    "  /sandbox disable  Disable sandbox mode",
+  ].join("\n");
+}

package/src/commands/security/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Security Module
+ *
+ * Exports security-related utilities for input validation and sanitization.
+ *
+ * @module cli/commands/security
+ */
+
+export { InputSanitizer } from "./input-sanitizer.js";
+export {
+  type CommandSecurityPolicy,
+  createPermissionChecker,
+  PermissionChecker,
+  type PermissionResult,
+} from "./permission-checker.js";
+export {
+  createDefaultHandler,
+  DEFAULT_SENSITIVE_PATTERNS,
+  SensitiveDataHandler,
+  type SensitivePattern,
+} from "./sensitive-data.js";

package/src/commands/security/input-sanitizer.ts

@@ -0,0 +1,168 @@
+/**
+ * Input Sanitizer
+ *
+ * Security utilities for sanitizing user input to prevent:
+ * - Shell injection attacks
+ * - Path traversal attacks
+ * - Command injection
+ *
+ * @module cli/commands/security/input-sanitizer
+ */
+
+import path from "node:path";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Shell metacharacters that need escaping
+ * Includes: | & ; $ ` \ ! ( ) { } [ ] < > * ? # ~
+ */
+const SHELL_METACHARACTERS = /[|&;$`\\!(){}[\]<>*?#~]/g;
+
+/**
+ * Pattern to detect path traversal attempts
+ * Matches: ../ ..\ ~/ and absolute paths
+ */
+const PATH_TRAVERSAL_PATTERNS = [
+  /\.\.[/\\]/, // ../ or ..\
+  /^~[/\\]?/, // ~/ or ~\ or just ~
+  /^[a-zA-Z]:[/\\]/, // Windows absolute path (C:\, D:/)
+  /^[/\\]/, // Unix absolute path
+];
+
+/**
+ * Dangerous characters to remove from general input
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: Need to match control chars for security
+const DANGEROUS_CHARS = /[|&;$`\\!(){}[\]<>*?#~\x00-\x1f\x7f]/g;
+
+// =============================================================================
+// InputSanitizer Class
+// =============================================================================
+
+/**
+ * Provides methods for sanitizing and validating user input.
+ *
+ * @example
+ * ```typescript
+ * const sanitizer = new InputSanitizer();
+ *
+ * // Sanitize general input
+ * const clean = sanitizer.sanitize("hello; rm -rf /");
+ * // => "hello rm -rf "
+ *
+ * // Validate paths
+ * const isValid = sanitizer.validatePath("../secret", "/app/data");
+ * // => false
+ *
+ * // Escape shell metacharacters
+ * const escaped = sanitizer.escapeShellMeta("hello; world");
+ * // => "hello\\; world"
+ * ```
+ */
+export class InputSanitizer {
+  /**
+   * Sanitizes input by removing dangerous characters.
+   *
+   * Removes shell metacharacters and control characters that could
+   * be used for injection attacks.
+   *
+   * @param input - The input string to sanitize
+   * @returns Sanitized string with dangerous characters removed
+   */
+  sanitize(input: string): string {
+    if (!input) {
+      return "";
+    }
+
+    // Remove dangerous characters
+    return input.replace(DANGEROUS_CHARS, "");
+  }
+
+  /**
+   * Validates that a path does not escape the allowed root directory.
+   *
+   * Prevents path traversal attacks by:
+   * - Rejecting paths with ../ or ..\
+   * - Rejecting absolute paths
+   * - Rejecting paths starting with ~/
+   * - Normalizing and checking the resolved path stays within root
+   *
+   * @param inputPath - The path to validate
+   * @param allowedRoot - The root directory that must contain the resolved path
+   * @returns true if path is safe and within allowedRoot, false otherwise
+   */
+  validatePath(inputPath: string, allowedRoot: string): boolean {
+    if (!inputPath || !allowedRoot) {
+      return false;
+    }
+
+    // Check for path traversal patterns in raw input
+    for (const pattern of PATH_TRAVERSAL_PATTERNS) {
+      if (pattern.test(inputPath)) {
+        return false;
+      }
+    }
+
+    // Normalize both paths for comparison
+    const normalizedRoot = path.resolve(allowedRoot);
+    const resolvedPath = path.resolve(allowedRoot, inputPath);
+
+    // Ensure resolved path starts with the allowed root
+    // Add path.sep to prevent partial directory name matches
+    // e.g., /app/data should not allow /app/data-secret
+    return resolvedPath === normalizedRoot || resolvedPath.startsWith(normalizedRoot + path.sep);
+  }
+
+  /**
+   * Escapes shell metacharacters in input.
+   *
+   * Instead of removing characters, this method escapes them with
+   * backslashes so they are treated literally by the shell.
+   *
+   * Characters escaped: | & ; $ ` \ ! ( ) { } [ ] < > * ? # ~
+   *
+   * @param input - The input string to escape
+   * @returns String with shell metacharacters escaped
+   */
+  escapeShellMeta(input: string): string {
+    if (!input) {
+      return "";
+    }
+
+    // Escape each metacharacter with a backslash
+    return input.replace(SHELL_METACHARACTERS, "\\$&");
+  }
+
+  /**
+   * Checks if a string contains any shell metacharacters.
+   *
+   * @param input - The input string to check
+   * @returns true if input contains shell metacharacters
+   */
+  containsShellMeta(input: string): boolean {
+    if (!input) {
+      return false;
+    }
+
+    // Use a fresh regex to avoid lastIndex issues with global flag
+    const pattern = /[|&;$`\\!(){}[\]<>*?#~]/;
+    return pattern.test(input);
+  }
+
+  /**
+   * Checks if a path contains traversal patterns.
+   *
+   * @param inputPath - The path to check
+   * @returns true if path contains traversal patterns
+   */
+  containsPathTraversal(inputPath: string): boolean {
+    if (!inputPath) {
+      return false;
+    }
+
+    return PATH_TRAVERSAL_PATTERNS.some((pattern) => pattern.test(inputPath));
+  }
+}