codeframe-ai 0.9.0__py3-none-any.whl

codeframe/ui/routers/blockers_v2.py

@@ -0,0 +1,320 @@
+"""V2 Blockers router - delegates to core/blockers module.
+
+This module provides v2-style API endpoints for blocker management (human-in-the-loop).
+Blockers represent questions that pause task execution until answered by a human.
+
+Routes:
+    GET  /api/v2/blockers             - List blockers with optional filters
+    GET  /api/v2/blockers/{id}        - Get a specific blocker
+    POST /api/v2/blockers             - Create a new blocker
+    POST /api/v2/blockers/{id}/answer - Answer a blocker
+    POST /api/v2/blockers/{id}/resolve - Mark blocker as resolved
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from pydantic import BaseModel, Field
+
+from codeframe.core.workspace import Workspace
+from codeframe.lib.rate_limiter import rate_limit_standard
+from codeframe.core import blockers
+from codeframe.core.blockers import BlockerStatus, BlockerOrigin
+from codeframe.ui.dependencies import get_v2_workspace
+from codeframe.ui.response_models import api_error, ErrorCodes
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v2/blockers", tags=["blockers-v2"])
+
+
+# ============================================================================
+# Request/Response Models
+# ============================================================================
+
+
+class BlockerResponse(BaseModel):
+    """Response for a single blocker."""
+
+    id: str
+    workspace_id: str
+    task_id: Optional[str]
+    question: str
+    answer: Optional[str]
+    status: str
+    created_at: str
+    answered_at: Optional[str]
+    created_by: BlockerOrigin = BlockerOrigin.HUMAN
+
+
+class BlockerListResponse(BaseModel):
+    """Response for blocker list."""
+
+    blockers: list[BlockerResponse]
+    total: int
+    by_status: dict[str, int]
+
+
+class CreateBlockerRequest(BaseModel):
+    """Request for creating a blocker."""
+
+    question: str = Field(..., min_length=1, description="The question to ask")
+    task_id: Optional[str] = Field(None, description="Optional associated task ID")
+
+
+class AnswerBlockerRequest(BaseModel):
+    """Request for answering a blocker."""
+
+    answer: str = Field(..., min_length=1, description="The answer text")
+
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+
+def _blocker_to_response(blocker: blockers.Blocker) -> BlockerResponse:
+    """Convert a Blocker to a BlockerResponse."""
+    return BlockerResponse(
+        id=blocker.id,
+        workspace_id=blocker.workspace_id,
+        task_id=blocker.task_id,
+        question=blocker.question,
+        answer=blocker.answer,
+        status=blocker.status.value,
+        created_at=blocker.created_at.isoformat(),
+        answered_at=blocker.answered_at.isoformat() if blocker.answered_at else None,
+        created_by=blocker.created_by.value,
+    )
+
+
+# ============================================================================
+# Endpoints
+# ============================================================================
+
+
+@router.get("", response_model=BlockerListResponse)
+@rate_limit_standard()
+async def list_blockers(
+    request: Request,
+    status: Optional[str] = Query(None, description="Filter by status (OPEN, ANSWERED, RESOLVED)"),
+    task_id: Optional[str] = Query(None, description="Filter by task ID"),
+    limit: int = Query(100, ge=1, le=1000),
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> BlockerListResponse:
+    """List blockers in the workspace.
+
+    Args:
+        status: Optional status filter
+        task_id: Optional task filter
+        limit: Maximum blockers to return
+        workspace: v2 Workspace
+
+    Returns:
+        List of blockers with counts by status
+    """
+    # Parse status filter
+    status_filter = None
+    if status:
+        try:
+            status_filter = BlockerStatus(status.upper())
+        except ValueError:
+            raise HTTPException(
+                status_code=400,
+                detail=api_error(
+                    f"Invalid status: {status}",
+                    ErrorCodes.VALIDATION_ERROR,
+                    f"Valid values: {[s.value for s in BlockerStatus]}",
+                ),
+            )
+
+    # Get blockers
+    blocker_list = blockers.list_all(
+        workspace,
+        status=status_filter,
+        task_id=task_id,
+        limit=limit,
+    )
+
+    # Get counts by status
+    status_counts = blockers.count_by_status(workspace)
+
+    return BlockerListResponse(
+        blockers=[_blocker_to_response(b) for b in blocker_list],
+        total=len(blocker_list),
+        by_status=status_counts,
+    )
+
+
+@router.get("/{blocker_id}", response_model=BlockerResponse)
+@rate_limit_standard()
+async def get_blocker(
+    request: Request,
+    blocker_id: str,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> BlockerResponse:
+    """Get a specific blocker by ID.
+
+    Supports partial ID matching (prefix).
+
+    Args:
+        blocker_id: Blocker identifier (can be partial)
+        workspace: v2 Workspace
+
+    Returns:
+        Blocker details
+
+    Raises:
+        HTTPException: 404 if blocker not found, 400 if multiple matches
+    """
+    try:
+        blocker = blockers.get(workspace, blocker_id)
+    except ValueError as e:
+        # Multiple blockers match partial ID
+        raise HTTPException(
+            status_code=400,
+            detail=api_error("Ambiguous blocker ID", ErrorCodes.VALIDATION_ERROR, str(e)),
+        )
+
+    if not blocker:
+        raise HTTPException(
+            status_code=404,
+            detail=api_error("Blocker not found", ErrorCodes.NOT_FOUND, f"No blocker with id {blocker_id}"),
+        )
+
+    return _blocker_to_response(blocker)
+
+
+@router.post("", response_model=BlockerResponse, status_code=201)
+@rate_limit_standard()
+async def create_blocker(
+    request: Request,
+    body: CreateBlockerRequest,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> BlockerResponse:
+    """Create a new blocker.
+
+    Args:
+        request: HTTP request for rate limiting
+        body: Blocker creation request
+        workspace: v2 Workspace
+
+    Returns:
+        Created blocker
+    """
+    try:
+        blocker = blockers.create(
+            workspace,
+            question=body.question,
+            task_id=body.task_id,
+        )
+        return _blocker_to_response(blocker)
+
+    except Exception as e:
+        logger.error(f"Failed to create blocker: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail=api_error("Failed to create blocker", ErrorCodes.EXECUTION_FAILED, str(e)),
+        )
+
+
+@router.post("/{blocker_id}/answer", response_model=BlockerResponse)
+@rate_limit_standard()
+async def answer_blocker(
+    request: Request,
+    blocker_id: str,
+    body: AnswerBlockerRequest,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> BlockerResponse:
+    """Answer a blocker.
+
+    Answering a blocker also resets the associated task to READY status,
+    so it can be restarted with `cf work start <task-id> --execute`.
+
+    Args:
+        request: HTTP request for rate limiting
+        blocker_id: Blocker to answer (can be partial ID)
+        body: Answer request
+        workspace: v2 Workspace
+
+    Returns:
+        Updated blocker
+
+    Raises:
+        HTTPException:
+            - 404: Blocker not found
+            - 400: Blocker already resolved or ambiguous ID
+    """
+    try:
+        blocker = blockers.answer(workspace, blocker_id, body.answer)
+        return _blocker_to_response(blocker)
+
+    except ValueError as e:
+        error_msg = str(e)
+        if "not found" in error_msg.lower():
+            raise HTTPException(
+                status_code=404,
+                detail=api_error("Blocker not found", ErrorCodes.NOT_FOUND, error_msg),
+            )
+        elif "already resolved" in error_msg.lower():
+            raise HTTPException(
+                status_code=400,
+                detail=api_error("Cannot answer", ErrorCodes.INVALID_STATE, error_msg),
+            )
+        else:
+            raise HTTPException(
+                status_code=400,
+                detail=api_error("Invalid request", ErrorCodes.VALIDATION_ERROR, error_msg),
+            )
+
+
+@router.post("/{blocker_id}/resolve", response_model=BlockerResponse)
+@rate_limit_standard()
+async def resolve_blocker(
+    request: Request,
+    blocker_id: str,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> BlockerResponse:
+    """Mark a blocker as resolved.
+
+    A blocker must be answered before it can be resolved.
+
+    Args:
+        blocker_id: Blocker to resolve (can be partial ID)
+        workspace: v2 Workspace
+
+    Returns:
+        Updated blocker
+
+    Raises:
+        HTTPException:
+            - 404: Blocker not found
+            - 400: Blocker not answered yet or already resolved
+    """
+    try:
+        blocker = blockers.resolve(workspace, blocker_id)
+        return _blocker_to_response(blocker)
+
+    except ValueError as e:
+        error_msg = str(e)
+        if "not found" in error_msg.lower():
+            raise HTTPException(
+                status_code=404,
+                detail=api_error("Blocker not found", ErrorCodes.NOT_FOUND, error_msg),
+            )
+        elif "must be answered" in error_msg.lower():
+            raise HTTPException(
+                status_code=400,
+                detail=api_error("Cannot resolve", ErrorCodes.INVALID_STATE, error_msg),
+            )
+        elif "already resolved" in error_msg.lower():
+            raise HTTPException(
+                status_code=400,
+                detail=api_error("Cannot resolve", ErrorCodes.INVALID_STATE, error_msg),
+            )
+        else:
+            raise HTTPException(
+                status_code=400,
+                detail=api_error("Invalid request", ErrorCodes.VALIDATION_ERROR, error_msg),
+            )

codeframe/ui/routers/checkpoints_v2.py

@@ -0,0 +1,310 @@
+"""V2 Checkpoint router - delegates to core modules.
+
+This module provides v2-style API endpoints for checkpoint management that
+delegate to core/checkpoints.py. It uses the v2 Workspace model.
+
+The v1 router (checkpoints.py) remains for backwards compatibility.
+"""
+
+import logging
+from typing import Any, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from pydantic import BaseModel, Field
+
+from codeframe.core.workspace import Workspace
+from codeframe.lib.rate_limiter import rate_limit_standard
+from codeframe.core import checkpoints
+from codeframe.ui.dependencies import get_v2_workspace
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v2/checkpoints", tags=["checkpoints-v2"])
+
+
+# ============================================================================
+# Request/Response Models
+# ============================================================================
+
+
+class CreateCheckpointRequest(BaseModel):
+    """Request for creating a checkpoint."""
+
+    name: str = Field(..., min_length=1, max_length=200)
+    include_git_ref: bool = Field(
+        default=True,
+        description="Whether to capture current git HEAD",
+    )
+
+
+class CheckpointResponse(BaseModel):
+    """Response for a single checkpoint."""
+
+    id: str
+    name: str
+    created_at: str
+    summary: dict[str, Any]
+
+
+class CheckpointListResponse(BaseModel):
+    """Response for checkpoint list."""
+
+    checkpoints: list[CheckpointResponse]
+    total: int
+
+
+class TaskDiffResponse(BaseModel):
+    """Response for a single task diff."""
+
+    task_id: str
+    title: str
+    old_status: Optional[str]
+    new_status: Optional[str]
+    change_type: str
+
+
+class CheckpointDiffResponse(BaseModel):
+    """Response for checkpoint diff."""
+
+    checkpoint_a: dict[str, str]
+    checkpoint_b: dict[str, str]
+    task_diffs: list[TaskDiffResponse]
+    summary: dict[str, int]
+
+
+# ============================================================================
+# Checkpoint Endpoints
+# ============================================================================
+
+
+@router.post("", response_model=CheckpointResponse)
+@rate_limit_standard()
+async def create_checkpoint(
+    request: Request,
+    body: CreateCheckpointRequest,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> CheckpointResponse:
+    """Create a new checkpoint.
+
+    Captures current state of tasks, blockers, and optionally git ref.
+
+    This is the v2 equivalent of `cf checkpoint create`.
+
+    Args:
+        request: HTTP request for rate limiting
+        body: Checkpoint creation request
+        workspace: v2 Workspace
+
+    Returns:
+        Created checkpoint
+    """
+    try:
+        checkpoint = checkpoints.create(
+            workspace,
+            name=body.name,
+            include_git_ref=body.include_git_ref,
+        )
+
+        return CheckpointResponse(
+            id=checkpoint.id,
+            name=checkpoint.name,
+            created_at=checkpoint.created_at.isoformat(),
+            summary=checkpoint.snapshot.get("summary", {}),
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to create checkpoint: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("", response_model=CheckpointListResponse)
+@rate_limit_standard()
+async def list_checkpoints(
+    request: Request,
+    limit: int = Query(50, ge=1, le=200),
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> CheckpointListResponse:
+    """List all checkpoints.
+
+    This is the v2 equivalent of `cf checkpoint list`.
+
+    Args:
+        limit: Maximum checkpoints to return
+        workspace: v2 Workspace
+
+    Returns:
+        List of checkpoints (newest first)
+    """
+    checkpoint_list = checkpoints.list_all(workspace, limit=limit)
+
+    return CheckpointListResponse(
+        checkpoints=[
+            CheckpointResponse(
+                id=c.id,
+                name=c.name,
+                created_at=c.created_at.isoformat(),
+                summary=c.snapshot.get("summary", {}),
+            )
+            for c in checkpoint_list
+        ],
+        total=len(checkpoint_list),
+    )
+
+
+@router.get("/{checkpoint_id}", response_model=CheckpointResponse)
+@rate_limit_standard()
+async def get_checkpoint(
+    request: Request,
+    checkpoint_id: str,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> CheckpointResponse:
+    """Get a specific checkpoint.
+
+    Args:
+        checkpoint_id: Checkpoint ID or name
+        workspace: v2 Workspace
+
+    Returns:
+        Checkpoint details
+
+    Raises:
+        HTTPException: 404 if checkpoint not found
+    """
+    checkpoint = checkpoints.get(workspace, checkpoint_id)
+    if not checkpoint:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Checkpoint not found: {checkpoint_id}",
+        )
+
+    return CheckpointResponse(
+        id=checkpoint.id,
+        name=checkpoint.name,
+        created_at=checkpoint.created_at.isoformat(),
+        summary=checkpoint.snapshot.get("summary", {}),
+    )
+
+
+@router.post("/{checkpoint_id}/restore")
+@rate_limit_standard()
+async def restore_checkpoint(
+    request: Request,
+    checkpoint_id: str,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> dict[str, Any]:
+    """Restore state from a checkpoint.
+
+    Restores task statuses from the checkpoint. Does not modify files.
+
+    This is the v2 equivalent of `cf checkpoint restore`.
+
+    Args:
+        checkpoint_id: Checkpoint ID or name
+        workspace: v2 Workspace
+
+    Returns:
+        Restore result
+
+    Raises:
+        HTTPException: 404 if checkpoint not found
+    """
+    try:
+        checkpoint = checkpoints.restore(workspace, checkpoint_id)
+        return {
+            "success": True,
+            "checkpoint_id": checkpoint.id,
+            "checkpoint_name": checkpoint.name,
+            "message": f"Restored state from checkpoint '{checkpoint.name}'",
+        }
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        logger.error(f"Failed to restore checkpoint: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("/{checkpoint_id}")
+@rate_limit_standard()
+async def delete_checkpoint(
+    request: Request,
+    checkpoint_id: str,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> dict[str, Any]:
+    """Delete a checkpoint.
+
+    Args:
+        checkpoint_id: Checkpoint ID or name
+        workspace: v2 Workspace
+
+    Returns:
+        Delete result
+
+    Raises:
+        HTTPException: 404 if checkpoint not found
+    """
+    deleted = checkpoints.delete(workspace, checkpoint_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Checkpoint not found: {checkpoint_id}",
+        )
+
+    return {
+        "success": True,
+        "message": f"Deleted checkpoint {checkpoint_id}",
+    }
+
+
+@router.get("/{checkpoint_id_a}/diff/{checkpoint_id_b}", response_model=CheckpointDiffResponse)
+@rate_limit_standard()
+async def diff_checkpoints(
+    request: Request,
+    checkpoint_id_a: str,
+    checkpoint_id_b: str,
+    workspace: Workspace = Depends(get_v2_workspace),
+) -> CheckpointDiffResponse:
+    """Compare two checkpoints.
+
+    Shows task status changes between two checkpoints.
+
+    Args:
+        checkpoint_id_a: First checkpoint ID (typically older)
+        checkpoint_id_b: Second checkpoint ID (typically newer)
+        workspace: v2 Workspace
+
+    Returns:
+        Diff result with task changes
+
+    Raises:
+        HTTPException: 404 if either checkpoint not found
+    """
+    try:
+        diff_result = checkpoints.diff(workspace, checkpoint_id_a, checkpoint_id_b)
+
+        return CheckpointDiffResponse(
+            checkpoint_a={
+                "id": diff_result.checkpoint_a_id,
+                "name": diff_result.checkpoint_a_name,
+            },
+            checkpoint_b={
+                "id": diff_result.checkpoint_b_id,
+                "name": diff_result.checkpoint_b_name,
+            },
+            task_diffs=[
+                TaskDiffResponse(
+                    task_id=td.task_id,
+                    title=td.title,
+                    old_status=td.old_status,
+                    new_status=td.new_status,
+                    change_type=td.change_type,
+                )
+                for td in diff_result.task_diffs
+            ],
+            summary=diff_result.summary,
+        )
+
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        logger.error(f"Failed to diff checkpoints: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))