steerdev 0.4.27__py3-none-any.whl

steerdev_agent/api/tasks.py

@@ -0,0 +1,659 @@
+"""Task management API client."""
+
+from typing import Any
+
+from loguru import logger
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from steerdev_agent.api.client import SteerDevClient, get_project_id
+from steerdev_agent.api.implementation_plan import (
+    display_implementation_plan,
+    extract_task_description,
+    parse_implementation_plan,
+)
+
+console = Console()
+
+# Linear-native status_type values
+VALID_STATUSES = [
+    "backlog",
+    "unstarted",
+    "started",
+    "completed",
+    "canceled",
+]
+
+# ===== Status Transition Validation =====
+# Uses Linear-native status_type values directly:
+# backlog -> unstarted (ready) -> started (in progress) -> completed
+
+VALID_STATUS_TRANSITIONS: dict[str, list[str]] = {
+    "backlog": ["unstarted", "canceled"],
+    "unstarted": ["started", "backlog", "canceled"],
+    "started": ["completed", "canceled"],
+    "completed": [],  # Terminal state
+    "canceled": [],  # Terminal state
+}
+
+
+def validate_status_transition(current: str, new: str) -> tuple[bool, str | None]:
+    """Validate if a status transition is allowed.
+
+    Args:
+        current: Current task status.
+        new: Desired new status.
+
+    Returns:
+        Tuple of (is_valid, error_message).
+        error_message is None if transition is valid.
+    """
+    if current == new:
+        return True, None
+
+    allowed = VALID_STATUS_TRANSITIONS.get(current, [])
+    if new not in allowed:
+        allowed_str = ", ".join(allowed) if allowed else "none (terminal state)"
+        return False, (
+            f"Cannot transition from '{current}' to '{new}'. Allowed transitions: {allowed_str}"
+        )
+
+    return True, None
+
+
+class TasksClient(SteerDevClient):
+    """Client for task management operations."""
+
+    def get_next_task(self, project_id: str | None = None) -> dict[str, Any] | None:
+        """Fetch the next task to work on (single-task mode, no waves).
+
+        Returns the highest priority task in order:
+        1. In Progress tasks (to continue work)
+        2. Todo tasks (to start new work)
+        3. Backlog tasks (if nothing else available)
+
+        Args:
+            project_id: Filter by project ID. Falls back to STEERDEV_PROJECT_ID env var.
+
+        Returns:
+            Task data dict or None if no tasks available.
+        """
+        effective_project_id = project_id or get_project_id()
+
+        params: dict[str, str] = {"waves": "false"}
+        if effective_project_id:
+            params["project_id"] = effective_project_id
+
+        console.print(f"Fetching next task from {self.api_base}/tasks/next")
+        response = self.get("/tasks/next", params=params if params else None)
+
+        if response.status_code == 404:
+            return None
+
+        if response.status_code != 200:
+            console.print(f"[red]API Error: {response.status_code} - {response.text}[/red]")
+            return None
+
+        return response.json()
+
+    def get_next_wave(self, project_id: str | None = None) -> dict[str, Any] | None:
+        """Fetch the next wave-aware task with full wave context.
+
+        Returns the full wave context including:
+        - Current wave info (number, description, total waves)
+        - All tasks in the current wave with statuses
+        - Completed waves summary
+        - The specific next task to work on
+
+        If no wave tasks exist, returns None (caller should fall back to get_next_task).
+
+        Args:
+            project_id: Filter by project ID. Falls back to STEERDEV_PROJECT_ID env var.
+
+        Returns:
+            Wave response dict or None if no wave tasks available.
+        """
+        effective_project_id = project_id or get_project_id()
+
+        params: dict[str, str] = {"waves": "true"}
+        if effective_project_id:
+            params["project_id"] = effective_project_id
+
+        console.print(f"Fetching next wave task from {self.api_base}/tasks/next")
+        response = self.get("/tasks/next", params=params)
+
+        if response.status_code == 404:
+            return None
+
+        if response.status_code != 200:
+            console.print(f"[red]API Error: {response.status_code} - {response.text}[/red]")
+            return None
+
+        data = response.json()
+        # Check if response is a wave response (has "wave" key) vs single task
+        if "wave" in data and "context" in data:
+            return data
+        # API returned a single task (no wave data) — return None so caller falls back
+        return None
+
+    def list_tasks(
+        self,
+        status: str | None = None,
+        project_id: str | None = None,
+        limit: int = 20,
+    ) -> list[dict[str, Any]]:
+        """List tasks with optional filters.
+
+        Args:
+            status: Filter by status.
+            project_id: Filter by project ID. Falls back to STEERDEV_PROJECT_ID env var.
+            limit: Maximum number of tasks to return.
+
+        Returns:
+            List of task dicts.
+        """
+        effective_project_id = project_id or get_project_id()
+
+        params: dict[str, str | int] = {"limit": limit}
+        if status:
+            params["status"] = status
+        if effective_project_id:
+            params["project_id"] = effective_project_id
+
+        console.print(f"Fetching tasks from {self.api_base}/tasks")
+        response = self.get("/tasks", params=params)
+
+        if response.status_code != 200:
+            console.print(f"[red]API Error: {response.status_code} - {response.text}[/red]")
+            return []
+
+        data = response.json()
+        return data.get("tasks", []) if isinstance(data, dict) else data
+
+    def get_task(self, task_id: str) -> dict[str, Any] | None:
+        """Get a specific task by ID.
+
+        Args:
+            task_id: Task ID (UUID) to fetch.
+
+        Returns:
+            Task data dict or None if not found.
+        """
+        console.print(f"Fetching task {task_id} from {self.api_base}/tasks/{task_id}")
+        response = self.get(f"/tasks/{task_id}")
+
+        if response.status_code == 404:
+            return None
+
+        if response.status_code != 200:
+            console.print(f"[red]API Error: {response.status_code} - {response.text}[/red]")
+            return None
+
+        return response.json()
+
+    def update_task(
+        self,
+        task_id: str,
+        status: str | None = None,
+        title: str | None = None,
+        prompt: str | None = None,
+        priority: int | None = None,
+        result_summary: str | None = None,
+        error_message: str | None = None,
+        comment: str | None = None,
+    ) -> bool:
+        """Update a task's fields.
+
+        Args:
+            task_id: Task ID to update.
+            status: New status.
+            title: New title.
+            prompt: New prompt.
+            priority: New priority (1=urgent, 2=high, 3=medium, 4=low, 0=none).
+            result_summary: Result summary for completed tasks.
+            error_message: Error message for failed tasks.
+            comment: Comment to add.
+
+        Returns:
+            True if update succeeded.
+        """
+        # If status is being updated, validate the transition first
+        if status:
+            current_task = self.get_task(task_id)
+            if current_task:
+                current_status = current_task.get("status", "")
+                is_valid, error = validate_status_transition(current_status, status)
+                if not is_valid:
+                    logger.error(f"Invalid status transition: {error}")
+                    console.print(f"[red]Error: {error}[/red]")
+                    return False
+
+        # Build payload
+        payload: dict[str, str | int] = {}
+        if status:
+            payload["status"] = status
+        if title:
+            payload["title"] = title
+        if prompt:
+            payload["prompt"] = prompt
+        if priority is not None:
+            payload["priority"] = priority
+        if result_summary:
+            payload["result_summary"] = result_summary
+        if error_message:
+            payload["error_message"] = error_message
+        if comment:
+            payload["comment"] = comment
+
+        if not payload:
+            return False
+
+        console.print(f"Updating task {task_id} at {self.api_base}/tasks/{task_id}")
+        response = self.patch(f"/tasks/{task_id}", json=payload)
+
+        if response.status_code == 404:
+            console.print(f"[red]Error: Task '{task_id}' not found[/red]")
+            return False
+
+        if response.status_code == 400:
+            # Status transition validation error from API
+            console.print(f"[red]Validation Error: {response.text}[/red]")
+            return False
+
+        if response.status_code not in (200, 204):
+            console.print(f"[red]API Error: {response.status_code} - {response.text}[/red]")
+            return False
+
+        return True
+
+    def create_task(
+        self,
+        title: str,
+        prompt: str,
+        project_id: str | None = None,
+        priority: int = 3,
+        working_directory: str | None = None,
+        spec_id: str | None = None,
+        cycle_id: str | None = None,
+    ) -> dict[str, Any] | None:
+        """Create a new task.
+
+        Args:
+            title: Task title.
+            prompt: Task prompt/description.
+            project_id: Project ID. Falls back to STEERDEV_PROJECT_ID env var.
+            priority: Task priority (1=urgent, 2=high, 3=medium, 4=low, 0=none).
+            working_directory: Working directory for the task.
+            spec_id: Specification ID to link this task to.
+            cycle_id: Cycle ID to link this task to.
+
+        Returns:
+            Created task data dict or None on failure.
+        """
+        effective_project_id = project_id or get_project_id()
+        if not effective_project_id:
+            console.print(
+                "[red]Error: project_id is required. "
+                "Use --project-id or set STEERDEV_PROJECT_ID environment variable[/red]"
+            )
+            return None
+
+        payload: dict[str, str | int | None] = {
+            "project_id": effective_project_id,
+            "title": title,
+            "prompt": prompt,
+            "priority": priority,
+            "source": "api",
+        }
+        if working_directory:
+            payload["working_directory"] = working_directory
+        if spec_id:
+            payload["spec_id"] = spec_id
+        if cycle_id:
+            payload["cycle_id"] = cycle_id
+
+        console.print(f"Creating task at {self.api_base}/tasks")
+        response = self.post("/tasks", json=payload)
+
+        if response.status_code not in (200, 201):
+            console.print(f"[red]API Error: {response.status_code} - {response.text}[/red]")
+            return None
+
+        return response.json()
+
+    # ===== Workflow Helper Methods =====
+    # These methods make the workflow explicit and easy to use.
+
+    def get_backlog_tasks(self, project_id: str | None = None) -> list[dict[str, Any]]:
+        """Get tasks in the backlog.
+
+        Args:
+            project_id: Filter by project ID. Falls back to STEERDEV_PROJECT_ID env var.
+
+        Returns:
+            List of backlog tasks.
+        """
+        return self.list_tasks(status="backlog", project_id=project_id)
+
+    def get_unstarted_tasks(self, project_id: str | None = None) -> list[dict[str, Any]]:
+        """Get tasks that are ready for implementation (unstarted).
+
+        Args:
+            project_id: Filter by project ID. Falls back to STEERDEV_PROJECT_ID env var.
+
+        Returns:
+            List of unstarted tasks ready to be implemented.
+        """
+        return self.list_tasks(status="unstarted", project_id=project_id)
+
+    def mark_ready(self, task_id: str) -> bool:
+        """Mark a task as ready for implementation.
+
+        Transitions task from 'backlog' to 'unstarted'.
+
+        Args:
+            task_id: Task ID to update.
+
+        Returns:
+            True if transition succeeded.
+        """
+        return self.update_task(task_id, status="unstarted")
+
+    def start_task(self, task_id: str) -> bool:
+        """Start working on a task.
+
+        Transitions task from 'unstarted' to 'started'.
+        This will fail if the task is not in 'unstarted' status.
+
+        Args:
+            task_id: Task ID to update.
+
+        Returns:
+            True if transition succeeded.
+        """
+        task = self.get_task(task_id)
+        if not task:
+            console.print(f"[red]Error: Task '{task_id}' not found[/red]")
+            return False
+
+        if task.get("status") != "unstarted":
+            logger.error(
+                f"Cannot start task: task {task_id} is not ready "
+                f"(current status: {task.get('status')})"
+            )
+            console.print(
+                f"[red]Error: Cannot start task. "
+                f"Task must be in 'unstarted' status, but is '{task.get('status')}'.[/red]"
+            )
+            return False
+
+        return self.update_task(task_id, status="started")
+
+    def complete_task(self, task_id: str, result_summary: str | None = None) -> bool:
+        """Mark a task as completed.
+
+        Transitions task from 'started' to 'completed'.
+
+        Args:
+            task_id: Task ID to update.
+            result_summary: Optional summary of what was accomplished.
+
+        Returns:
+            True if transition succeeded.
+        """
+        return self.update_task(task_id, status="completed", result_summary=result_summary)
+
+    def cancel_task(self, task_id: str, error_message: str) -> bool:
+        """Mark a task as canceled.
+
+        Transitions task from 'started' to 'canceled'.
+
+        Args:
+            task_id: Task ID to update.
+            error_message: Description of what went wrong.
+
+        Returns:
+            True if transition succeeded.
+        """
+        return self.update_task(task_id, status="canceled", error_message=error_message)
+
+
+def get_priority_display(priority: int | None) -> str:
+    """Get human-readable priority display.
+
+    Args:
+        priority: Priority number (1=urgent, 2=high, 3=medium, 4=low, 0=none).
+
+    Returns:
+        Formatted priority string like "Urgent (1)" or "N/A".
+    """
+    priority_names = {
+        1: "Urgent",
+        2: "High",
+        3: "Medium",
+        4: "Low",
+        0: "None",
+    }
+    if priority is None:
+        return "N/A"
+    name = priority_names.get(priority, "Unknown")
+    return f"{name} ({priority})"
+
+
+def display_task(task: dict[str, Any], title: str = "Task") -> None:
+    """Display a task in a formatted panel.
+
+    Args:
+        task: Task data dict.
+        title: Panel title.
+    """
+    priority_display = get_priority_display(task.get("priority"))
+    linear_id = task.get("linear_identifier", "N/A")
+    task_info = (
+        f"[bold cyan]Linear ID:[/bold cyan] {linear_id}\n"
+        f"[bold cyan]ID:[/bold cyan] {task.get('id', 'N/A')}\n"
+        f"[bold cyan]Title:[/bold cyan] {task.get('title', 'N/A')}\n"
+        f"[bold cyan]Status:[/bold cyan] {task.get('status', 'N/A')}\n"
+        f"[bold cyan]Priority:[/bold cyan] {priority_display}\n"
+        f"[bold cyan]Project ID:[/bold cyan] {task.get('project_id', 'N/A')}"
+    )
+
+    # Parse implementation plan from prompt
+    prompt = task.get("prompt", "")
+    impl_plan = parse_implementation_plan(prompt)
+    task_description = extract_task_description(prompt) if impl_plan else prompt
+
+    if task_description:
+        task_info += f"\n\n[bold cyan]Description:[/bold cyan]\n{task_description}"
+
+    if task.get("working_directory"):
+        task_info += f"\n\n[bold cyan]Working Directory:[/bold cyan] {task['working_directory']}"
+
+    if task.get("spec_id"):
+        task_info += f"\n[bold cyan]Spec ID:[/bold cyan] {task.get('spec_id')}"
+
+    if task.get("cycle_id"):
+        task_info += f"\n[bold cyan]Cycle ID:[/bold cyan] {task.get('cycle_id')}"
+
+    console.print(Panel(task_info, title=title, border_style="green"))
+
+    # Display implementation plan if present
+    if impl_plan and not impl_plan.is_empty():
+        display_implementation_plan(impl_plan)
+
+
+def display_task_list(tasks: list[dict[str, Any]], full_ids: bool = True) -> None:
+    """Display a list of tasks in a formatted table.
+
+    Args:
+        tasks: List of task data dicts.
+        full_ids: If True, show full UUIDs. If False, truncate to 8 chars.
+    """
+    if not tasks:
+        console.print("[yellow]No tasks found[/yellow]")
+        return
+
+    table = Table(title="Tasks")
+    table.add_column("Linear ID", style="cyan", no_wrap=True)
+    table.add_column("Title", style="white")
+    table.add_column("Status", style="magenta")
+    table.add_column("Priority", style="yellow")
+    table.add_column("ID", style="dim")
+
+    for task in tasks:
+        # Linear-native status_type styling
+        status_style = {
+            "backlog": "dim",
+            "unstarted": "cyan",
+            "started": "yellow",
+            "completed": "green",
+            "canceled": "dim",
+        }.get(task.get("status", ""), "white")
+
+        task_id = str(task.get("id", "N/A"))
+        linear_id = task.get("linear_identifier", "N/A")
+
+        if not full_ids:
+            task_id = task_id[:8] + "..." if len(task_id) > 8 else task_id
+
+        table.add_row(
+            linear_id,
+            task.get("title", "N/A")[:50],
+            f"[{status_style}]{task.get('status', 'N/A')}[/{status_style}]",
+            get_priority_display(task.get("priority")),
+            task_id,
+        )
+
+    console.print(table)
+    console.print(f"\n[dim]Total: {len(tasks)} tasks[/dim]")
+
+
+def display_wave_context(wave_response: dict[str, Any]) -> None:
+    """Display wave context in a formatted panel.
+
+    Shows the current wave overview, task statuses, completed waves,
+    and the next task to work on.
+
+    Args:
+        wave_response: Wave response dict from the API.
+    """
+    wave = wave_response.get("wave", {})
+    context = wave_response.get("context", {})
+    tasks = wave_response.get("tasks", [])
+    next_task = context.get("next_task", {})
+    completed_waves = context.get("completed_waves", [])
+
+    wave_number = wave.get("wave_number", "?")
+    total_waves = wave.get("total_waves", "?")
+    wave_desc = wave.get("description", "")
+
+    # Count task statuses in current wave
+    status_counts: dict[str, int] = {}
+    for t in tasks:
+        s = t.get("status", "unknown")
+        status_counts[s] = status_counts.get(s, 0) + 1
+
+    status_parts = []
+    for s in ["completed", "started", "unstarted", "backlog", "canceled"]:
+        if s in status_counts:
+            status_parts.append(f"{status_counts[s]} {s}")
+    status_summary = ", ".join(status_parts) if status_parts else "no tasks"
+
+    # Wave header
+    header = f"[bold blue]Wave {wave_number} of {total_waves}[/bold blue]"
+    if wave_desc:
+        header += f" — {wave_desc}"
+    header += f"\n[dim]{len(tasks)} tasks: {status_summary}[/dim]"
+
+    # Completed waves
+    if completed_waves:
+        header += "\n\n[green]Completed waves:[/green]"
+        for cw in completed_waves:
+            header += f"\n  [green]✓[/green] Wave {cw.get('wave_number', '?')}: {cw.get('description', '')}"
+
+    console.print(Panel(header, title="Wave Context", border_style="blue"))
+
+    # Task table for current wave
+    table = Table(title=f"Wave {wave_number} Tasks")
+    table.add_column("", style="bold", width=3)
+    table.add_column("Linear ID", style="cyan", no_wrap=True)
+    table.add_column("Title", style="white")
+    table.add_column("Status", style="magenta")
+    table.add_column("Priority", style="yellow")
+
+    next_task_id = next_task.get("id", "")
+    for t in tasks:
+        is_next = t.get("id") == next_task_id
+        marker = ">>>" if is_next else ""
+
+        status = t.get("status", "unknown")
+        status_style = {
+            "backlog": "dim",
+            "unstarted": "cyan",
+            "started": "yellow",
+            "completed": "green",
+            "canceled": "dim",
+        }.get(status, "white")
+
+        table.add_row(
+            f"[bold yellow]{marker}[/bold yellow]" if is_next else "",
+            t.get("linear_identifier", "N/A"),
+            t.get("title", "N/A")[:50],
+            f"[{status_style}]{status}[/{status_style}]",
+            get_priority_display(t.get("priority")),
+        )
+
+    console.print(table)
+
+    # Next task detail
+    if next_task:
+        display_task(next_task, title="Next Task")
+
+
+def display_update_success(
+    task_id: str,
+    status: str | None = None,
+    title: str | None = None,
+    prompt: str | None = None,
+    priority: int | None = None,
+    result_summary: str | None = None,
+    error_message: str | None = None,
+    comment: str | None = None,
+) -> None:
+    """Display update success message.
+
+    Args:
+        task_id: Updated task ID.
+        status: Updated status if any.
+        title: Updated title if any.
+        prompt: Updated prompt if any.
+        priority: Updated priority if any.
+        result_summary: Added result summary if any.
+        error_message: Added error message if any.
+        comment: Added comment if any.
+    """
+    updates = []
+    if status:
+        updates.append(f"Status -> {status}")
+    if title:
+        updates.append("Title updated")
+    if prompt:
+        updates.append("Prompt updated")
+    if priority is not None:
+        updates.append(f"Priority -> {priority}")
+    if result_summary:
+        updates.append("Result summary added")
+    if error_message:
+        updates.append("Error message added")
+    if comment:
+        updates.append("Comment added")
+
+    console.print(
+        Panel(
+            f"[bold green]Task {task_id} updated[/bold green]\n\n"
+            + "\n".join(f"* {u}" for u in updates),
+            title="Success",
+            border_style="green",
+        )
+    )