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

claude_mpm/services/agents/deployment/agent_validator.py

@@ -0,0 +1,376 @@
+"""Agent Validator Service
+
+This service handles validation and repair of agent configurations, templates, and deployments.
+Ensures agent files meet Claude Code requirements and can fix common issues.
+
+Extracted from AgentDeploymentService as part of the refactoring to improve
+maintainability and testability.
+"""
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from claude_mpm.core.logging_config import get_logger
+
+
+class AgentValidator:
+    """Service for validating and repairing agent configurations.
+
+    This service handles:
+    - Agent template validation
+    - YAML frontmatter validation and repair
+    - Agent file structure verification
+    - Configuration compliance checking
+    """
+
+    def __init__(self):
+        """Initialize the agent validator."""
+        self.logger = get_logger(__name__)
+
+    def validate_agent(self, agent_path: Path) -> Tuple[bool, List[str]]:
+        """
+        Validate agent configuration and structure.
+
+        Args:
+            agent_path: Path to the agent file to validate
+
+        Returns:
+            Tuple of (is_valid: bool, errors: List[str])
+        """
+        errors = []
+
+        try:
+            if not agent_path.exists():
+                errors.append(f"Agent file does not exist: {agent_path}")
+                return False, errors
+
+            # Read agent content
+            content = agent_path.read_text()
+
+            # Validate YAML frontmatter
+            frontmatter_valid, frontmatter_errors = self._validate_yaml_frontmatter(
+                content
+            )
+            errors.extend(frontmatter_errors)
+
+            # Validate required fields
+            required_fields_valid, field_errors = self._validate_required_fields(
+                content
+            )
+            errors.extend(field_errors)
+
+            # Validate agent name format
+            name_valid, name_errors = self._validate_agent_name(content)
+            errors.extend(name_errors)
+
+            # Validate tools format
+            tools_valid, tools_errors = self._validate_tools_format(content)
+            errors.extend(tools_errors)
+
+            is_valid = (
+                frontmatter_valid
+                and required_fields_valid
+                and name_valid
+                and tools_valid
+            )
+
+        except Exception as e:
+            errors.append(f"Error validating agent: {e}")
+            is_valid = False
+
+        return is_valid, errors
+
+    def validate_and_repair_existing_agents(self, agents_dir: Path) -> Dict[str, Any]:
+        """
+        Validate and repair broken frontmatter in existing agent files.
+
+        This method scans all agent files in the directory and attempts to repair
+        common issues like malformed YAML frontmatter, missing required fields, etc.
+
+        Args:
+            agents_dir: Directory containing agent files
+
+        Returns:
+            Dictionary with repair results
+        """
+        results = {"repaired": [], "errors": [], "skipped": [], "total_checked": 0}
+
+        if not agents_dir.exists():
+            self.logger.info(f"Agents directory does not exist: {agents_dir}")
+            return results
+
+        # Find all agent files (both .md and .yaml)
+        agent_files = list(agents_dir.glob("*.md")) + list(agents_dir.glob("*.yaml"))
+        results["total_checked"] = len(agent_files)
+
+        for agent_file in agent_files:
+            try:
+                self.logger.debug(f"Checking agent file: {agent_file.name}")
+
+                # Read current content
+                original_content = agent_file.read_text()
+
+                # Attempt to repair the file
+                repaired_content, was_repaired, repair_issues = self._repair_agent_file(
+                    original_content
+                )
+
+                if was_repaired:
+                    # Write repaired content back to file
+                    agent_file.write_text(repaired_content)
+
+                    repair_info = {
+                        "file": agent_file.name,
+                        "issues_fixed": repair_issues,
+                    }
+                    results["repaired"].append(repair_info)
+                    self.logger.info(
+                        f"Repaired agent file: {agent_file.name} (fixed: {', '.join(repair_issues)})"
+                    )
+                else:
+                    results["skipped"].append(agent_file.name)
+                    self.logger.debug(f"No repairs needed for: {agent_file.name}")
+
+            except Exception as e:
+                error_msg = f"Failed to repair {agent_file.name}: {e}"
+                results["errors"].append(error_msg)
+                self.logger.error(error_msg)
+
+        self.logger.info(
+            f"Agent validation complete: {len(results['repaired'])} repaired, {len(results['errors'])} errors"
+        )
+        return results
+
+    def verify_deployment(self, config_dir: Optional[Path] = None) -> Dict[str, Any]:
+        """
+        Verify agent deployment and Claude configuration.
+
+        Args:
+            config_dir: Claude configuration directory (default: .claude/)
+
+        Returns:
+            Dictionary with verification results
+        """
+        if not config_dir:
+            config_dir = Path.cwd() / ".claude"
+
+        results = {
+            "config_dir": str(config_dir),
+            "agents_found": [],
+            "agents_needing_migration": [],
+            "environment": {},
+            "warnings": [],
+        }
+
+        # Check if config directory exists
+        if not config_dir.exists():
+            results["warnings"].append(f"Config directory does not exist: {config_dir}")
+            return results
+
+        # Check agents directory
+        agents_dir = config_dir / "agents"
+        if not agents_dir.exists():
+            results["warnings"].append(f"Agents directory does not exist: {agents_dir}")
+            return results
+
+        # Scan for agent files
+        agent_files = list(agents_dir.glob("*.md")) + list(agents_dir.glob("*.yaml"))
+
+        for agent_file in agent_files:
+            try:
+                content = agent_file.read_text()
+
+                # Extract basic info from YAML frontmatter
+                agent_info = self._extract_agent_info(content, agent_file)
+
+                # Check if agent needs migration (old version format)
+                if self._needs_version_migration(content):
+                    agent_info["needs_migration"] = True
+                    results["agents_needing_migration"].append(agent_info["name"])
+
+                results["agents_found"].append(agent_info)
+
+            except Exception as e:
+                self.logger.warning(
+                    f"Could not process agent file {agent_file.name}: {e}"
+                )
+
+        # Add environment information
+        import os
+
+        results["environment"] = {
+            key: value for key, value in os.environ.items() if key.startswith("CLAUDE_")
+        }
+
+        return results
+
+    def _validate_yaml_frontmatter(self, content: str) -> Tuple[bool, List[str]]:
+        """Validate YAML frontmatter structure."""
+        errors = []
+
+        # Check if content starts with YAML frontmatter
+        if not content.strip().startswith("---"):
+            errors.append("Missing YAML frontmatter")
+            return False, errors
+
+        # Find the end of frontmatter
+        lines = content.split("\n")
+        frontmatter_end = -1
+
+        for i, line in enumerate(lines[1:], 1):  # Skip first ---
+            if line.strip() == "---":
+                frontmatter_end = i
+                break
+
+        if frontmatter_end == -1:
+            errors.append("YAML frontmatter not properly closed")
+            return False, errors
+
+        return True, errors
+
+    def _validate_required_fields(self, content: str) -> Tuple[bool, List[str]]:
+        """Validate required fields in agent content."""
+        errors = []
+        required_fields = ["name", "description", "tools"]
+
+        for field in required_fields:
+            field_pattern = rf"^{field}:\s*.+$"
+            if not re.search(field_pattern, content, re.MULTILINE):
+                errors.append(f"Missing required field: {field}")
+
+        return len(errors) == 0, errors
+
+    def _validate_agent_name(self, content: str) -> Tuple[bool, List[str]]:
+        """Validate agent name format."""
+        errors = []
+
+        # Extract name from frontmatter
+        name_match = re.search(r'^name:\s*["\']?(.+?)["\']?$', content, re.MULTILINE)
+        if name_match:
+            name = name_match.group(1).strip()
+
+            # Validate Claude Code name requirements
+            if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", name):
+                errors.append(
+                    f"Invalid agent name format: '{name}'. Must match ^[a-z0-9]+(-[a-z0-9]+)*$"
+                )
+
+        return len(errors) == 0, errors
+
+    def _validate_tools_format(self, content: str) -> Tuple[bool, List[str]]:
+        """Validate tools format."""
+        errors = []
+
+        # Extract tools from frontmatter
+        tools_match = re.search(r"^tools:\s*(.+)$", content, re.MULTILINE)
+        if tools_match:
+            tools_str = tools_match.group(1).strip()
+
+            # Check for spaces in comma-separated tools (not allowed)
+            if ", " in tools_str:
+                errors.append("Tools must be comma-separated WITHOUT spaces")
+
+        return len(errors) == 0, errors
+
+    def _repair_agent_file(self, content: str) -> Tuple[str, bool, List[str]]:
+        """
+        Attempt to repair common issues in agent file content.
+
+        Returns:
+            Tuple of (repaired_content, was_repaired, issues_fixed)
+        """
+        repaired_content = content
+        issues_fixed = []
+        was_repaired = False
+
+        # Fix tools format (remove spaces after commas)
+        tools_pattern = r"^(tools:\s*)([^,\n]+(?:,\s+[^,\n]+)+)$"
+        tools_match = re.search(tools_pattern, repaired_content, re.MULTILINE)
+        if tools_match:
+            tools_prefix = tools_match.group(1)
+            tools_value = tools_match.group(2)
+
+            if ", " in tools_value:
+                # Remove spaces after commas
+                fixed_tools = tools_value.replace(", ", ",")
+                repaired_content = re.sub(
+                    tools_pattern,
+                    f"{tools_prefix}{fixed_tools}",
+                    repaired_content,
+                    flags=re.MULTILINE,
+                )
+                issues_fixed.append("tools_spacing")
+                was_repaired = True
+
+        # Add missing required fields with defaults
+        if "description:" not in repaired_content:
+            # Insert description after name if possible
+            name_match = re.search(r"^(name:\s*.+)$", repaired_content, re.MULTILINE)
+            if name_match:
+                name_line = name_match.group(1)
+                repaired_content = repaired_content.replace(
+                    name_line,
+                    f'{name_line}\ndescription: "Agent for specialized tasks"',
+                )
+                issues_fixed.append("missing_description")
+                was_repaired = True
+
+        return repaired_content, was_repaired, issues_fixed
+
+    def _extract_agent_info(self, content: str, agent_file: Path) -> Dict[str, Any]:
+        """Extract basic agent information from content."""
+        agent_info = {
+            "file": agent_file.name,
+            "name": agent_file.stem,
+            "path": str(agent_file),
+            "description": "No description",
+            "version": "unknown",
+            "type": "agent",  # Default type
+        }
+
+        # Extract ONLY from YAML frontmatter (between --- markers)
+        lines = content.split("\n")
+        in_frontmatter = False
+        frontmatter_ended = False
+
+        for line in lines:
+            stripped_line = line.strip()
+
+            # Track frontmatter boundaries
+            if stripped_line == "---":
+                if not in_frontmatter:
+                    in_frontmatter = True
+                    continue
+                frontmatter_ended = True
+                break  # Stop parsing after frontmatter ends
+
+            # Only parse within frontmatter
+            if not in_frontmatter or frontmatter_ended:
+                continue
+
+            if stripped_line.startswith("name:"):
+                agent_info["name"] = stripped_line.split(":", 1)[1].strip().strip("\"'")
+            elif stripped_line.startswith("description:"):
+                agent_info["description"] = (
+                    stripped_line.split(":", 1)[1].strip().strip("\"'")
+                )
+            elif stripped_line.startswith("version:"):
+                agent_info["version"] = (
+                    stripped_line.split(":", 1)[1].strip().strip("\"'")
+                )
+            elif stripped_line.startswith("type:"):
+                agent_info["type"] = stripped_line.split(":", 1)[1].strip().strip("\"'")
+
+        return agent_info
+
+    def _needs_version_migration(self, content: str) -> bool:
+        """Check if agent needs version migration."""
+        version_match = re.search(
+            r'^version:\s*["\']?(.+?)["\']?$', content, re.MULTILINE
+        )
+        if version_match:
+            version_str = version_match.group(1)
+            # Check for old format (contains hyphen and all digits)
+            return bool(re.match(r"^\d+-\d+$", version_str))
+        return False

claude_mpm/services/agents/deployment/agent_version_manager.py

@@ -0,0 +1,322 @@
+"""Agent Version Manager Service
+
+This service handles all version-related operations for agent deployment,
+including version parsing, comparison, migration detection, and format conversion.
+
+Extracted from AgentDeploymentService as part of the refactoring to improve
+maintainability and testability.
+"""
+
+import re
+from pathlib import Path
+from typing import Any, Tuple
+
+from claude_mpm.core.logging_config import get_logger
+
+
+class AgentVersionManager:
+    """Service for managing agent versions and migrations.
+
+    This service handles:
+    - Version parsing from various formats (integer, semantic, legacy)
+    - Version comparison for update decisions
+    - Migration detection from old to new formats
+    - Version format validation and conversion
+    """
+
+    def __init__(self):
+        """Initialize the version manager."""
+        self.logger = get_logger(__name__)
+
+    def parse_version(self, version_value: Any) -> Tuple[int, int, int]:
+        """
+        Parse version from various formats to semantic version tuple.
+
+        Handles:
+        - Integer values: 5 -> (0, 5, 0)
+        - String integers: "5" -> (0, 5, 0)
+        - Semantic versions: "2.1.0" -> (2, 1, 0)
+        - Invalid formats: returns (0, 0, 0)
+
+        Args:
+            version_value: Version in various formats
+
+        Returns:
+            Tuple of (major, minor, patch) for comparison
+        """
+        if isinstance(version_value, int):
+            # Legacy integer version - treat as minor version
+            return (0, version_value, 0)
+
+        if isinstance(version_value, str):
+            # Try to parse as simple integer
+            if version_value.isdigit():
+                return (0, int(version_value), 0)
+
+            # Try to parse semantic version (e.g., "2.1.0" or "v2.1.0")
+            sem_ver_match = re.match(r"^v?(\d+)\.(\d+)\.(\d+)", version_value)
+            if sem_ver_match:
+                major = int(sem_ver_match.group(1))
+                minor = int(sem_ver_match.group(2))
+                patch = int(sem_ver_match.group(3))
+                return (major, minor, patch)
+
+            # Try to extract first number from string as minor version
+            num_match = re.search(r"(\d+)", version_value)
+            if num_match:
+                return (0, int(num_match.group(1)), 0)
+
+        # Default to 0.0.0 for invalid formats
+        return (0, 0, 0)
+
+    def format_version_display(self, version_tuple: Tuple[int, int, int]) -> str:
+        """
+        Format version tuple for display.
+
+        Args:
+            version_tuple: Tuple of (major, minor, patch)
+
+        Returns:
+            Formatted version string
+        """
+        if isinstance(version_tuple, tuple) and len(version_tuple) == 3:
+            major, minor, patch = version_tuple
+            return f"{major}.{minor}.{patch}"
+        # Fallback for legacy format
+        return str(version_tuple)
+
+    def is_old_version_format(self, version_str: str) -> bool:
+        """
+        Check if a version string is in the old serial format.
+
+        Old formats include:
+        - Serial format: "0002-0005" (contains hyphen, all digits)
+        - Missing version field
+        - Non-semantic version formats
+
+        Args:
+            version_str: Version string to check
+
+        Returns:
+            True if old format, False if semantic version
+        """
+        if not version_str:
+            return True
+
+        # Check for serial format (e.g., "0002-0005")
+        if re.match(r"^\d+-\d+$", version_str):
+            return True
+
+        # Check for semantic version format (e.g., "2.1.0")
+        if re.match(r"^v?\d+\.\d+\.\d+$", version_str):
+            return False
+
+        # Any other format is considered old
+        return True
+
+    def compare_versions(
+        self, v1: Tuple[int, int, int], v2: Tuple[int, int, int]
+    ) -> int:
+        """
+        Compare two version tuples.
+
+        Args:
+            v1: First version tuple
+            v2: Second version tuple
+
+        Returns:
+            -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+        """
+        for a, b in zip(v1, v2):
+            if a < b:
+                return -1
+            if a > b:
+                return 1
+        return 0
+
+    def extract_version_from_content(self, content: str, version_marker: str) -> int:
+        """
+        Extract version number from content using a marker.
+
+        Args:
+            content: File content
+            version_marker: Version marker to look for (e.g., "AGENT_VERSION:" or "BASE_AGENT_VERSION:")
+
+        Returns:
+            Version number or 0 if not found
+        """
+        pattern = rf"<!-- {version_marker} (\d+) -->"
+        match = re.search(pattern, content)
+        if match:
+            return int(match.group(1))
+        return 0
+
+    def extract_version_from_frontmatter(
+        self, content: str
+    ) -> Tuple[Tuple[int, int, int], bool, str]:
+        """
+        Extract version information from YAML frontmatter.
+
+        Args:
+            content: File content with YAML frontmatter
+
+        Returns:
+            Tuple of (version_tuple, is_old_format, version_string)
+        """
+        is_old_format = False
+        version_string = None
+
+        # Try legacy combined format (e.g., "0002-0005")
+        legacy_match = re.search(
+            r'^version:\s*["\']?(\d+)-(\d+)["\']?', content, re.MULTILINE
+        )
+        if legacy_match:
+            is_old_format = True
+            version_string = f"{legacy_match.group(1)}-{legacy_match.group(2)}"
+            # Convert legacy format to semantic version
+            # Treat the agent version (second number) as minor version
+            version_tuple = (0, int(legacy_match.group(2)), 0)
+            self.logger.info(f"Detected old serial version format: {version_string}")
+            return version_tuple, is_old_format, version_string
+
+        # Try to extract semantic version format (e.g., "2.1.0")
+        version_match = re.search(
+            r'^version:\s*["\']?v?(\d+)\.(\d+)\.(\d+)["\']?', content, re.MULTILINE
+        )
+        if version_match:
+            version_tuple = (
+                int(version_match.group(1)),
+                int(version_match.group(2)),
+                int(version_match.group(3)),
+            )
+            version_string = f"{version_match.group(1)}.{version_match.group(2)}.{version_match.group(3)}"
+            return version_tuple, is_old_format, version_string
+
+        # Fallback: try separate fields (very old format)
+        agent_version_match = re.search(
+            r"^agent_version:\s*(\d+)", content, re.MULTILINE
+        )
+        if agent_version_match:
+            is_old_format = True
+            version_string = f"agent_version: {agent_version_match.group(1)}"
+            version_tuple = (0, int(agent_version_match.group(1)), 0)
+            self.logger.info(f"Detected old separate version format: {version_string}")
+            return version_tuple, is_old_format, version_string
+
+        # Check for missing version field
+        if "version:" not in content:
+            is_old_format = True
+            version_string = "missing"
+            version_tuple = (0, 0, 0)
+            self.logger.info("Detected missing version field")
+            return version_tuple, is_old_format, version_string
+
+        # Default case
+        return (0, 0, 0), False, "0.0.0"
+
+    def check_agent_needs_update(
+        self,
+        deployed_file: Path,
+        template_file: Path,
+        current_base_version: Tuple[int, int, int],
+    ) -> Tuple[bool, str]:
+        """
+        Check if a deployed agent needs to be updated.
+
+        Args:
+            deployed_file: Path to the deployed agent file
+            template_file: Path to the template file
+            current_base_version: Current base agent version (for compatibility)
+
+        Returns:
+            Tuple of (needs_update: bool, reason: str)
+        """
+        try:
+            # Read deployed agent content
+            deployed_content = deployed_file.read_text()
+
+            # Skip non-system agents (user-created)
+            # Check for various author formats used by system agents
+            if not any(
+                author in deployed_content.lower()
+                for author in [
+                    "author: claude-mpm",
+                    "author: claude mpm team",
+                    "author: claude mpm",
+                ]
+            ):
+                return (False, "not a system agent")
+
+            # Extract version info from YAML frontmatter
+            (
+                deployed_version,
+                is_old_format,
+                old_version_str,
+            ) = self.extract_version_from_frontmatter(deployed_content)
+
+            # Read template to get current agent version
+            import json
+
+            template_data = json.loads(template_file.read_text())
+
+            # Extract agent version from template
+            metadata = template_data.get("metadata", {})
+            current_agent_version = self.parse_version(
+                template_data.get("agent_version")
+                or template_data.get("version")
+                or metadata.get("version", 0)
+            )
+
+            # If old format detected, always trigger update for migration
+            if is_old_format:
+                new_version_str = self.format_version_display(current_agent_version)
+                return (
+                    True,
+                    f"migration needed from old format ({old_version_str}) to semantic version ({new_version_str})",
+                )
+
+            # Check if agent template version is newer
+            if self.compare_versions(current_agent_version, deployed_version) > 0:
+                deployed_str = self.format_version_display(deployed_version)
+                current_str = self.format_version_display(current_agent_version)
+                return (
+                    True,
+                    f"agent template updated ({deployed_str} -> {current_str})",
+                )
+
+            return (False, "up to date")
+
+        except Exception as e:
+            self.logger.warning(f"Error checking agent update status: {e}")
+            # On error, assume update is needed
+            return (True, "version check failed")
+
+    def validate_version_in_content(self, content: str) -> Tuple[bool, list]:
+        """
+        Validate version information in agent content.
+
+        Args:
+            content: Agent file content
+
+        Returns:
+            Tuple of (is_valid: bool, errors: list)
+        """
+        errors = []
+
+        # Check for YAML frontmatter
+        if not content.strip().startswith("---"):
+            errors.append("Missing YAML frontmatter")
+            return False, errors
+
+        # Extract and validate version
+        version_match = re.search(
+            r'^version:\s*["\']?(.+?)["\']?$', content, re.MULTILINE
+        )
+        if not version_match:
+            errors.append("Missing version field in frontmatter")
+        else:
+            version_str = version_match.group(1)
+            if self.is_old_version_format(version_str):
+                errors.append(f"Old version format detected: {version_str}")
+
+        return len(errors) == 0, errors