claude-mpm 5.4.65__py3-none-any.whl → 5.6.10__py3-none-any.whl

claude_mpm/commander/api/routes/projects.py

@@ -0,0 +1,271 @@
+"""Project management endpoints for MPM Commander API.
+
+This module implements REST endpoints for registering, listing, and managing
+projects in the MPM Commander.
+"""
+
+from pathlib import Path
+from typing import List
+
+from fastapi import APIRouter, Response
+
+from ...models import ProjectState
+from ..errors import InvalidPathError, ProjectAlreadyExistsError, ProjectNotFoundError
+from ..schemas import ProjectResponse, RegisterProjectRequest, SessionResponse
+
+router = APIRouter()
+
+
+def _get_registry():
+    """Get registry instance from app global."""
+    from ..app import registry
+
+    if registry is None:
+        raise RuntimeError("Registry not initialized")
+    return registry
+
+
+def _project_to_response(project) -> ProjectResponse:
+    """Convert Project model to ProjectResponse schema.
+
+    Args:
+        project: Project instance
+
+    Returns:
+        ProjectResponse with all project data
+    """
+    # Convert sessions dict to list of SessionResponse
+    session_responses = [
+        SessionResponse(
+            id=session.id,
+            project_id=session.project_id,
+            runtime=session.runtime,
+            tmux_target=session.tmux_target,
+            status=session.status,
+            created_at=session.created_at,
+        )
+        for session in project.sessions.values()
+    ]
+
+    return ProjectResponse(
+        id=project.id,
+        path=project.path,
+        name=project.name,
+        state=project.state.value,
+        state_reason=project.state_reason,
+        sessions=session_responses,
+        pending_events_count=len(project.pending_events),
+        last_activity=project.last_activity,
+        created_at=project.created_at,
+    )
+
+
+@router.get("/projects", response_model=List[ProjectResponse])
+async def list_projects() -> List[ProjectResponse]:
+    """List all registered projects.
+
+    Returns:
+        List of project information (may be empty)
+
+    Example:
+        GET /api/projects
+        Response: [
+            {
+                "id": "abc-123",
+                "path": "/Users/user/projects/my-app",
+                "name": "my-app",
+                "state": "idle",
+                "state_reason": null,
+                "sessions": [],
+                "pending_events_count": 0,
+                "last_activity": "2025-01-12T10:00:00Z",
+                "created_at": "2025-01-12T09:00:00Z"
+            }
+        ]
+    """
+    registry = _get_registry()
+    projects = registry.list_all()
+    return [_project_to_response(p) for p in projects]
+
+
+@router.get("/projects/{project_id}", response_model=ProjectResponse)
+async def get_project(project_id: str) -> ProjectResponse:
+    """Get project details by ID.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        Project information
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        GET /api/projects/abc-123
+        Response: {
+            "id": "abc-123",
+            "path": "/Users/user/projects/my-app",
+            "name": "my-app",
+            "state": "idle",
+            ...
+        }
+    """
+    registry = _get_registry()
+    project = registry.get(project_id)
+
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    return _project_to_response(project)
+
+
+@router.post("/projects", response_model=ProjectResponse, status_code=201)
+async def register_project(req: RegisterProjectRequest) -> ProjectResponse:
+    """Register a new project.
+
+    Args:
+        req: Registration request with path and optional name
+
+    Returns:
+        Newly registered project information
+
+    Raises:
+        InvalidPathError: If path doesn't exist or isn't a directory
+        ProjectAlreadyExistsError: If path already registered
+
+    Example:
+        POST /api/projects
+        Body: {
+            "path": "/Users/user/projects/my-app",
+            "name": "My App"
+        }
+        Response: {
+            "id": "abc-123",
+            "path": "/Users/user/projects/my-app",
+            "name": "My App",
+            "state": "idle",
+            ...
+        }
+    """
+    registry = _get_registry()
+
+    # Validate path exists and is directory
+    path_obj = Path(req.path)
+    if not path_obj.exists() or not path_obj.is_dir():
+        raise InvalidPathError(req.path)
+
+    try:
+        project = registry.register(req.path, req.name)
+        return _project_to_response(project)
+    except ValueError as e:
+        # Registry raises ValueError for duplicate registration
+        error_msg = str(e)
+        if "already registered" in error_msg.lower():
+            raise ProjectAlreadyExistsError(req.path) from e
+        # Re-raise as InvalidPathError for other validation errors
+        raise InvalidPathError(req.path) from e
+
+
+@router.delete("/projects/{project_id}", status_code=204)
+async def unregister_project(project_id: str) -> Response:
+    """Unregister a project.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        Empty response with 204 status
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        DELETE /api/projects/abc-123
+        Response: 204 No Content
+    """
+    registry = _get_registry()
+
+    try:
+        registry.unregister(project_id)
+        return Response(status_code=204)
+    except KeyError as e:
+        raise ProjectNotFoundError(project_id) from e
+
+
+@router.post("/projects/{project_id}/pause", response_model=ProjectResponse)
+async def pause_project(project_id: str) -> ProjectResponse:
+    """Pause a project.
+
+    Sets project state to PAUSED to prevent automatic work processing.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        Updated project information
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        POST /api/projects/abc-123/pause
+        Response: {
+            "id": "abc-123",
+            "state": "paused",
+            "state_reason": "Manually paused via API",
+            ...
+        }
+    """
+    registry = _get_registry()
+    project = registry.get(project_id)
+
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    registry.update_state(
+        project_id,
+        ProjectState.PAUSED,
+        reason="Manually paused via API",
+    )
+
+    return _project_to_response(project)
+
+
+@router.post("/projects/{project_id}/resume", response_model=ProjectResponse)
+async def resume_project(project_id: str) -> ProjectResponse:
+    """Resume a paused project.
+
+    Sets project state back to IDLE to allow work processing.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        Updated project information
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        POST /api/projects/abc-123/resume
+        Response: {
+            "id": "abc-123",
+            "state": "idle",
+            "state_reason": "Resumed via API",
+            ...
+        }
+    """
+    registry = _get_registry()
+    project = registry.get(project_id)
+
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    registry.update_state(
+        project_id,
+        ProjectState.IDLE,
+        reason="Resumed via API",
+    )
+
+    return _project_to_response(project)

claude_mpm/commander/api/routes/sessions.py

@@ -0,0 +1,228 @@
+"""Session management endpoints for MPM Commander API.
+
+This module implements REST endpoints for creating and managing tool sessions
+(Claude Code, Aider, etc.) within projects.
+"""
+
+import logging
+import subprocess  # nosec B404 - needed for tmux error handling
+import uuid
+from typing import List
+
+from fastapi import APIRouter, Response
+
+from ...models import ToolSession
+from ..errors import (
+    InvalidRuntimeError,
+    ProjectNotFoundError,
+    SessionNotFoundError,
+    TmuxNoSpaceError,
+)
+from ..schemas import CreateSessionRequest, SessionResponse
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+# Valid runtime adapters (Phase 1: claude-code only)
+VALID_RUNTIMES = {"claude-code"}
+
+
+def _get_registry():
+    """Get registry instance from app global."""
+    from ..app import registry
+
+    if registry is None:
+        raise RuntimeError("Registry not initialized")
+    return registry
+
+
+def _get_tmux():
+    """Get tmux orchestrator instance from app global."""
+    from ..app import tmux
+
+    if tmux is None:
+        raise RuntimeError("Tmux orchestrator not initialized")
+    return tmux
+
+
+def _session_to_response(session: ToolSession) -> SessionResponse:
+    """Convert ToolSession model to SessionResponse schema.
+
+    Args:
+        session: ToolSession instance
+
+    Returns:
+        SessionResponse with session data
+    """
+    return SessionResponse(
+        id=session.id,
+        project_id=session.project_id,
+        runtime=session.runtime,
+        tmux_target=session.tmux_target,
+        status=session.status,
+        created_at=session.created_at,
+    )
+
+
+@router.get("/projects/{project_id}/sessions", response_model=List[SessionResponse])
+async def list_sessions(project_id: str) -> List[SessionResponse]:
+    """List all sessions for a project.
+
+    Args:
+        project_id: Unique project identifier
+
+    Returns:
+        List of session information (may be empty)
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+
+    Example:
+        GET /api/projects/abc-123/sessions
+        Response: [
+            {
+                "id": "sess-456",
+                "project_id": "abc-123",
+                "runtime": "claude-code",
+                "tmux_target": "%1",
+                "status": "running",
+                "created_at": "2025-01-12T10:00:00Z"
+            }
+        ]
+    """
+    registry = _get_registry()
+    project = registry.get(project_id)
+
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    # Convert sessions dict to list of responses
+    return [_session_to_response(s) for s in project.sessions.values()]
+
+
+@router.post(
+    "/projects/{project_id}/sessions", response_model=SessionResponse, status_code=201
+)
+async def create_session(project_id: str, req: CreateSessionRequest) -> SessionResponse:
+    """Create a new session for a project.
+
+    Creates a new tmux pane and initializes the specified runtime adapter.
+
+    Args:
+        project_id: Unique project identifier
+        req: Session creation request
+
+    Returns:
+        Newly created session information
+
+    Raises:
+        ProjectNotFoundError: If project_id doesn't exist
+        InvalidRuntimeError: If runtime is not supported
+        TmuxNoSpaceError: If tmux has no space for new pane
+
+    Example:
+        POST /api/projects/abc-123/sessions
+        Body: {
+            "runtime": "claude-code",
+            "agent_prompt": "You are a helpful coding assistant"
+        }
+        Response: {
+            "id": "sess-456",
+            "project_id": "abc-123",
+            "runtime": "claude-code",
+            "tmux_target": "%1",
+            "status": "initializing",
+            "created_at": "2025-01-12T10:00:00Z"
+        }
+    """
+    registry = _get_registry()
+    tmux_orch = _get_tmux()
+
+    # Validate project exists
+    project = registry.get(project_id)
+    if project is None:
+        raise ProjectNotFoundError(project_id)
+
+    # Validate runtime
+    if req.runtime not in VALID_RUNTIMES:
+        raise InvalidRuntimeError(req.runtime)
+
+    # Generate session ID
+    session_id = str(uuid.uuid4())
+
+    # Create tmux pane for session
+    try:
+        tmux_target = tmux_orch.create_pane(
+            pane_id=f"{project.name}-{req.runtime}",
+            working_dir=project.path,
+        )
+    except subprocess.CalledProcessError as e:
+        stderr = e.stderr.decode() if e.stderr else ""
+        if "no space for new pane" in stderr.lower():
+            raise TmuxNoSpaceError() from None
+        raise  # Re-raise other subprocess errors
+
+    # Create session object
+    session = ToolSession(
+        id=session_id,
+        project_id=project_id,
+        runtime=req.runtime,
+        tmux_target=tmux_target,
+        status="initializing",
+    )
+
+    # Add session to project
+    registry.add_session(project_id, session)
+
+    # TODO: Start runtime adapter in pane (Phase 2)
+    # For Phase 1, session stays in "initializing" state
+
+    return _session_to_response(session)
+
+
+@router.delete("/sessions/{session_id}", status_code=204)
+async def stop_session(session_id: str) -> Response:
+    """Stop and remove a session.
+
+    Kills the tmux pane and removes the session from its project.
+
+    Args:
+        session_id: Unique session identifier
+
+    Returns:
+        Empty response with 204 status
+
+    Raises:
+        SessionNotFoundError: If session_id doesn't exist
+
+    Example:
+        DELETE /api/sessions/sess-456
+        Response: 204 No Content
+    """
+    registry = _get_registry()
+    tmux_orch = _get_tmux()
+
+    # Find session across all projects
+    session = None
+    parent_project_id = None
+
+    for project in registry.list_all():
+        if session_id in project.sessions:
+            session = project.sessions[session_id]
+            parent_project_id = project.id
+            break
+
+    if session is None or parent_project_id is None:
+        raise SessionNotFoundError(session_id)
+
+    # Kill tmux pane
+    try:
+        tmux_orch.kill_pane(session.tmux_target)
+    except Exception as e:
+        # Pane may already be dead, continue with cleanup
+        logger.debug("Failed to kill pane (may already be dead): %s", e)
+
+    # Remove session from project
+    registry.remove_session(parent_project_id, session_id)
+
+    return Response(status_code=204)