feat(parser): Add semantic error handling and command registry

- SemanticParseError with enhanced error context using semantic types
- SemanticCommandRegistry for type-safe command management
- Fuzzy command suggestions with semantic return types
- Command metadata with proper type safety

Author: dugshub

src/cli_patterns/ui/parser/semantic_errors.py

@@ -0,0 +1,72 @@
+"""Semantic parse errors using semantic types for enhanced error handling.
+
+This module provides SemanticParseError, which extends ParseError to include
+semantic type information for better error reporting and recovery.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from cli_patterns.core.parser_types import CommandId, OptionKey
+from cli_patterns.ui.parser.types import ParseError
+
+
+class SemanticParseError(ParseError):
+    """Exception raised during semantic command parsing with semantic type context.
+
+    This extends ParseError to include semantic type information that can be
+    used for better error reporting and recovery mechanisms.
+
+    Attributes:
+        message: Human-readable error message
+        error_type: Type of parsing error
+        suggestions: List of suggested corrections (semantic types, shadows base class)
+        command: Command that caused the error (if applicable)
+        invalid_option: Invalid option key (if applicable)
+        valid_options: List of valid option keys (if applicable)
+        required_role: Required role for command (if applicable)
+        current_role: Current user role (if applicable)
+        context_info: Additional context information
+    """
+
+    def __init__(
+        self,
+        error_type: str,
+        message: str,
+        suggestions: Optional[list[CommandId]] = None,
+        command: Optional[CommandId] = None,
+        invalid_option: Optional[OptionKey] = None,
+        valid_options: Optional[list[OptionKey]] = None,
+        required_role: Optional[str] = None,
+        current_role: Optional[str] = None,
+        context_info: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize SemanticParseError.
+
+        Args:
+            error_type: Type/category of error
+            message: Error message
+            suggestions: Optional list of command suggestions for fixing the error
+            command: Command that caused the error
+            invalid_option: Invalid option key that caused the error
+            valid_options: List of valid option keys
+            required_role: Required role for command execution
+            current_role: Current user role
+            context_info: Additional context information
+        """
+        # Convert semantic suggestions to strings for base class
+        string_suggestions: Optional[list[str]] = (
+            [str(cmd) for cmd in suggestions] if suggestions else None
+        )
+        super().__init__(error_type, message, string_suggestions)
+
+        # Store semantic type information - we shadow the base class suggestions
+        # This is intentional to provide semantic type access
+        self.suggestions: list[CommandId] = suggestions or []  # type: ignore[assignment]
+        self.command = command
+        self.invalid_option = invalid_option
+        self.valid_options = valid_options or []
+        self.required_role = required_role
+        self.current_role = current_role
+        self.context_info = context_info or {}

src/cli_patterns/ui/parser/semantic_registry.py

@@ -0,0 +1,147 @@
+"""Semantic command registry using semantic types for type-safe command management.
+
+This module provides SemanticCommandRegistry, which manages command metadata
+using semantic types for enhanced type safety and better intellisense support.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from cli_patterns.core.parser_types import CommandId, FlagName, OptionKey
+
+
+@dataclass
+class CommandMetadata:
+    """Metadata for a registered command using semantic types.
+
+    Attributes:
+        description: Human-readable command description
+        category: Command category for grouping
+        aliases: List of command aliases
+        options: List of valid option keys for this command
+        flags: List of valid flag names for this command
+    """
+
+    description: str
+    category: str = "general"
+    aliases: list[CommandId] = field(default_factory=list)
+    options: list[OptionKey] = field(default_factory=list)
+    flags: list[FlagName] = field(default_factory=list)
+
+
+class SemanticCommandRegistry:
+    """Registry for managing commands with semantic type safety.
+
+    This registry stores command metadata using semantic types to provide
+    type-safe operations for command registration, lookup, and suggestions.
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty command registry."""
+        self._commands: dict[CommandId, CommandMetadata] = {}
+
+    def register_command(
+        self,
+        command: CommandId,
+        description: str,
+        category: str = "general",
+        aliases: Optional[list[CommandId]] = None,
+        options: Optional[list[OptionKey]] = None,
+        flags: Optional[list[FlagName]] = None,
+    ) -> None:
+        """Register a command with its metadata.
+
+        Args:
+            command: Semantic command ID to register
+            description: Human-readable command description
+            category: Command category for grouping
+            aliases: List of command aliases
+            options: List of valid option keys for this command
+            flags: List of valid flag names for this command
+        """
+        metadata = CommandMetadata(
+            description=description,
+            category=category,
+            aliases=aliases or [],
+            options=options or [],
+            flags=flags or [],
+        )
+        self._commands[command] = metadata
+
+    def is_registered(self, command: CommandId) -> bool:
+        """Check if a command is registered.
+
+        Args:
+            command: Semantic command ID to check
+
+        Returns:
+            True if command is registered, False otherwise
+        """
+        return command in self._commands
+
+    def get_command_metadata(self, command: CommandId) -> Optional[CommandMetadata]:
+        """Get metadata for a registered command.
+
+        Args:
+            command: Semantic command ID to get metadata for
+
+        Returns:
+            CommandMetadata if command is registered, None otherwise
+        """
+        return self._commands.get(command)
+
+    def get_suggestions(
+        self, partial: str, max_suggestions: int = 5
+    ) -> list[CommandId]:
+        """Get command suggestions for a partial input.
+
+        Args:
+            partial: Partial command string to match against
+            max_suggestions: Maximum number of suggestions to return
+
+        Returns:
+            List of matching command IDs as suggestions
+        """
+        if not partial:
+            return []
+
+        partial_lower = partial.lower()
+        exact_matches = []
+        partial_matches = []
+
+        # Separate exact prefix matches from partial matches
+        for command in self._commands:
+            command_str = str(command).lower()
+            if command_str.startswith(partial_lower):
+                exact_matches.append(command)
+            elif partial_lower in command_str:
+                partial_matches.append(command)
+
+        # Combine exact matches first, then partial matches
+        suggestions = exact_matches + partial_matches
+        return suggestions[:max_suggestions]
+
+    def get_all_commands(self) -> list[CommandId]:
+        """Get all registered commands.
+
+        Returns:
+            List of all registered command IDs
+        """
+        return list(self._commands.keys())
+
+    def get_commands_by_category(self, category: str) -> list[CommandId]:
+        """Get all commands in a specific category.
+
+        Args:
+            category: Category name to filter by
+
+        Returns:
+            List of command IDs in the specified category
+        """
+        return [
+            command
+            for command, metadata in self._commands.items()
+            if metadata.category == category
+        ]