claude-mpm 5.4.41__py3-none-any.whl → 5.6.72__py3-none-any.whl

claude_mpm/commander/persistence/state_store.py

@@ -0,0 +1,403 @@
+"""State persistence for MPM Commander.
+
+This module handles atomic persistence and recovery of project registry
+and session states to disk.
+"""
+
+import asyncio
+import json
+import logging
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..frameworks.base import RegisteredInstance
+from ..models import Project, ProjectState, ToolSession
+from ..registry import ProjectRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class StateStore:
+    """Persists and recovers project registry state.
+
+    Provides atomic writes to prevent corruption and handles graceful
+    recovery from missing or corrupted files.
+
+    Attributes:
+        state_dir: Directory for state files
+        projects_path: Path to projects.json
+        sessions_path: Path to sessions.json
+
+    Example:
+        >>> store = StateStore(Path("~/.claude-mpm/commander"))
+        >>> await store.save_projects(registry)
+        >>> projects = await store.load_projects()
+    """
+
+    VERSION = "1.0"
+
+    def __init__(self, state_dir: Path):
+        """Initialize state store.
+
+        Args:
+            state_dir: Directory for state files (created if needed)
+        """
+        self.state_dir = state_dir.expanduser()
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+
+        self.projects_path = self.state_dir / "projects.json"
+        self.sessions_path = self.state_dir / "sessions.json"
+        self.instances_path = self.state_dir / "instances.json"
+
+        logger.info(f"Initialized StateStore at {self.state_dir}")
+
+    async def save_projects(self, registry: ProjectRegistry) -> None:
+        """Save all projects to disk (atomic write).
+
+        Args:
+            registry: ProjectRegistry to persist
+
+        Raises:
+            IOError: If write fails
+        """
+        projects = registry.list_all()
+
+        data = {
+            "version": self.VERSION,
+            "saved_at": datetime.now(timezone.utc).isoformat(),
+            "projects": [self._serialize_project(p) for p in projects],
+        }
+
+        # Run sync I/O in executor to avoid blocking
+        await asyncio.get_event_loop().run_in_executor(
+            None, self._atomic_write, self.projects_path, data
+        )
+
+        logger.info(f"Saved {len(projects)} projects to {self.projects_path}")
+
+    async def load_projects(self) -> List[Project]:
+        """Load projects from disk.
+
+        Returns:
+            List of Project instances (empty if file missing or corrupt)
+        """
+        if not self.projects_path.exists():
+            logger.info("No projects file found, returning empty list")
+            return []
+
+        try:
+            # Run sync I/O in executor
+            data = await asyncio.get_event_loop().run_in_executor(
+                None, self._read_json, self.projects_path
+            )
+
+            if data.get("version") != self.VERSION:
+                logger.warning(
+                    f"Version mismatch: expected {self.VERSION}, "
+                    f"got {data.get('version')}"
+                )
+
+            projects = [self._deserialize_project(p) for p in data.get("projects", [])]
+
+            logger.info(f"Loaded {len(projects)} projects from {self.projects_path}")
+            return projects
+
+        except Exception as e:
+            logger.error(f"Failed to load projects: {e}", exc_info=True)
+            return []
+
+    async def save_sessions(self, sessions: Dict[str, Any]) -> None:
+        """Save session states (for recovery).
+
+        Args:
+            sessions: Active ProjectSession instances by project_id
+
+        Raises:
+            IOError: If write fails
+        """
+        data = {
+            "version": self.VERSION,
+            "saved_at": datetime.now(timezone.utc).isoformat(),
+            "sessions": {
+                project_id: {
+                    "state": session.state.value,
+                    "pane_target": session.active_pane,
+                    "paused_event_id": session.pause_reason,
+                }
+                for project_id, session in sessions.items()
+            },
+        }
+
+        # Run sync I/O in executor
+        await asyncio.get_event_loop().run_in_executor(
+            None, self._atomic_write, self.sessions_path, data
+        )
+
+        logger.info(f"Saved {len(sessions)} sessions to {self.sessions_path}")
+
+    async def load_sessions(self) -> Dict[str, Dict[str, Any]]:
+        """Load session states.
+
+        Returns:
+            Dict mapping project_id to session state dict
+            (empty if file missing or corrupt)
+        """
+        if not self.sessions_path.exists():
+            logger.info("No sessions file found, returning empty dict")
+            return {}
+
+        try:
+            # Run sync I/O in executor
+            data = await asyncio.get_event_loop().run_in_executor(
+                None, self._read_json, self.sessions_path
+            )
+
+            if data.get("version") != self.VERSION:
+                logger.warning(
+                    f"Version mismatch: expected {self.VERSION}, "
+                    f"got {data.get('version')}"
+                )
+
+            sessions = data.get("sessions", {})
+            logger.info(f"Loaded {len(sessions)} sessions from {self.sessions_path}")
+            return sessions
+
+        except Exception as e:
+            logger.error(f"Failed to load sessions: {e}", exc_info=True)
+            return {}
+
+    def _atomic_write(self, path: Path, data: Dict) -> None:
+        """Write atomically (write to temp, then rename).
+
+        Args:
+            path: Target file path
+            data: Data to serialize as JSON
+
+        Raises:
+            IOError: If write fails
+        """
+        # Write to temporary file in same directory
+        # (ensures atomic rename works across filesystems)
+        fd, tmp_path = tempfile.mkstemp(
+            dir=path.parent, prefix=f".{path.name}.", suffix=".tmp"
+        )
+
+        try:
+            with open(fd, "w") as f:
+                json.dump(data, f, indent=2)
+
+            # Atomic rename (POSIX guarantees atomicity)
+            Path(tmp_path).rename(path)
+
+            logger.debug(f"Atomically wrote to {path}")
+
+        except Exception as e:
+            # Clean up temp file on error
+            try:
+                Path(tmp_path).unlink()
+            except Exception:  # nosec B110
+                pass  # Ignore errors during cleanup
+            raise OSError(f"Failed to write {path}: {e}") from e
+
+    def _read_json(self, path: Path) -> Dict:
+        """Read JSON file.
+
+        Args:
+            path: File to read
+
+        Returns:
+            Parsed JSON data
+
+        Raises:
+            IOError: If read fails
+        """
+        with open(path) as f:
+            return json.load(f)
+
+    def _serialize_project(self, project: Project) -> Dict[str, Any]:
+        """Serialize Project to JSON-compatible dict.
+
+        Args:
+            project: Project instance
+
+        Returns:
+            JSON-serializable dict
+        """
+        return {
+            "id": project.id,
+            "path": project.path,
+            "name": project.name,
+            "state": project.state.value,
+            "state_reason": project.state_reason,
+            "config_loaded": project.config_loaded,
+            "config": project.config,
+            "sessions": {
+                sid: self._serialize_session(session)
+                for sid, session in project.sessions.items()
+            },
+            "created_at": project.created_at.isoformat(),
+            "last_activity": project.last_activity.isoformat(),
+        }
+
+    def _serialize_session(self, session: ToolSession) -> Dict[str, Any]:
+        """Serialize ToolSession to JSON-compatible dict.
+
+        Args:
+            session: ToolSession instance
+
+        Returns:
+            JSON-serializable dict
+        """
+        return {
+            "id": session.id,
+            "project_id": session.project_id,
+            "runtime": session.runtime,
+            "tmux_target": session.tmux_target,
+            "status": session.status,
+            "created_at": session.created_at.isoformat(),
+            "last_output_at": (
+                session.last_output_at.isoformat() if session.last_output_at else None
+            ),
+        }
+
+    def _deserialize_project(self, data: Dict[str, Any]) -> Project:
+        """Deserialize Project from JSON dict.
+
+        Args:
+            data: Serialized project data
+
+        Returns:
+            Project instance
+        """
+        return Project(
+            id=data["id"],
+            path=data["path"],
+            name=data["name"],
+            state=ProjectState(data["state"]),
+            state_reason=data.get("state_reason"),
+            config_loaded=data.get("config_loaded", False),
+            config=data.get("config"),
+            sessions={
+                sid: self._deserialize_session(sess)
+                for sid, sess in data.get("sessions", {}).items()
+            },
+            created_at=datetime.fromisoformat(data["created_at"]),
+            last_activity=datetime.fromisoformat(data["last_activity"]),
+        )
+
+    def _deserialize_session(self, data: Dict[str, Any]) -> ToolSession:
+        """Deserialize ToolSession from JSON dict.
+
+        Args:
+            data: Serialized session data
+
+        Returns:
+            ToolSession instance
+        """
+        return ToolSession(
+            id=data["id"],
+            project_id=data["project_id"],
+            runtime=data["runtime"],
+            tmux_target=data["tmux_target"],
+            status=data.get("status", "initializing"),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            last_output_at=(
+                datetime.fromisoformat(data["last_output_at"])
+                if data.get("last_output_at")
+                else None
+            ),
+        )
+
+    # Instance persistence methods
+
+    def save_instances(self, instances: Dict[str, RegisteredInstance]) -> None:
+        """Save registered instances to disk.
+
+        Args:
+            instances: Dict mapping instance name to RegisteredInstance
+
+        Raises:
+            IOError: If write fails
+        """
+        data = {
+            "version": self.VERSION,
+            "saved_at": datetime.now(timezone.utc).isoformat(),
+            "instances": {name: inst.to_dict() for name, inst in instances.items()},
+        }
+        self._atomic_write(self.instances_path, data)
+        logger.info(f"Saved {len(instances)} instances to {self.instances_path}")
+
+    def load_instances(self) -> Dict[str, RegisteredInstance]:
+        """Load registered instances from disk.
+
+        Returns:
+            Dict mapping instance name to RegisteredInstance
+            (empty if file missing or corrupt)
+        """
+        if not self.instances_path.exists():
+            logger.info("No instances file found, returning empty dict")
+            return {}
+
+        try:
+            data = self._read_json(self.instances_path)
+
+            if data.get("version") != self.VERSION:
+                logger.warning(
+                    f"Version mismatch: expected {self.VERSION}, "
+                    f"got {data.get('version')}"
+                )
+
+            instances = {
+                name: RegisteredInstance.from_dict(inst_data)
+                for name, inst_data in data.get("instances", {}).items()
+            }
+
+            logger.info(f"Loaded {len(instances)} instances from {self.instances_path}")
+            return instances
+
+        except Exception as e:
+            logger.error(f"Failed to load instances: {e}", exc_info=True)
+            return {}
+
+    def register_instance(self, instance: RegisteredInstance) -> None:
+        """Register a single instance (add to existing).
+
+        Args:
+            instance: RegisteredInstance to add
+        """
+        instances = self.load_instances()
+        instances[instance.name] = instance
+        self.save_instances(instances)
+        logger.info(f"Registered instance '{instance.name}'")
+
+    def unregister_instance(self, name: str) -> bool:
+        """Remove an instance registration.
+
+        Args:
+            name: Instance name to remove
+
+        Returns:
+            True if instance was found and removed, False if not found
+        """
+        instances = self.load_instances()
+        if name in instances:
+            del instances[name]
+            self.save_instances(instances)
+            logger.info(f"Unregistered instance '{name}'")
+            return True
+        logger.warning(f"Instance '{name}' not found for unregistration")
+        return False
+
+    def get_registered_instance(self, name: str) -> Optional[RegisteredInstance]:
+        """Get a single registered instance by name.
+
+        Args:
+            name: Instance name to look up
+
+        Returns:
+            RegisteredInstance if found, None otherwise
+        """
+        instances = self.load_instances()
+        return instances.get(name)

claude_mpm/commander/persistence/work_store.py

@@ -0,0 +1,164 @@
+"""Work item persistence for MPM Commander.
+
+This module handles persistence and recovery of work queues,
+including all work items across all projects.
+"""
+
+import asyncio
+import json
+import logging
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List
+
+from ..models.work import WorkItem
+
+logger = logging.getLogger(__name__)
+
+
+class WorkStore:
+    """Persists and recovers work items.
+
+    Provides efficient work item persistence with:
+    - Batch save of all work items across all projects
+    - Atomic writes to prevent corruption
+    - Schema validation on load
+
+    Attributes:
+        state_dir: Directory for state files
+        work_path: Path to work.json
+
+    Example:
+        >>> store = WorkStore(Path("~/.claude-mpm/commander"))
+        >>> await store.save_work(work_queues)
+        >>> work_items = await store.load_work()
+    """
+
+    VERSION = "1.0"
+
+    def __init__(self, state_dir: Path):
+        """Initialize work store.
+
+        Args:
+            state_dir: Directory for state files (created if needed)
+        """
+        self.state_dir = state_dir.expanduser()
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+
+        self.work_path = self.state_dir / "work.json"
+
+        logger.info(f"Initialized WorkStore at {self.state_dir}")
+
+    async def save_work(self, work_queues: Dict[str, "WorkQueue"]) -> None:  # noqa: F821
+        """Save work items from all queues to disk.
+
+        Args:
+            work_queues: Dict of project_id -> WorkQueue
+
+        Raises:
+            IOError: If write fails
+        """
+        # Collect all work items from all queues
+        all_items: List[WorkItem] = []
+        for queue in work_queues.values():
+            all_items.extend(queue.list())
+
+        data = {
+            "version": self.VERSION,
+            "saved_at": self._get_timestamp(),
+            "work_items": [item.to_dict() for item in all_items],
+        }
+
+        # Run sync I/O in executor
+        await asyncio.get_event_loop().run_in_executor(
+            None, self._atomic_write, self.work_path, data
+        )
+
+        logger.info(
+            f"Saved {len(all_items)} work items from {len(work_queues)} "
+            f"queues to {self.work_path}"
+        )
+
+    async def load_work(self) -> List[WorkItem]:
+        """Load work items from disk.
+
+        Returns:
+            List of WorkItem instances (empty if file missing or corrupt)
+        """
+        if not self.work_path.exists():
+            logger.info("No work file found, returning empty list")
+            return []
+
+        try:
+            # Run sync I/O in executor
+            data = await asyncio.get_event_loop().run_in_executor(
+                None, self._read_json, self.work_path
+            )
+
+            if data.get("version") != self.VERSION:
+                logger.warning(
+                    f"Version mismatch: expected {self.VERSION}, "
+                    f"got {data.get('version')}"
+                )
+
+            # Deserialize work items
+            items = []
+            for item_data in data.get("work_items", []):
+                try:
+                    item = WorkItem.from_dict(item_data)
+                    items.append(item)
+                except Exception as e:
+                    logger.error(f"Failed to deserialize work item: {e}")
+                    logger.debug(f"Item data: {item_data}")
+
+            logger.info(f"Loaded {len(items)} work items from {self.work_path}")
+            return items
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse work file: {e}")
+            return []
+        except Exception as e:
+            logger.error(f"Failed to load work items: {e}")
+            return []
+
+    def _atomic_write(self, path: Path, data: Dict[str, Any]) -> None:
+        """Write data to file atomically.
+
+        Uses temp file + rename to ensure atomic write.
+
+        Args:
+            path: Target file path
+            data: Dictionary to write as JSON
+        """
+        # Write to temp file
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            dir=path.parent,
+            prefix=".work-",
+            suffix=".tmp",
+            delete=False,
+        ) as tmp:
+            json.dump(data, tmp, indent=2, default=str)
+            tmp_path = Path(tmp.name)
+
+        # Atomic rename
+        tmp_path.replace(path)
+        logger.debug(f"Wrote work file atomically: {path}")
+
+    def _read_json(self, path: Path) -> Dict[str, Any]:
+        """Read JSON file.
+
+        Args:
+            path: File path
+
+        Returns:
+            Parsed JSON data
+        """
+        with open(path) as f:
+            return json.load(f)
+
+    def _get_timestamp(self) -> str:
+        """Get current timestamp as ISO string."""
+        from datetime import datetime, timezone
+
+        return datetime.now(timezone.utc).isoformat()

claude_mpm/commander/polling/__init__.py

@@ -0,0 +1,13 @@
+"""Output polling and event detection for MPM Commander."""
+
+from .event_detector import BasicEventDetector, DetectedEvent, EventType
+from .output_buffer import OutputBuffer
+from .output_poller import OutputPoller
+
+__all__ = [
+    "BasicEventDetector",
+    "DetectedEvent",
+    "EventType",
+    "OutputBuffer",
+    "OutputPoller",
+]

claude_mpm/commander/polling/event_detector.py

@@ -0,0 +1,104 @@
+"""Event detection for MPM Commander output."""
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class EventType(Enum):
+    """Types of events that can be detected in output."""
+
+    ERROR = "error"
+    IDLE = "idle"
+
+
+@dataclass
+class DetectedEvent:
+    """An event detected in session output."""
+
+    event_type: EventType
+    content: str
+    context: str  # Surrounding lines for context
+    line_number: Optional[int] = None
+
+
+class BasicEventDetector:
+    """Phase 1: Detect errors and idle states only."""
+
+    # ANSI escape code pattern
+    ANSI_ESCAPE = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+    ERROR_PATTERNS = [
+        r"Error:",
+        r"Failed:",
+        r"Exception:",
+        r"Traceback \(most recent call last\):",
+        r"Permission denied",
+        r"command not found",
+        r"FATAL:",
+        r"✗",  # Claude Code error indicator
+    ]
+
+    IDLE_PATTERNS = [
+        r"^>\s*$",  # Claude Code prompt
+        r"^claude>\s*$",  # Alternative prompt
+        r"^\$\s*$",  # Shell prompt
+        r"What would you like",
+    ]
+
+    def strip_ansi(self, text: str) -> str:
+        """Remove ANSI escape codes from text.
+
+        Args:
+            text: Text potentially containing ANSI codes
+
+        Returns:
+            Clean text with ANSI codes removed
+        """
+        return self.ANSI_ESCAPE.sub("", text)
+
+    def detect_error(self, content: str) -> Optional[DetectedEvent]:
+        """Check for error patterns in output.
+
+        Args:
+            content: Output content to check
+
+        Returns:
+            DetectedEvent if error found, None otherwise
+        """
+        clean = self.strip_ansi(content)
+        lines = clean.split("\n")
+
+        for i, line in enumerate(lines):
+            for pattern in self.ERROR_PATTERNS:
+                if re.search(pattern, line, re.IGNORECASE):
+                    # Extract context (3 lines before/after)
+                    start = max(0, i - 3)
+                    end = min(len(lines), i + 4)
+                    context = "\n".join(lines[start:end])
+
+                    return DetectedEvent(
+                        event_type=EventType.ERROR,
+                        content=line.strip(),
+                        context=context,
+                        line_number=i + 1,
+                    )
+        return None
+
+    def detect_idle(self, content: str) -> bool:
+        """Check if tool is waiting for input (last line is a prompt).
+
+        Args:
+            content: Output content to check
+
+        Returns:
+            True if session appears to be idle (waiting for input)
+        """
+        clean = self.strip_ansi(content)
+        lines = clean.strip().split("\n")
+        if not lines:
+            return False
+
+        last_line = lines[-1]
+        return any(re.search(p, last_line) for p in self.IDLE_PATTERNS)