claude-mpm 3.9.9__py3-none-any.whl → 4.0.3__py3-none-any.whl

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

@@ -0,0 +1,150 @@
+"""Project-specific agent deployment strategy."""
+
+from pathlib import Path
+
+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
+        if context.deployment_mode == "project":
+            return True
+
+        return False
+
+    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

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

@@ -0,0 +1,117 @@
+"""Strategy selector for choosing the appropriate deployment strategy."""
+
+from typing import List, Optional
+
+from claude_mpm.core.logger import get_logger
+
+from .base_strategy import BaseDeploymentStrategy, DeploymentContext
+from .project_strategy import ProjectAgentDeploymentStrategy
+from .system_strategy import SystemAgentDeploymentStrategy
+from .user_strategy import UserAgentDeploymentStrategy
+
+
+class DeploymentStrategySelector:
+    """Selects the appropriate deployment strategy based on context.
+
+    This class manages all available deployment strategies and selects
+    the most appropriate one based on the deployment context.
+    """
+
+    def __init__(self):
+        """Initialize the strategy selector with all available strategies."""
+        self.logger = get_logger(__name__)
+        self._strategies: List[BaseDeploymentStrategy] = [
+            UserAgentDeploymentStrategy(),
+            ProjectAgentDeploymentStrategy(),
+            SystemAgentDeploymentStrategy(),
+        ]
+
+        # Sort strategies by priority (lower number = higher priority)
+        self._strategies.sort(key=lambda s: s.get_deployment_priority())
+
+        self.logger.debug(
+            f"Initialized with {len(self._strategies)} deployment strategies"
+        )
+        for strategy in self._strategies:
+            self.logger.debug(f"  - {strategy}")
+
+    def select_strategy(self, context: DeploymentContext) -> BaseDeploymentStrategy:
+        """Select the most appropriate deployment strategy.
+
+        Iterates through strategies in priority order and returns the first
+        one that can handle the given context.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            The selected deployment strategy
+
+        Raises:
+            RuntimeError: If no strategy can handle the context
+        """
+        self.logger.debug(f"Selecting deployment strategy for context: {context}")
+
+        for strategy in self._strategies:
+            if strategy.can_handle(context):
+                self.logger.info(f"Selected deployment strategy: {strategy.name}")
+                return strategy
+
+        # This should never happen as SystemAgentDeploymentStrategy
+        # should handle any context as a fallback
+        raise RuntimeError(f"No deployment strategy can handle context: {context}")
+
+    def get_available_strategies(self) -> List[BaseDeploymentStrategy]:
+        """Get list of all available strategies.
+
+        Returns:
+            List of all registered deployment strategies
+        """
+        return self._strategies.copy()
+
+    def add_strategy(self, strategy: BaseDeploymentStrategy) -> None:
+        """Add a new deployment strategy.
+
+        Args:
+            strategy: The strategy to add
+        """
+        self._strategies.append(strategy)
+        # Re-sort by priority
+        self._strategies.sort(key=lambda s: s.get_deployment_priority())
+        self.logger.debug(f"Added strategy: {strategy}")
+
+    def remove_strategy(self, strategy_class: type) -> bool:
+        """Remove a deployment strategy by class type.
+
+        Args:
+            strategy_class: The class type of strategy to remove
+
+        Returns:
+            True if strategy was removed, False if not found
+        """
+        original_count = len(self._strategies)
+        self._strategies = [
+            s for s in self._strategies if not isinstance(s, strategy_class)
+        ]
+        removed = len(self._strategies) < original_count
+
+        if removed:
+            self.logger.debug(f"Removed strategy of type: {strategy_class.__name__}")
+
+        return removed
+
+    def get_strategy_for_context(
+        self, context: DeploymentContext
+    ) -> Optional[BaseDeploymentStrategy]:
+        """Get strategy for context without raising exceptions.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            Selected strategy or None if no strategy can handle the context
+        """
+        try:
+            return self.select_strategy(context)
+        except RuntimeError:
+            return None

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

@@ -0,0 +1,116 @@
+"""System agent deployment strategy."""
+
+from pathlib import Path
+
+from claude_mpm.core.unified_paths import get_path_manager
+
+from .base_strategy import BaseDeploymentStrategy, DeploymentContext
+
+
+class SystemAgentDeploymentStrategy(BaseDeploymentStrategy):
+    """Strategy for deploying system-wide agents.
+
+    System agents are the default agents provided by claude-mpm,
+    deployed to ~/.claude/agents/ for global availability.
+    """
+
+    def __init__(self):
+        super().__init__("System Agent Deployment")
+
+    def can_handle(self, context: DeploymentContext) -> bool:
+        """Check if this is a system agent deployment.
+
+        System deployment is the default when:
+        - No specific target directory is provided, OR
+        - Templates directory points to system templates, OR
+        - Working directory is not set (CLI usage)
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            True if this should handle system agent deployment
+        """
+        # If templates_dir points to system templates, this is system deployment
+        if context.templates_dir:
+            system_templates_dir = (
+                get_path_manager().get_user_agents_dir() / "templates"
+            )
+            if context.templates_dir.resolve() == system_templates_dir.resolve():
+                return True
+
+        # If no target_dir specified and no working_directory, assume system deployment
+        if not context.target_dir and not context.working_directory:
+            return True
+
+        # If target_dir points to user's home .claude directory
+        if context.target_dir:
+            home_claude_dir = Path.home() / ".claude" / "agents"
+            if context.target_dir.resolve() == home_claude_dir.resolve():
+                return True
+
+        return False
+
+    def determine_target_directory(self, context: DeploymentContext) -> Path:
+        """Determine target directory for system agents.
+
+        System agents are always deployed to ~/.claude/agents/
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            Path to ~/.claude/agents/
+        """
+        return Path.home() / ".claude" / "agents"
+
+    def get_templates_directory(self, context: DeploymentContext) -> Path:
+        """Get templates directory for system agents.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            Path to system templates directory
+        """
+        if context.templates_dir:
+            return context.templates_dir
+        return get_path_manager().get_user_agents_dir() / "templates"
+
+    def get_excluded_agents(self, context: DeploymentContext) -> List[str]:
+        """Get excluded agents for system deployment.
+
+        System deployment respects global exclusion configuration.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            List of excluded agent names
+        """
+        if not context.config:
+            return []
+
+        return context.config.get("agent_deployment.excluded_agents", [])
+
+    def should_deploy_system_instructions(self, context: DeploymentContext) -> bool:
+        """System deployment should deploy system instructions.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            True - system deployment includes instructions
+        """
+        return True
+
+    def get_deployment_priority(self) -> int:
+        """System deployment has lowest priority (highest number).
+
+        This ensures project and user deployments take precedence
+        when multiple strategies could handle the same context.
+
+        Returns:
+            Priority 100 (lowest priority)
+        """
+        return 100

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

@@ -0,0 +1,137 @@
+"""User-specific agent deployment strategy."""
+
+from pathlib import Path
+
+from .base_strategy import BaseDeploymentStrategy, DeploymentContext
+
+
+class UserAgentDeploymentStrategy(BaseDeploymentStrategy):
+    """Strategy for deploying user-specific agents.
+
+    User agents are custom agents created by the user,
+    deployed to user-specific directories.
+    """
+
+    def __init__(self):
+        super().__init__("User Agent Deployment")
+
+    def can_handle(self, context: DeploymentContext) -> bool:
+        """Check if this is a user-specific deployment.
+
+        User deployment when:
+        - Templates directory is in ~/.claude-mpm/agents/, OR
+        - Target directory is explicitly set to user directory, OR
+        - Environment variable CLAUDE_MPM_USER_PWD is set
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            True if this should handle user agent deployment
+        """
+        # Check if templates_dir is in user's home directory
+        if context.templates_dir:
+            user_agents_dir = Path.home() / ".claude-mpm" / "agents"
+            try:
+                context.templates_dir.resolve().relative_to(user_agents_dir.resolve())
+                return True
+            except ValueError:
+                # templates_dir is not within user agents directory
+                pass
+
+        # Check if target_dir is explicitly set to user directory
+        if context.target_dir:
+            user_claude_dir = Path.home() / ".claude-mpm" / "agents"
+            if context.target_dir.resolve() == user_claude_dir.resolve():
+                return True
+
+        # Check for user-specific environment variable
+        import os
+
+        if "CLAUDE_MPM_USER_PWD" in os.environ:
+            return True
+
+        return False
+
+    def determine_target_directory(self, context: DeploymentContext) -> Path:
+        """Determine target directory for user agents.
+
+        User agents can be deployed to various user-specific locations.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            Path to user agents directory
+        """
+        if context.target_dir:
+            return context.target_dir
+
+        # Check for user-specific environment variable
+        import os
+
+        if "CLAUDE_MPM_USER_PWD" in os.environ:
+            user_pwd = Path(os.environ["CLAUDE_MPM_USER_PWD"])
+            return user_pwd / ".claude" / "agents"
+
+        # Default to user's home directory
+        return Path.home() / ".claude-mpm" / "agents"
+
+    def get_templates_directory(self, context: DeploymentContext) -> Path:
+        """Get templates directory for user agents.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            Path to user templates directory
+        """
+        if context.templates_dir:
+            return context.templates_dir
+
+        # User-specific templates directory
+        return Path.home() / ".claude-mpm" / "agents"
+
+    def get_excluded_agents(self, context: DeploymentContext) -> List[str]:
+        """Get excluded agents for user deployment.
+
+        User deployment typically has minimal exclusions.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            List of excluded agent names (usually empty for user deployment)
+        """
+        if not context.config:
+            return []
+
+        # User deployments might have different exclusion rules
+        # or might ignore global exclusions
+        return context.config.get("agent_deployment.user_excluded_agents", [])
+
+    def should_deploy_system_instructions(self, context: DeploymentContext) -> bool:
+        """User deployment may or may not deploy system instructions.
+
+        Depends on user preferences and configuration.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            True if user wants system instructions deployed
+        """
+        if context.config:
+            return context.config.get("agent_deployment.deploy_user_instructions", True)
+        return True
+
+    def get_deployment_priority(self) -> int:
+        """User deployment has highest priority.
+
+        User-specific deployments should take precedence over
+        system and project deployments.
+
+        Returns:
+            Priority 10 (highest priority)
+        """
+        return 10

claude_mpm/services/agents/deployment/system_instructions_deployer.py

@@ -0,0 +1,108 @@
+"""System instructions deployment for agent deployment service.
+
+This module handles deployment of system instructions and framework files.
+Extracted from AgentDeploymentService to reduce complexity and improve maintainability.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any, Dict
+
+
+class SystemInstructionsDeployer:
+    """Handles deployment of system instructions and framework files."""
+
+    def __init__(self, logger: logging.Logger, working_directory: Path):
+        """Initialize the deployer with logger and working directory."""
+        self.logger = logger
+        self.working_directory = working_directory
+
+    def deploy_system_instructions(
+        self,
+        target_dir: Path,
+        force_rebuild: bool,
+        results: Dict[str, Any],
+        is_project_specific: bool,
+    ) -> None:
+        """
+        Deploy system instructions and framework files for PM framework.
+
+        Deploys INSTRUCTIONS.md, WORKFLOW.md, and MEMORY.md files following hierarchy:
+        - System/User versions → Deploy to ~/.claude/
+        - Project-specific versions → Deploy to <project>/.claude/
+
+        Args:
+            target_dir: Target directory for deployment
+            force_rebuild: Force rebuild even if exists
+            results: Results dictionary to update
+            is_project_specific: Whether this is a project-specific deployment
+        """
+        try:
+            # Determine target location based on deployment type
+            if is_project_specific:
+                # Project-specific files go to project's .claude directory
+                claude_dir = self.working_directory / ".claude"
+            else:
+                # System and user files go to home ~/.claude directory
+                claude_dir = Path.home() / ".claude"
+
+            # Ensure .claude directory exists
+            claude_dir.mkdir(parents=True, exist_ok=True)
+
+            # Framework files to deploy
+            framework_files = [
+                (
+                    "INSTRUCTIONS.md",
+                    "CLAUDE.md",
+                ),  # INSTRUCTIONS.md deploys as CLAUDE.md
+                ("WORKFLOW.md", "WORKFLOW.md"),
+                ("MEMORY.md", "MEMORY.md"),
+            ]
+
+            # Find the agents directory with framework files
+            # Use centralized paths for consistency
+            from claude_mpm.config.paths import paths
+
+            agents_path = paths.agents_dir
+
+            for source_name, target_name in framework_files:
+                source_path = agents_path / source_name
+
+                if not source_path.exists():
+                    self.logger.warning(f"Framework file not found: {source_path}")
+                    continue
+
+                target_file = claude_dir / target_name
+
+                # Check if update needed
+                if not force_rebuild and target_file.exists():
+                    # Compare modification times
+                    if target_file.stat().st_mtime >= source_path.stat().st_mtime:
+                        results["skipped"].append(target_name)
+                        self.logger.debug(f"Framework file {target_name} up to date")
+                        continue
+
+                # Read and deploy framework file
+                file_content = source_path.read_text()
+                target_file.write_text(file_content)
+
+                # Track deployment
+                file_existed = target_file.exists()
+                deployment_info = {
+                    "name": target_name,
+                    "template": str(source_path),
+                    "target": str(target_file),
+                }
+
+                if file_existed:
+                    results["updated"].append(deployment_info)
+                    self.logger.info(f"Updated framework file: {target_name}")
+                else:
+                    results["deployed"].append(deployment_info)
+                    self.logger.info(f"Deployed framework file: {target_name}")
+
+        except Exception as e:
+            error_msg = f"Failed to deploy system instructions: {e}"
+            self.logger.error(error_msg)
+            results["errors"].append(error_msg)
+            # Not raising AgentDeploymentError as this is non-critical

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

@@ -0,0 +1,19 @@
+"""Validation services for agent deployment.
+
+This module provides validation services for agent deployment,
+including template validation, agent file validation, and
+deployment environment validation.
+"""
+
+from .agent_validator import AgentValidator
+from .deployment_validator import DeploymentValidator
+from .template_validator import TemplateValidator
+from .validation_result import ValidationResult, ValidationSeverity
+
+__all__ = [
+    "DeploymentValidator",
+    "AgentValidator",
+    "TemplateValidator",
+    "ValidationResult",
+    "ValidationSeverity",
+]