foundry-mcp 0.3.3__py3-none-any.whl

foundry_mcp/core/pagination.py

@@ -0,0 +1,255 @@
+"""
+Pagination utilities for MCP tool operations.
+
+Provides cursor-based pagination with opaque cursors, encoding/decoding,
+and response formatting helpers for list-style operations.
+
+Pagination Defaults
+===================
+
+Use these constants for consistent pagination across tools:
+
+    DEFAULT_PAGE_SIZE (100)  - Default number of items per page
+    MAX_PAGE_SIZE (1000)     - Maximum allowed page size
+
+Example usage:
+
+    from foundry_mcp.core.pagination import (
+        DEFAULT_PAGE_SIZE,
+        MAX_PAGE_SIZE,
+        encode_cursor,
+        decode_cursor,
+        paginated_response,
+    )
+
+    @mcp.tool()
+    def list_items(cursor: str = None, limit: int = DEFAULT_PAGE_SIZE) -> dict:
+        limit = min(max(1, limit), MAX_PAGE_SIZE)
+
+        # Decode cursor if provided
+        start_after = None
+        if cursor:
+            cursor_data = decode_cursor(cursor)
+            start_after = cursor_data.get("last_id")
+
+        # Fetch items (one extra to detect has_more)
+        items = db.list_items(start_after=start_after, limit=limit + 1)
+        has_more = len(items) > limit
+        if has_more:
+            items = items[:limit]
+
+        # Build response with pagination
+        next_cursor = None
+        if has_more and items:
+            next_cursor = encode_cursor({"last_id": items[-1]["id"]})
+
+        return paginated_response(
+            data={"items": items},
+            cursor=next_cursor,
+            has_more=has_more,
+            page_size=limit,
+        )
+"""
+
+import base64
+import json
+from dataclasses import asdict
+from typing import Any, Dict, Optional
+
+from foundry_mcp.core.responses import success_response
+
+
+# ---------------------------------------------------------------------------
+# Pagination Constants
+# ---------------------------------------------------------------------------
+
+#: Default number of items per page
+DEFAULT_PAGE_SIZE: int = 100
+
+#: Maximum allowed page size
+MAX_PAGE_SIZE: int = 1000
+
+#: Cursor format version (for future compatibility)
+CURSOR_VERSION: int = 1
+
+
+# ---------------------------------------------------------------------------
+# Cursor Encoding/Decoding
+# ---------------------------------------------------------------------------
+
+
+class CursorError(Exception):
+    """Error during cursor encoding or decoding.
+
+    Attributes:
+        cursor: The invalid cursor string (if decoding).
+        reason: Description of what went wrong.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        cursor: Optional[str] = None,
+        reason: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.cursor = cursor
+        self.reason = reason
+
+
+def encode_cursor(data: Dict[str, Any]) -> str:
+    """Encode cursor data as opaque Base64 token.
+
+    The cursor is a URL-safe Base64-encoded JSON object containing
+    position information for resuming pagination.
+
+    Args:
+        data: Dictionary containing cursor data (typically last_id,
+              timestamp, or other position markers).
+
+    Returns:
+        Opaque cursor string (URL-safe Base64 encoded).
+
+    Example:
+        >>> cursor = encode_cursor({"last_id": "item_123"})
+        >>> # Returns: "eyJsYXN0X2lkIjogIml0ZW1fMTIzIiwgInZlcnNpb24iOiAxfQ=="
+    """
+    # Add version for future format migrations
+    cursor_data = {**data, "version": CURSOR_VERSION}
+    json_str = json.dumps(cursor_data, separators=(",", ":"))
+    return base64.urlsafe_b64encode(json_str.encode()).decode()
+
+
+def decode_cursor(cursor: str) -> Dict[str, Any]:
+    """Decode cursor token to dictionary.
+
+    Args:
+        cursor: Opaque cursor string from previous response.
+
+    Returns:
+        Dictionary with cursor data including position markers.
+
+    Raises:
+        CursorError: If cursor is invalid or cannot be decoded.
+
+    Example:
+        >>> data = decode_cursor("eyJsYXN0X2lkIjogIml0ZW1fMTIzIiwgInZlcnNpb24iOiAxfQ==")
+        >>> print(data["last_id"])
+        "item_123"
+    """
+    if not cursor:
+        raise CursorError("Cursor cannot be empty", cursor=cursor, reason="empty")
+
+    try:
+        decoded_bytes = base64.urlsafe_b64decode(cursor.encode())
+        data = json.loads(decoded_bytes.decode())
+
+        if not isinstance(data, dict):
+            raise CursorError(
+                "Invalid cursor format",
+                cursor=cursor,
+                reason="not_a_dict",
+            )
+
+        return data
+
+    except (ValueError, json.JSONDecodeError) as e:
+        raise CursorError(
+            f"Failed to decode cursor: {str(e)}",
+            cursor=cursor,
+            reason="decode_failed",
+        )
+
+
+def validate_cursor(cursor: str) -> bool:
+    """Check if cursor is valid without raising exceptions.
+
+    Args:
+        cursor: Cursor string to validate.
+
+    Returns:
+        True if cursor is valid, False otherwise.
+    """
+    try:
+        decode_cursor(cursor)
+        return True
+    except CursorError:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Pagination Response Helper
+# ---------------------------------------------------------------------------
+
+
+def paginated_response(
+    data: Dict[str, Any],
+    cursor: Optional[str] = None,
+    has_more: bool = False,
+    page_size: int = DEFAULT_PAGE_SIZE,
+    total_count: Optional[int] = None,
+    **kwargs: Any,
+) -> Dict[str, Any]:
+    """Create a success response with pagination metadata.
+
+    Wraps the data in a standard MCP response envelope with
+    meta.pagination containing cursor and pagination info.
+
+    Args:
+        data: Response data (typically contains items list).
+        cursor: Next page cursor (None if no more pages).
+        has_more: Whether more items exist after this page.
+        page_size: Number of items in this page.
+        total_count: Total count of items (optional, only if efficient).
+        **kwargs: Additional arguments passed to success_response.
+
+    Returns:
+        Dict formatted as MCP response with pagination metadata.
+
+    Example:
+        >>> response = paginated_response(
+        ...     data={"items": [...]},
+        ...     cursor="abc123",
+        ...     has_more=True,
+        ...     page_size=100,
+        ... )
+        >>> # Response includes meta.pagination with cursor, has_more, etc.
+    """
+    pagination = {
+        "cursor": cursor,
+        "has_more": has_more,
+        "page_size": page_size,
+    }
+
+    if total_count is not None:
+        pagination["total_count"] = total_count
+
+    return asdict(success_response(data=data, pagination=pagination, **kwargs))
+
+
+def normalize_page_size(
+    requested: Optional[int],
+    default: int = DEFAULT_PAGE_SIZE,
+    maximum: int = MAX_PAGE_SIZE,
+) -> int:
+    """Normalize requested page size to valid range.
+
+    Args:
+        requested: Requested page size (may be None or out of range).
+        default: Default page size if None provided.
+        maximum: Maximum allowed page size.
+
+    Returns:
+        Valid page size between 1 and maximum.
+
+    Example:
+        >>> normalize_page_size(None)
+        100
+        >>> normalize_page_size(5000)
+        1000
+        >>> normalize_page_size(-1)
+        1
+    """
+    if requested is None:
+        return default
+    return min(max(1, requested), maximum)

foundry_mcp/core/progress.py

@@ -0,0 +1,317 @@
+"""
+Progress calculation utilities for SDD JSON specs.
+Provides hierarchical progress recalculation and status updates.
+"""
+
+from datetime import datetime, timezone
+from typing import Dict, List, Any
+
+
+# Status icons for task visualization
+STATUS_ICONS = {
+    "pending": "⏳",
+    "in_progress": "🔄",
+    "completed": "✅",
+    "blocked": "🚫",
+    "failed": "❌",
+}
+
+
+def get_status_icon(status: str) -> str:
+    """
+    Get icon for a task status.
+
+    Args:
+        status: Task status string
+
+    Returns:
+        Status icon character
+    """
+    return STATUS_ICONS.get(status, "❓")
+
+
+def recalculate_progress(spec_data: Dict[str, Any], node_id: str = "spec-root") -> Dict[str, Any]:
+    """
+    Recursively recalculate progress for a node and all its parents.
+
+    Modifies spec_data in-place by updating completed_tasks, total_tasks,
+    and status fields for the node and all ancestors.
+
+    Args:
+        spec_data: JSON spec file data dictionary
+        node_id: Node to start recalculation from (default: spec-root)
+
+    Returns:
+        The modified spec_data dictionary (for convenience/chaining)
+    """
+    if not spec_data:
+        return {}
+
+    hierarchy = spec_data.get("hierarchy", {})
+
+    if node_id not in hierarchy:
+        return spec_data
+
+    node = hierarchy[node_id]
+    children = node.get("children", [])
+
+    if not children:
+        # Leaf node - set based on own status
+        node["completed_tasks"] = 1 if node.get("status") == "completed" else 0
+        node["total_tasks"] = 1
+    else:
+        # Non-leaf node - recursively calculate from children
+        total_completed = 0
+        total_tasks = 0
+
+        for child_id in children:
+            # Recursively recalculate child first
+            recalculate_progress(spec_data, child_id)
+
+            child = hierarchy.get(child_id, {})
+            total_completed += child.get("completed_tasks", 0)
+            total_tasks += child.get("total_tasks", 0)
+
+        node["completed_tasks"] = total_completed
+        node["total_tasks"] = total_tasks
+
+    # Update node status based on progress
+    update_node_status(node, hierarchy)
+
+    return spec_data
+
+
+def update_node_status(node: Dict[str, Any], hierarchy: Dict[str, Any] = None) -> None:
+    """
+    Update a node's status based on its children's progress.
+
+    Modifies node in-place. Does not affect manually set statuses
+    for leaf nodes (tasks).
+
+    Args:
+        node: Node dictionary from hierarchy
+        hierarchy: Full hierarchy dictionary (needed to check child statuses)
+    """
+    # Don't auto-update status for leaf tasks (they're set manually)
+    if node.get("type") == "task" and not node.get("children"):
+        return
+
+    # Track if node is blocked (we'll skip status changes but allow parent updates)
+    is_blocked = node.get("status") == "blocked"
+
+    # Handle manually-completed tasks with children
+    if node.get("metadata", {}).get("completed_at") and node.get("children"):
+        # Check if actual children progress matches the "completed" state
+        actual_completed = node.get("completed_tasks", 0)
+        total = node.get("total_tasks", 0)
+
+        if actual_completed < total:
+            # Inconsistent state: parent marked complete but children aren't.
+            # Remove completed_at to allow normal status calculation to take over below.
+            if "metadata" in node and "completed_at" in node["metadata"]:
+                del node["metadata"]["completed_at"]
+        else:
+            # Consistent state, enforce completion
+            node["status"] = "completed"
+
+    # If blocked, don't change status but continue to allow count updates
+    if is_blocked:
+        return
+
+    # Check if any children are in_progress (takes priority over count-based logic)
+    if hierarchy and node.get("children"):
+        for child_id in node.get("children", []):
+            child = hierarchy.get(child_id, {})
+            if child.get("status") == "in_progress":
+                node["status"] = "in_progress"
+                return
+
+    completed = node.get("completed_tasks", 0)
+    total = node.get("total_tasks", 0)
+
+    if total == 0:
+        node["status"] = "pending"
+    elif completed == 0:
+        node["status"] = "pending"
+    elif completed == total:
+        # Check if status is changing to completed (auto-completion)
+        was_completed = node.get("status") == "completed"
+        node["status"] = "completed"
+
+        # Set needs_journaling flag for parent nodes (groups, phases)
+        # when they auto-complete (not manually set)
+        if not was_completed and node.get("type") in ["group", "phase"]:
+            if "metadata" not in node:
+                node["metadata"] = {}
+            node["metadata"]["needs_journaling"] = True
+            node["metadata"]["completed_at"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    else:
+        node["status"] = "in_progress"
+
+
+def update_parent_status(spec_data: Dict[str, Any], node_id: str) -> Dict[str, Any]:
+    """
+    Update status and progress for a node's parent chain.
+
+    Use this after updating a task status to propagate changes up the hierarchy.
+
+    Args:
+        spec_data: JSON spec file data dictionary
+        node_id: Node whose parents should be updated
+
+    Returns:
+        The modified spec_data dictionary (for convenience/chaining)
+    """
+    if not spec_data:
+        return {}
+
+    hierarchy = spec_data.get("hierarchy", {})
+
+    if node_id not in hierarchy:
+        return spec_data
+
+    node = hierarchy[node_id]
+    parent_id = node.get("parent")
+
+    # Walk up the parent chain
+    while parent_id and parent_id in hierarchy:
+        # Recalculate progress for parent
+        recalculate_progress(spec_data, parent_id)
+
+        # Move to next parent
+        parent = hierarchy[parent_id]
+        parent_id = parent.get("parent")
+
+    return spec_data
+
+
+def get_progress_summary(spec_data: Dict[str, Any], node_id: str = "spec-root") -> Dict[str, Any]:
+    """
+    Get progress summary for a node.
+
+    Args:
+        spec_data: JSON spec file data
+        node_id: Node to get progress for (default: spec-root)
+
+    Returns:
+        Dictionary with progress information
+    """
+    if not spec_data:
+        return {"error": "No state data provided"}
+
+    # Recalculate progress to ensure counts are up-to-date
+    recalculate_progress(spec_data, node_id)
+
+    hierarchy = spec_data.get("hierarchy", {})
+    node = hierarchy.get(node_id)
+
+    if not node:
+        return {"error": f"Node {node_id} not found"}
+
+    total = node.get("total_tasks", 0)
+    completed = node.get("completed_tasks", 0)
+    percentage = int((completed / total * 100)) if total > 0 else 0
+
+    # Extract spec_id from spec_data
+    spec_id = spec_data.get("spec_id", "")
+
+    # Find current phase (first in_progress, or first pending if none)
+    current_phase = None
+    for key, value in hierarchy.items():
+        if value.get("type") == "phase":
+            if value.get("status") == "in_progress":
+                current_phase = {
+                    "id": key,
+                    "title": value.get("title", ""),
+                    "completed": value.get("completed_tasks", 0),
+                    "total": value.get("total_tasks", 0)
+                }
+                break
+            elif current_phase is None and value.get("status") == "pending":
+                current_phase = {
+                    "id": key,
+                    "title": value.get("title", ""),
+                    "completed": value.get("completed_tasks", 0),
+                    "total": value.get("total_tasks", 0)
+                }
+
+    return {
+        "node_id": node_id,
+        "spec_id": spec_id,
+        "title": node.get("title", ""),
+        "type": node.get("type", ""),
+        "status": node.get("status", ""),
+        "total_tasks": total,
+        "completed_tasks": completed,
+        "percentage": percentage,
+        "remaining_tasks": total - completed,
+        "current_phase": current_phase
+    }
+
+
+def list_phases(spec_data: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """
+    List all phases with their status and progress.
+
+    Args:
+        spec_data: JSON spec file data
+
+    Returns:
+        List of phase dictionaries
+    """
+    if not spec_data:
+        return []
+
+    hierarchy = spec_data.get("hierarchy", {})
+
+    phases = []
+    for key, value in hierarchy.items():
+        if value.get("type") == "phase":
+            total = value.get("total_tasks", 0)
+            completed = value.get("completed_tasks", 0)
+            percentage = int((completed / total * 100)) if total > 0 else 0
+
+            phases.append({
+                "id": key,
+                "title": value.get("title", ""),
+                "status": value.get("status", ""),
+                "completed_tasks": completed,
+                "total_tasks": total,
+                "percentage": percentage
+            })
+
+    # Sort by phase ID (phase-1, phase-2, etc.)
+    phases.sort(key=lambda p: p["id"])
+
+    return phases
+
+
+def get_task_counts_by_status(spec_data: Dict[str, Any]) -> Dict[str, int]:
+    """
+    Count tasks by their status.
+
+    Args:
+        spec_data: JSON spec file data
+
+    Returns:
+        Dictionary mapping status to count
+    """
+    if not spec_data:
+        return {"pending": 0, "in_progress": 0, "completed": 0, "blocked": 0}
+
+    hierarchy = spec_data.get("hierarchy", {})
+
+    counts = {
+        "pending": 0,
+        "in_progress": 0,
+        "completed": 0,
+        "blocked": 0
+    }
+
+    for node in hierarchy.values():
+        if node.get("type") == "task":
+            status = node.get("status", "pending")
+            if status in counts:
+                counts[status] += 1
+
+    return counts