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

claude_mpm/services/agents/deployment/single_agent_deployer.py

@@ -0,0 +1,315 @@
+"""Single agent deployer for deploying individual agents."""
+
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+from claude_mpm.core.exceptions import AgentDeploymentError
+
+
+class SingleAgentDeployer:
+    """Service for deploying individual agents.
+
+    This service handles the deployment of single agent templates,
+    including version checking, building, and writing agent files.
+    """
+
+    def __init__(
+        self,
+        template_builder,
+        version_manager,
+        results_manager,
+        logger: Optional[logging.Logger] = None,
+    ):
+        """Initialize the single agent deployer.
+
+        Args:
+            template_builder: Template builder service
+            version_manager: Version manager service
+            results_manager: Results manager service
+            logger: Optional logger instance
+        """
+        self.template_builder = template_builder
+        self.version_manager = version_manager
+        self.results_manager = results_manager
+        self.logger = logger or logging.getLogger(__name__)
+
+    def deploy_single_agent(
+        self,
+        template_file: Path,
+        agents_dir: Path,
+        base_agent_data: dict,
+        base_agent_version: tuple,
+        force_rebuild: bool,
+        deployment_mode: str,
+        results: Dict[str, Any],
+        source_info: str = "unknown",
+    ) -> None:
+        """Deploy a single agent template.
+
+        WHY: Extracting single agent deployment logic reduces complexity
+        and makes the main deployment loop more readable.
+
+        Args:
+            template_file: Agent template file
+            agents_dir: Target agents directory
+            base_agent_data: Base agent data
+            base_agent_version: Base agent version
+            force_rebuild: Whether to force rebuild
+            deployment_mode: Deployment mode (update/project)
+            results: Results dictionary to update
+            source_info: Source of the agent (system/project/user)
+        """
+        try:
+            # METRICS: Track individual agent deployment time
+            agent_start_time = time.time()
+
+            agent_name = template_file.stem
+            target_file = agents_dir / f"{agent_name}.md"
+
+            # Check if agent needs update
+            needs_update, is_migration, reason = self._check_update_status(
+                target_file,
+                template_file,
+                base_agent_version,
+                force_rebuild,
+                deployment_mode,
+            )
+
+            # Skip if exists and doesn't need update (only in update mode)
+            if (
+                target_file.exists()
+                and not needs_update
+                and deployment_mode != "project"
+            ):
+                results["skipped"].append(agent_name)
+                self.logger.debug(f"Skipped up-to-date agent: {agent_name}")
+                return
+
+            # Build the agent file as markdown with YAML frontmatter
+            agent_content = self.template_builder.build_agent_markdown(
+                agent_name, template_file, base_agent_data, source_info
+            )
+
+            # Write the agent file
+            is_update = target_file.exists()
+            target_file.write_text(agent_content)
+
+            # Record metrics and update results
+            self.results_manager.record_agent_deployment(
+                agent_name,
+                template_file,
+                target_file,
+                is_update,
+                is_migration,
+                reason,
+                agent_start_time,
+                results,
+                self.logger,
+            )
+
+        except AgentDeploymentError as e:
+            # Re-raise our custom exceptions
+            self.logger.error(str(e))
+            results["errors"].append(str(e))
+        except Exception as e:
+            # Wrap generic exceptions with context
+            error_msg = f"Failed to build {template_file.name}: {e}"
+            self.logger.error(error_msg)
+            results["errors"].append(error_msg)
+
+    def _check_update_status(
+        self,
+        target_file: Path,
+        template_file: Path,
+        base_agent_version: tuple,
+        force_rebuild: bool,
+        deployment_mode: str,
+    ) -> Tuple[bool, bool, str]:
+        """Check if agent needs update and determine status.
+
+        WHY: Centralized update checking logic ensures consistent
+        version comparison and migration detection.
+
+        Args:
+            target_file: Target agent file
+            template_file: Template file
+            base_agent_version: Base agent version
+            force_rebuild: Whether to force rebuild
+            deployment_mode: Deployment mode
+
+        Returns:
+            Tuple of (needs_update, is_migration, reason)
+        """
+        needs_update = force_rebuild
+        is_migration = False
+        reason = ""
+
+        # In project deployment mode, always deploy regardless of version
+        if deployment_mode == "project":
+            if target_file.exists():
+                needs_update = True
+                self.logger.debug(
+                    f"Project deployment mode: will deploy {template_file.stem}"
+                )
+            else:
+                needs_update = True
+        elif not needs_update and target_file.exists():
+            # In update mode, check version compatibility
+            needs_update, reason = self.version_manager.check_agent_needs_update(
+                target_file, template_file, base_agent_version
+            )
+            if needs_update:
+                # Check if this is a migration from old format
+                if "migration needed" in reason:
+                    is_migration = True
+                    self.logger.info(f"Migrating agent {template_file.stem}: {reason}")
+                else:
+                    self.logger.info(
+                        f"Agent {template_file.stem} needs update: {reason}"
+                    )
+
+        return needs_update, is_migration, reason
+
+    def deploy_agent(
+        self,
+        agent_name: str,
+        templates_dir: Path,
+        target_dir: Path,
+        base_agent_path: Path,
+        force_rebuild: bool = False,
+        working_directory: Optional[Path] = None,
+    ) -> bool:
+        """Deploy a single agent to the specified directory.
+
+        Args:
+            agent_name: Name of the agent to deploy
+            templates_dir: Directory containing templates
+            target_dir: Target directory for deployment (Path object)
+            base_agent_path: Path to base agent configuration
+            force_rebuild: Whether to force rebuild even if version is current
+            working_directory: Working directory for determining agent source
+
+        Returns:
+            True if deployment was successful, False otherwise
+
+        WHY: Single agent deployment because:
+        - Users may want to deploy specific agents only
+        - Reduces deployment time for targeted updates
+        - Enables selective agent management in projects
+        """
+        try:
+            # Find the template file (templates migrated to .md in v4.26.0+)
+            template_file = templates_dir / f"{agent_name}.md"
+            if not template_file.exists():
+                self.logger.error(f"Agent template not found: {agent_name}")
+                return False
+
+            # Ensure target directory exists
+            target_dir.mkdir(parents=True, exist_ok=True)
+
+            # Build and deploy the agent
+            target_file = target_dir / f"{agent_name}.md"
+
+            # Check if update is needed
+            if not force_rebuild and target_file.exists():
+                # Load base agent data for version checking
+                base_agent_data = {}
+                base_agent_version = (0, 0, 0)
+                if base_agent_path.exists():
+                    try:
+                        import json
+
+                        base_agent_data = json.loads(base_agent_path.read_text())
+                        base_agent_version = self.version_manager.parse_version(
+                            base_agent_data.get("base_version")
+                            or base_agent_data.get("version", 0)
+                        )
+                    except Exception as e:
+                        self.logger.warning(
+                            f"Could not load base agent for version check: {e}"
+                        )
+
+                needs_update, reason = self.version_manager.check_agent_needs_update(
+                    target_file, template_file, base_agent_version
+                )
+                if not needs_update:
+                    self.logger.info(f"Agent {agent_name} is up to date")
+                    return True
+                self.logger.info(f"Updating agent {agent_name}: {reason}")
+
+            # Load base agent data for building
+            base_agent_data = {}
+            if base_agent_path.exists():
+                try:
+                    import json
+
+                    base_agent_data = json.loads(base_agent_path.read_text())
+                except Exception as e:
+                    self.logger.warning(f"Could not load base agent: {e}")
+
+            # Build the agent markdown
+            # For single agent deployment, determine source from template location
+            source_info = self._determine_agent_source(
+                template_file, working_directory or Path.cwd()
+            )
+            agent_content = self.template_builder.build_agent_markdown(
+                agent_name, template_file, base_agent_data, source_info
+            )
+            if not agent_content:
+                self.logger.error(f"Failed to build agent content for {agent_name}")
+                return False
+
+            # Write to target file
+            target_file.write_text(agent_content)
+            self.logger.info(
+                f"Successfully deployed agent: {agent_name} to {target_file}"
+            )
+
+            return True
+
+        except AgentDeploymentError:
+            # Re-raise our custom exceptions
+            raise
+        except Exception as e:
+            # Wrap generic exceptions with context
+            raise AgentDeploymentError(
+                f"Failed to deploy agent {agent_name}",
+                context={"agent_name": agent_name, "error": str(e)},
+            ) from e
+
+    def _determine_agent_source(
+        self, template_path: Path, working_directory: Path
+    ) -> str:
+        """Determine the source of an agent from its template path.
+
+        WHY: When deploying single agents, we need to track their source
+        for proper version management and debugging.
+
+        Args:
+            template_path: Path to the agent template
+            working_directory: Current working directory
+
+        Returns:
+            Source string (system/project/user/unknown)
+        """
+        template_str = str(template_path.resolve())
+
+        # Check if it's a system template
+        if (
+            "/claude_mpm/agents/templates/" in template_str
+            or "/src/claude_mpm/agents/templates/" in template_str
+        ):
+            return "system"
+
+        # Check if it's a project agent
+        if "/.claude-mpm/agents/" in template_str:
+            # Check if it's in the current working directory
+            if str(working_directory) in template_str:
+                return "project"
+            # Check if it's in user home
+            if str(Path.home()) in template_str:
+                return "user"
+
+        return "unknown"

claude_mpm/services/agents/deployment/strategies/__init__.py

@@ -0,0 +1,25 @@
+"""Deployment strategy pattern for agent deployment.
+
+This module provides different deployment strategies for various scenarios:
+- SystemAgentDeploymentStrategy: For system-wide agent deployment
+- ProjectAgentDeploymentStrategy: For project-specific agent deployment
+- UserAgentDeploymentStrategy: For user-specific agent deployment
+
+The strategy pattern allows for clean separation of deployment logic
+and makes it easy to add new deployment types in the future.
+"""
+
+from .base_strategy import BaseDeploymentStrategy, DeploymentContext
+from .project_strategy import ProjectAgentDeploymentStrategy
+from .strategy_selector import DeploymentStrategySelector
+from .system_strategy import SystemAgentDeploymentStrategy
+from .user_strategy import UserAgentDeploymentStrategy
+
+__all__ = [
+    "BaseDeploymentStrategy",
+    "DeploymentContext",
+    "DeploymentStrategySelector",
+    "ProjectAgentDeploymentStrategy",
+    "SystemAgentDeploymentStrategy",
+    "UserAgentDeploymentStrategy",
+]

claude_mpm/services/agents/deployment/strategies/base_strategy.py

@@ -0,0 +1,113 @@
+"""Base deployment strategy interface and context."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from claude_mpm.core.config import Config
+
+
+@dataclass
+class DeploymentContext:
+    """Context object containing all deployment parameters."""
+
+    target_dir: Optional[Path] = None
+    force_rebuild: bool = False
+    deployment_mode: str = "update"
+    config: Optional[Config] = None
+    use_async: bool = False
+    working_directory: Optional[Path] = None
+    templates_dir: Optional[Path] = None
+    base_agent_path: Optional[Path] = None
+
+
+class BaseDeploymentStrategy(ABC):
+    """Base class for all deployment strategies.
+
+    This abstract base class defines the interface that all deployment
+    strategies must implement. Each strategy handles a specific type
+    of deployment (system, project, user) with its own logic.
+    """
+
+    def __init__(self, name: str):
+        """Initialize the deployment strategy.
+
+        Args:
+            name: Human-readable name for this strategy
+        """
+        self.name = name
+
+    @abstractmethod
+    def can_handle(self, context: DeploymentContext) -> bool:
+        """Check if this strategy can handle the given deployment context.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            True if this strategy should handle the deployment
+        """
+
+    @abstractmethod
+    def determine_target_directory(self, context: DeploymentContext) -> Path:
+        """Determine the target directory for deployment.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            Path where agents should be deployed
+        """
+
+    @abstractmethod
+    def get_templates_directory(self, context: DeploymentContext) -> Path:
+        """Get the templates directory for this deployment type.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            Path to the templates directory
+        """
+
+    @abstractmethod
+    def get_excluded_agents(self, context: DeploymentContext) -> List[str]:
+        """Get list of agents to exclude for this deployment type.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            List of agent names to exclude from deployment
+        """
+
+    @abstractmethod
+    def should_deploy_system_instructions(self, context: DeploymentContext) -> bool:
+        """Check if system instructions should be deployed.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            True if system instructions should be deployed
+        """
+
+    @abstractmethod
+    def get_deployment_priority(self) -> int:
+        """Get the priority of this deployment strategy.
+
+        Lower numbers have higher priority. Used when multiple
+        strategies can handle the same context.
+
+        Returns:
+            Priority number (lower = higher priority)
+        """
+
+    def __str__(self) -> str:
+        """String representation of the strategy."""
+        return f"{self.__class__.__name__}({self.name})"
+
+    def __repr__(self) -> str:
+        """Detailed string representation of the strategy."""
+        return f"{self.__class__.__name__}(name='{self.name}', priority={self.get_deployment_priority()})"

claude_mpm/services/agents/deployment/strategies/project_strategy.py

@@ -0,0 +1,148 @@
+"""Project-specific agent deployment strategy."""
+
+from pathlib import Path
+from typing import List
+
+from .base_strategy import BaseDeploymentStrategy, DeploymentContext
+
+
+class ProjectAgentDeploymentStrategy(BaseDeploymentStrategy):
+    """Strategy for deploying project-specific agents.
+
+    Project agents are deployed to the project's .claude/agents/
+    directory and are specific to that project.
+    """
+
+    def __init__(self):
+        super().__init__("Project Agent Deployment")
+
+    def can_handle(self, context: DeploymentContext) -> bool:
+        """Check if this is a project-specific deployment.
+
+        Project deployment when:
+        - Working directory is set AND
+        - Target directory is within the working directory, OR
+        - Templates directory is within working directory's .claude-mpm/agents/
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            True if this should handle project agent deployment
+        """
+        if not context.working_directory:
+            return False
+
+        # Check if target_dir is within working directory
+        if context.target_dir:
+            try:
+                # Check if target is within working directory
+                context.target_dir.resolve().relative_to(
+                    context.working_directory.resolve()
+                )
+                return True
+            except ValueError:
+                # target_dir is not within working_directory
+                pass
+
+        # Check if templates_dir suggests project deployment
+        if context.templates_dir:
+            project_agents_dir = context.working_directory / ".claude-mpm" / "agents"
+            try:
+                context.templates_dir.resolve().relative_to(
+                    project_agents_dir.resolve()
+                )
+                return True
+            except ValueError:
+                # templates_dir is not within project agents directory
+                pass
+
+        # Check if deployment_mode is "project" - this should be sufficient
+        return context.deployment_mode == "project"
+
+    def determine_target_directory(self, context: DeploymentContext) -> Path:
+        """Determine target directory for project agents.
+
+        Project agents are deployed to {working_directory}/.claude/agents/
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            Path to project's .claude/agents/ directory
+        """
+        if context.target_dir:
+            return context.target_dir
+
+        if context.working_directory:
+            return context.working_directory / ".claude" / "agents"
+
+        # Fallback to current directory
+        return Path.cwd() / ".claude" / "agents"
+
+    def get_templates_directory(self, context: DeploymentContext) -> Path:
+        """Get templates directory for project agents.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            Path to project templates directory or system fallback
+        """
+        if context.templates_dir:
+            return context.templates_dir
+
+        if context.working_directory:
+            # Try project-specific agents directory first
+            project_agents_dir = context.working_directory / ".claude-mpm" / "agents"
+            if project_agents_dir.exists():
+                return project_agents_dir
+
+        # Fallback to system templates
+        from claude_mpm.core.unified_paths import get_path_manager
+
+        return get_path_manager().get_user_agents_dir() / "templates"
+
+    def get_excluded_agents(self, context: DeploymentContext) -> List[str]:
+        """Get excluded agents for project deployment.
+
+        Project deployment may have project-specific exclusions.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            List of excluded agent names
+        """
+        if not context.config:
+            return []
+
+        # Project deployments might have different exclusion rules
+        excluded = context.config.get("agent_deployment.excluded_agents", [])
+
+        # In project mode, we might want to include all agents by default
+        if context.deployment_mode == "project":
+            return []
+
+        return excluded
+
+    def should_deploy_system_instructions(self, context: DeploymentContext) -> bool:
+        """Project deployment should deploy system instructions.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            True - project deployment includes instructions
+        """
+        return True
+
+    def get_deployment_priority(self) -> int:
+        """Project deployment has medium priority.
+
+        Higher priority than system, lower than user.
+
+        Returns:
+            Priority 50 (medium priority)
+        """
+        return 50