draft-board 0.1.0-beta.0

package/app/backend/app/routers/webhooks.py

@@ -0,0 +1,143 @@
+"""Router for webhook configuration (CRUD on Board.config.webhooks)."""
+
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel, Field
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.models.board import Board
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/webhooks", tags=["webhooks"])
+
+
+# --- Schemas ---
+
+
+class WebhookCreate(BaseModel):
+    url: str = Field(..., description="URL to POST webhook payloads to")
+    events: list[str] = Field(
+        default=["*"],
+        description='Event filter list. Use ["*"] for all events.',
+    )
+    secret: str | None = Field(
+        None, description="Optional HMAC-SHA256 secret for payload signing"
+    )
+
+
+class WebhookResponse(BaseModel):
+    id: str
+    url: str
+    events: list[str]
+    has_secret: bool
+
+
+class WebhookListResponse(BaseModel):
+    webhooks: list[WebhookResponse]
+    board_id: str
+
+
+# --- Helpers ---
+
+
+async def _resolve_board(db: AsyncSession, board_id: str | None) -> Board:
+    if board_id:
+        result = await db.execute(select(Board).where(Board.id == board_id))
+        board = result.scalar_one_or_none()
+        if not board:
+            raise HTTPException(status_code=404, detail=f"Board not found: {board_id}")
+        return board
+    result = await db.execute(select(Board).limit(1))
+    board = result.scalar_one_or_none()
+    if not board:
+        raise HTTPException(status_code=400, detail="No boards exist.")
+    return board
+
+
+def _get_webhooks(board: Board) -> list[dict]:
+    config = board.config or {}
+    return config.get("webhooks", [])
+
+
+def _set_webhooks(board: Board, webhooks: list[dict]) -> None:
+    config = board.config or {}
+    config["webhooks"] = webhooks
+    board.config = config
+
+
+def _to_response(wh: dict) -> WebhookResponse:
+    return WebhookResponse(
+        id=wh["id"],
+        url=wh["url"],
+        events=wh.get("events", ["*"]),
+        has_secret=bool(wh.get("secret")),
+    )
+
+
+# --- Endpoints ---
+
+
+@router.get("", response_model=WebhookListResponse)
+async def list_webhooks(
+    board_id: str | None = Query(None),
+    db: AsyncSession = Depends(get_db),
+):
+    """List all webhooks configured for a board."""
+    board = await _resolve_board(db, board_id)
+    webhooks = _get_webhooks(board)
+    return WebhookListResponse(
+        webhooks=[_to_response(wh) for wh in webhooks],
+        board_id=board.id,
+    )
+
+
+@router.post("", response_model=WebhookResponse, status_code=201)
+async def create_webhook(
+    data: WebhookCreate,
+    board_id: str | None = Query(None),
+    db: AsyncSession = Depends(get_db),
+):
+    """Add a new webhook to a board."""
+    board = await _resolve_board(db, board_id)
+    webhooks = _get_webhooks(board)
+
+    wh = {
+        "id": str(uuid.uuid4()),
+        "url": data.url,
+        "events": data.events,
+    }
+    if data.secret:
+        wh["secret"] = data.secret
+
+    webhooks.append(wh)
+    _set_webhooks(board, webhooks)
+    await db.commit()
+    await db.refresh(board)
+
+    logger.info("Webhook created: id=%s url=%s board=%s", wh["id"], wh["url"], board.id)
+    return _to_response(wh)
+
+
+@router.delete("/{webhook_id}", status_code=204)
+async def delete_webhook(
+    webhook_id: str,
+    board_id: str | None = Query(None),
+    db: AsyncSession = Depends(get_db),
+):
+    """Remove a webhook from a board."""
+    board = await _resolve_board(db, board_id)
+    webhooks = _get_webhooks(board)
+    original_len = len(webhooks)
+    webhooks = [wh for wh in webhooks if wh.get("id") != webhook_id]
+
+    if len(webhooks) == original_len:
+        raise HTTPException(status_code=404, detail=f"Webhook not found: {webhook_id}")
+
+    _set_webhooks(board, webhooks)
+    await db.commit()
+    logger.info("Webhook deleted: id=%s board=%s", webhook_id, board.id)

package/app/backend/app/routers/websocket.py

@@ -0,0 +1,249 @@
+"""WebSocket endpoints for real-time updates.
+
+This module provides WebSocket endpoints for streaming live updates to clients:
+- Job output streaming (live execution logs)
+- Board updates (ticket status changes, new jobs, etc.)
+- Board JSON patches (incremental state updates via RFC 6902)
+"""
+
+import json
+import logging
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+from app.websocket.manager import manager
+from app.websocket.state_tracker import get_tracker, remove_tracker
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/ws", tags=["websocket"])
+
+
+@router.websocket("/jobs/{job_id}")
+async def job_output_stream(websocket: WebSocket, job_id: str):
+    """Stream live output from a running job.
+
+    Clients subscribe to this endpoint to receive real-time updates about
+    job execution, including stdout/stderr output and status changes.
+
+    Subscribes to the in-memory log broadcaster so terminal output from
+    the worker is forwarded to the WebSocket in real-time.
+
+    Args:
+        websocket: The WebSocket connection
+        job_id: The job ID to stream updates for
+
+    Message format:
+        {
+            "type": "output" | "status" | "complete" | "error",
+            "content": str,  # For output messages
+            "status": str,   # For status messages
+            "timestamp": str # ISO format timestamp
+        }
+    """
+    import asyncio
+
+    from app.services.log_stream_service import LogLevel, log_stream_service
+
+    channel = f"job:{job_id}"
+    await manager.connect(websocket, channel)
+
+    # Background task to forward log stream messages to WebSocket
+    async def _forward_logs():
+        try:
+            async for msg in log_stream_service.subscribe(job_id):
+                try:
+                    if msg.level == LogLevel.FINISHED:
+                        await websocket.send_json(
+                            {
+                                "type": "complete",
+                                "content": "",
+                                "timestamp": msg.timestamp.isoformat(),
+                            }
+                        )
+                        return
+                    elif msg.level in (LogLevel.STDOUT, LogLevel.STDERR):
+                        await websocket.send_json(
+                            {
+                                "type": "output",
+                                "content": msg.content,
+                                "timestamp": msg.timestamp.isoformat(),
+                            }
+                        )
+                    elif msg.level == LogLevel.ERROR:
+                        await websocket.send_json(
+                            {
+                                "type": "error",
+                                "content": msg.content,
+                                "timestamp": msg.timestamp.isoformat(),
+                            }
+                        )
+                    elif msg.level == LogLevel.PROGRESS:
+                        await websocket.send_json(
+                            {
+                                "type": "status",
+                                "content": msg.content,
+                                "status": msg.stage or "running",
+                                "progress_pct": msg.progress_pct,
+                                "timestamp": msg.timestamp.isoformat(),
+                            }
+                        )
+                    else:
+                        await websocket.send_json(
+                            {
+                                "type": "output",
+                                "content": msg.content,
+                                "timestamp": msg.timestamp.isoformat(),
+                            }
+                        )
+                except Exception:
+                    return  # WebSocket closed
+        except asyncio.CancelledError:
+            pass
+
+    forward_task = asyncio.create_task(_forward_logs())
+
+    try:
+        # Keep connection alive and handle client messages
+        while True:
+            data = await websocket.receive_text()
+
+            # Handle ping/pong for keep-alive
+            if data == "ping":
+                await websocket.send_text("pong")
+            elif data == "subscribe":
+                # Already subscribed, acknowledge
+                await websocket.send_json(
+                    {"type": "subscribed", "channel": channel, "job_id": job_id}
+                )
+            elif data == "unsubscribe":
+                # Client wants to unsubscribe
+                break
+
+    except WebSocketDisconnect:
+        logger.info(f"WebSocket disconnected from job stream: {job_id}")
+    except Exception as e:
+        logger.error(f"WebSocket error on job stream {job_id}: {e}", exc_info=True)
+    finally:
+        forward_task.cancel()
+        try:
+            await forward_task
+        except asyncio.CancelledError:
+            pass
+        await manager.disconnect(websocket, channel)
+
+
+@router.websocket("/board/{board_id}")
+async def board_updates(websocket: WebSocket, board_id: str):
+    """Stream board updates (ticket status changes, new jobs, etc.).
+
+    Supports two protocols:
+    1. Legacy: broadcasts raw event messages
+    2. JSON Patch: sends snapshot on connect, then RFC 6902 patches
+
+    Client can request a resync by sending: {"type": "resync"}
+
+    Args:
+        websocket: The WebSocket connection
+        board_id: The board ID to stream updates for
+
+    Message format (legacy):
+        {
+            "type": "ticket_update" | "job_created" | "job_completed",
+            "ticket_id": str,
+            "job_id": str,
+            "data": dict,
+            "timestamp": str
+        }
+
+    Message format (JSON Patch):
+        Connect:  {"type": "snapshot", "data": {...}, "seq": 0}
+        Update:   {"type": "patch", "ops": [...], "seq": N}
+        Resync:   client sends {"type": "resync"} → server sends snapshot
+    """
+    channel = f"board:{board_id}"
+    await manager.connect(websocket, channel)
+
+    try:
+        # Keep connection alive and handle client messages
+        while True:
+            data = await websocket.receive_text()
+
+            if data == "ping":
+                await websocket.send_text("pong")
+            elif data == "subscribe":
+                await websocket.send_json(
+                    {"type": "subscribed", "channel": channel, "board_id": board_id}
+                )
+            elif data == "unsubscribe":
+                break
+            else:
+                # Try to parse JSON messages
+                try:
+                    msg = json.loads(data)
+                    if msg.get("type") == "resync":
+                        # Client requested a full resync - tracker will send
+                        # snapshot on next broadcast
+                        tracker = get_tracker(board_id)
+                        if tracker.has_state:
+                            # Re-send current snapshot
+                            snapshot = tracker.get_snapshot_message(
+                                tracker._state  # type: ignore[arg-type]
+                            )
+                            await websocket.send_json(snapshot)
+                except (json.JSONDecodeError, TypeError):
+                    pass
+
+    except WebSocketDisconnect:
+        logger.info(f"WebSocket disconnected from board: {board_id}")
+    except Exception as e:
+        logger.error(f"WebSocket error on board {board_id}: {e}", exc_info=True)
+    finally:
+        await manager.disconnect(websocket, channel)
+        # Clean up tracker if no more connections
+        if manager.get_connection_count(channel) == 0:
+            remove_tracker(board_id)
+
+
+@router.websocket("/goals/{goal_id}")
+async def goal_updates(websocket: WebSocket, goal_id: str):
+    """Stream goal updates (ticket generation, pipeline progress, etc.).
+
+    Clients subscribe to this endpoint to receive real-time updates about
+    goal-level changes, including ticket generation progress, pipeline
+    execution status, and goal completion.
+
+    Args:
+        websocket: The WebSocket connection
+        goal_id: The goal ID to stream updates for
+
+    Message format:
+        {
+            "type": "ticket_generated" | "pipeline_progress" | "goal_completed",
+            "goal_id": str,
+            "data": dict,
+            "timestamp": str
+        }
+    """
+    channel = f"goal:{goal_id}"
+    await manager.connect(websocket, channel)
+
+    try:
+        while True:
+            data = await websocket.receive_text()
+
+            if data == "ping":
+                await websocket.send_text("pong")
+            elif data == "subscribe":
+                await websocket.send_json(
+                    {"type": "subscribed", "channel": channel, "goal_id": goal_id}
+                )
+            elif data == "unsubscribe":
+                break
+
+    except WebSocketDisconnect:
+        logger.info(f"WebSocket disconnected from goal: {goal_id}")
+    except Exception as e:
+        logger.error(f"WebSocket error on goal {goal_id}: {e}", exc_info=True)
+    finally:
+        await manager.disconnect(websocket, channel)

package/app/backend/app/schemas/__init__.py

@@ -0,0 +1,109 @@
+"""Pydantic schemas for Draft API."""
+
+from app.schemas.board import (
+    BoardCreate,
+    BoardListResponse,
+    BoardUpdate,
+)
+from app.schemas.board import (
+    BoardResponse as BoardEntityResponse,
+)
+from app.schemas.common import ErrorResponse, SuccessResponse
+from app.schemas.evidence import (
+    EvidenceDetailResponse,
+    EvidenceKind,
+    EvidenceListResponse,
+    EvidenceResponse,
+)
+from app.schemas.goal import GoalCreate, GoalListResponse, GoalResponse
+from app.schemas.job import (
+    CancelJobResponse,
+    JobCreateResponse,
+    JobDetailResponse,
+    JobKind,
+    JobListResponse,
+    JobResponse,
+    JobStatus,
+)
+from app.schemas.review import (
+    AuthorType,
+    FeedbackBundle,
+    FeedbackComment,
+    ReviewCommentCreate,
+    ReviewCommentListResponse,
+    ReviewCommentResponse,
+    ReviewDecision,
+    ReviewSubmit,
+    ReviewSummaryResponse,
+)
+from app.schemas.revision import (
+    DiffFile,
+    RevisionDetailResponse,
+    RevisionDiffResponse,
+    RevisionListResponse,
+    RevisionResponse,
+    RevisionStatus,
+)
+from app.schemas.ticket import (
+    BoardResponse,
+    TicketCreate,
+    TicketDetailResponse,
+    TicketResponse,
+    TicketsByState,
+    TicketTransition,
+    TicketWithGoal,
+)
+from app.schemas.ticket_event import TicketEventListResponse, TicketEventResponse
+from app.schemas.workspace import WorkspaceResponse
+
+__all__ = [
+    # Board schemas
+    "BoardCreate",
+    "BoardEntityResponse",
+    "BoardListResponse",
+    "BoardUpdate",
+    # Goal schemas
+    "GoalCreate",
+    "GoalResponse",
+    "GoalListResponse",
+    "TicketCreate",
+    "TicketResponse",
+    "TicketDetailResponse",
+    "TicketTransition",
+    "TicketWithGoal",
+    "TicketsByState",
+    "BoardResponse",
+    "TicketEventResponse",
+    "TicketEventListResponse",
+    "ErrorResponse",
+    "SuccessResponse",
+    "EvidenceKind",
+    "EvidenceResponse",
+    "EvidenceDetailResponse",
+    "EvidenceListResponse",
+    "JobKind",
+    "JobStatus",
+    "JobResponse",
+    "JobDetailResponse",
+    "JobListResponse",
+    "JobCreateResponse",
+    "CancelJobResponse",
+    "WorkspaceResponse",
+    # Revision schemas
+    "RevisionStatus",
+    "RevisionResponse",
+    "RevisionDetailResponse",
+    "RevisionListResponse",
+    "RevisionDiffResponse",
+    "DiffFile",
+    # Review schemas
+    "AuthorType",
+    "ReviewDecision",
+    "ReviewCommentCreate",
+    "ReviewCommentResponse",
+    "ReviewCommentListResponse",
+    "ReviewSubmit",
+    "ReviewSummaryResponse",
+    "FeedbackComment",
+    "FeedbackBundle",
+]

package/app/backend/app/schemas/board.py

@@ -0,0 +1,87 @@
+"""Board schemas for API request/response validation."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class BoardCreate(BaseModel):
+    """Schema for creating a new board."""
+
+    name: str = Field(..., min_length=1, max_length=255, description="Board name")
+    description: str | None = Field(None, description="Optional description")
+    repo_root: str = Field(
+        ...,
+        min_length=1,
+        max_length=1024,
+        description="Absolute path to repository root",
+    )
+    default_branch: str | None = Field(
+        None,
+        max_length=255,
+        description="Default branch (e.g., main, master)",
+    )
+    template_id: str | None = Field(
+        None,
+        description="Optional template ID to apply project template configuration and starter goals",
+    )
+    create_starter_goals: bool = Field(
+        True,
+        description="Whether to create starter goals from the template (default: true)",
+    )
+
+
+class BoardUpdate(BaseModel):
+    """Schema for updating a board."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    name: str | None = Field(None, min_length=1, max_length=255)
+    description: str | None = None
+    default_branch: str | None = None
+    config: dict | None = Field(None, description="Board-level configuration overrides")
+
+
+class BoardResponse(BaseModel):
+    """Schema for board API response."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    name: str
+    description: str | None
+    repo_root: str
+    default_branch: str | None
+    config: dict | None
+    owner_id: str | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class BoardListResponse(BaseModel):
+    """Schema for list of boards."""
+
+    boards: list[BoardResponse]
+    total: int
+
+
+class BoardConfigUpdate(BaseModel):
+    """Schema for updating board-level configuration overrides."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    config: dict | None = Field(
+        None,
+        description="Board-level configuration that overrides draft.yaml settings",
+    )
+
+
+class BoardConfigResponse(BaseModel):
+    """Schema for board configuration response."""
+
+    board_id: str
+    config: dict | None = Field(None, description="Board-level configuration JSON")
+    has_overrides: bool = Field(
+        default=False,
+        description="Whether the board has custom configuration overrides",
+    )

package/app/backend/app/schemas/common.py

@@ -0,0 +1,33 @@
+"""Common Pydantic schemas for API responses."""
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+class ErrorResponse(BaseModel):
+    """Schema for error responses."""
+
+    detail: str
+    error_type: str | None = None
+
+
+class SuccessResponse(BaseModel):
+    """Schema for simple success responses."""
+
+    message: str
+    success: bool = True
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    """Generic paginated response wrapper.
+
+    Used for list endpoints that support pagination via page/limit params.
+    """
+
+    items: list[T]
+    total: int = Field(description="Total number of items matching the query")
+    page: int = Field(description="Current page number (1-based)")
+    limit: int = Field(description="Number of items per page")