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

claude_mpm/services/core/interfaces/communication.py

@@ -0,0 +1,316 @@
+"""
+Communication and External Service Interfaces for Claude MPM Framework
+======================================================================
+
+WHY: This module contains interfaces for external communication including
+WebSocket/SocketIO services, project analysis, and ticket management.
+These are grouped together because they handle external interactions.
+
+DESIGN DECISION: Communication interfaces are separated because they deal
+with external systems and protocols, requiring different error handling
+and reliability patterns than internal services.
+
+EXTRACTED FROM: services/core/interfaces.py (lines 1195-1397)
+- WebSocket/SocketIO communication
+- Project analysis
+- Ticket management
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+# WebSocket/SocketIO service interface
+class SocketIOServiceInterface(ABC):
+    """Interface for WebSocket communication.
+
+    WHY: Real-time communication is essential for monitoring and interactive
+    features. This interface abstracts WebSocket/SocketIO implementation to
+    enable different transport mechanisms and fallback strategies.
+
+    DESIGN DECISION: Provides both broadcasting and targeted messaging to
+    support different communication patterns and enable efficient updates.
+    """
+
+    @abstractmethod
+    def start_sync(self) -> None:
+        """Start the WebSocket server synchronously."""
+
+    @abstractmethod
+    def stop_sync(self) -> None:
+        """Stop the WebSocket server synchronously."""
+
+    @abstractmethod
+    def broadcast_event(self, event_type: str, data: Dict[str, Any]) -> None:
+        """Broadcast an event to all connected clients.
+
+        Args:
+            event_type: Type of event to broadcast
+            data: Event data to send
+        """
+
+    @abstractmethod
+    def send_to_client(
+        self, client_id: str, event_type: str, data: Dict[str, Any]
+    ) -> bool:
+        """Send an event to a specific client.
+
+        Args:
+            client_id: ID of the target client
+            event_type: Type of event to send
+            data: Event data to send
+
+        Returns:
+            True if message sent successfully
+        """
+
+    @abstractmethod
+    def get_connection_count(self) -> int:
+        """Get number of connected clients.
+
+        Returns:
+            Number of connected clients
+        """
+
+    @abstractmethod
+    def is_running(self) -> bool:
+        """Check if server is running.
+
+        Returns:
+            True if server is active
+        """
+
+    @abstractmethod
+    def session_started(
+        self, session_id: str, launch_method: str, working_dir: str
+    ) -> None:
+        """Notify that a session has started.
+
+        Args:
+            session_id: ID of the started session
+            launch_method: Method used to launch the session
+            working_dir: Working directory of the session
+        """
+
+    @abstractmethod
+    def session_ended(self) -> None:
+        """Notify that a session has ended."""
+
+    @abstractmethod
+    def claude_status_changed(
+        self, status: str, pid: Optional[int] = None, message: str = ""
+    ) -> None:
+        """Notify Claude status change.
+
+        Args:
+            status: New status of Claude
+            pid: Process ID if applicable
+            message: Optional status message
+        """
+
+    @abstractmethod
+    def agent_delegated(self, agent: str, task: str, status: str = "started") -> None:
+        """Notify agent delegation.
+
+        Args:
+            agent: Name of the delegated agent
+            task: Task assigned to the agent
+            status: Status of the delegation
+        """
+
+    @abstractmethod
+    def todo_updated(self, todos: List[Dict[str, Any]]) -> None:
+        """Notify todo list update.
+
+        Args:
+            todos: Updated list of todo items
+        """
+
+
+# Project analyzer interface
+class ProjectAnalyzerInterface(ABC):
+    """Interface for project analysis operations.
+
+    WHY: Understanding project structure and characteristics is essential for
+    context-aware agent behavior. This interface abstracts project analysis
+    to support different project types and structures.
+
+    DESIGN DECISION: Analysis methods return structured data to enable caching
+    and incremental updates when project structure changes.
+    """
+
+    @abstractmethod
+    def analyze_project(self, project_path: Path) -> Dict[str, Any]:
+        """Analyze project structure and characteristics.
+
+        Args:
+            project_path: Path to the project root
+
+        Returns:
+            Dictionary with project analysis results
+        """
+
+    @abstractmethod
+    def detect_technology_stack(self) -> List[str]:
+        """Detect technologies used in the project.
+
+        Returns:
+            List of detected technologies
+        """
+
+    @abstractmethod
+    def analyze_code_patterns(self) -> Dict[str, Any]:
+        """Analyze code patterns and conventions.
+
+        Returns:
+            Dictionary of pattern analysis results
+        """
+
+    @abstractmethod
+    def get_project_structure(self) -> Dict[str, Any]:
+        """Get project directory structure analysis.
+
+        Returns:
+            Dictionary representing project structure
+        """
+
+    @abstractmethod
+    def identify_entry_points(self) -> List[Path]:
+        """Identify project entry points.
+
+        Returns:
+            List of entry point paths
+        """
+
+    @abstractmethod
+    def get_dependencies(self) -> Dict[str, List[str]]:
+        """Get project dependencies by type.
+
+        Returns:
+            Dictionary mapping dependency types to lists of dependencies
+        """
+
+    @abstractmethod
+    def analyze_test_coverage(self) -> Dict[str, Any]:
+        """Analyze test coverage if available.
+
+        Returns:
+            Dictionary with test coverage information
+        """
+
+    @abstractmethod
+    def get_build_configuration(self) -> Dict[str, Any]:
+        """Get build configuration information.
+
+        Returns:
+            Dictionary with build configuration details
+        """
+
+
+# Ticket manager interface
+class TicketManagerInterface(ABC):
+    """Interface for ticket management operations.
+
+    WHY: Ticket management provides work tracking and organization. This
+    interface abstracts ticket operations to support different backend
+    systems (file-based, API-based, database).
+
+    DESIGN DECISION: Ticket operations return success/failure status to enable
+    proper error handling and fallback strategies when ticket systems are unavailable.
+    """
+
+    @abstractmethod
+    def create_ticket(
+        self, title: str, description: str, priority: str = "medium"
+    ) -> str:
+        """Create a new ticket.
+
+        Args:
+            title: Ticket title
+            description: Ticket description
+            priority: Ticket priority level
+
+        Returns:
+            Ticket ID
+        """
+
+    @abstractmethod
+    def get_ticket(self, ticket_id: str) -> Optional[Dict[str, Any]]:
+        """Get ticket by ID.
+
+        Args:
+            ticket_id: ID of ticket to retrieve
+
+        Returns:
+            Ticket data or None if not found
+        """
+
+    @abstractmethod
+    def update_ticket(self, ticket_id: str, updates: Dict[str, Any]) -> bool:
+        """Update ticket information.
+
+        Args:
+            ticket_id: ID of ticket to update
+            updates: Dictionary of fields to update
+
+        Returns:
+            True if update successful
+        """
+
+    @abstractmethod
+    def list_tickets(
+        self, status: Optional[str] = None, priority: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """List tickets with optional filtering.
+
+        Args:
+            status: Optional status filter
+            priority: Optional priority filter
+
+        Returns:
+            List of ticket data
+        """
+
+    @abstractmethod
+    def assign_ticket(self, ticket_id: str, assignee: str) -> bool:
+        """Assign ticket to a user.
+
+        Args:
+            ticket_id: ID of ticket to assign
+            assignee: User to assign ticket to
+
+        Returns:
+            True if assignment successful
+        """
+
+    @abstractmethod
+    def close_ticket(self, ticket_id: str, resolution: Optional[str] = None) -> bool:
+        """Close a ticket.
+
+        Args:
+            ticket_id: ID of ticket to close
+            resolution: Optional resolution description
+
+        Returns:
+            True if close successful
+        """
+
+    @abstractmethod
+    def search_tickets(self, query: str) -> List[Dict[str, Any]]:
+        """Search tickets by query.
+
+        Args:
+            query: Search query string
+
+        Returns:
+            List of matching ticket data
+        """
+
+    @abstractmethod
+    def get_ticket_statistics(self) -> Dict[str, Any]:
+        """Get ticket statistics.
+
+        Returns:
+            Dictionary with ticket statistics
+        """

claude_mpm/services/core/interfaces/health.py

@@ -0,0 +1,169 @@
+"""
+Health Check Interfaces for Claude MPM Framework
+=================================================
+
+WHY: This module defines interfaces for health monitoring operations,
+enabling the local-ops-agent to perform comprehensive health checks on
+deployed processes including HTTP endpoints, process status, and resource usage.
+
+DESIGN DECISION: Health check interfaces are separated to enable modular
+health monitoring with different check types (HTTP, process, resource).
+
+ARCHITECTURE:
+- IHealthCheck: Interface for individual health check implementations
+- IHealthCheckManager: Interface for orchestrating multiple health checks
+- Health data models defined in models/health.py
+
+USAGE:
+    http_check = HttpHealthCheck(endpoint="http://localhost:3000/health")
+    process_check = ProcessHealthCheck(process_manager)
+    resource_check = ResourceHealthCheck(process_manager)
+
+    health_manager = HealthCheckManager(
+        process_manager=process_manager,
+        check_interval=30
+    )
+    health_manager.start_monitoring()
+"""
+
+from abc import ABC, abstractmethod
+from typing import List
+
+from claude_mpm.services.core.models.health import DeploymentHealth, HealthCheckResult
+
+
+class IHealthCheck(ABC):
+    """
+    Interface for individual health check implementations.
+
+    WHY: Abstracts different types of health checks (HTTP, process, resource)
+    to enable flexible health monitoring strategies.
+
+    DESIGN DECISION: Each check type implements this interface to provide
+    a consistent API for executing checks and interpreting results.
+
+    Thread Safety: Implementations must be thread-safe for concurrent execution.
+    """
+
+    @abstractmethod
+    def check(self, deployment_id: str, **kwargs) -> HealthCheckResult:
+        """
+        Execute the health check for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            **kwargs: Check-specific parameters (e.g., endpoint URL, thresholds)
+
+        Returns:
+            HealthCheckResult with check status and details
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def get_check_type(self) -> str:
+        """
+        Get the type identifier for this health check.
+
+        Returns:
+            Check type string (e.g., "http", "process", "resource")
+        """
+
+
+class IHealthCheckManager(ABC):
+    """
+    Interface for coordinating health checks across deployments.
+
+    WHY: Health monitoring requires orchestrating multiple check types,
+    aggregating results, and maintaining historical data. This interface
+    provides a high-level API for comprehensive health monitoring.
+
+    DESIGN DECISION: Provides both synchronous (check_health) and asynchronous
+    (background monitoring) operations to support different use cases.
+
+    Background Monitoring:
+    - Runs health checks at regular intervals
+    - Maintains historical health data
+    - Triggers callbacks on status changes
+    - Thread-safe with proper locking
+    """
+
+    @abstractmethod
+    def check_health(self, deployment_id: str) -> DeploymentHealth:
+        """
+        Execute all health checks for a deployment.
+
+        WHY: Provides a comprehensive health snapshot by running all
+        registered health checks and aggregating results.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            DeploymentHealth with aggregated status and check results
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def start_monitoring(self) -> None:
+        """
+        Start background health monitoring.
+
+        WHY: Enables continuous health tracking without manual polling.
+        Monitoring runs in a separate daemon thread.
+
+        Thread Safety: Creates a daemon thread that performs periodic checks.
+        """
+
+    @abstractmethod
+    def stop_monitoring(self) -> None:
+        """
+        Stop background health monitoring.
+
+        WHY: Gracefully stops the monitoring thread and releases resources.
+        """
+
+    @abstractmethod
+    def is_monitoring(self) -> bool:
+        """
+        Check if background monitoring is active.
+
+        Returns:
+            True if monitoring thread is running
+        """
+
+    @abstractmethod
+    def get_health_history(
+        self, deployment_id: str, limit: int = 10
+    ) -> List[DeploymentHealth]:
+        """
+        Get historical health check results for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            limit: Maximum number of historical entries to return
+
+        Returns:
+            List of DeploymentHealth objects, newest first
+        """
+
+    @abstractmethod
+    def register_status_callback(self, callback) -> None:
+        """
+        Register a callback for health status changes.
+
+        WHY: Enables reactive behavior based on health status changes
+        (e.g., alerts, auto-recovery, logging).
+
+        Args:
+            callback: Function called with (deployment_id, old_status, new_status)
+        """
+
+
+__all__ = [
+    "IHealthCheck",
+    "IHealthCheckManager",
+]