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

claude_mpm/services/agents/deployment/pipeline/steps/agent_processing_step.py

@@ -0,0 +1,240 @@
+"""Agent processing step for deployment pipeline."""
+
+import time
+from pathlib import Path
+
+from claude_mpm.core.enums import OperationResult
+from claude_mpm.services.agents.deployment.processors import (
+    AgentDeploymentContext,
+    AgentDeploymentResult,
+    AgentProcessor,
+)
+
+from .base_step import BaseDeploymentStep, StepResult
+
+
+class AgentProcessingStep(BaseDeploymentStep):
+    """Step to process and deploy individual agents."""
+
+    def __init__(self, template_builder, version_manager):
+        super().__init__(
+            name="Agent Processing",
+            description="Process and deploy individual agent templates",
+        )
+        self.processor = AgentProcessor(template_builder, version_manager)
+
+    def execute(self, context) -> StepResult:
+        """Execute agent processing step.
+
+        Args:
+            context: Pipeline context
+
+        Returns:
+            Result of agent processing
+        """
+        start_time = time.time()
+
+        try:
+            if not context.template_files:
+                self.logger.warning("No template files to process")
+                return StepResult(
+                    status=OperationResult.SKIPPED,
+                    message="No template files found to process",
+                    execution_time=time.time() - start_time,
+                )
+
+            # Initialize results tracking
+            processed_count = 0
+            failed_count = 0
+
+            # Process each template file
+            for template_file in context.template_files:
+                try:
+                    # Determine source for this agent
+                    agent_name = template_file.stem
+                    # Use source from context if available (multi-source deployment), otherwise determine it
+                    if context.agent_sources and agent_name in context.agent_sources:
+                        source_info = context.agent_sources[agent_name]
+                    else:
+                        source_info = self._determine_agent_source(template_file)
+
+                    # Create agent deployment context
+                    agent_context = AgentDeploymentContext.from_template_file(
+                        template_file=template_file,
+                        agents_dir=context.actual_target_dir,
+                        base_agent_data=context.base_agent_data or {},
+                        base_agent_version=context.base_agent_version or (1, 0, 0),
+                        force_rebuild=context.force_rebuild,
+                        deployment_mode=context.deployment_mode,
+                        source_info=source_info,
+                    )
+
+                    # Validate agent if requested
+                    if context.should_repair_existing_agents:
+                        if not self.processor.validate_agent(agent_context):
+                            self.logger.warning(
+                                f"Agent validation failed: {agent_context.agent_name}"
+                            )
+                            context.add_warning(
+                                f"Agent validation failed: {agent_context.agent_name}"
+                            )
+                            failed_count += 1
+                            continue
+
+                    # Process the agent
+                    result = self.processor.process_agent(agent_context)
+
+                    # Update context results based on outcome
+                    self._update_context_with_result(context, result)
+
+                    if result.is_successful():
+                        processed_count += 1
+                    else:
+                        failed_count += 1
+
+                except Exception as e:
+                    error_msg = f"Failed to process agent {template_file.stem}: {e!s}"
+                    self.logger.error(error_msg, exc_info=True)
+                    context.add_error(error_msg)
+                    failed_count += 1
+
+            # Calculate execution time
+            execution_time = time.time() - start_time
+            context.step_timings[self.name] = execution_time
+
+            # Determine step status
+            if failed_count == 0:
+                status = OperationResult.SUCCESS
+                message = f"Successfully processed {processed_count} agents in {execution_time:.3f}s"
+            elif processed_count > 0:
+                status = OperationResult.WARNING
+                message = f"Processed {processed_count} agents with {failed_count} failures in {execution_time:.3f}s"
+            else:
+                status = OperationResult.FAILED
+                message = f"Failed to process any agents ({failed_count} failures) in {execution_time:.3f}s"
+
+            self.logger.info(message)
+
+            return StepResult(
+                status=status, message=message, execution_time=execution_time
+            )
+
+        except Exception as e:
+            execution_time = time.time() - start_time
+            context.step_timings[self.name] = execution_time
+
+            error_msg = f"Agent processing step failed: {e!s}"
+            self.logger.error(error_msg, exc_info=True)
+            context.add_error(error_msg)
+
+            return StepResult(
+                status=OperationResult.FAILED,
+                message=error_msg,
+                error=e,
+                execution_time=execution_time,
+            )
+
+    def _update_context_with_result(
+        self, context, result: AgentDeploymentResult
+    ) -> None:
+        """Update pipeline context with agent deployment result.
+
+        Args:
+            context: Pipeline context
+            result: Agent deployment result
+        """
+        # Ensure results structure exists
+        if "deployed" not in context.results:
+            context.results["deployed"] = []
+        if "updated" not in context.results:
+            context.results["updated"] = []
+        if "migrated" not in context.results:
+            context.results["migrated"] = []
+        if "skipped" not in context.results:
+            context.results["skipped"] = []
+        if "errors" not in context.results:
+            context.results["errors"] = []
+
+        # Add result to appropriate list
+        result_dict = result.to_dict()
+
+        if result.status.value == "deployed":
+            context.results["deployed"].append(result_dict)
+        elif result.status.value == "updated":
+            context.results["updated"].append(result_dict)
+        elif result.status.value == "migrated":
+            context.results["migrated"].append(result_dict)
+        elif result.status.value == "skipped":
+            context.results["skipped"].append(result.agent_name)
+        elif result.status.value == "failed":
+            context.results["errors"].append(
+                result.error_message or f"Failed to deploy {result.agent_name}"
+            )
+
+    def should_execute(self, context) -> bool:
+        """Check if this step should be executed.
+
+        Args:
+            context: Pipeline context
+
+        Returns:
+            True if there are template files to process
+        """
+        return bool(context.template_files)
+
+    def can_continue_on_failure(self) -> bool:
+        """Agent processing failures should not stop the pipeline.
+
+        Individual agent failures are tracked but don't prevent
+        other agents from being processed.
+
+        Returns:
+            True - continue on failure
+        """
+        return True
+
+    def get_dependencies(self) -> list:
+        """This step depends on target directory setup.
+
+        Returns:
+            List of required step classes
+        """
+        from .target_directory_step import TargetDirectorySetupStep
+
+        return [TargetDirectorySetupStep]
+
+    def _determine_agent_source(self, template_path: Path) -> str:
+        """Determine the source of an agent from its template path.
+
+        Args:
+            template_path: Path to the agent template
+
+        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
+            try:
+                from pathlib import Path
+
+                cwd = Path.cwd()
+                if str(cwd) in template_str:
+                    return "project"
+            except Exception:
+                pass
+
+        # Check if it's a user agent
+        if "/.claude/agents/" in template_str:
+            return "user"
+
+        return "unknown"

claude_mpm/services/agents/deployment/pipeline/steps/base_step.py

@@ -0,0 +1,110 @@
+"""Base deployment step interface."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+from claude_mpm.core.enums import OperationResult
+from claude_mpm.core.logger import get_logger
+
+
+@dataclass
+class StepResult:
+    """Result of executing a pipeline step."""
+
+    status: OperationResult
+    message: Optional[str] = None
+    error: Optional[Exception] = None
+    execution_time: Optional[float] = None
+
+    @property
+    def is_success(self) -> bool:
+        """Check if the step was successful."""
+        return self.status == OperationResult.SUCCESS
+
+    @property
+    def is_failure(self) -> bool:
+        """Check if the step failed."""
+        return self.status == OperationResult.FAILED
+
+    @property
+    def is_skipped(self) -> bool:
+        """Check if the step was skipped."""
+        return self.status == OperationResult.SKIPPED
+
+    @property
+    def is_warning(self) -> bool:
+        """Check if the step completed with warnings."""
+        return self.status == OperationResult.WARNING
+
+
+class BaseDeploymentStep(ABC):
+    """Base class for all deployment pipeline steps.
+
+    Each step in the deployment pipeline should inherit from this class
+    and implement the execute method. Steps can read from and modify
+    the pipeline context as needed.
+    """
+
+    def __init__(self, name: str, description: str = ""):
+        """Initialize the deployment step.
+
+        Args:
+            name: Human-readable name for this step
+            description: Optional description of what this step does
+        """
+        self.name = name
+        self.description = description
+        self.logger = get_logger(f"{__name__}.{self.__class__.__name__}")
+
+    @abstractmethod
+    def execute(self, context) -> "StepResult":
+        """Execute this deployment step.
+
+        Args:
+            context: Pipeline context containing deployment data
+
+        Returns:
+            Result of executing this step
+        """
+
+    def should_execute(self, context) -> bool:
+        """Check if this step should be executed.
+
+        Override this method to add conditional execution logic.
+
+        Args:
+            context: Pipeline context
+
+        Returns:
+            True if this step should be executed
+        """
+        return True
+
+    def can_continue_on_failure(self) -> bool:
+        """Check if pipeline can continue if this step fails.
+
+        Override this method for steps that are not critical.
+
+        Returns:
+            True if pipeline can continue after this step fails
+        """
+        return False
+
+    def get_dependencies(self) -> list:
+        """Get list of step classes this step depends on.
+
+        Override this method to specify dependencies.
+
+        Returns:
+            List of step classes that must execute before this step
+        """
+        return []
+
+    def __str__(self) -> str:
+        """String representation of the step."""
+        return f"{self.name}"
+
+    def __repr__(self) -> str:
+        """Detailed string representation of the step."""
+        return f"{self.__class__.__name__}(name='{self.name}', description='{self.description}')"

claude_mpm/services/agents/deployment/pipeline/steps/configuration_step.py

@@ -0,0 +1,80 @@
+"""Configuration loading step for deployment pipeline."""
+
+import time
+
+from claude_mpm.core.config import Config
+from claude_mpm.core.enums import OperationResult
+
+from .base_step import BaseDeploymentStep, StepResult
+
+
+class ConfigurationLoadStep(BaseDeploymentStep):
+    """Step to load and process deployment configuration."""
+
+    def __init__(self):
+        super().__init__(
+            name="Configuration Loading",
+            description="Load and process deployment configuration settings",
+        )
+
+    def execute(self, context) -> StepResult:
+        """Execute configuration loading step.
+
+        Args:
+            context: Pipeline context
+
+        Returns:
+            Result of configuration loading
+        """
+        start_time = time.time()
+
+        try:
+            # Load configuration if not provided
+            if context.config is None:
+                self.logger.debug("Loading default configuration")
+                context.config = Config()
+
+            # Extract excluded agents
+            context.excluded_agents = context.config.get(
+                "agent_deployment.excluded_agents", []
+            )
+
+            # Extract case sensitivity setting
+            context.case_sensitive_exclusion = context.config.get(
+                "agent_deployment.case_sensitive_exclusion", True
+            )
+
+            # Log configuration details
+            self.logger.info(
+                f"Loaded configuration with {len(context.excluded_agents)} excluded agents"
+            )
+            if context.excluded_agents:
+                self.logger.debug(f"Excluded agents: {context.excluded_agents}")
+
+            execution_time = time.time() - start_time
+            context.step_timings[self.name] = execution_time
+
+            return StepResult(
+                status=OperationResult.SUCCESS,
+                message=f"Configuration loaded successfully in {execution_time:.3f}s",
+                execution_time=execution_time,
+            )
+
+        except Exception as e:
+            execution_time = time.time() - start_time
+            context.step_timings[self.name] = execution_time
+
+            error_msg = f"Failed to load configuration: {e!s}"
+            self.logger.error(error_msg)
+            context.add_error(error_msg)
+
+            return StepResult(
+                status=OperationResult.FAILED,
+                message=error_msg,
+                error=e,
+                execution_time=execution_time,
+            )
+
+    def can_continue_on_failure(self) -> bool:
+        """Configuration loading failure should stop the pipeline."""
+        return False

claude_mpm/services/agents/deployment/pipeline/steps/target_directory_step.py

@@ -0,0 +1,92 @@
+"""Target directory setup step for deployment pipeline."""
+
+import time
+from pathlib import Path
+
+from claude_mpm.core.enums import OperationResult
+
+from .base_step import BaseDeploymentStep, StepResult
+
+
+class TargetDirectorySetupStep(BaseDeploymentStep):
+    """Step to determine and setup the target directory for deployment."""
+
+    def __init__(self):
+        super().__init__(
+            name="Target Directory Setup",
+            description="Determine and create the target directory for agent deployment",
+        )
+
+    def execute(self, context) -> StepResult:
+        """Execute target directory setup step.
+
+        Args:
+            context: Pipeline context
+
+        Returns:
+            Result of target directory setup
+        """
+        start_time = time.time()
+
+        try:
+            # Use strategy to determine target directory
+            if context.strategy:
+                context.actual_target_dir = context.strategy.determine_target_directory(
+                    context  # Pass the context which has the DeploymentContext interface
+                )
+            # Fallback logic if no strategy is set
+            elif context.target_dir:
+                context.actual_target_dir = context.target_dir
+            else:
+                # MODIFIED: Default to project .claude/agents directory
+                # All agents now deploy to the project level
+                context.actual_target_dir = Path.cwd() / ".claude" / "agents"
+
+            # Create target directory if it doesn't exist
+            context.actual_target_dir.mkdir(parents=True, exist_ok=True)
+
+            # Verify directory is writable
+            test_file = context.actual_target_dir / ".write_test"
+            try:
+                test_file.write_text("test")
+                test_file.unlink()
+            except Exception as e:
+                raise PermissionError(
+                    f"Target directory is not writable: {context.actual_target_dir}"
+                ) from e
+
+            self.logger.info(f"Target directory set up: {context.actual_target_dir}")
+
+            execution_time = time.time() - start_time
+            context.step_timings[self.name] = execution_time
+
+            return StepResult(
+                status=OperationResult.SUCCESS,
+                message=f"Target directory set up at {context.actual_target_dir} in {execution_time:.3f}s",
+                execution_time=execution_time,
+            )
+
+        except Exception as e:
+            execution_time = time.time() - start_time
+            context.step_timings[self.name] = execution_time
+
+            error_msg = f"Failed to set up target directory: {e!s}"
+            self.logger.error(error_msg)
+            context.add_error(error_msg)
+
+            return StepResult(
+                status=OperationResult.FAILED,
+                message=error_msg,
+                error=e,
+                execution_time=execution_time,
+            )
+
+    def can_continue_on_failure(self) -> bool:
+        """Target directory setup failure should stop the pipeline."""
+        return False
+
+    def get_dependencies(self) -> list:
+        """This step depends on configuration loading."""
+        from .configuration_step import ConfigurationLoadStep
+
+        return [ConfigurationLoadStep]

claude_mpm/services/agents/deployment/pipeline/steps/validation_step.py

@@ -0,0 +1,101 @@
+"""Validation step for deployment pipeline."""
+
+import time
+
+from claude_mpm.core.enums import OperationResult
+from claude_mpm.services.agents.deployment.validation import DeploymentValidator
+
+from .base_step import BaseDeploymentStep, StepResult
+
+
+class ValidationStep(BaseDeploymentStep):
+    """Step to validate deployment context and templates."""
+
+    def __init__(self):
+        super().__init__(
+            name="Validation",
+            description="Validate deployment environment, templates, and configuration",
+        )
+        self.validator = DeploymentValidator()
+
+    def execute(self, context) -> StepResult:
+        """Execute validation step.
+
+        Args:
+            context: Pipeline context
+
+        Returns:
+            Result of validation
+        """
+        start_time = time.time()
+
+        try:
+            # Validate deployment context
+            validation_result = self.validator.validate_deployment_context(context)
+
+            # Update context with validation results
+            if not validation_result.is_valid:
+                for error in validation_result.errors:
+                    context.add_error(str(error))
+
+            for warning in validation_result.warnings:
+                context.add_warning(str(warning))
+
+            # Store validation metadata
+            context.results["validation"] = validation_result.to_dict()
+
+            # Calculate execution time
+            execution_time = time.time() - start_time
+            context.step_timings[self.name] = execution_time
+
+            # Determine step status
+            if not validation_result.is_valid:
+                status = OperationResult.FAILED
+                message = f"Validation failed with {validation_result.error_count} errors in {execution_time:.3f}s"
+            elif validation_result.has_warnings:
+                status = OperationResult.WARNING
+                message = f"Validation completed with {validation_result.warning_count} warnings in {execution_time:.3f}s"
+            else:
+                status = OperationResult.SUCCESS
+                message = f"Validation passed successfully in {execution_time:.3f}s"
+
+            self.logger.info(message)
+
+            return StepResult(
+                status=status, message=message, execution_time=execution_time
+            )
+
+        except Exception as e:
+            execution_time = time.time() - start_time
+            context.step_timings[self.name] = execution_time
+
+            error_msg = f"Validation step failed: {e!s}"
+            self.logger.error(error_msg, exc_info=True)
+            context.add_error(error_msg)
+
+            return StepResult(
+                status=OperationResult.FAILED,
+                message=error_msg,
+                error=e,
+                execution_time=execution_time,
+            )
+
+    def can_continue_on_failure(self) -> bool:
+        """Validation failures should stop the pipeline.
+
+        If validation fails, it's not safe to continue with deployment.
+
+        Returns:
+            False - stop pipeline on validation failure
+        """
+        return False
+
+    def get_dependencies(self) -> list:
+        """This step depends on target directory setup.
+
+        Returns:
+            List of required step classes
+        """
+        from .target_directory_step import TargetDirectorySetupStep
+
+        return [TargetDirectorySetupStep]

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

@@ -0,0 +1,15 @@
+"""Agent processing components for deployment.
+
+This module provides classes for processing individual agents during deployment,
+including building, validation, and deployment logic.
+"""
+
+from .agent_deployment_context import AgentDeploymentContext
+from .agent_deployment_result import AgentDeploymentResult
+from .agent_processor import AgentProcessor
+
+__all__ = [
+    "AgentDeploymentContext",
+    "AgentDeploymentResult",
+    "AgentProcessor",
+]