claude-mpm 5.4.85__py3-none-any.whl → 5.6.76__py3-none-any.whl

claude_mpm/commander/events/manager.py

@@ -0,0 +1,392 @@
+"""EventManager for MPM Commander inbox system.
+
+Manages event lifecycle, inbox queries, and project event tracking.
+"""
+
+import asyncio
+import logging
+import threading
+import uuid
+from asyncio import Queue
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional
+
+from ..models.events import (
+    DEFAULT_PRIORITIES,
+    Event,
+    EventPriority,
+    EventStatus,
+    EventType,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class EventManager:
+    """Manages event lifecycle and inbox queries.
+
+    Thread-safe event storage with support for:
+    - Creating events with automatic priority assignment
+    - Querying pending events by project or globally
+    - Inbox sorting by priority then timestamp
+    - Responding to, acknowledging, or dismissing events
+    - Detecting blocking events
+    - Clearing project events
+
+    Example:
+        manager = EventManager()
+        event = manager.create(
+            project_id="proj_123",
+            event_type=EventType.DECISION_NEEDED,
+            title="Choose deployment target",
+            options=["staging", "production"]
+        )
+        inbox = manager.get_inbox()
+        manager.respond(event.id, "staging")
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty event storage."""
+        self._events: Dict[str, Event] = {}
+        self._project_index: Dict[str, List[str]] = {}  # project_id -> event_ids
+        self._lock = threading.RLock()
+        self._subscribers: Dict[EventType, List[Callable]] = {}
+        self._event_queue: Queue = Queue()
+
+    def create(
+        self,
+        project_id: str,
+        event_type: EventType,
+        title: str,
+        content: str = "",
+        session_id: Optional[str] = None,
+        priority: Optional[EventPriority] = None,
+        options: Optional[List[str]] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> Event:
+        """Create and queue a new event.
+
+        Args:
+            project_id: ID of project raising this event
+            event_type: Type of event
+            title: Short summary
+            content: Detailed description
+            session_id: Optional session ID
+            priority: Optional priority (uses default if not specified)
+            options: For DECISION_NEEDED, list of choices
+            context: Additional structured data
+
+        Returns:
+            The created Event
+
+        Example:
+            event = manager.create(
+                project_id="proj_123",
+                event_type=EventType.ERROR,
+                title="Database connection failed",
+                content="Could not connect to postgres://..."
+            )
+        """
+        with self._lock:
+            event_id = f"evt_{uuid.uuid4().hex[:12]}"
+
+            # Use default priority if not specified
+            if priority is None:
+                priority = DEFAULT_PRIORITIES.get(event_type, EventPriority.NORMAL)
+
+            event = Event(
+                id=event_id,
+                project_id=project_id,
+                session_id=session_id,
+                type=event_type,
+                priority=priority,
+                title=title,
+                content=content,
+                context=context or {},
+                options=options,
+            )
+
+            self._events[event_id] = event
+
+            # Index by project
+            if project_id not in self._project_index:
+                self._project_index[project_id] = []
+            self._project_index[project_id].append(event_id)
+
+            logger.info("Created event %s: [%s] %s", event_id, event_type.value, title)
+            return event
+
+    def add_event(self, event: Event) -> None:
+        """Add existing event to manager (for loading from persistence).
+
+        Args:
+            event: Event instance to add
+
+        Example:
+            # Load events from disk and add to manager
+            for event in loaded_events:
+                manager.add_event(event)
+        """
+        with self._lock:
+            self._events[event.id] = event
+
+            # Index by project
+            if event.project_id not in self._project_index:
+                self._project_index[event.project_id] = []
+            if event.id not in self._project_index[event.project_id]:
+                self._project_index[event.project_id].append(event.id)
+
+            logger.debug("Added event %s to manager", event.id)
+
+    def get(self, event_id: str) -> Optional[Event]:
+        """Get event by ID.
+
+        Args:
+            event_id: Unique event identifier
+
+        Returns:
+            Event if found, None otherwise
+        """
+        return self._events.get(event_id)
+
+    def get_pending(self, project_id: Optional[str] = None) -> List[Event]:
+        """Get all pending events, optionally filtered by project.
+
+        Args:
+            project_id: If provided, only return events for this project
+
+        Returns:
+            List of pending events (unsorted)
+
+        Example:
+            # Get all pending events
+            all_pending = manager.get_pending()
+
+            # Get pending events for one project
+            project_pending = manager.get_pending("proj_123")
+        """
+        with self._lock:
+            if project_id:
+                event_ids = self._project_index.get(project_id, [])
+                events = [self._events[eid] for eid in event_ids if eid in self._events]
+            else:
+                events = list(self._events.values())
+
+            return [e for e in events if e.status == EventStatus.PENDING]
+
+    def get_inbox(self, limit: int = 50) -> List[Event]:
+        """Get events for inbox, sorted by priority then time.
+
+        Sorting order:
+        1. Priority: CRITICAL > HIGH > NORMAL > LOW > INFO
+        2. Within same priority: oldest first (created_at ascending)
+
+        Args:
+            limit: Maximum number of events to return
+
+        Returns:
+            Sorted list of pending events, limited to `limit` items
+
+        Example:
+            inbox = manager.get_inbox(limit=20)
+            for event in inbox:
+                print(f"{event.priority.value}: {event.title}")
+        """
+        with self._lock:
+            pending = [
+                e for e in self._events.values() if e.status == EventStatus.PENDING
+            ]
+
+            # Sort by priority (CRITICAL first) then by created_at (oldest first)
+            priority_order = [
+                EventPriority.CRITICAL,
+                EventPriority.HIGH,
+                EventPriority.NORMAL,
+                EventPriority.LOW,
+                EventPriority.INFO,
+            ]
+
+            def sort_key(event: Event) -> tuple[int, datetime]:
+                pri_idx = (
+                    priority_order.index(event.priority)
+                    if event.priority in priority_order
+                    else 99
+                )
+                return (pri_idx, event.created_at)
+
+            sorted_events = sorted(pending, key=sort_key)
+            return sorted_events[:limit]
+
+    def respond(self, event_id: str, response: str) -> Event:
+        """Record response to event and mark as resolved.
+
+        Args:
+            event_id: ID of event to respond to
+            response: User's response text
+
+        Returns:
+            The updated Event
+
+        Raises:
+            KeyError: If event_id not found
+
+        Example:
+            event = manager.respond("evt_abc123", "Deploy to staging")
+        """
+        with self._lock:
+            event = self._events.get(event_id)
+            if not event:
+                raise KeyError(f"Event not found: {event_id}")
+
+            event.response = response
+            event.responded_at = datetime.now(timezone.utc)
+            event.status = EventStatus.RESOLVED
+
+            logger.info("Responded to event %s: %s", event_id, response[:50])
+            return event
+
+    def dismiss(self, event_id: str) -> Event:
+        """Mark event as dismissed without providing a response.
+
+        Args:
+            event_id: ID of event to dismiss
+
+        Returns:
+            The updated Event
+
+        Raises:
+            KeyError: If event_id not found
+
+        Example:
+            manager.dismiss("evt_abc123")
+        """
+        with self._lock:
+            event = self._events.get(event_id)
+            if not event:
+                raise KeyError(f"Event not found: {event_id}")
+
+            event.status = EventStatus.DISMISSED
+
+            logger.info("Dismissed event %s", event_id)
+            return event
+
+    def acknowledge(self, event_id: str) -> Event:
+        """Mark event as seen but not resolved yet.
+
+        Args:
+            event_id: ID of event to acknowledge
+
+        Returns:
+            The updated Event
+
+        Raises:
+            KeyError: If event_id not found
+
+        Example:
+            manager.acknowledge("evt_abc123")
+        """
+        with self._lock:
+            event = self._events.get(event_id)
+            if not event:
+                raise KeyError(f"Event not found: {event_id}")
+
+            event.status = EventStatus.ACKNOWLEDGED
+
+            logger.info("Acknowledged event %s", event_id)
+            return event
+
+    def get_blocking_events(self, project_id: Optional[str] = None) -> List[Event]:
+        """Get events that are blocking progress.
+
+        Args:
+            project_id: If provided, include project-scoped blocking events
+                       for this project. Always includes global blocking events.
+
+        Returns:
+            List of blocking events
+
+        Example:
+            # Get all blocking events (global scope only)
+            blockers = manager.get_blocking_events()
+
+            # Get blocking events for specific project (global + project scope)
+            blockers = manager.get_blocking_events("proj_123")
+        """
+        with self._lock:
+            pending = self.get_pending(project_id)
+            return [e for e in pending if e.is_blocking]
+
+    def clear_project_events(self, project_id: str) -> int:
+        """Clear all events for a project.
+
+        Args:
+            project_id: ID of project whose events should be cleared
+
+        Returns:
+            Number of events removed
+
+        Example:
+            removed = manager.clear_project_events("proj_123")
+            print(f"Cleared {removed} events")
+        """
+        with self._lock:
+            event_ids = self._project_index.pop(project_id, [])
+            for eid in event_ids:
+                self._events.pop(eid, None)
+            return len(event_ids)
+
+    def subscribe(self, event_type: EventType, callback: Callable) -> None:
+        """Subscribe callback to event type.
+
+        Args:
+            event_type: Type of event to subscribe to
+            callback: Function to call when event occurs (sync or async)
+
+        Example:
+            def on_error(event):
+                print(f"Error: {event.title}")
+
+            manager.subscribe(EventType.ERROR, on_error)
+        """
+        if event_type not in self._subscribers:
+            self._subscribers[event_type] = []
+        self._subscribers[event_type].append(callback)
+
+    def unsubscribe(self, event_type: EventType, callback: Callable) -> None:
+        """Unsubscribe callback from event type.
+
+        Args:
+            event_type: Type of event to unsubscribe from
+            callback: Function to remove from subscribers
+
+        Example:
+            manager.unsubscribe(EventType.ERROR, on_error)
+        """
+        if (
+            event_type in self._subscribers
+            and callback in self._subscribers[event_type]
+        ):
+            self._subscribers[event_type].remove(callback)
+
+    async def emit(self, event: Event) -> None:
+        """Emit event to all subscribers.
+
+        Queues the event and notifies all subscribed callbacks.
+        Supports both sync and async callbacks.
+
+        Args:
+            event: Event to emit
+
+        Example:
+            await manager.emit(event)
+        """
+        await self._event_queue.put(event)
+        if event.type in self._subscribers:
+            for callback in self._subscribers[event.type]:
+                try:
+                    if asyncio.iscoroutinefunction(callback):
+                        await callback(event)
+                    else:
+                        callback(event)
+                except Exception as e:
+                    logger.error(f"Subscriber callback error: {e}")

claude_mpm/commander/frameworks/__init__.py

@@ -0,0 +1,12 @@
+"""Framework abstractions for AI coding assistants."""
+
+from .base import BaseFramework, InstanceInfo
+from .claude_code import ClaudeCodeFramework
+from .mpm import MPMFramework
+
+__all__ = [
+    "BaseFramework",
+    "ClaudeCodeFramework",
+    "InstanceInfo",
+    "MPMFramework",
+]

claude_mpm/commander/frameworks/base.py

@@ -0,0 +1,233 @@
+"""Base framework abstraction for different AI coding assistants."""
+
+import subprocess  # nosec B404 - Required for git operations
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class InstanceInfo:
+    """Information about a running framework instance.
+
+    Attributes:
+        name: Instance name (e.g., "myapp")
+        project_path: Path to project directory
+        framework: Framework identifier (e.g., "cc", "mpm")
+        tmux_session: Tmux session name
+        pane_target: Tmux pane target (e.g., "%1")
+        git_branch: Current git branch if project is a git repo
+        git_status: Git status summary if project is a git repo
+        connected: Whether instance has an active adapter connection
+
+    Example:
+        >>> info = InstanceInfo(
+        ...     name="myapp",
+        ...     project_path=Path("/Users/user/myapp"),
+        ...     framework="cc",
+        ...     tmux_session="mpm-commander",
+        ...     pane_target="%1",
+        ...     git_branch="main",
+        ...     git_status="clean",
+        ...     connected=True
+        ... )
+    """
+
+    name: str
+    project_path: Path
+    framework: str
+    tmux_session: str
+    pane_target: str
+    git_branch: Optional[str] = None
+    git_status: Optional[str] = None
+    connected: bool = False
+    ready: bool = False
+
+
+@dataclass
+class RegisteredInstance:
+    """Persistent instance configuration (survives daemon restart).
+
+    Attributes:
+        name: Instance identifier
+        path: Original project directory path (stored as string for JSON)
+        framework: Framework identifier ("cc" or "mpm")
+        registered_at: ISO timestamp when instance was registered
+        worktree_path: Path to git worktree (if using worktree isolation)
+        worktree_branch: Branch name in the worktree
+        use_worktree: Whether worktree isolation is enabled
+
+    Example:
+        >>> instance = RegisteredInstance(
+        ...     name="myapp",
+        ...     path="/Users/user/myapp",
+        ...     framework="cc",
+        ...     registered_at="2024-01-15T10:30:00"
+        ... )
+        >>> instance.to_dict()
+        {'name': 'myapp', 'path': '/Users/user/myapp', 'framework': 'cc', ...}
+        >>> instance.working_path
+        '/Users/user/myapp'
+
+        >>> # With worktree enabled
+        >>> instance = RegisteredInstance(
+        ...     name="myapp",
+        ...     path="/Users/user/myapp",
+        ...     framework="cc",
+        ...     registered_at="2024-01-15T10:30:00",
+        ...     worktree_path="/Users/user/.mpm/worktrees/myapp",
+        ...     worktree_branch="feature/new-feature",
+        ...     use_worktree=True
+        ... )
+        >>> instance.working_path
+        '/Users/user/.mpm/worktrees/myapp'
+    """
+
+    name: str
+    path: str  # Original project path
+    framework: str
+    registered_at: str
+    # Worktree fields
+    worktree_path: Optional[str] = None  # Path to worktree (if using)
+    worktree_branch: Optional[str] = None  # Branch in worktree
+    use_worktree: bool = False  # Whether worktree is enabled
+
+    def to_dict(self) -> dict:
+        """Serialize for JSON storage."""
+        return {
+            "name": self.name,
+            "path": self.path,
+            "framework": self.framework,
+            "registered_at": self.registered_at,
+            "worktree_path": self.worktree_path,
+            "worktree_branch": self.worktree_branch,
+            "use_worktree": self.use_worktree,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "RegisteredInstance":
+        """Deserialize from JSON."""
+        return cls(
+            name=data["name"],
+            path=data["path"],
+            framework=data["framework"],
+            registered_at=data.get("registered_at", ""),
+            worktree_path=data.get("worktree_path"),
+            worktree_branch=data.get("worktree_branch"),
+            use_worktree=data.get("use_worktree", False),
+        )
+
+    @property
+    def working_path(self) -> str:
+        """Get the actual working path (worktree or original).
+
+        Returns:
+            The worktree path if worktree is enabled and configured,
+            otherwise the original project path.
+        """
+        if self.use_worktree and self.worktree_path:
+            return self.worktree_path
+        return self.path
+
+
+class BaseFramework(ABC):
+    """Base class for AI coding assistant frameworks.
+
+    A framework represents a specific AI coding tool (Claude Code, Claude MPM, etc.)
+    that can be launched in a project directory via tmux.
+
+    Attributes:
+        name: Short identifier (e.g., "cc", "mpm")
+        display_name: Human-readable name (e.g., "Claude Code", "Claude MPM")
+        command: The command to run (e.g., "claude")
+
+    Example:
+        >>> class MyFramework(BaseFramework):
+        ...     name = "my"
+        ...     display_name = "My Framework"
+        ...     command = "my-command"
+        ...
+        ...     def get_startup_command(self, project_path: Path) -> str:
+        ...         return f"cd {project_path} && my-command"
+        ...
+        ...     def is_available(self) -> bool:
+        ...         return True
+    """
+
+    name: str  # "cc", "mpm", etc.
+    display_name: str  # "Claude Code", "Claude MPM", etc.
+    command: str  # The command to run
+
+    @abstractmethod
+    def get_startup_command(self, project_path: Path) -> str:
+        """Get the command to start this framework in a project.
+
+        Args:
+            project_path: Path to the project directory
+
+        Returns:
+            Shell command string to start the framework
+
+        Example:
+            >>> framework = ClaudeCodeFramework()
+            >>> framework.get_startup_command(Path("/Users/user/myapp"))
+            "cd /Users/user/myapp && claude"
+        """
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if this framework is installed/available.
+
+        Returns:
+            True if the framework command is available on the system
+
+        Example:
+            >>> framework = ClaudeCodeFramework()
+            >>> framework.is_available()
+            True
+        """
+
+    def get_git_info(self, project_path: Path) -> tuple[Optional[str], Optional[str]]:
+        """Get git branch and status for project.
+
+        Args:
+            project_path: Path to the project directory
+
+        Returns:
+            Tuple of (branch, status) where:
+            - branch: Current git branch name or None if not a git repo
+            - status: "clean" if no changes, "dirty" if changes, or None if not a git repo
+
+        Example:
+            >>> framework = ClaudeCodeFramework()
+            >>> branch, status = framework.get_git_info(Path("/Users/user/myapp"))
+            >>> print(branch, status)
+            main clean
+        """
+        if not (project_path / ".git").exists():
+            return None, None
+
+        try:
+            # Get current branch
+            result = subprocess.run(  # nosec B603, B607 - Controlled git command
+                ["git", "-C", str(project_path), "rev-parse", "--abbrev-ref", "HEAD"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            branch = result.stdout.strip()
+
+            # Check if working directory is clean
+            result = subprocess.run(  # nosec B603, B607 - Controlled git command
+                ["git", "-C", str(project_path), "status", "--porcelain"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            status = "clean" if not result.stdout.strip() else "dirty"
+
+            return branch, status
+
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return None, None

claude_mpm/commander/frameworks/claude_code.py

@@ -0,0 +1,58 @@
+"""Claude Code (cc) framework implementation."""
+
+import shlex
+import shutil
+from pathlib import Path
+
+from .base import BaseFramework
+
+
+class ClaudeCodeFramework(BaseFramework):
+    """Claude Code CLI framework.
+
+    This framework launches the standard Claude Code CLI in a project directory.
+    It uses the 'claude' command with appropriate flags for automated operation.
+
+    Example:
+        >>> framework = ClaudeCodeFramework()
+        >>> framework.name
+        'cc'
+        >>> framework.is_available()
+        True
+        >>> framework.get_startup_command(Path("/Users/user/myapp"))
+        "cd '/Users/user/myapp' && claude --dangerously-skip-permissions"
+    """
+
+    name = "cc"
+    display_name = "Claude Code"
+    command = "claude"
+
+    def get_startup_command(self, project_path: Path) -> str:
+        """Get the command to start Claude Code in a project.
+
+        Args:
+            project_path: Path to the project directory
+
+        Returns:
+            Shell command string to start Claude Code
+
+        Example:
+            >>> framework = ClaudeCodeFramework()
+            >>> framework.get_startup_command(Path("/Users/user/myapp"))
+            "cd '/Users/user/myapp' && claude --dangerously-skip-permissions"
+        """
+        quoted_path = shlex.quote(str(project_path))
+        return f"cd {quoted_path} && claude --dangerously-skip-permissions"
+
+    def is_available(self) -> bool:
+        """Check if 'claude' command is available.
+
+        Returns:
+            True if 'claude' command exists in PATH
+
+        Example:
+            >>> framework = ClaudeCodeFramework()
+            >>> framework.is_available()
+            True
+        """
+        return shutil.which("claude") is not None