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

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,131 @@
+"""System agent deployment strategy."""
+
+from pathlib import Path
+from typing import List
+
+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:
+            # Check for user system templates directory
+            system_templates_dir = (
+                get_path_manager().get_user_agents_dir() / "templates"
+            )
+            if context.templates_dir.resolve() == system_templates_dir.resolve():
+                return True
+
+            # Check for framework templates directory (packaged installation)
+            framework_templates_dir = (
+                get_path_manager().get_agents_dir("framework") / "templates"
+            )
+            if context.templates_dir.resolve() == framework_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.
+
+        MODIFIED: System agents are now deployed to project .claude/agents/
+        to maintain consistency with the new deployment behavior.
+        All agents (system, user, project) deploy to the project level.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            Path to <project>/.claude/agents/
+        """
+        # Always deploy to project directory
+        if context.working_directory:
+            return context.working_directory / ".claude" / "agents"
+        # Fallback to current working directory if not specified
+        return Path.cwd() / ".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,130 @@
+"""User-specific agent deployment strategy."""
+
+from pathlib import Path
+from typing import List
+
+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
+
+        return "CLAUDE_MPM_USER_PWD" in os.environ
+
+    def determine_target_directory(self, context: DeploymentContext) -> Path:
+        """Determine target directory for user agents.
+
+        MODIFIED: User agents are now deployed to project .claude/agents/
+        to maintain consistency with the new deployment behavior.
+        All agents (system, user, project) deploy to the project level.
+
+        Args:
+            context: Deployment context
+
+        Returns:
+            Path to <project>/.claude/agents/
+        """
+        # Always deploy to project directory
+        if context.working_directory:
+            return context.working_directory / ".claude" / "agents"
+        # Fallback to current working directory if not specified
+        return Path.cwd() / ".claude" / "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,228 @@
+"""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
+import shutil
+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],
+    ) -> None:
+        """
+        Deploy system instructions and framework files for PM framework.
+
+        Deploys to project .claude-mpm directory as merged PM_INSTRUCTIONS_DEPLOYED.md
+        containing PM_INSTRUCTIONS.md + WORKFLOW.md + MEMORY.md.
+
+        Args:
+            target_dir: Target directory for deployment (not used - always uses project .claude-mpm)
+            force_rebuild: Force rebuild even if exists
+            results: Results dictionary to update
+        """
+        try:
+            # Deploy to project's .claude-mpm directory (project-local)
+            claude_mpm_dir = self.working_directory / ".claude-mpm"
+
+            # Ensure .claude-mpm directory exists
+            claude_mpm_dir.mkdir(parents=True, exist_ok=True)
+
+            # Find the agents directory with framework files
+            # Use centralized paths for consistency
+            from claude_mpm.config.paths import paths
+
+            agents_path = paths.agents_dir
+
+            # Read and merge PM_INSTRUCTIONS.md + WORKFLOW.md + MEMORY.md
+            pm_instructions_path = agents_path / "PM_INSTRUCTIONS.md"
+            workflow_path = agents_path / "WORKFLOW.md"
+            memory_path = agents_path / "MEMORY.md"
+
+            merged_content = []
+            source_files = []
+
+            for path in [pm_instructions_path, workflow_path, memory_path]:
+                if path.exists():
+                    merged_content.append(path.read_text())
+                    source_files.append(str(path))
+                else:
+                    self.logger.warning(f"Framework file not found: {path}")
+
+            if not merged_content:
+                self.logger.error("No framework files found to merge")
+                results["errors"].append("No framework files found to merge")
+                return
+
+            # Determine the most recent modification time of source files
+            latest_mtime = max(
+                path.stat().st_mtime
+                for path in [pm_instructions_path, workflow_path, memory_path]
+                if path.exists()
+            )
+
+            # Write merged content to PM_INSTRUCTIONS_DEPLOYED.md
+            target_file = claude_mpm_dir / "PM_INSTRUCTIONS_DEPLOYED.md"
+
+            # Check if update needed
+            if (
+                not force_rebuild
+                and target_file.exists()
+                and target_file.stat().st_mtime >= latest_mtime
+            ):
+                # File is up to date based on modification time
+                results["skipped"].append("PM_INSTRUCTIONS_DEPLOYED.md")
+                self.logger.debug("PM_INSTRUCTIONS_DEPLOYED.md up to date")
+            else:
+                # Check if file exists before writing (for proper tracking)
+                file_existed = target_file.exists()
+
+                # Write merged content
+                target_file.write_text("\n\n".join(merged_content))
+
+                # Track deployment
+                deployment_info = {
+                    "name": "PM_INSTRUCTIONS_DEPLOYED.md",
+                    "template": ", ".join(source_files),
+                    "target": str(target_file),
+                }
+
+                if file_existed:
+                    results["updated"].append(deployment_info)
+                    self.logger.info("Updated merged PM_INSTRUCTIONS_DEPLOYED.md")
+                else:
+                    results["deployed"].append(deployment_info)
+                    self.logger.info("Deployed merged PM_INSTRUCTIONS_DEPLOYED.md")
+
+        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
+
+        # Also deploy templates directory
+        self.deploy_templates(claude_mpm_dir, force_rebuild, results)
+
+    def deploy_templates(
+        self,
+        claude_mpm_dir: Path,
+        force_rebuild: bool,
+        results: Dict[str, Any],
+    ) -> None:
+        """
+        Deploy PM instruction template files to project .claude-mpm/templates directory.
+
+        Only deploys PM instruction templates (not agent definition templates).
+        Templates are documentation files referenced in PM_INSTRUCTIONS.md that provide
+        detailed protocols, examples, and matrices.
+
+        Args:
+            claude_mpm_dir: Project .claude-mpm directory
+            force_rebuild: Force rebuild even if exists
+            results: Results dictionary to update
+        """
+        try:
+            # Find templates source directory
+            from claude_mpm.config.paths import paths
+
+            templates_source = paths.agents_dir / "templates"
+
+            if not templates_source.exists():
+                self.logger.warning(
+                    f"Templates source directory not found: {templates_source}"
+                )
+                return
+
+            # Create templates target directory
+            templates_target = claude_mpm_dir / "templates"
+            templates_target.mkdir(parents=True, exist_ok=True)
+
+            # Only deploy PM instruction templates (not agent definitions)
+            pm_templates = [
+                "circuit-breakers.md",
+                "context-management-examples.md",
+                "git-file-tracking.md",
+                "pm-examples.md",
+                "pm-red-flags.md",
+                "pr-workflow-examples.md",
+                "research-gate-examples.md",
+                "response-format.md",
+                "structured-questions-examples.md",
+                "ticketing-examples.md",
+                "validation-templates.md",
+            ]
+
+            # Get template files that exist
+            template_files = [
+                templates_source / name
+                for name in pm_templates
+                if (templates_source / name).exists()
+            ]
+
+            deployed_count = 0
+            skipped_count = 0
+            missing_count = 0
+
+            # Track missing templates
+            for name in pm_templates:
+                if not (templates_source / name).exists():
+                    self.logger.warning(f"PM template not found: {name}")
+                    missing_count += 1
+
+            for template_file in template_files:
+                target_file = templates_target / template_file.name
+
+                # Check if update needed
+                if (
+                    not force_rebuild
+                    and target_file.exists()
+                    and target_file.stat().st_mtime >= template_file.stat().st_mtime
+                ):
+                    skipped_count += 1
+                    continue
+
+                # Copy template file
+                shutil.copy2(template_file, target_file)
+                deployed_count += 1
+
+                self.logger.debug(f"Deployed PM template: {template_file.name}")
+
+            # Track results
+            if deployed_count > 0:
+                template_info = {
+                    "name": "templates/",
+                    "count": deployed_count,
+                    "target": str(templates_target),
+                }
+                results["deployed"].append(template_info)
+                self.logger.info(
+                    f"Deployed {deployed_count} PM template files to {templates_target}"
+                )
+
+            if skipped_count > 0:
+                self.logger.debug(
+                    f"Skipped {skipped_count} up-to-date PM template files"
+                )
+
+            if missing_count > 0:
+                self.logger.warning(f"{missing_count} PM templates not found in source")
+
+        except Exception as e:
+            error_msg = f"Failed to deploy templates: {e}"
+            self.logger.error(error_msg)
+            results["errors"].append(error_msg)
+            # Not raising exception as template deployment is non-critical

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

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