foundry-mcp 0.3.3__py3-none-any.whl → 0.8.10__py3-none-any.whl

foundry_mcp/core/responses.py

@@ -113,14 +113,23 @@ class ErrorCode(str, Enum):
     VALIDATION_ERROR = "VALIDATION_ERROR"
     INVALID_FORMAT = "INVALID_FORMAT"
     MISSING_REQUIRED = "MISSING_REQUIRED"
+    INVALID_PARENT = "INVALID_PARENT"
+    INVALID_POSITION = "INVALID_POSITION"
+    INVALID_REGEX_PATTERN = "INVALID_REGEX_PATTERN"
+    PATTERN_TOO_BROAD = "PATTERN_TOO_BROAD"
 
     # Resource errors
     NOT_FOUND = "NOT_FOUND"
     SPEC_NOT_FOUND = "SPEC_NOT_FOUND"
     TASK_NOT_FOUND = "TASK_NOT_FOUND"
     PHASE_NOT_FOUND = "PHASE_NOT_FOUND"
+    DEPENDENCY_NOT_FOUND = "DEPENDENCY_NOT_FOUND"
+    BACKUP_NOT_FOUND = "BACKUP_NOT_FOUND"
+    NO_MATCHES_FOUND = "NO_MATCHES_FOUND"
     DUPLICATE_ENTRY = "DUPLICATE_ENTRY"
     CONFLICT = "CONFLICT"
+    CIRCULAR_DEPENDENCY = "CIRCULAR_DEPENDENCY"
+    SELF_REFERENCE = "SELF_REFERENCE"
 
     # Access errors
     UNAUTHORIZED = "UNAUTHORIZED"
@@ -131,6 +140,11 @@ class ErrorCode(str, Enum):
     # System errors
     INTERNAL_ERROR = "INTERNAL_ERROR"
     UNAVAILABLE = "UNAVAILABLE"
+    RESOURCE_BUSY = "RESOURCE_BUSY"
+    BACKUP_CORRUPTED = "BACKUP_CORRUPTED"
+    ROLLBACK_FAILED = "ROLLBACK_FAILED"
+    COMPARISON_FAILED = "COMPARISON_FAILED"
+    OPERATION_FAILED = "OPERATION_FAILED"
 
     # AI/LLM Provider errors
     AI_NO_PROVIDER = "AI_NO_PROVIDER"
@@ -604,6 +618,443 @@ def unavailable_error(
     )
 
 
+# ---------------------------------------------------------------------------
+# Spec Modification Error Helpers
+# ---------------------------------------------------------------------------
+
+
+def circular_dependency_error(
+    task_id: str,
+    target_id: str,
+    *,
+    cycle_path: Optional[Sequence[str]] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for circular dependency detection.
+
+    Use when a move or dependency operation would create a cycle.
+
+    Args:
+        task_id: The task being moved or modified.
+        target_id: The target parent or dependency that would create a cycle.
+        cycle_path: Optional sequence showing the dependency cycle path.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> circular_dependency_error("task-3", "task-1", cycle_path=["task-1", "task-2", "task-3"])
+    """
+    data: Dict[str, Any] = {
+        "task_id": task_id,
+        "target_id": target_id,
+    }
+    if cycle_path:
+        data["cycle_path"] = list(cycle_path)
+
+    return error_response(
+        f"Circular dependency detected: {task_id} cannot depend on {target_id}",
+        error_code=ErrorCode.CIRCULAR_DEPENDENCY,
+        error_type=ErrorType.CONFLICT,
+        data=data,
+        remediation=remediation
+        or "Remove an existing dependency to break the cycle before adding this one.",
+        request_id=request_id,
+    )
+
+
+def invalid_parent_error(
+    task_id: str,
+    target_parent: str,
+    reason: str,
+    *,
+    valid_parents: Optional[Sequence[str]] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for invalid parent in move operation.
+
+    Use when a task cannot be moved to the specified parent.
+
+    Args:
+        task_id: The task being moved.
+        target_parent: The invalid target parent.
+        reason: Why the parent is invalid (e.g., "is a task, not a phase").
+        valid_parents: Optional list of valid parent IDs.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> invalid_parent_error("task-3-1", "task-2-1", "target is a task, not a phase")
+    """
+    data: Dict[str, Any] = {
+        "task_id": task_id,
+        "target_parent": target_parent,
+        "reason": reason,
+    }
+    if valid_parents:
+        data["valid_parents"] = list(valid_parents)
+
+    return error_response(
+        f"Invalid parent '{target_parent}' for task '{task_id}': {reason}",
+        error_code=ErrorCode.INVALID_PARENT,
+        error_type=ErrorType.VALIDATION,
+        data=data,
+        remediation=remediation or "Specify a valid phase or parent task as the target.",
+        request_id=request_id,
+    )
+
+
+def self_reference_error(
+    task_id: str,
+    operation: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for self-referencing operations.
+
+    Use when a task references itself in dependencies or move operations.
+
+    Args:
+        task_id: The task that references itself.
+        operation: The operation attempted (e.g., "add-dependency", "move").
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> self_reference_error("task-1-1", "add-dependency")
+    """
+    return error_response(
+        f"Task '{task_id}' cannot reference itself in {operation}",
+        error_code=ErrorCode.SELF_REFERENCE,
+        error_type=ErrorType.VALIDATION,
+        data={"task_id": task_id, "operation": operation},
+        remediation=remediation or "Specify a different task ID as the target.",
+        request_id=request_id,
+    )
+
+
+def dependency_not_found_error(
+    task_id: str,
+    dependency_id: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for missing dependency in remove operation.
+
+    Use when trying to remove a dependency that doesn't exist.
+
+    Args:
+        task_id: The task being modified.
+        dependency_id: The dependency that wasn't found.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> dependency_not_found_error("task-1-1", "task-2-1")
+    """
+    return error_response(
+        f"Dependency '{dependency_id}' not found on task '{task_id}'",
+        error_code=ErrorCode.DEPENDENCY_NOT_FOUND,
+        error_type=ErrorType.NOT_FOUND,
+        data={"task_id": task_id, "dependency_id": dependency_id},
+        remediation=remediation
+        or "Check existing dependencies using task info before removing.",
+        request_id=request_id,
+    )
+
+
+def invalid_position_error(
+    item_id: str,
+    position: int,
+    max_position: int,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for invalid position in move/reorder operation.
+
+    Use when the specified position is out of valid range.
+
+    Args:
+        item_id: The item being moved (phase or task ID).
+        position: The invalid position specified.
+        max_position: The maximum valid position.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> invalid_position_error("phase-3", 10, 5)
+    """
+    return error_response(
+        f"Invalid position {position} for '{item_id}': must be 1-{max_position}",
+        error_code=ErrorCode.INVALID_POSITION,
+        error_type=ErrorType.VALIDATION,
+        data={
+            "item_id": item_id,
+            "position": position,
+            "max_position": max_position,
+            "valid_range": f"1-{max_position}",
+        },
+        remediation=remediation or f"Specify a position between 1 and {max_position}.",
+        request_id=request_id,
+    )
+
+
+def invalid_regex_error(
+    pattern: str,
+    error_detail: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for invalid regex pattern.
+
+    Use when a find/replace pattern is not valid regex.
+
+    Args:
+        pattern: The invalid regex pattern.
+        error_detail: The regex error message.
+        remediation: Guidance on how to fix the pattern.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> invalid_regex_error("[unclosed", "unterminated character set")
+    """
+    return error_response(
+        f"Invalid regex pattern: {error_detail}",
+        error_code=ErrorCode.INVALID_REGEX_PATTERN,
+        error_type=ErrorType.VALIDATION,
+        data={"pattern": pattern, "error_detail": error_detail},
+        remediation=remediation
+        or "Check regex syntax. Use raw strings and escape special characters.",
+        request_id=request_id,
+    )
+
+
+def pattern_too_broad_error(
+    pattern: str,
+    match_count: int,
+    max_matches: int,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for overly broad patterns.
+
+    Use when a find/replace pattern matches too many items.
+
+    Args:
+        pattern: The pattern that matched too broadly.
+        match_count: Number of matches found.
+        max_matches: Maximum allowed matches.
+        remediation: Guidance on how to narrow the pattern.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> pattern_too_broad_error(".*", 500, 100)
+    """
+    return error_response(
+        f"Pattern too broad: {match_count} matches exceeds limit of {max_matches}",
+        error_code=ErrorCode.PATTERN_TOO_BROAD,
+        error_type=ErrorType.VALIDATION,
+        data={
+            "pattern": pattern,
+            "match_count": match_count,
+            "max_matches": max_matches,
+        },
+        remediation=remediation
+        or "Use a more specific pattern or apply to a narrower scope.",
+        request_id=request_id,
+    )
+
+
+def no_matches_error(
+    pattern: str,
+    scope: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for patterns with no matches.
+
+    Use when a find/replace pattern matches nothing.
+
+    Args:
+        pattern: The pattern that found no matches.
+        scope: Where the search was performed (e.g., "spec", "phase-1").
+        remediation: Guidance on what to check.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> no_matches_error("deprecated_function", "spec my-spec-001")
+    """
+    return error_response(
+        f"No matches found for pattern '{pattern}' in {scope}",
+        error_code=ErrorCode.NO_MATCHES_FOUND,
+        error_type=ErrorType.NOT_FOUND,
+        data={"pattern": pattern, "scope": scope},
+        remediation=remediation
+        or "Verify the pattern and scope. Use dry-run to preview matches.",
+        request_id=request_id,
+    )
+
+
+def backup_not_found_error(
+    spec_id: str,
+    backup_id: Optional[str] = None,
+    *,
+    available_backups: Optional[Sequence[str]] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for missing backup.
+
+    Use when a rollback or diff references a non-existent backup.
+
+    Args:
+        spec_id: The spec whose backup is missing.
+        backup_id: The specific backup ID that wasn't found.
+        available_backups: Optional list of available backup IDs.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> backup_not_found_error("my-spec-001", "backup-2024-01-15")
+    """
+    data: Dict[str, Any] = {"spec_id": spec_id}
+    if backup_id:
+        data["backup_id"] = backup_id
+    if available_backups:
+        data["available_backups"] = list(available_backups)
+
+    message = f"Backup not found for spec '{spec_id}'"
+    if backup_id:
+        message = f"Backup '{backup_id}' not found for spec '{spec_id}'"
+
+    return error_response(
+        message,
+        error_code=ErrorCode.BACKUP_NOT_FOUND,
+        error_type=ErrorType.NOT_FOUND,
+        data=data,
+        remediation=remediation or "List available backups using spec action='history'.",
+        request_id=request_id,
+    )
+
+
+def backup_corrupted_error(
+    spec_id: str,
+    backup_id: str,
+    error_detail: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for corrupted backup.
+
+    Use when a backup file exists but cannot be loaded.
+
+    Args:
+        spec_id: The spec whose backup is corrupted.
+        backup_id: The corrupted backup identifier.
+        error_detail: Description of the corruption.
+        remediation: Guidance on how to recover.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> backup_corrupted_error("my-spec", "backup-001", "Invalid JSON structure")
+    """
+    return error_response(
+        f"Backup '{backup_id}' for spec '{spec_id}' is corrupted: {error_detail}",
+        error_code=ErrorCode.BACKUP_CORRUPTED,
+        error_type=ErrorType.INTERNAL,
+        data={
+            "spec_id": spec_id,
+            "backup_id": backup_id,
+            "error_detail": error_detail,
+        },
+        remediation=remediation
+        or "Try an earlier backup or restore from version control.",
+        request_id=request_id,
+    )
+
+
+def rollback_failed_error(
+    spec_id: str,
+    backup_id: str,
+    error_detail: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for failed rollback operation.
+
+    Use when a rollback operation fails after starting.
+
+    Args:
+        spec_id: The spec being rolled back.
+        backup_id: The backup being restored from.
+        error_detail: What went wrong during rollback.
+        remediation: Guidance on how to recover.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> rollback_failed_error("my-spec", "backup-001", "Write permission denied")
+    """
+    return error_response(
+        f"Rollback failed for spec '{spec_id}' from backup '{backup_id}': {error_detail}",
+        error_code=ErrorCode.ROLLBACK_FAILED,
+        error_type=ErrorType.INTERNAL,
+        data={
+            "spec_id": spec_id,
+            "backup_id": backup_id,
+            "error_detail": error_detail,
+        },
+        remediation=remediation
+        or "Check file permissions. A safety backup was created before rollback attempt.",
+        request_id=request_id,
+    )
+
+
+def comparison_failed_error(
+    source: str,
+    target: str,
+    error_detail: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for failed diff/comparison operation.
+
+    Use when a spec comparison operation fails.
+
+    Args:
+        source: The source spec or backup being compared.
+        target: The target spec or backup being compared.
+        error_detail: What went wrong during comparison.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> comparison_failed_error("my-spec-v1", "my-spec-v2", "Schema version mismatch")
+    """
+    return error_response(
+        f"Comparison failed between '{source}' and '{target}': {error_detail}",
+        error_code=ErrorCode.COMPARISON_FAILED,
+        error_type=ErrorType.INTERNAL,
+        data={
+            "source": source,
+            "target": target,
+            "error_detail": error_detail,
+        },
+        remediation=remediation
+        or "Ensure both specs are valid and use compatible schema versions.",
+        request_id=request_id,
+    )
+
+
 # ---------------------------------------------------------------------------
 # AI/LLM Provider Error Helpers
 # ---------------------------------------------------------------------------
@@ -881,6 +1332,13 @@ def ai_cache_stale_error(
 # ---------------------------------------------------------------------------
 
 
+try:
+    from pydantic import BaseModel, Field
+    PYDANTIC_AVAILABLE = True
+except ImportError:
+    PYDANTIC_AVAILABLE = False
+
+
 def sanitize_error_message(
     exc: Exception,
     context: str = "",
@@ -932,3 +1390,235 @@ def sanitize_error_message(
     # Generic fallback - don't expose exception message
     suffix = f" ({type_name})" if include_type else ""
     return f"An internal error occurred{suffix}"
+
+
+# ---------------------------------------------------------------------------
+# Batch Operation Response Schemas (Pydantic)
+# ---------------------------------------------------------------------------
+# These schemas provide type-safe definitions for batch operation responses.
+# They ensure contract stability and enable validation of batch operation data.
+
+
+if PYDANTIC_AVAILABLE:
+
+    class DependencyNode(BaseModel):
+        """A node in the dependency graph representing a task."""
+
+        id: str = Field(..., description="Task identifier")
+        title: str = Field(default="", description="Task title")
+        status: str = Field(default="", description="Task status")
+        file_path: Optional[str] = Field(
+            default=None, description="File path associated with the task"
+        )
+        is_target: bool = Field(
+            default=False, description="Whether this is a target task in the batch"
+        )
+
+    class DependencyEdge(BaseModel):
+        """An edge in the dependency graph representing a dependency relationship."""
+
+        from_id: str = Field(..., alias="from", description="Source task ID")
+        to_id: str = Field(..., alias="to", description="Target task ID")
+        edge_type: str = Field(
+            default="blocks", alias="type", description="Type of dependency (blocks)"
+        )
+
+        model_config = {"populate_by_name": True}
+
+    class DependencyGraph(BaseModel):
+        """Dependency graph structure for batch tasks.
+
+        Contains nodes (tasks) and edges (dependency relationships) to visualize
+        task dependencies for parallel execution planning.
+        """
+
+        nodes: list[DependencyNode] = Field(
+            default_factory=list, description="Task nodes in the graph"
+        )
+        edges: list[DependencyEdge] = Field(
+            default_factory=list, description="Dependency edges between tasks"
+        )
+
+    class BatchTaskDependencies(BaseModel):
+        """Dependency status for a task in a batch."""
+
+        task_id: str = Field(..., description="Task identifier")
+        can_start: bool = Field(
+            default=True, description="Whether the task can be started"
+        )
+        blocked_by: list[str] = Field(
+            default_factory=list, description="IDs of tasks blocking this one"
+        )
+        soft_depends: list[str] = Field(
+            default_factory=list, description="IDs of soft dependencies"
+        )
+        blocks: list[str] = Field(
+            default_factory=list, description="IDs of tasks this one blocks"
+        )
+
+    class BatchTaskContext(BaseModel):
+        """Context for a single task in a batch prepare response.
+
+        Contains all information needed to execute a task in parallel with others.
+        """
+
+        task_id: str = Field(..., description="Unique task identifier")
+        title: str = Field(default="", description="Task title")
+        task_type: str = Field(
+            default="task", alias="type", description="Task type (task, subtask, verify)"
+        )
+        status: str = Field(default="pending", description="Current task status")
+        metadata: Dict[str, Any] = Field(
+            default_factory=dict,
+            description="Task metadata including file_path, description, etc.",
+        )
+        dependencies: Optional[BatchTaskDependencies] = Field(
+            default=None, description="Dependency status for the task"
+        )
+        phase: Optional[Dict[str, Any]] = Field(
+            default=None, description="Phase context (id, title, progress)"
+        )
+        parent: Optional[Dict[str, Any]] = Field(
+            default=None, description="Parent task context (id, title, position_label)"
+        )
+
+        model_config = {"populate_by_name": True}
+
+    class StaleTaskInfo(BaseModel):
+        """Information about a stale in_progress task."""
+
+        task_id: str = Field(..., description="Task identifier")
+        title: str = Field(default="", description="Task title")
+
+    class BatchPrepareResponse(BaseModel):
+        """Response schema for prepare_batch_context operation.
+
+        Contains independent tasks that can be executed in parallel along with
+        context, dependency information, and warnings.
+        """
+
+        tasks: list[BatchTaskContext] = Field(
+            default_factory=list, description="Tasks ready for parallel execution"
+        )
+        task_count: int = Field(default=0, description="Number of tasks in the batch")
+        spec_complete: bool = Field(
+            default=False, description="Whether the spec has no remaining tasks"
+        )
+        all_blocked: bool = Field(
+            default=False, description="Whether all remaining tasks are blocked"
+        )
+        warnings: list[str] = Field(
+            default_factory=list, description="Non-fatal warnings about the batch"
+        )
+        stale_tasks: list[StaleTaskInfo] = Field(
+            default_factory=list, description="In-progress tasks exceeding time threshold"
+        )
+        dependency_graph: DependencyGraph = Field(
+            default_factory=DependencyGraph,
+            description="Dependency graph for batch tasks",
+        )
+        token_estimate: Optional[int] = Field(
+            default=None, description="Estimated token count for the batch context"
+        )
+
+    class BatchStartResponse(BaseModel):
+        """Response schema for start_batch operation.
+
+        Confirms which tasks were atomically started and when.
+        """
+
+        started: list[str] = Field(
+            default_factory=list, description="IDs of tasks successfully started"
+        )
+        started_count: int = Field(
+            default=0, description="Number of tasks started"
+        )
+        started_at: Optional[str] = Field(
+            default=None, description="ISO timestamp when tasks were started"
+        )
+        errors: Optional[list[str]] = Field(
+            default=None, description="Validation errors if operation failed"
+        )
+
+    class BatchTaskCompletion(BaseModel):
+        """Input schema for a single task completion in complete_batch.
+
+        Used to specify outcome for each task being completed.
+        """
+
+        task_id: str = Field(..., description="Task identifier to complete")
+        success: bool = Field(
+            ..., description="True if task succeeded, False if failed"
+        )
+        completion_note: str = Field(
+            default="", description="Note describing what was accomplished or why it failed"
+        )
+
+    class BatchTaskResult(BaseModel):
+        """Result for a single task in the complete_batch response."""
+
+        status: str = Field(
+            ..., description="Result status: completed, failed, skipped, error"
+        )
+        completed_at: Optional[str] = Field(
+            default=None, description="ISO timestamp when completed (if successful)"
+        )
+        failed_at: Optional[str] = Field(
+            default=None, description="ISO timestamp when failed (if unsuccessful)"
+        )
+        retry_count: Optional[int] = Field(
+            default=None, description="Updated retry count (if failed)"
+        )
+        error: Optional[str] = Field(
+            default=None, description="Error message (if status is error or skipped)"
+        )
+
+    class BatchCompleteResponse(BaseModel):
+        """Response schema for complete_batch operation.
+
+        Contains per-task results and summary counts for the batch completion.
+        """
+
+        results: Dict[str, BatchTaskResult] = Field(
+            default_factory=dict,
+            description="Per-task results keyed by task_id",
+        )
+        completed_count: int = Field(
+            default=0, description="Number of tasks successfully completed"
+        )
+        failed_count: int = Field(
+            default=0, description="Number of tasks that failed"
+        )
+        total_processed: int = Field(
+            default=0, description="Total number of completions processed"
+        )
+
+    # Export Pydantic models
+    __all_pydantic__ = [
+        "DependencyNode",
+        "DependencyEdge",
+        "DependencyGraph",
+        "BatchTaskDependencies",
+        "BatchTaskContext",
+        "StaleTaskInfo",
+        "BatchPrepareResponse",
+        "BatchStartResponse",
+        "BatchTaskCompletion",
+        "BatchTaskResult",
+        "BatchCompleteResponse",
+    ]
+
+else:
+    # Pydantic not available - provide None placeholders
+    DependencyNode = None  # type: ignore[misc,assignment]
+    DependencyEdge = None  # type: ignore[misc,assignment]
+    DependencyGraph = None  # type: ignore[misc,assignment]
+    BatchTaskDependencies = None  # type: ignore[misc,assignment]
+    BatchTaskContext = None  # type: ignore[misc,assignment]
+    StaleTaskInfo = None  # type: ignore[misc,assignment]
+    BatchPrepareResponse = None  # type: ignore[misc,assignment]
+    BatchStartResponse = None  # type: ignore[misc,assignment]
+    BatchTaskCompletion = None  # type: ignore[misc,assignment]
+    BatchTaskResult = None  # type: ignore[misc,assignment]
+    BatchCompleteResponse = None  # type: ignore[misc,assignment]
+    __all_pydantic__ = []