claudetools/api/routers/tasks.py

"""
Task API router for ClaudeTools.

This module defines all REST API endpoints for managing tasks, including
CRUD operations with proper authentication, validation, and error handling.
"""

from uuid import UUID

from fastapi import APIRouter, Depends, HTTPException, Query, status
from sqlalchemy.orm import Session

from api.database import get_db
from api.middleware.auth import get_current_user
from api.schemas.task import (
    TaskCreate,
    TaskResponse,
    TaskUpdate,
)
from api.services import task_service

# Create router with prefix and tags
router = APIRouter()


@router.get(
    "",
    response_model=dict,
    summary="List all tasks",
    description="Retrieve a paginated list of all tasks with optional filtering",
    status_code=status.HTTP_200_OK,
)
def list_tasks(
    skip: int = Query(
        default=0,
        ge=0,
        description="Number of records to skip for pagination"
    ),
    limit: int = Query(
        default=100,
        ge=1,
        le=1000,
        description="Maximum number of records to return (max 1000)"
    ),
    session_id: UUID | None = Query(
        default=None,
        description="Filter tasks by session ID"
    ),
    status_filter: str | None = Query(
        default=None,
        description="Filter tasks by status (pending, in_progress, blocked, completed, cancelled)"
    ),
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    List all tasks with pagination.

    - **skip**: Number of tasks to skip (default: 0)
    - **limit**: Maximum number of tasks to return (default: 100, max: 1000)
    - **session_id**: Optional filter by session ID
    - **status_filter**: Optional filter by status

    Returns a list of tasks with pagination metadata.

    **Example Request:**
    ```
    GET /api/tasks?skip=0&limit=50
    Authorization: Bearer <token>
    ```

    **Example Response:**
    ```json
    {
        "total": 25,
        "skip": 0,
        "limit": 50,
        "tasks": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "title": "Implement authentication",
                "task_order": 1,
                "status": "in_progress",
                "task_type": "implementation",
                "estimated_complexity": "moderate",
                "created_at": "2024-01-15T10:30:00Z",
                "updated_at": "2024-01-15T10:30:00Z"
            }
        ]
    }
    ```
    """
    try:
        # Filter by session if specified
        if session_id:
            tasks, total = task_service.get_tasks_by_session(db, session_id, skip, limit)
        # Filter by status if specified
        elif status_filter:
            tasks, total = task_service.get_tasks_by_status(db, status_filter, skip, limit)
        # Otherwise get all tasks
        else:
            tasks, total = task_service.get_tasks(db, skip, limit)

        return {
            "total": total,
            "skip": skip,
            "limit": limit,
            "tasks": [TaskResponse.model_validate(task) for task in tasks]
        }

    except Exception as e:
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to retrieve tasks: {str(e)}"
        )


@router.get(
    "/{task_id}",
    response_model=TaskResponse,
    summary="Get task by ID",
    description="Retrieve a single task by its unique identifier",
    status_code=status.HTTP_200_OK,
    responses={
        200: {
            "description": "Task found and returned",
            "model": TaskResponse,
        },
        404: {
            "description": "Task not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Task with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
    },
)
def get_task(
    task_id: UUID,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Get a specific task by ID.

    - **task_id**: UUID of the task to retrieve

    Returns the complete task details.

    **Example Request:**
    ```
    GET /api/tasks/123e4567-e89b-12d3-a456-426614174000
    Authorization: Bearer <token>
    ```

    **Example Response:**
    ```json
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "parent_task_id": null,
        "task_order": 1,
        "title": "Implement authentication",
        "description": "Add JWT-based authentication to the API",
        "task_type": "implementation",
        "status": "in_progress",
        "blocking_reason": null,
        "session_id": "456e7890-e89b-12d3-a456-426614174001",
        "client_id": "789e0123-e89b-12d3-a456-426614174002",
        "project_id": "012e3456-e89b-12d3-a456-426614174003",
        "assigned_agent": "agent-1",
        "estimated_complexity": "moderate",
        "started_at": "2024-01-15T09:00:00Z",
        "completed_at": null,
        "task_context": null,
        "dependencies": null,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
    }
    ```
    """
    task = task_service.get_task_by_id(db, task_id)
    return TaskResponse.model_validate(task)


@router.post(
    "",
    response_model=TaskResponse,
    summary="Create new task",
    description="Create a new task with the provided details",
    status_code=status.HTTP_201_CREATED,
    responses={
        201: {
            "description": "Task created successfully",
            "model": TaskResponse,
        },
        404: {
            "description": "Referenced session, client, project, or parent task not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Session with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
        422: {
            "description": "Validation error",
            "content": {
                "application/json": {
                    "example": {
                        "detail": [
                            {
                                "loc": ["body", "title"],
                                "msg": "field required",
                                "type": "value_error.missing"
                            }
                        ]
                    }
                }
            },
        },
    },
)
def create_task(
    task_data: TaskCreate,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Create a new task.

    Requires a valid JWT token with appropriate permissions.

    **Example Request:**
    ```json
    POST /api/tasks
    Authorization: Bearer <token>
    Content-Type: application/json

    {
        "title": "Implement authentication",
        "task_order": 1,
        "description": "Add JWT-based authentication to the API",
        "task_type": "implementation",
        "status": "pending",
        "session_id": "456e7890-e89b-12d3-a456-426614174001",
        "project_id": "012e3456-e89b-12d3-a456-426614174003",
        "assigned_agent": "agent-1",
        "estimated_complexity": "moderate"
    }
    ```

    **Example Response:**
    ```json
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "title": "Implement authentication",
        "task_order": 1,
        "status": "pending",
        "task_type": "implementation",
        "estimated_complexity": "moderate",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
    }
    ```
    """
    task = task_service.create_task(db, task_data)
    return TaskResponse.model_validate(task)


@router.put(
    "/{task_id}",
    response_model=TaskResponse,
    summary="Update task",
    description="Update an existing task's details",
    status_code=status.HTTP_200_OK,
    responses={
        200: {
            "description": "Task updated successfully",
            "model": TaskResponse,
        },
        404: {
            "description": "Task, session, client, project, or parent task not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Task with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
        422: {
            "description": "Validation error",
            "content": {
                "application/json": {
                    "example": {"detail": "Invalid session_id"}
                }
            },
        },
    },
)
def update_task(
    task_id: UUID,
    task_data: TaskUpdate,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Update an existing task.

    - **task_id**: UUID of the task to update

    Only provided fields will be updated. All fields are optional.

    **Example Request:**
    ```json
    PUT /api/tasks/123e4567-e89b-12d3-a456-426614174000
    Authorization: Bearer <token>
    Content-Type: application/json

    {
        "status": "completed",
        "completed_at": "2024-01-15T15:00:00Z"
    }
    ```

    **Example Response:**
    ```json
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "title": "Implement authentication",
        "task_order": 1,
        "status": "completed",
        "completed_at": "2024-01-15T15:00:00Z",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T15:00:00Z"
    }
    ```
    """
    task = task_service.update_task(db, task_id, task_data)
    return TaskResponse.model_validate(task)


@router.delete(
    "/{task_id}",
    response_model=dict,
    summary="Delete task",
    description="Delete a task by its ID",
    status_code=status.HTTP_200_OK,
    responses={
        200: {
            "description": "Task deleted successfully",
            "content": {
                "application/json": {
                    "example": {
                        "message": "Task deleted successfully",
                        "task_id": "123e4567-e89b-12d3-a456-426614174000"
                    }
                }
            },
        },
        404: {
            "description": "Task not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Task with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
    },
)
def delete_task(
    task_id: UUID,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Delete a task.

    - **task_id**: UUID of the task to delete

    This is a permanent operation and cannot be undone.

    **Example Request:**
    ```
    DELETE /api/tasks/123e4567-e89b-12d3-a456-426614174000
    Authorization: Bearer <token>
    ```

    **Example Response:**
    ```json
    {
        "message": "Task deleted successfully",
        "task_id": "123e4567-e89b-12d3-a456-426614174000"
    }
    ```
    """
    return task_service.delete_task(db, task_id)