claude-mpm 3.7.8__py3-none-any.whl → 3.8.1__py3-none-any.whl

claude_mpm/services/ticket_manager.py

@@ -4,13 +4,12 @@ from pathlib import Path
 from typing import Optional, Dict, Any, List
 from datetime import datetime
 
-try:
-    from ..core.logger import get_logger
-except ImportError:
-    from core.logger import get_logger
+from claude_mpm.core.logging_config import get_logger
 
+from ..core.interfaces import TicketManagerInterface
 
-class TicketManager:
+
+class TicketManager(TicketManagerInterface):
     """
     Manage ticket creation using ai-trackdown-pytools.
     
@@ -25,7 +24,7 @@ class TicketManager:
         Args:
             project_path: Project root (defaults to current directory)
         """
-        self.logger = get_logger("ticket_manager")
+        self.logger = get_logger(__name__)
         self.project_path = project_path or Path.cwd()
         self.task_manager = self._init_task_manager()
         
@@ -373,4 +372,168 @@ class TicketManager:
             self.logger.error(f"Failed to get ticket {ticket_id}: {e.__class__.__name__}: {e}")
             self.logger.info(f"Try using the CLI: aitrackdown show {ticket_id}")
             self.logger.debug("Full error details:", exc_info=True)
-            return None
+            return None
+    
+    # ================================================================================
+    # Interface Adapter Methods
+    # ================================================================================
+    # These methods adapt the existing implementation to comply with TicketManagerInterface
+    
+    def create_task(self, title: str, description: str, **kwargs) -> Optional[str]:
+        """Create a new task ticket.
+        
+        WHY: This adapter method provides interface compliance by wrapping
+        the underlying task manager's create functionality.
+        
+        Args:
+            title: Task title
+            description: Task description
+            **kwargs: Additional task properties
+            
+        Returns:
+            Task ID if created successfully, None otherwise
+        """
+        if not self.task_manager:
+            self.logger.error("Task manager not initialized")
+            return None
+        
+        try:
+            # Create task using ai-trackdown-pytools
+            from ai_trackdown_pytools.core.task import Task
+            
+            task = Task(
+                title=title,
+                description=description,
+                status=kwargs.get('status', 'open'),
+                priority=kwargs.get('priority', 'medium'),
+                tags=kwargs.get('tags', []),
+                assignees=kwargs.get('assignees', [])
+            )
+            
+            # Save the task
+            task_id = self.task_manager.create_task(task)
+            self.logger.info(f"Created task {task_id}: {title}")
+            return task_id
+            
+        except ImportError:
+            self.logger.error("ai-trackdown-pytools not available")
+            return None
+        except Exception as e:
+            self.logger.error(f"Failed to create task: {e}")
+            return None
+    
+    def update_task(self, task_id: str, **updates) -> bool:
+        """Update an existing task.
+        
+        WHY: This adapter method provides interface compliance by wrapping
+        task update operations.
+        
+        Args:
+            task_id: ID of task to update
+            **updates: Fields to update
+            
+        Returns:
+            True if update successful
+        """
+        if not self.task_manager:
+            self.logger.error("Task manager not initialized")
+            return False
+        
+        try:
+            # Get the existing task
+            task = self.task_manager.get_task(task_id)
+            if not task:
+                self.logger.error(f"Task {task_id} not found")
+                return False
+            
+            # Apply updates
+            for key, value in updates.items():
+                if hasattr(task, key):
+                    setattr(task, key, value)
+            
+            # Save the updated task
+            self.task_manager.update_task(task)
+            self.logger.info(f"Updated task {task_id}")
+            return True
+            
+        except Exception as e:
+            self.logger.error(f"Failed to update task {task_id}: {e}")
+            return False
+    
+    def get_task(self, task_id: str) -> Optional[Dict[str, Any]]:
+        """Get task details.
+        
+        WHY: This adapter method provides interface compliance by wrapping
+        the existing get_ticket method.
+        
+        Args:
+            task_id: ID of task to retrieve
+            
+        Returns:
+            Task data dictionary or None if not found
+        """
+        # Use existing get_ticket method which already returns dict format
+        return self.get_ticket(task_id)
+    
+    def list_tasks(self, status: Optional[str] = None, **filters) -> List[Dict[str, Any]]:
+        """List tasks with optional filtering.
+        
+        WHY: This adapter method provides interface compliance by wrapping
+        task listing operations.
+        
+        Args:
+            status: Optional status filter
+            **filters: Additional filter criteria
+            
+        Returns:
+            List of task dictionaries
+        """
+        if not self.task_manager:
+            self.logger.error("Task manager not initialized")
+            return []
+        
+        try:
+            # Get all tasks
+            tasks = self.task_manager.list_tasks()
+            
+            # Apply filters
+            filtered_tasks = []
+            for task in tasks:
+                # Check status filter
+                if status and task.get('status') != status:
+                    continue
+                
+                # Check additional filters
+                match = True
+                for key, value in filters.items():
+                    if task.get(key) != value:
+                        match = False
+                        break
+                
+                if match:
+                    filtered_tasks.append(task)
+            
+            return filtered_tasks
+            
+        except Exception as e:
+            self.logger.error(f"Failed to list tasks: {e}")
+            return []
+    
+    def close_task(self, task_id: str, resolution: Optional[str] = None) -> bool:
+        """Close a task.
+        
+        WHY: This adapter method provides interface compliance by updating
+        task status to closed.
+        
+        Args:
+            task_id: ID of task to close
+            resolution: Optional resolution description
+            
+        Returns:
+            True if close successful
+        """
+        updates = {'status': 'closed'}
+        if resolution:
+            updates['resolution'] = resolution
+        
+        return self.update_task(task_id, **updates)

claude_mpm/utils/error_handler.py

@@ -6,7 +6,7 @@ Inspired by awesome-claude-code's comprehensive error handling approach.
 
 import logging
 import sys
-from typing import Optional, Type, Callable, Any, Dict
+from typing import Optional, Type, Callable, Any, Dict, List
 from functools import wraps
 import traceback
 from datetime import datetime

claude_mpm/validation/agent_validator.py

@@ -28,6 +28,14 @@ from datetime import datetime
 import jsonschema
 from jsonschema import validate, ValidationError, Draft7Validator
 from claude_mpm.config.paths import paths
+from claude_mpm.core.constants import (
+    SystemLimits,
+    ResourceLimits,
+    TimeoutConfig,
+    ComplexityMetrics,
+    ErrorMessages,
+    ValidationRules
+)
 
 logger = logging.getLogger(__name__)
 
@@ -198,8 +206,11 @@ class AgentValidator:
         # SECURITY: Validate instruction length to prevent memory exhaustion
         # Double-check even though schema enforces this - defense in depth
         instructions = agent_data.get("instructions", "")
-        if len(instructions) > 8000:
-            result.errors.append(f"Instructions exceed 8000 character limit: {len(instructions)} characters")
+        if len(instructions) > SystemLimits.MAX_INSTRUCTION_LENGTH:
+            result.errors.append(ErrorMessages.INSTRUCTION_TOO_LONG.format(
+                limit=SystemLimits.MAX_INSTRUCTION_LENGTH,
+                actual=len(instructions)
+            ))
             result.is_valid = False
         
         # Validate model compatibility with tools
@@ -237,19 +248,19 @@ class AgentValidator:
         """
         tier_limits = {
             "intensive": {
-                "memory_limit": (4096, 8192),
-                "cpu_limit": (60, 100),
-                "timeout": (600, 3600)
+                "memory_limit": ResourceLimits.INTENSIVE_MEMORY_RANGE,
+                "cpu_limit": ResourceLimits.INTENSIVE_CPU_RANGE,
+                "timeout": TimeoutConfig.INTENSIVE_TIMEOUT_RANGE
             },
             "standard": {
-                "memory_limit": (2048, 4096),
-                "cpu_limit": (30, 60),
-                "timeout": (300, 1200)
+                "memory_limit": ResourceLimits.STANDARD_MEMORY_RANGE,
+                "cpu_limit": ResourceLimits.STANDARD_CPU_RANGE,
+                "timeout": TimeoutConfig.STANDARD_TIMEOUT_RANGE
             },
             "lightweight": {
-                "memory_limit": (512, 2048),
-                "cpu_limit": (10, 30),
-                "timeout": (30, 600)
+                "memory_limit": ResourceLimits.LIGHTWEIGHT_MEMORY_RANGE,
+                "cpu_limit": ResourceLimits.LIGHTWEIGHT_CPU_RANGE,
+                "timeout": TimeoutConfig.LIGHTWEIGHT_TIMEOUT_RANGE
             }
         }
         
@@ -345,9 +356,11 @@ class AgentValidator:
             
             # SECURITY: Check file size to prevent memory exhaustion
             file_size = file_path.stat().st_size
-            max_size = 1024 * 1024  # 1MB limit for agent configs
+            max_size = SystemLimits.MAX_AGENT_CONFIG_SIZE
             if file_size > max_size:
-                raise ValueError(f"File too large: {file_size} bytes (max {max_size} bytes)")
+                raise ValueError(ErrorMessages.FILE_TOO_LARGE.format(
+                    limit=max_size
+                ))
             with open(file_path, 'r') as f:
                 agent_data = json.load(f)
             
@@ -381,7 +394,7 @@ class AgentValidator:
             raise ValueError(f"Path is not a directory: {directory}")
         
         # SECURITY: Limit number of files to prevent DoS
-        max_files = 100
+        max_files = SystemLimits.MAX_FILES_TO_VALIDATE
         file_count = 0
         
         for json_file in directory.glob("*.json"):

claude_mpm/validation/frontmatter_validator.py

@@ -0,0 +1,231 @@
+"""
+Claude Code Frontmatter Validator
+
+Validates agent frontmatter against Claude Code Desktop specification.
+Critical for ensuring agents work correctly with Claude Desktop.
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+import yaml
+
+
+class FrontmatterValidator:
+    """Validates agent frontmatter against Claude Code specification."""
+    
+    # Claude Code name pattern: lowercase letters, numbers, hyphens only
+    # NO UNDERSCORES, NO UPPERCASE, NO SPECIAL CHARACTERS
+    NAME_PATTERN = re.compile(r'^[a-z0-9]+(-[a-z0-9]+)*$')
+    
+    # Valid tool names (from Claude Code spec)
+    VALID_TOOLS = {
+        'Read', 'Write', 'Edit', 'MultiEdit', 'Bash', 'Grep', 'Glob', 'LS',
+        'WebSearch', 'WebFetch', 'TodoWrite', 'BashOutput', 'KillBash',
+        'NotebookEdit', 'Task', 'ExitPlanMode'
+    }
+    
+    # Valid model tiers
+    VALID_MODELS = {'opus', 'sonnet', 'haiku'}
+    
+    # Required fields in frontmatter
+    REQUIRED_FIELDS = {'name', 'description', 'tools'}
+    
+    @classmethod
+    def validate_name(cls, name: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate agent name field against Claude Code spec.
+        
+        Args:
+            name: Agent name to validate
+            
+        Returns:
+            (is_valid, error_message)
+        """
+        if not name:
+            return False, "Name field is required"
+        
+        if not cls.NAME_PATTERN.match(name):
+            return False, (
+                f"Invalid name '{name}'. Must match pattern ^[a-z0-9]+(-[a-z0-9]+)*$ "
+                "(lowercase letters, numbers, and hyphens only - NO underscores!)"
+            )
+        
+        if len(name) > 50:
+            return False, f"Name '{name}' too long (max 50 characters)"
+        
+        return True, None
+    
+    @classmethod
+    def validate_tools(cls, tools: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate tools field format and content.
+        
+        CRITICAL: Tools must be comma-separated WITHOUT spaces!
+        
+        Args:
+            tools: Tools string to validate
+            
+        Returns:
+            (is_valid, error_message)
+        """
+        if not tools:
+            return False, "Tools field is required"
+        
+        # Check for spaces after commas (CRITICAL ERROR)
+        if ', ' in tools:
+            return False, (
+                f"CRITICAL: Tools contain spaces after commas! '{tools}' "
+                "Must be comma-separated WITHOUT spaces (e.g., 'Read,Write,Edit')"
+            )
+        
+        # Validate individual tools
+        tool_list = tools.split(',')
+        invalid_tools = [t for t in tool_list if t not in cls.VALID_TOOLS]
+        
+        if invalid_tools:
+            return False, f"Invalid tools: {', '.join(invalid_tools)}. Valid tools: {', '.join(sorted(cls.VALID_TOOLS))}"
+        
+        return True, None
+    
+    @classmethod
+    def validate_model(cls, model: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate model field.
+        
+        Args:
+            model: Model tier to validate
+            
+        Returns:
+            (is_valid, error_message)
+        """
+        if model and model not in cls.VALID_MODELS:
+            return False, f"Invalid model '{model}'. Must be one of: {', '.join(cls.VALID_MODELS)}"
+        
+        return True, None
+    
+    @classmethod
+    def validate_frontmatter(cls, frontmatter: Dict) -> List[str]:
+        """
+        Validate complete frontmatter structure.
+        
+        Args:
+            frontmatter: Parsed frontmatter dictionary
+            
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+        
+        # Check required fields
+        missing = cls.REQUIRED_FIELDS - set(frontmatter.keys())
+        if missing:
+            errors.append(f"Missing required fields: {', '.join(missing)}")
+        
+        # Validate name
+        if 'name' in frontmatter:
+            valid, error = cls.validate_name(frontmatter['name'])
+            if not valid:
+                errors.append(error)
+        
+        # Validate tools
+        if 'tools' in frontmatter:
+            valid, error = cls.validate_tools(frontmatter['tools'])
+            if not valid:
+                errors.append(error)
+        
+        # Validate model
+        if 'model' in frontmatter:
+            valid, error = cls.validate_model(frontmatter['model'])
+            if not valid:
+                errors.append(error)
+        
+        # Validate description
+        if 'description' in frontmatter:
+            desc = frontmatter['description']
+            if len(desc) < 10:
+                errors.append(f"Description too short ({len(desc)} chars, min 10)")
+            if len(desc) > 200:
+                errors.append(f"Description too long ({len(desc)} chars, max 200)")
+        
+        return errors
+    
+    @classmethod
+    def validate_agent_file(cls, file_path: Path) -> List[str]:
+        """
+        Validate an agent markdown file.
+        
+        Args:
+            file_path: Path to agent .md file
+            
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+        
+        try:
+            with open(file_path, 'r') as f:
+                content = f.read()
+            
+            # Check for frontmatter markers
+            if not content.startswith('---\n'):
+                errors.append("File must start with '---' frontmatter marker")
+                return errors
+            
+            # Extract frontmatter
+            end_marker = content.find('\n---\n', 4)
+            if end_marker == -1:
+                errors.append("Missing closing '---' frontmatter marker")
+                return errors
+            
+            frontmatter_text = content[4:end_marker]
+            
+            # Parse YAML
+            try:
+                frontmatter = yaml.safe_load(frontmatter_text)
+            except yaml.YAMLError as e:
+                errors.append(f"Invalid YAML in frontmatter: {e}")
+                return errors
+            
+            # Validate frontmatter content
+            validation_errors = cls.validate_frontmatter(frontmatter)
+            errors.extend(validation_errors)
+            
+        except Exception as e:
+            errors.append(f"Error reading file: {e}")
+        
+        return errors
+
+
+def main():
+    """Command-line validation tool."""
+    import sys
+    
+    if len(sys.argv) < 2:
+        print("Usage: python frontmatter_validator.py <agent.md> [agent2.md ...]")
+        sys.exit(1)
+    
+    all_valid = True
+    
+    for file_path in sys.argv[1:]:
+        path = Path(file_path)
+        if not path.exists():
+            print(f"❌ {file_path}: File not found")
+            all_valid = False
+            continue
+        
+        errors = FrontmatterValidator.validate_agent_file(path)
+        
+        if errors:
+            print(f"❌ {file_path}:")
+            for error in errors:
+                print(f"   - {error}")
+            all_valid = False
+        else:
+            print(f"✅ {file_path}: Valid")
+    
+    sys.exit(0 if all_valid else 1)
+
+
+if __name__ == "__main__":
+    main()

{claude_mpm-3.7.8.dist-info → claude_mpm-3.8.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.7.8
+Version: 3.8.1
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -189,6 +189,26 @@ Dependencies are automatically aggregated from all agent sources (PROJECT > USER
 
 For comprehensive documentation, see [docs/AGENT_DEPENDENCIES.md](docs/AGENT_DEPENDENCIES.md).
 
+## Architecture
+
+Claude MPM v3.7.8+ features a **modern service-oriented architecture** with:
+
+### Service Layer Organization
+- **Core Services**: Foundation interfaces and dependency injection
+- **Agent Services**: Agent lifecycle, deployment, and management
+- **Communication Services**: Real-time WebSocket and SocketIO
+- **Project Services**: Project analysis and workspace management
+- **Infrastructure Services**: Logging, monitoring, and error handling
+
+### Key Architectural Features
+- **Interface-Based Design**: All services implement well-defined contracts
+- **Dependency Injection**: Loose coupling through service container
+- **Lazy Loading**: Performance optimization with deferred initialization
+- **Multi-Level Caching**: Intelligent caching with TTL and invalidation
+- **Security Framework**: Input validation, path sanitization, and secure operations
+
+For detailed architecture information, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
 ## Key Capabilities
 
 ### Multi-Agent Orchestration
@@ -246,31 +266,48 @@ See [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.m
 
 ## Documentation
 
+### User Documentation
 - **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
 - **[Agent Memory System](docs/MEMORY.md)** - Comprehensive memory documentation
 - **[Monitoring Dashboard](docs/developer/11-dashboard/README.md)** - Real-time monitoring features
-- **[Project Structure](docs/STRUCTURE.md)** - Codebase organization
-- **[Deployment Guide](docs/DEPLOY.md)** - Publishing and versioning
 - **[User Guide](docs/user/)** - Detailed usage documentation
-- **[Developer Guide](docs/developer/)** - Architecture and API reference
-
-## Recent Updates (v3.4.27)
-
-### Core System Enhancements
-- **Project Structure Reorganization**: Centralized path management with ClaudeMPMPaths enum
-- **Agent Services Hierarchy**: Reorganized agent and memory services into hierarchical structures  
-- **Response Logging Improvements**: Flat structure logging without session_ prefix
-- **Memory System Expansion**: Added data_engineer and test_integration agents with specialized keywords
-- **Path Management System**: Implemented centralized configuration path handling
 
-### Project Cleanup & Organization
-- **Test File Migration**: Moved 66 test files from scripts/ to tests/ directory
-- **Documentation Archives**: Archived 35+ QA reports to docs/archive/
-- **Obsolete Directory Removal**: Cleaned up orchestration, docker, security, and terminal_wrapper directories
-- **Agent Registry Caching**: Enhanced performance with intelligent caching mechanisms
-- **Improved TodoWrite Integration**: Enhanced agent prefix guidelines across all agent templates
-
-See [CHANGELOG.md](CHANGELOG.md) for full history.
+### Developer Documentation
+- **[Architecture Overview](docs/ARCHITECTURE.md)** - Service-oriented architecture and design
+- **[Service Layer Guide](docs/developer/SERVICES.md)** - Service interfaces and implementations
+- **[Performance Guide](docs/PERFORMANCE.md)** - Optimization and caching strategies
+- **[Security Guide](docs/SECURITY.md)** - Security framework and best practices
+- **[Testing Guide](docs/TESTING.md)** - Testing patterns and strategies
+- **[Migration Guide](docs/MIGRATION.md)** - Upgrading from previous versions
+- **[Project Structure](docs/STRUCTURE.md)** - Codebase organization
+- **[Deployment Guide](docs/DEPLOY.md)** - Publishing and versioning
+- **[Developer Guide](docs/developer/)** - API reference and internals
+
+## Recent Updates (v3.7.8)
+
+### TSK-0053: Service Layer Architecture Refactoring
+- **Service-Oriented Architecture**: Complete redesign with five service domains
+- **Interface-Based Contracts**: All services implement explicit interfaces
+- **Dependency Injection System**: Service container with automatic dependency resolution
+- **Performance Optimizations**: Lazy loading, multi-level caching, connection pooling
+- **Security Framework**: Input validation, path traversal prevention, secure operations
+- **Backward Compatibility**: Lazy imports maintain existing import paths
+
+### Key Improvements
+- **50-80% Performance Improvement**: Optimized caching and lazy loading
+- **Enhanced Security**: Comprehensive input validation and sanitization
+- **Better Testability**: Interface-based architecture enables easy mocking
+- **Improved Maintainability**: Clear separation of concerns and service boundaries
+- **Developer Experience**: Rich documentation and migration guides
+
+### Architecture Benefits
+- **Scalability**: Service-oriented design supports future growth
+- **Extensibility**: Plugin architecture through interfaces and hooks
+- **Reliability**: Comprehensive testing with 85%+ coverage
+- **Security**: Defense-in-depth security architecture
+- **Performance**: Intelligent caching and resource optimization
+
+See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
 
 ## Development