siada-cli 0.0.1__py3-none-any.whl

siada/services/handle_at_command/README.md

@@ -0,0 +1,247 @@
+# HandleAtCommand Service
+
+A comprehensive service for processing @ commands in user queries, enabling intelligent file content injection into AI context.
+
+## Overview
+
+The HandleAtCommand service allows users to reference files using simple `@` syntax in their queries. The service automatically:
+
+1. **Parses** user input to extract @ commands
+2. **Resolves** file paths using intelligent matching
+3. **Reads** file contents using the existing ReadManyFiles tool
+4. **Injects** content into the AI context seamlessly
+
+## Features
+
+### 🎯 Core Functionality
+- **Smart Path Resolution**: Direct matching, fuzzy search, directory expansion
+- **Multiple File Support**: Handle multiple @ commands in a single query
+- **Content Injection**: Automatic file content integration into AI context
+- **Error Handling**: Graceful handling of missing or inaccessible files
+
+### 🔍 Supported @ Command Formats
+- `@filename.ext` - Single file reference
+- `@path/to/file.ext` - Relative path file reference
+- `@directory/` - Directory reference (converted to glob pattern)
+- `@my\ file.txt` - Files with spaces (escaped)
+- `请解释 @file1.js 和 @file2.py` - Mixed text and file references
+
+### 🛡️ Security Features
+- **Workspace Boundary Checking**: Ensures files are within allowed directories
+- **Path Traversal Protection**: Prevents `../` attacks
+- **Git Ignore Support**: Respects .gitignore rules
+- **File Size Limits**: Prevents reading of excessively large files
+
+## Architecture
+
+```
+HandleAtCommand/
+├── processor.py          # Main coordinator (AtCommandProcessor)
+├── parser.py            # @ command parsing (AtCommandParser)
+├── resolver.py          # Path resolution (PathResolver)
+├── models.py            # Data structures
+├── exceptions.py        # Custom exceptions
+├── utils.py            # Utility functions
+└── __init__.py         # Package interface
+```
+
+### Component Responsibilities
+
+#### AtCommandProcessor
+- **Main Entry Point**: Coordinates all components
+- **File Reading**: Integrates with ReadManyFilesTool
+- **Query Reconstruction**: Builds final processed query
+- **Statistics Tracking**: Monitors processing metrics
+
+#### AtCommandParser
+- **Input Parsing**: Extracts @ commands from user queries
+- **Escape Handling**: Processes escaped characters in paths
+- **Content Extraction**: Parses file content from tool output
+
+#### PathResolver
+- **Path Resolution**: Converts @ paths to actual file paths
+- **Security Validation**: Ensures paths are safe and within workspace
+- **Fuzzy Matching**: Provides glob-based search for partial matches
+- **Directory Handling**: Converts directories to appropriate glob patterns
+
+## Usage
+
+### Basic Usage
+
+```python
+from siada.services.handle_at_command import AtCommandProcessor, HandleAtCommandParams
+
+# Initialize processor
+processor = AtCommandProcessor(config)
+
+# Create parameters
+params = HandleAtCommandParams(
+    query="Please explain @main.py and @config.json",
+    config=config,
+    add_item=add_item_function,
+    on_debug_message=debug_function,
+    message_id=123
+)
+
+# Process @ commands
+result = await processor.handle_at_command(params)
+
+if result.should_proceed:
+    # Use result.processed_query for AI context
+    print("Processed query:", result.processed_query)
+```
+
+### Convenience Function
+
+```python
+from siada.services.handle_at_command import handle_at_command
+
+result = await handle_at_command(
+    query="Show me @file.py",
+    config=config,
+    add_item=add_item_function,
+    on_debug_message=debug_function,
+    message_id=123
+)
+```
+
+## Configuration
+
+### Required Configuration Properties
+
+```python
+class Config:
+    root_dir: str  # Root directory for file operations
+    
+    # Optional: Additional workspace directories
+    # Optional: File filtering options
+    # Optional: Enable recursive search
+```
+
+### File Filtering Options
+
+```python
+file_filtering_options = {
+    'respect_git_ignore': True,  # Respect .gitignore rules
+    # Add more filtering options as needed
+}
+```
+
+## Examples
+
+### Single File Reference
+```
+Input:  "Explain @main.py"
+Output: Query with main.py content injected
+```
+
+### Multiple Files
+```
+Input:  "Compare @file1.py and @file2.py"
+Output: Query with both files' content injected
+```
+
+### Directory Reference
+```
+Input:  "Show me @src/"
+Output: Query with all files in src/ directory
+```
+
+### Mixed Content
+```
+Input:  "The function in @utils.py needs to handle @config.json"
+Output: Query with both files' content injected
+```
+
+### Fuzzy Matching
+```
+Input:  "Check @main"
+Output: Finds and includes main.py (if it exists)
+```
+
+## Error Handling
+
+The service handles various error conditions gracefully:
+
+- **File Not Found**: Attempts fuzzy search, reports if not found
+- **Permission Denied**: Skips file, continues with others
+- **Path Outside Workspace**: Security violation, file skipped
+- **File Too Large**: Respects size limits, skips oversized files
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run parser tests
+cd tests/services/handle_at_command
+python test_parser.py
+
+# Run demo
+python demo_handle_at_command.py
+```
+
+### Test Coverage
+
+- ✅ @ Command parsing (various formats)
+- ✅ Path resolution (direct, fuzzy, directory)
+- ✅ File content injection
+- ✅ Error handling
+- ✅ Security validation
+- ✅ Integration with ReadManyFilesTool
+
+## Performance Considerations
+
+### Optimization Features
+- **Concurrent Processing**: Multiple files processed in parallel
+- **Intelligent Caching**: Avoids re-reading unchanged files
+- **Content Limits**: Respects file size and line count limits
+- **Early Exit**: Skips processing if no @ commands found
+
+### Performance Metrics
+- Processing time tracking
+- File read statistics
+- Path resolution success rates
+- Error categorization
+
+## Integration Points
+
+### Dependencies
+- **ReadManyFilesTool**: For actual file reading
+- **FileFilter**: For .gitignore and filtering support
+- **PathLib**: For cross-platform path handling
+
+### Extension Points
+- Custom path resolvers
+- Additional file type support
+- Enhanced security policies
+- Custom content formatters
+
+## Future Enhancements
+
+### Planned Features
+- **Caching Layer**: Persistent file content caching
+- **Advanced Filtering**: More sophisticated ignore rules
+- **Content Preprocessing**: Syntax highlighting, formatting
+- **Batch Operations**: Optimized multi-file processing
+- **Plugin System**: Extensible resolver and formatter plugins
+
+### Potential Improvements
+- **AI-Powered Matching**: Semantic file matching
+- **Context-Aware Resolution**: Smart path suggestions
+- **Real-time Updates**: File change monitoring
+- **Performance Analytics**: Detailed performance insights
+
+## Contributing
+
+When contributing to this service:
+
+1. **Follow Architecture**: Maintain separation of concerns
+2. **Add Tests**: Include unit tests for new functionality
+3. **Update Documentation**: Keep README and docstrings current
+4. **Security First**: Consider security implications of changes
+5. **Performance Aware**: Monitor impact on processing speed
+
+## License
+
+This service is part of the Siada project and follows the project's licensing terms.

siada/services/handle_at_command/__init__.py

@@ -0,0 +1,115 @@
+"""
+HandleAtCommand - A service for processing @ commands in user queries.
+
+This package provides functionality to parse user input containing @ commands,
+resolve file paths, read file contents, and inject them into AI context.
+
+Main Components:
+- AtCommandProcessor: Main processor that coordinates all components
+- AtCommandParser: Parses @ commands from user input
+- PathResolver: Resolves @ paths to actual file paths
+- Models: Data structures and type definitions
+- Exceptions: Custom exception classes
+- Utils: Utility functions
+
+Usage:
+    from siada.services.handle_at_command import AtCommandProcessor, HandleAtCommandParams
+    
+    processor = AtCommandProcessor(config)
+    params = HandleAtCommandParams(
+        query="Please explain @file.py",
+        config=config,
+        add_item=add_item_func,
+        on_debug_message=debug_func,
+        message_id=123
+    )
+    result = await processor.handle_at_command(params)
+"""
+
+from .processor import AtCommandProcessor
+from .parser import AtCommandParser
+from .resolver import PathResolver
+from .models import (
+    AtCommandPart,
+    HandleAtCommandParams,
+    HandleAtCommandResult,
+    ResolverContext,
+    PathResolutionResult,
+    ProcessingStats,
+    IgnoredFileStats
+)
+from .exceptions import (
+    AtCommandError,
+    PathNotFoundError,
+    PathIgnoredError,
+    FileTooLargeError,
+    PermissionDeniedError,
+    SecurityViolationError,
+    InvalidPathError,
+    WorkspaceSecurityError
+)
+from . import utils
+
+__all__ = [
+    # Main classes
+    'AtCommandProcessor',
+    'AtCommandParser',
+    'PathResolver',
+    
+    # Data models
+    'AtCommandPart',
+    'HandleAtCommandParams',
+    'HandleAtCommandResult',
+    'ResolverContext',
+    'PathResolutionResult',
+    'ProcessingStats',
+    'IgnoredFileStats',
+    
+    # Exceptions
+    'AtCommandError',
+    'PathNotFoundError',
+    'PathIgnoredError',
+    'FileTooLargeError',
+    'PermissionDeniedError',
+    'SecurityViolationError',
+    'InvalidPathError',
+    'WorkspaceSecurityError',
+    
+    # Utilities
+    'utils'
+]
+
+# Version information
+__version__ = '1.0.0'
+__author__ = 'Siada Team'
+__description__ = 'A service for processing @ commands in user queries'
+
+
+# Convenience function for easy usage
+async def handle_at_command(query: str, config, add_item: callable, 
+                           on_debug_message: callable, message_id: int, 
+                           signal=None) -> HandleAtCommandResult:
+    """
+    Convenience function to handle @ commands
+    
+    Args:
+        query: User input query
+        config: Configuration object
+        add_item: Function to add items to history
+        on_debug_message: Debug message callback
+        message_id: Message ID
+        signal: Cancellation signal (optional)
+        
+    Returns:
+        HandleAtCommandResult with processed query and status
+    """
+    processor = AtCommandProcessor(config)
+    params = HandleAtCommandParams(
+        query=query,
+        config=config,
+        add_item=add_item,
+        on_debug_message=on_debug_message,
+        message_id=message_id,
+        signal=signal
+    )
+    return await processor.handle_at_command(params)

siada/services/handle_at_command/exceptions.py

@@ -0,0 +1,46 @@
+"""
+Custom exceptions for HandleAtCommand functionality.
+"""
+
+
+class AtCommandError(Exception):
+    """Base class for @ command processing errors"""
+    
+    def __init__(self, message: str, file_path: str = None):
+        super().__init__(message)
+        self.file_path = file_path
+
+
+class PathNotFoundError(AtCommandError):
+    """Raised when a path cannot be found"""
+    pass
+
+
+class PathIgnoredError(AtCommandError):
+    """Raised when a path is ignored by filtering rules"""
+    pass
+
+
+class FileTooLargeError(AtCommandError):
+    """Raised when a file exceeds size limits"""
+    pass
+
+
+class PermissionDeniedError(AtCommandError):
+    """Raised when access to a file is denied"""
+    pass
+
+
+class SecurityViolationError(AtCommandError):
+    """Raised when a security violation is detected (e.g., path traversal)"""
+    pass
+
+
+class InvalidPathError(AtCommandError):
+    """Raised when a path is invalid or malformed"""
+    pass
+
+
+class WorkspaceSecurityError(AtCommandError):
+    """Raised when a path is outside the workspace boundaries"""
+    pass

siada/services/handle_at_command/models.py

@@ -0,0 +1,92 @@
+"""
+HandleAtCommand data models and structures.
+"""
+
+from dataclasses import dataclass
+from typing import List, Dict, Optional, Union, Any, Literal
+
+
+@dataclass
+class AtCommandPart:
+    """Represents a part of the parsed @ command query"""
+    type: Literal['text', 'atPath']  # Part type
+    content: str                     # Content
+
+
+@dataclass
+class HandleAtCommandParams:
+    """Input parameters for handleAtCommand function"""
+    query: str                       # User's original query
+    config: Any                      # Configuration object
+    add_item: callable              # History addition function
+    on_debug_message: callable      # Debug message callback
+    message_id: int                 # Message ID
+    signal: Optional[Any] = None    # Cancellation signal
+
+
+@dataclass
+class HandleAtCommandResult:
+    """Output result from handleAtCommand function"""
+    processed_query: Optional[List[Dict]]  # Processed query parts
+    should_proceed: bool                   # Whether to continue processing
+
+
+@dataclass
+class ResolverContext:
+    """Context for path resolution"""
+    workspace_directories: List[str]
+    target_directory: str
+    enable_recursive_search: bool = True
+    file_filtering_options: Optional[Dict[str, bool]] = None
+    
+    def __post_init__(self):
+        if self.file_filtering_options is None:
+            self.file_filtering_options = {
+                'respect_git_ignore': True
+            }
+
+
+@dataclass
+class PathResolutionResult:
+    """Result of path resolution"""
+    resolved_path: Optional[str]
+    original_path: str
+    resolution_type: Literal['direct', 'glob', 'directory', 'not_found']
+    reason: Optional[str] = None
+
+
+@dataclass
+class ProcessingStats:
+    """Statistics for @ command processing"""
+    total_at_commands: int = 0
+    resolved_paths: int = 0
+    failed_paths: int = 0
+    ignored_paths: int = 0
+    files_read: int = 0
+    processing_time: float = 0.0
+    
+    
+@dataclass
+class IgnoredFileStats:
+    """Statistics for ignored files"""
+    git_ignored: List[str]
+    gemini_ignored: List[str]
+    both_ignored: List[str]
+    
+    def __init__(self):
+        self.git_ignored = []
+        self.gemini_ignored = []
+        self.both_ignored = []
+    
+    def add_ignored_file(self, file_path: str, reason: Literal['git', 'gemini', 'both']):
+        """Add a file to the ignored list"""
+        if reason == 'git':
+            self.git_ignored.append(file_path)
+        elif reason == 'gemini':
+            self.gemini_ignored.append(file_path)
+        elif reason == 'both':
+            self.both_ignored.append(file_path)
+    
+    def get_total_ignored(self) -> int:
+        """Get total number of ignored files"""
+        return len(self.git_ignored) + len(self.gemini_ignored) + len(self.both_ignored)

siada/services/handle_at_command/parser.py

@@ -0,0 +1,189 @@
+"""
+@ Command Parser - Parses user input to extract @ commands.
+"""
+
+import re
+from typing import List
+
+from .models import AtCommandPart
+from .exceptions import InvalidPathError
+
+
+class AtCommandParser:
+    """Parser for @ commands in user queries"""
+    
+    def __init__(self):
+        # Regex pattern to match file content format from read_many_files
+        self.file_content_regex = re.compile(r'^--- (.*?) ---\n\n([\s\S]*?)\n\n$')
+    
+    def parse_all_at_commands(self, query: str) -> List[AtCommandPart]:
+        """
+        Parse all @ commands from the query string
+        
+        Args:
+            query: User input query string
+            
+        Returns:
+            List of AtCommandPart objects representing parsed parts
+        """
+        if not query:
+            return []
+        
+        parts = []
+        current_index = 0
+        
+        while current_index < len(query):
+            # Find next unescaped '@'
+            at_index = self._find_next_unescaped_at(query, current_index)
+            
+            if at_index == -1:
+                # No more '@' symbols, add remaining text
+                if current_index < len(query):
+                    remaining_text = query[current_index:]
+                    if remaining_text.strip():  # Only add non-empty text
+                        parts.append(AtCommandPart('text', remaining_text))
+                break
+            
+            # Add text before '@' if any
+            if at_index > current_index:
+                text_before = query[current_index:at_index]
+                if text_before.strip():  # Only add non-empty text
+                    parts.append(AtCommandPart('text', text_before))
+            
+            # Parse '@path'
+            path_end_index = self._find_path_end(query, at_index + 1)
+            raw_at_path = query[at_index:path_end_index]
+            
+            # Handle lone '@' symbol
+            if raw_at_path == '@':
+                parts.append(AtCommandPart('text', '@'))
+            else:
+                at_path = self._unescape_path(raw_at_path)
+                parts.append(AtCommandPart('atPath', at_path))
+            
+            current_index = path_end_index
+        
+        # Filter out empty text parts
+        return [p for p in parts if not (p.type == 'text' and not p.content.strip())]
+    
+    def _find_next_unescaped_at(self, query: str, start_index: int) -> int:
+        """
+        Find the next unescaped '@' symbol
+        
+        Args:
+            query: Query string
+            start_index: Starting index for search
+            
+        Returns:
+            Index of next unescaped '@', or -1 if not found
+        """
+        index = start_index
+        while index < len(query):
+            if query[index] == '@':
+                # Check if it's escaped (preceded by backslash)
+                if index == 0 or query[index - 1] != '\\':
+                    return index
+            index += 1
+        return -1
+    
+    def _find_path_end(self, query: str, start_index: int) -> int:
+        """
+        Find the end of the path, handling escape characters
+        
+        Args:
+            query: Query string
+            start_index: Starting index (after '@')
+            
+        Returns:
+            Index where the path ends
+        """
+        index = start_index
+        in_escape = False
+        
+        while index < len(query):
+            char = query[index]
+            
+            if in_escape:
+                # Previous character was escape, skip this character
+                in_escape = False
+            elif char == '\\':
+                # This is an escape character
+                in_escape = True
+            elif char.isspace():
+                # Unescaped whitespace marks end of path
+                break
+            
+            index += 1
+        
+        return index
+    
+    def _unescape_path(self, path: str) -> str:
+        """
+        Process escape characters in the path
+        
+        Args:
+            path: Raw path string with potential escape characters
+            
+        Returns:
+            Unescaped path string
+        """
+        if not path:
+            return path
+        
+        # Handle escaped spaces and other characters
+        result = []
+        i = 0
+        while i < len(path):
+            if path[i] == '\\' and i + 1 < len(path):
+                # Escape sequence - add the next character literally
+                result.append(path[i + 1])
+                i += 2
+            else:
+                result.append(path[i])
+                i += 1
+        
+        return ''.join(result)
+    
+    def validate_at_path(self, at_path: str) -> bool:
+        """
+        Validate that an @ path is well-formed
+        
+        Args:
+            at_path: @ path string (including '@' prefix)
+            
+        Returns:
+            True if valid, False otherwise
+        """
+        if not at_path or not at_path.startswith('@'):
+            return False
+        
+        path_part = at_path[1:]  # Remove '@' prefix
+        
+        # Empty path after '@' is invalid (except lone '@')
+        if not path_part and at_path != '@':
+            return False
+        
+        # Check for invalid characters
+        invalid_chars = ['<', '>', '|', '"', '*', '?']
+        for char in invalid_chars:
+            if char in path_part:
+                return False
+        
+        return True
+    
+    def extract_file_content_info(self, content_part: str) -> tuple[str, str]:
+        """
+        Extract file path and content from formatted file content
+        
+        Args:
+            content_part: Formatted content from read_many_files tool
+            
+        Returns:
+            Tuple of (file_path, content) or (None, content) if not matched
+        """
+        match = self.file_content_regex.match(content_part)
+        if match:
+            file_path = match.group(1)
+            content = match.group(2).strip()
+            return file_path, content
+        return None, content_part