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

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.4.dist-info → claude_mpm-3.8.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.7.4
+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
@@ -30,7 +30,6 @@ Requires-Dist: flask>=3.0.0
 Requires-Dist: flask-cors>=4.0.0
 Requires-Dist: watchdog>=3.0.0
 Requires-Dist: tree-sitter>=0.21.0
-Requires-Dist: tree-sitter-language-pack>=0.8.0
 Requires-Dist: python-socketio>=5.11.0
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: aiohttp-cors>=0.8.0
@@ -47,53 +46,48 @@ Requires-Dist: flake8; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Provides-Extra: monitor
 Provides-Extra: agents
-Requires-Dist: allure-pytest>=2.13.0; extra == "agents"
-Requires-Dist: ansible>=9.0.0; extra == "agents"
-Requires-Dist: apache-airflow>=2.8.0; extra == "agents"
 Requires-Dist: bandit>=1.7.5; extra == "agents"
 Requires-Dist: black>=23.0.0; extra == "agents"
-Requires-Dist: checkov>=3.1.0; extra == "agents"
 Requires-Dist: commitizen>=3.13.0; extra == "agents"
-Requires-Dist: cryptography>=41.0.0; extra == "agents"
 Requires-Dist: dask>=2023.12.0; extra == "agents"
 Requires-Dist: detect-secrets>=1.4.0; extra == "agents"
 Requires-Dist: diagrams>=0.23.0; extra == "agents"
-Requires-Dist: docker>=7.0.0; extra == "agents"
 Requires-Dist: docstring-parser>=0.15.0; extra == "agents"
 Requires-Dist: faker>=20.0.0; extra == "agents"
 Requires-Dist: gitlint>=0.19.0; extra == "agents"
 Requires-Dist: gitpython>=3.1.40; extra == "agents"
-Requires-Dist: great-expectations>=0.18.0; extra == "agents"
 Requires-Dist: hypothesis>=6.92.0; extra == "agents"
 Requires-Dist: isort>=5.12.0; extra == "agents"
-Requires-Dist: kubernetes>=28.0.0; extra == "agents"
 Requires-Dist: lizard>=1.17.0; extra == "agents"
 Requires-Dist: mermaid-py>=0.2.0; extra == "agents"
 Requires-Dist: mkdocs>=1.5.0; extra == "agents"
 Requires-Dist: mutmut>=2.4.0; extra == "agents"
 Requires-Dist: mypy>=1.8.0; extra == "agents"
 Requires-Dist: pandas>=2.1.0; extra == "agents"
-Requires-Dist: pip-audit>=2.6.0; extra == "agents"
 Requires-Dist: pre-commit>=3.5.0; extra == "agents"
 Requires-Dist: prometheus-client>=0.19.0; extra == "agents"
 Requires-Dist: pydoc-markdown>=4.8.0; extra == "agents"
 Requires-Dist: pydriller>=2.5.0; extra == "agents"
 Requires-Dist: pygments>=2.17.0; extra == "agents"
-Requires-Dist: pyjwt>=2.8.0; extra == "agents"
 Requires-Dist: pytest>=7.4.0; extra == "agents"
 Requires-Dist: pytest-benchmark>=4.0.0; extra == "agents"
 Requires-Dist: pytest-cov>=4.1.0; extra == "agents"
 Requires-Dist: radon>=6.0.0; extra == "agents"
 Requires-Dist: rope>=1.11.0; extra == "agents"
-Requires-Dist: safety>=3.0.0; extra == "agents"
-Requires-Dist: semgrep>=1.45.0; extra == "agents"
 Requires-Dist: sphinx>=7.2.0; extra == "agents"
 Requires-Dist: sqlalchemy>=2.0.0; extra == "agents"
 Requires-Dist: sqlparse>=0.4.4; extra == "agents"
-Requires-Dist: terraform-compliance>=1.3.0; extra == "agents"
 Requires-Dist: tree-sitter>=0.21.0; extra == "agents"
-Requires-Dist: tree-sitter-language-pack>=0.8.0; extra == "agents"
-Requires-Dist: ydata-profiling>=4.6.0; extra == "agents"
+Requires-Dist: tree-sitter-python>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-javascript>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-typescript>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-go>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-rust>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-java>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-cpp>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-c>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-ruby>=0.21.0; extra == "agents"
+Requires-Dist: tree-sitter-php>=0.21.0; extra == "agents"
 Dynamic: author-email
 Dynamic: home-page
 Dynamic: license-file
@@ -118,19 +112,21 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 ## Installation
 
 ```bash
-# Install from PyPI
+# Basic installation - pure Python, no compilation required
 pip install claude-mpm
 
 # Install with development dependencies
 pip install "claude-mpm[dev]"
 
-# Install with agent dependencies (recommended for full functionality)
+# Install with agent dependencies - pure Python tools
 pip install "claude-mpm[agents]"
 
 # Install with all optional dependencies
 pip install "claude-mpm[agents,dev]"
 ```
 
+All dependencies are pure Python - no Rust or compilation required. The `agents` dependency group includes tools for testing, code analysis, documentation, and development workflows.
+
 ## Basic Usage
 
 ```bash
@@ -164,10 +160,10 @@ For detailed usage, see [QUICKSTART.md](QUICKSTART.md)
 
 ### Agent Dependencies
 
-Claude MPM automatically manages Python dependencies required by agents. Agents can declare their dependencies in their configuration files, and the system aggregates them for easy installation.
+Claude MPM automatically manages Python dependencies required by agents. All dependencies are pure Python packages that don't require compilation. Agents can declare their dependencies in their configuration files, and the system aggregates them for easy installation.
 
 ```bash
-# Install all agent dependencies
+# Install all agent dependencies (pure Python)
 pip install "claude-mpm[agents]"
 
 # View current agent dependencies
@@ -193,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
@@ -250,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