claude-mpm 4.13.2__py3-none-any.whl → 4.14.0__py3-none-any.whl

claude_mpm/services/core/interfaces/process.py

@@ -0,0 +1,372 @@
+"""
+Process Management Interfaces for Claude MPM Framework
+=======================================================
+
+WHY: This module defines interfaces for local process management operations,
+enabling the local-ops-agent to spawn, track, and manage background processes
+with proper isolation, state persistence, and port conflict prevention.
+
+DESIGN DECISION: Process management interfaces are separated from other service
+interfaces to maintain clear boundaries between deployment operations and other
+system services.
+
+ARCHITECTURE:
+- ILocalProcessManager: Core interface for process lifecycle management
+- IDeploymentStateManager: Interface for persistent state tracking
+- Process data models defined in models/process.py
+
+USAGE:
+    state_manager = DeploymentStateManager(state_file_path)
+    process_manager = LocalProcessManager(state_manager)
+
+    config = StartConfig(
+        command=["npm", "run", "dev"],
+        working_directory="/path/to/project",
+        port=3000
+    )
+
+    deployment = await process_manager.start(config)
+    print(f"Started process {deployment.process_id} on port {deployment.port}")
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+
+from claude_mpm.services.core.models.process import (
+    DeploymentState,
+    ProcessInfo,
+    ProcessStatus,
+    StartConfig,
+)
+
+
+class IDeploymentStateManager(ABC):
+    """
+    Interface for deployment state persistence and management.
+
+    WHY: State persistence is critical for tracking processes across restarts
+    and preventing orphaned processes. This interface abstracts the storage
+    mechanism to enable different backends (JSON file, database, etc.).
+
+    DESIGN DECISION: Provides both low-level (save/load) and high-level (query)
+    operations to support different use cases. Uses file locking to prevent
+    corruption from concurrent access.
+
+    Thread Safety: All operations must be thread-safe with proper locking.
+    """
+
+    @abstractmethod
+    def load_state(self) -> Dict[str, DeploymentState]:
+        """
+        Load all deployment states from persistent storage.
+
+        Returns:
+            Dictionary mapping deployment_id to DeploymentState
+
+        Raises:
+            StateCorruptionError: If state file is corrupted
+            IOError: If state file cannot be read
+        """
+
+    @abstractmethod
+    def save_state(self, states: Dict[str, DeploymentState]) -> None:
+        """
+        Save all deployment states to persistent storage.
+
+        Args:
+            states: Dictionary mapping deployment_id to DeploymentState
+
+        Raises:
+            IOError: If state file cannot be written
+        """
+
+    @abstractmethod
+    def get_deployment(self, deployment_id: str) -> Optional[DeploymentState]:
+        """
+        Get a specific deployment by ID.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            DeploymentState if found, None otherwise
+        """
+
+    @abstractmethod
+    def get_all_deployments(self) -> List[DeploymentState]:
+        """
+        Get all tracked deployments.
+
+        Returns:
+            List of all DeploymentState objects
+        """
+
+    @abstractmethod
+    def get_deployments_by_status(self, status: ProcessStatus) -> List[DeploymentState]:
+        """
+        Get all deployments with a specific status.
+
+        Args:
+            status: ProcessStatus to filter by
+
+        Returns:
+            List of matching DeploymentState objects
+        """
+
+    @abstractmethod
+    def get_deployment_by_port(self, port: int) -> Optional[DeploymentState]:
+        """
+        Get deployment using a specific port.
+
+        Args:
+            port: Port number to search for
+
+        Returns:
+            DeploymentState if found, None otherwise
+        """
+
+    @abstractmethod
+    def get_deployments_by_project(
+        self, working_directory: str
+    ) -> List[DeploymentState]:
+        """
+        Get all deployments for a specific project directory.
+
+        Args:
+            working_directory: Project directory path
+
+        Returns:
+            List of matching DeploymentState objects
+        """
+
+    @abstractmethod
+    def add_deployment(self, deployment: DeploymentState) -> None:
+        """
+        Add or update a deployment in state.
+
+        Args:
+            deployment: DeploymentState to add/update
+
+        Raises:
+            IOError: If state cannot be persisted
+        """
+
+    @abstractmethod
+    def remove_deployment(self, deployment_id: str) -> bool:
+        """
+        Remove a deployment from state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if deployment was removed, False if not found
+
+        Raises:
+            IOError: If state cannot be persisted
+        """
+
+    @abstractmethod
+    def update_deployment_status(
+        self, deployment_id: str, status: ProcessStatus
+    ) -> bool:
+        """
+        Update the status of a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            status: New ProcessStatus
+
+        Returns:
+            True if updated, False if deployment not found
+
+        Raises:
+            IOError: If state cannot be persisted
+        """
+
+    @abstractmethod
+    def cleanup_dead_pids(self) -> int:
+        """
+        Remove deployments with dead process IDs.
+
+        WHY: Processes may crash or be killed externally. This method cleans
+        up stale state entries for processes that no longer exist.
+
+        Returns:
+            Number of dead PIDs cleaned up
+
+        Raises:
+            IOError: If state cannot be persisted
+        """
+
+
+class ILocalProcessManager(ABC):
+    """
+    Interface for local process lifecycle management.
+
+    WHY: Process management involves complex operations like spawning, tracking,
+    and terminating background processes. This interface abstracts these operations
+    to enable different implementations and improve testability.
+
+    DESIGN DECISION: Provides high-level operations (start, stop, restart) that
+    handle all the complexity internally including port checking, process group
+    isolation, and state tracking.
+
+    Process Lifecycle:
+    1. Start: Spawn process with isolation and port checking
+    2. Monitor: Track status and update state
+    3. Stop: Graceful shutdown with fallback to force kill
+    4. Cleanup: Remove state and release resources
+    """
+
+    @abstractmethod
+    def start(self, config: StartConfig) -> DeploymentState:
+        """
+        Start a new background process.
+
+        WHY: Combines process spawning, port allocation, and state tracking in
+        a single operation to ensure consistency.
+
+        Args:
+            config: Configuration for the process to start
+
+        Returns:
+            DeploymentState with process information
+
+        Raises:
+            ProcessSpawnError: If process cannot be spawned
+            PortConflictError: If requested port is unavailable and no alternative found
+            ValueError: If configuration is invalid
+        """
+
+    @abstractmethod
+    def stop(self, deployment_id: str, timeout: int = 10, force: bool = False) -> bool:
+        """
+        Stop a running process.
+
+        WHY: Provides graceful shutdown with configurable timeout and force
+        option for stuck processes.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            timeout: Seconds to wait for graceful shutdown
+            force: If True, kill immediately without waiting
+
+        Returns:
+            True if process stopped successfully
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def restart(self, deployment_id: str, timeout: int = 10) -> DeploymentState:
+        """
+        Restart a process (stop then start with same config).
+
+        Args:
+            deployment_id: Unique deployment identifier
+            timeout: Seconds to wait for graceful shutdown
+
+        Returns:
+            New DeploymentState after restart
+
+        Raises:
+            ValueError: If deployment_id not found
+            ProcessSpawnError: If restart fails
+        """
+
+    @abstractmethod
+    def get_status(self, deployment_id: str) -> Optional[ProcessInfo]:
+        """
+        Get current status and runtime information for a process.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            ProcessInfo with current status, or None if not found
+        """
+
+    @abstractmethod
+    def list_processes(
+        self, status_filter: Optional[ProcessStatus] = None
+    ) -> List[ProcessInfo]:
+        """
+        List all managed processes.
+
+        Args:
+            status_filter: Optional status to filter by
+
+        Returns:
+            List of ProcessInfo for all matching processes
+        """
+
+    @abstractmethod
+    def is_port_available(self, port: int) -> bool:
+        """
+        Check if a port is available for use.
+
+        WHY: Port conflict prevention is critical for reliable deployments.
+        This check happens before process spawn.
+
+        Args:
+            port: Port number to check
+
+        Returns:
+            True if port is available
+        """
+
+    @abstractmethod
+    def find_available_port(
+        self, preferred_port: int, max_attempts: int = 10
+    ) -> Optional[int]:
+        """
+        Find an available port starting from preferred_port.
+
+        WHY: Uses linear probing to find alternative ports when the preferred
+        port is unavailable. Respects protected port ranges.
+
+        Args:
+            preferred_port: Starting port number
+            max_attempts: Maximum number of ports to try
+
+        Returns:
+            Available port number, or None if none found
+        """
+
+    @abstractmethod
+    def cleanup_orphans(self) -> int:
+        """
+        Clean up orphaned process state entries.
+
+        WHY: Processes may crash or be killed externally, leaving stale state.
+        This method identifies and cleans up these orphans.
+
+        Returns:
+            Number of orphaned entries cleaned up
+        """
+
+    @abstractmethod
+    def generate_deployment_id(
+        self, project_name: str, port: Optional[int] = None
+    ) -> str:
+        """
+        Generate a unique deployment ID.
+
+        WHY: Provides consistent ID generation with optional port suffix for
+        projects with multiple deployments.
+
+        Args:
+            project_name: Name of the project
+            port: Optional port number to include in ID
+
+        Returns:
+            Unique deployment identifier
+        """
+
+
+__all__ = [
+    "IDeploymentStateManager",
+    "ILocalProcessManager",
+]

claude_mpm/services/core/interfaces/restart.py

@@ -0,0 +1,307 @@
+"""
+Restart Management Interfaces for Claude MPM Framework
+========================================================
+
+WHY: This module defines interfaces for auto-restart functionality with crash
+detection, intelligent restart policies, and circuit breaker patterns.
+
+DESIGN DECISION: Restart interfaces are separated to enable modular restart
+management with different crash detection strategies and restart policies.
+
+ARCHITECTURE:
+- ICrashDetector: Interface for detecting process crashes and failures
+- IRestartPolicy: Interface for restart decision logic with backoff
+- IRestartManager: Interface for orchestrating the full restart workflow
+
+USAGE:
+    crash_detector = CrashDetector(health_manager)
+    restart_policy = RestartPolicy(config)
+    restart_manager = RestartManager(
+        process_manager=process_manager,
+        health_manager=health_manager,
+        config=config
+    )
+    restart_manager.enable_auto_restart(deployment_id)
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Callable, Optional
+
+if TYPE_CHECKING:
+    from claude_mpm.services.core.models.restart import RestartHistory
+
+
+class ICrashDetector(ABC):
+    """
+    Interface for detecting process crashes and failures.
+
+    WHY: Crash detection requires monitoring health status changes, process
+    exits, and zombie states. This interface abstracts different detection
+    strategies to enable flexible crash monitoring.
+
+    DESIGN DECISION: Integrates with IHealthCheckManager via callbacks to
+    receive real-time status updates. Tracks crash history per deployment
+    to enable pattern detection.
+
+    Thread Safety: Implementations must be thread-safe for concurrent monitoring.
+    """
+
+    @abstractmethod
+    def register_crash_callback(self, callback: Callable[[str, str], None]) -> None:
+        """
+        Register a callback to be invoked when a crash is detected.
+
+        Args:
+            callback: Function called with (deployment_id, reason)
+        """
+
+    @abstractmethod
+    def start_monitoring(self, deployment_id: str) -> None:
+        """
+        Start monitoring a deployment for crashes.
+
+        WHY: Enables targeted monitoring for specific deployments.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def stop_monitoring(self, deployment_id: str) -> None:
+        """
+        Stop monitoring a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+    @abstractmethod
+    def is_monitoring(self, deployment_id: str) -> bool:
+        """
+        Check if a deployment is being monitored.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if deployment is being monitored
+        """
+
+    @abstractmethod
+    def get_crash_count(self, deployment_id: str) -> int:
+        """
+        Get the number of crashes detected for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Number of crashes detected
+        """
+
+
+class IRestartPolicy(ABC):
+    """
+    Interface for restart decision logic with exponential backoff.
+
+    WHY: Restart policies prevent restart loops through exponential backoff,
+    max attempts, and circuit breaker patterns. This interface abstracts
+    the decision-making logic to enable different strategies.
+
+    DESIGN DECISION: Implements exponential backoff with configurable
+    parameters and circuit breaker state transitions (CLOSED → OPEN → HALF_OPEN).
+
+    Circuit Breaker States:
+    - CLOSED: Normal operation, restarts allowed
+    - OPEN: Circuit breaker tripped, restarts blocked
+    - HALF_OPEN: Testing if service recovered
+    """
+
+    @abstractmethod
+    def should_restart(self, deployment_id: str) -> bool:
+        """
+        Determine if a deployment should be restarted.
+
+        WHY: Central decision point that considers attempt count, circuit
+        breaker state, and backoff timing.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if restart should proceed
+        """
+
+    @abstractmethod
+    def calculate_backoff(self, deployment_id: str) -> float:
+        """
+        Calculate backoff time in seconds for next restart.
+
+        WHY: Implements exponential backoff to prevent restart storms.
+        Formula: min(initial * (multiplier ** (attempt - 1)), max_backoff)
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Backoff time in seconds (0 if first attempt)
+        """
+
+    @abstractmethod
+    def record_restart_attempt(
+        self, deployment_id: str, success: bool, failure_reason: Optional[str] = None
+    ) -> None:
+        """
+        Record a restart attempt and update circuit breaker state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            success: Whether restart succeeded
+            failure_reason: Optional reason for failure
+        """
+
+    @abstractmethod
+    def reset_restart_history(self, deployment_id: str) -> None:
+        """
+        Reset restart history for a deployment.
+
+        WHY: Clears restart attempts after successful recovery or manual
+        intervention.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+    @abstractmethod
+    def get_circuit_breaker_state(self, deployment_id: str) -> str:
+        """
+        Get current circuit breaker state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Circuit breaker state (CLOSED, OPEN, HALF_OPEN)
+        """
+
+    @abstractmethod
+    def get_restart_attempt_count(self, deployment_id: str) -> int:
+        """
+        Get number of restart attempts for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Number of restart attempts
+        """
+
+
+class IRestartManager(ABC):
+    """
+    Interface for orchestrating the complete restart workflow.
+
+    WHY: Restart management requires coordinating crash detection, policy
+    evaluation, process restart, and health verification. This interface
+    provides a high-level API for automatic and manual restarts.
+
+    DESIGN DECISION: Provides both automatic (background) and manual
+    (on-demand) restart operations. Integrates with all components:
+    CrashDetector, RestartPolicy, ProcessManager, and HealthCheckManager.
+
+    Restart Workflow:
+    1. Detect crash (via CrashDetector callback)
+    2. Check restart policy (max attempts, circuit breaker)
+    3. Wait for backoff period
+    4. Execute restart (preserve original StartConfig)
+    5. Verify health after restart
+    6. Record attempt and update circuit breaker
+    """
+
+    @abstractmethod
+    def enable_auto_restart(self, deployment_id: str) -> None:
+        """
+        Enable automatic restarts for a deployment.
+
+        WHY: Enables hands-free recovery from crashes. Starts monitoring
+        via CrashDetector and registers restart callbacks.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def disable_auto_restart(self, deployment_id: str) -> None:
+        """
+        Disable automatic restarts for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+    @abstractmethod
+    def is_auto_restart_enabled(self, deployment_id: str) -> bool:
+        """
+        Check if auto-restart is enabled for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if auto-restart is enabled
+        """
+
+    @abstractmethod
+    def restart_deployment(self, deployment_id: str, manual: bool = False) -> bool:
+        """
+        Restart a deployment (manual or automatic trigger).
+
+        WHY: Provides unified restart operation that respects policy
+        constraints and performs health verification.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            manual: If True, bypass some policy checks (e.g., circuit breaker)
+
+        Returns:
+            True if restart succeeded
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def get_restart_history(self, deployment_id: str) -> Optional["RestartHistory"]:
+        """
+        Get restart history for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            RestartHistory if found, None otherwise
+        """
+
+    @abstractmethod
+    def clear_restart_history(self, deployment_id: str) -> None:
+        """
+        Clear restart history and reset circuit breaker.
+
+        WHY: Allows manual intervention to clear failed restart state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+
+__all__ = [
+    "ICrashDetector",
+    "IRestartManager",
+    "IRestartPolicy",
+]