claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/services/agents/deployment/validation/agent_validator.py

@@ -0,0 +1,323 @@
+"""Agent validator for deployed agent files."""
+
+import re
+from pathlib import Path
+from typing import Any, Dict
+
+import yaml
+
+from claude_mpm.core.logger import get_logger
+
+from .validation_result import ValidationResult
+
+
+class AgentValidator:
+    """Validator for deployed agent markdown files.
+
+    This validator checks deployed agent .md files for:
+    - Valid YAML frontmatter
+    - Required frontmatter fields
+    - Proper markdown structure
+    - Content validation
+    """
+
+    def __init__(self):
+        """Initialize the agent validator."""
+        self.logger = get_logger(__name__)
+
+        # Required frontmatter fields
+        self.required_frontmatter_fields = {
+            "name": str,
+            "description": str,
+            "author": str,
+            "version": str,
+            "model": str,
+            "tools": list,
+        }
+
+    def validate_agent_file(self, agent_file: Path) -> ValidationResult:
+        """Validate a deployed agent file.
+
+        Args:
+            agent_file: Path to agent markdown file
+
+        Returns:
+            ValidationResult with validation outcome
+        """
+        result = ValidationResult(is_valid=True)
+
+        # Check if file exists
+        if not agent_file.exists():
+            result.add_error(f"Agent file does not exist: {agent_file}")
+            return result
+
+        # Check if it's a file
+        if not agent_file.is_file():
+            result.add_error(f"Agent path is not a file: {agent_file}")
+            return result
+
+        try:
+            # Read file content
+            content = agent_file.read_text(encoding="utf-8")
+
+            # Validate frontmatter
+            frontmatter_result = self._validate_frontmatter(content)
+            result = result.merge(frontmatter_result)
+
+            # Validate markdown structure
+            markdown_result = self._validate_markdown_structure(content)
+            result = result.merge(markdown_result)
+
+            # Add metadata
+            result.metadata["agent_file"] = str(agent_file)
+            result.metadata["agent_name"] = agent_file.stem
+
+        except UnicodeDecodeError as e:
+            result.add_error(f"File encoding error: {e}")
+        except Exception as e:
+            result.add_error(f"Unexpected error reading agent file: {e}")
+
+        return result
+
+    def _validate_frontmatter(self, content: str) -> ValidationResult:
+        """Validate YAML frontmatter in agent file.
+
+        Args:
+            content: File content
+
+        Returns:
+            ValidationResult for frontmatter validation
+        """
+        result = ValidationResult(is_valid=True)
+
+        # Check if content starts with frontmatter
+        if not content.startswith("---"):
+            result.add_error("Agent file must start with YAML frontmatter (---)")
+            return result
+
+        # Extract frontmatter
+        frontmatter_match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+        if not frontmatter_match:
+            result.add_error("Invalid frontmatter format - missing closing ---")
+            return result
+
+        frontmatter_content = frontmatter_match.group(1)
+
+        try:
+            # Parse YAML
+            frontmatter_data = yaml.safe_load(frontmatter_content)
+
+            if not isinstance(frontmatter_data, dict):
+                result.add_error("Frontmatter must be a YAML dictionary")
+                return result
+
+            # Validate required fields
+            self._validate_frontmatter_fields(frontmatter_data, result)
+
+            # Validate specific field values
+            self._validate_frontmatter_values(frontmatter_data, result)
+
+        except yaml.YAMLError as e:
+            result.add_error(f"Invalid YAML in frontmatter: {e}")
+
+        return result
+
+    def _validate_frontmatter_fields(
+        self, frontmatter: Dict[str, Any], result: ValidationResult
+    ) -> None:
+        """Validate frontmatter fields.
+
+        Args:
+            frontmatter: Frontmatter dictionary
+            result: ValidationResult to update
+        """
+        for field, expected_type in self.required_frontmatter_fields.items():
+            if field not in frontmatter:
+                result.add_error(f"Missing required frontmatter field: {field}")
+            else:
+                value = frontmatter[field]
+                if not isinstance(value, expected_type):
+                    result.add_error(
+                        f"Frontmatter field '{field}' should be {expected_type.__name__}, got {type(value).__name__}",
+                        field_name=field,
+                    )
+
+    def _validate_frontmatter_values(
+        self, frontmatter: Dict[str, Any], result: ValidationResult
+    ) -> None:
+        """Validate frontmatter field values.
+
+        Args:
+            frontmatter: Frontmatter dictionary
+            result: ValidationResult to update
+        """
+        # Validate name
+        if "name" in frontmatter:
+            name = frontmatter["name"]
+            if not name or not str(name).strip():
+                result.add_error("Agent name cannot be empty", field_name="name")
+
+        # Validate description
+        if "description" in frontmatter:
+            description = frontmatter["description"]
+            if not description or not str(description).strip():
+                result.add_error(
+                    "Agent description cannot be empty", field_name="description"
+                )
+
+        # Validate author
+        if "author" in frontmatter:
+            author = frontmatter["author"]
+            if not author or not str(author).strip():
+                result.add_error("Agent author cannot be empty", field_name="author")
+
+        # Validate version
+        if "version" in frontmatter:
+            version = frontmatter["version"]
+            if not self._is_valid_version(str(version)):
+                result.add_warning(
+                    f"Version '{version}' does not follow semantic versioning",
+                    field_name="version",
+                    suggestion="Use semantic versioning (e.g., '1.0.0')",
+                )
+
+        # Validate model
+        if "model" in frontmatter:
+            model = frontmatter["model"]
+            valid_models = ["sonnet", "haiku", "opus"]
+            if model not in valid_models:
+                result.add_warning(
+                    f"Unknown model '{model}'",
+                    field_name="model",
+                    suggestion=f"Use one of: {', '.join(valid_models)}",
+                )
+
+        # Validate tools
+        if "tools" in frontmatter:
+            tools = frontmatter["tools"]
+            if not isinstance(tools, list):
+                result.add_error("Tools should be a list", field_name="tools")
+            elif len(tools) == 0:
+                result.add_warning("No tools specified", field_name="tools")
+            else:
+                # Check for common tool names
+                for tool in tools:
+                    if not isinstance(tool, str):
+                        result.add_warning(
+                            f"Tool '{tool}' should be a string", field_name="tools"
+                        )
+
+    def _validate_markdown_structure(self, content: str) -> ValidationResult:
+        """Validate markdown structure of agent file.
+
+        Args:
+            content: File content
+
+        Returns:
+            ValidationResult for markdown validation
+        """
+        result = ValidationResult(is_valid=True)
+
+        # Remove frontmatter for markdown analysis
+        content_without_frontmatter = re.sub(
+            r"^---\n.*?\n---\n", "", content, flags=re.DOTALL
+        )
+
+        # Check if there's content after frontmatter
+        if not content_without_frontmatter.strip():
+            result.add_warning("Agent file has no content after frontmatter")
+            return result
+
+        # Check for basic markdown structure
+        lines = content_without_frontmatter.split("\n")
+
+        # Look for at least one heading or substantial content
+        has_heading = any(line.strip().startswith("#") for line in lines)
+        has_content = any(len(line.strip()) > 10 for line in lines)
+
+        if not has_heading and not has_content:
+            result.add_warning("Agent file appears to have minimal content")
+
+        # Check for common sections
+        content_lower = content_without_frontmatter.lower()
+        if "instruction" not in content_lower and "prompt" not in content_lower:
+            result.add_info("Agent file may benefit from explicit instructions section")
+
+        return result
+
+    def _is_valid_version(self, version: str) -> bool:
+        """Check if version follows semantic versioning.
+
+        Args:
+            version: Version string to validate
+
+        Returns:
+            True if version is valid semantic version
+        """
+        # Simple semantic version pattern
+        pattern = r"^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$"
+        return bool(re.match(pattern, version))
+
+    def repair_agent_file(
+        self, agent_file: Path, dry_run: bool = True
+    ) -> ValidationResult:
+        """Attempt to repair common issues in agent file.
+
+        Args:
+            agent_file: Path to agent file
+            dry_run: If True, don't actually modify the file
+
+        Returns:
+            ValidationResult with repair information
+        """
+        result = ValidationResult(is_valid=True)
+
+        try:
+            content = agent_file.read_text(encoding="utf-8")
+            original_content = content
+
+            # Try to fix common frontmatter issues
+            content = self._repair_frontmatter(content, result)
+
+            # If changes were made and not dry run, write back
+            if content != original_content:
+                if not dry_run:
+                    agent_file.write_text(content, encoding="utf-8")
+                    result.add_info(f"Repaired agent file: {agent_file}")
+                else:
+                    result.add_info(f"Would repair agent file: {agent_file} (dry run)")
+            else:
+                result.add_info("No repairs needed")
+
+        except Exception as e:
+            result.add_error(f"Failed to repair agent file: {e}")
+
+        return result
+
+    def _repair_frontmatter(self, content: str, result: ValidationResult) -> str:
+        """Attempt to repair frontmatter issues.
+
+        Args:
+            content: File content
+            result: ValidationResult to update with repair info
+
+        Returns:
+            Repaired content
+        """
+        # This is a simplified repair - in practice, you'd want more sophisticated logic
+        if not content.startswith("---"):
+            result.add_info("Added missing frontmatter delimiters")
+            # Add basic frontmatter if missing
+            basic_frontmatter = """---
+name: "Unknown Agent"
+description: "Agent description needed"
+author: "claude-mpm"
+version: "1.0.0"
+model: "sonnet"
+tools: []
+---
+
+"""
+            return basic_frontmatter + content
+
+        return content

claude_mpm/services/agents/deployment/validation/deployment_validator.py

@@ -0,0 +1,238 @@
+"""Main deployment validator service."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.logger import get_logger
+
+from .agent_validator import AgentValidator
+from .template_validator import TemplateValidator
+from .validation_result import ValidationResult
+
+
+class DeploymentValidator:
+    """Main validator for deployment operations.
+
+    This service orchestrates validation of templates, agents,
+    and deployment environments.
+    """
+
+    def __init__(self):
+        """Initialize the deployment validator."""
+        self.logger = get_logger(__name__)
+        self.template_validator = TemplateValidator()
+        self.agent_validator = AgentValidator()
+
+    def validate_template_files(
+        self, template_files: List[Path]
+    ) -> Dict[str, ValidationResult]:
+        """Validate multiple template files.
+
+        Args:
+            template_files: List of template file paths
+
+        Returns:
+            Dictionary mapping file paths to validation results
+        """
+        results = {}
+
+        for template_file in template_files:
+            self.logger.debug(f"Validating template: {template_file}")
+            result = self.template_validator.validate_template_file(template_file)
+            results[str(template_file)] = result
+
+            if not result.is_valid:
+                self.logger.warning(
+                    f"Template validation failed for {template_file}: {result}"
+                )
+            elif result.has_warnings:
+                self.logger.info(
+                    f"Template validation warnings for {template_file}: {result.warning_count} warnings"
+                )
+
+        return results
+
+    def validate_agent_files(
+        self, agent_files: List[Path]
+    ) -> Dict[str, ValidationResult]:
+        """Validate multiple agent files.
+
+        Args:
+            agent_files: List of agent file paths
+
+        Returns:
+            Dictionary mapping file paths to validation results
+        """
+        results = {}
+
+        for agent_file in agent_files:
+            self.logger.debug(f"Validating agent: {agent_file}")
+            result = self.agent_validator.validate_agent_file(agent_file)
+            results[str(agent_file)] = result
+
+            if not result.is_valid:
+                self.logger.warning(
+                    f"Agent validation failed for {agent_file}: {result}"
+                )
+            elif result.has_warnings:
+                self.logger.info(
+                    f"Agent validation warnings for {agent_file}: {result.warning_count} warnings"
+                )
+
+        return results
+
+    def validate_deployment_environment(
+        self, target_dir: Path, templates_dir: Optional[Path] = None
+    ) -> ValidationResult:
+        """Validate deployment environment.
+
+        Args:
+            target_dir: Target deployment directory
+            templates_dir: Optional templates directory
+
+        Returns:
+            ValidationResult for environment validation
+        """
+        result = ValidationResult(is_valid=True)
+
+        # Validate target directory
+        if not target_dir.exists():
+            try:
+                target_dir.mkdir(parents=True, exist_ok=True)
+                result.add_info(f"Created target directory: {target_dir}")
+            except Exception as e:
+                result.add_error(f"Cannot create target directory {target_dir}: {e}")
+                return result
+
+        if not target_dir.is_dir():
+            result.add_error(f"Target path is not a directory: {target_dir}")
+            return result
+
+        # Check if target directory is writable
+        test_file = target_dir / ".write_test"
+        try:
+            test_file.write_text("test")
+            test_file.unlink()
+            result.add_info("Target directory is writable")
+        except Exception as e:
+            result.add_error(f"Target directory is not writable: {target_dir} - {e}")
+
+        # Validate templates directory if provided
+        if templates_dir:
+            if not templates_dir.exists():
+                result.add_error(f"Templates directory does not exist: {templates_dir}")
+            elif not templates_dir.is_dir():
+                result.add_error(f"Templates path is not a directory: {templates_dir}")
+            else:
+                # Check for template files (templates migrated to .md in v4.26.0+)
+                template_files = list(templates_dir.glob("*.md"))
+                if not template_files:
+                    result.add_warning(f"No template files found in: {templates_dir}")
+                else:
+                    result.add_info(f"Found {len(template_files)} template files")
+
+        return result
+
+    def validate_deployment_context(self, context) -> ValidationResult:
+        """Validate deployment context.
+
+        Args:
+            context: Deployment context (pipeline or deployment context)
+
+        Returns:
+            ValidationResult for context validation
+        """
+        result = ValidationResult(is_valid=True)
+
+        # Validate target directory
+        target_dir = getattr(context, "actual_target_dir", None) or getattr(
+            context, "target_dir", None
+        )
+        if target_dir:
+            env_result = self.validate_deployment_environment(target_dir)
+            result = result.merge(env_result)
+        else:
+            result.add_error("No target directory specified in context")
+
+        # Validate template files
+        template_files = getattr(context, "template_files", [])
+        if template_files:
+            template_results = self.validate_template_files(template_files)
+
+            # Aggregate template validation results
+            total_templates = len(template_results)
+            valid_templates = sum(1 for r in template_results.values() if r.is_valid)
+
+            if valid_templates == total_templates:
+                result.add_info(f"All {total_templates} templates are valid")
+            else:
+                invalid_count = total_templates - valid_templates
+                result.add_error(
+                    f"{invalid_count} of {total_templates} templates are invalid"
+                )
+
+            # Add template validation details to metadata
+            result.metadata["template_validation"] = {
+                "total": total_templates,
+                "valid": valid_templates,
+                "invalid": total_templates - valid_templates,
+                "details": {path: r.to_dict() for path, r in template_results.items()},
+            }
+        else:
+            result.add_warning("No template files to validate")
+
+        return result
+
+    def repair_agent_files(
+        self, agent_files: List[Path], dry_run: bool = True
+    ) -> Dict[str, ValidationResult]:
+        """Repair multiple agent files.
+
+        Args:
+            agent_files: List of agent file paths
+            dry_run: If True, don't actually modify files
+
+        Returns:
+            Dictionary mapping file paths to repair results
+        """
+        results = {}
+
+        for agent_file in agent_files:
+            self.logger.debug(f"Repairing agent: {agent_file}")
+            result = self.agent_validator.repair_agent_file(agent_file, dry_run=dry_run)
+            results[str(agent_file)] = result
+
+            if not result.is_valid:
+                self.logger.error(f"Agent repair failed for {agent_file}: {result}")
+            else:
+                self.logger.info(f"Agent repair completed for {agent_file}")
+
+        return results
+
+    def get_validation_summary(
+        self, results: Dict[str, ValidationResult]
+    ) -> Dict[str, Any]:
+        """Get summary of validation results.
+
+        Args:
+            results: Dictionary of validation results
+
+        Returns:
+            Summary dictionary
+        """
+        total = len(results)
+        valid = sum(1 for r in results.values() if r.is_valid)
+        invalid = total - valid
+
+        total_errors = sum(r.error_count for r in results.values())
+        total_warnings = sum(r.warning_count for r in results.values())
+
+        return {
+            "total_files": total,
+            "valid_files": valid,
+            "invalid_files": invalid,
+            "total_errors": total_errors,
+            "total_warnings": total_warnings,
+            "success_rate": (valid / total * 100) if total > 0 else 0,
+            "details": {path: r.to_dict() for path, r in results.items()},
+        }