steerdev 0.4.27__py3-none-any.whl

steerdev_agent/api/specs.py

@@ -0,0 +1,321 @@
+"""Specs API client for SteerDev Agent.
+
+Provides methods for interacting with specification documents (PRDs)
+through the CLI skill interface.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+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
+
+console = Console()
+
+
+# Valid spec statuses
+VALID_SPEC_STATUSES = [
+    "draft",
+    "analyzing",
+    "clarifying",
+    "planning",
+    "ready",
+    "completed",
+]
+
+
+class SpecDocument(BaseModel):
+    """Spec document model."""
+
+    id: str
+    project_id: str
+    title: str
+    content: str
+    source: str
+    source_file_name: str | None = None
+    status: str  # draft, analyzing, clarifying, planning, ready, completed
+    implementation_plan: dict[str, Any] | None = None
+    run_id: str | None = None
+    created_by: str
+    created_at: str
+    updated_at: str
+    linear_identifier: str | None = Field(default=None, description="Linear issue ID")
+
+
+class SpecsClient(SteerDevClient):
+    """Client for spec management operations.
+
+    Provides CRUD operations for specification documents (PRDs).
+    """
+
+    def get_spec(self, spec_id: str) -> dict[str, Any] | None:
+        """Get a spec document by ID.
+
+        Args:
+            spec_id: Spec document ID (UUID).
+
+        Returns:
+            Spec data dict or None if not found.
+        """
+        console.print(f"Fetching spec {spec_id} from {self.api_base}/prd/{spec_id}")
+        response = self.get(f"/prd/{spec_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 list_specs(
+        self,
+        project_id: str | None = None,
+        status: str | None = None,
+        limit: int = 20,
+    ) -> list[dict[str, Any]]:
+        """List specs with optional filters.
+
+        Args:
+            project_id: Filter by project ID. Falls back to STEERDEV_PROJECT_ID env var.
+            status: Filter by status.
+            limit: Maximum number of specs to return.
+
+        Returns:
+            List of spec 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 specs from {self.api_base}/prd")
+        response = self.get("/prd", 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("specs", data.get("documents", [])) if isinstance(data, dict) else data
+
+    def update_spec(
+        self,
+        spec_id: str,
+        content: str | None = None,
+        status: str | None = None,
+        title: str | None = None,
+    ) -> bool:
+        """Update a spec's fields.
+
+        Args:
+            spec_id: Spec ID to update.
+            content: New content (markdown).
+            status: New status.
+            title: New title.
+
+        Returns:
+            True if update succeeded.
+        """
+        payload: dict[str, str] = {}
+        if content:
+            payload["content"] = content
+        if status:
+            payload["status"] = status
+        if title:
+            payload["title"] = title
+
+        if not payload:
+            return False
+
+        console.print(f"Updating spec {spec_id} at {self.api_base}/prd/{spec_id}")
+        response = self.patch(f"/prd/{spec_id}", json=payload)
+
+        if response.status_code == 404:
+            console.print(f"[red]Error: Spec '{spec_id}' not found[/red]")
+            return False
+
+        if response.status_code == 400:
+            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_spec(
+        self,
+        title: str,
+        content: str,
+        project_id: str | None = None,
+        source: str = "agent",
+    ) -> dict[str, Any] | None:
+        """Create a new spec document.
+
+        Args:
+            title: Spec title.
+            content: Spec content (markdown).
+            project_id: Project ID. Falls back to STEERDEV_PROJECT_ID env var.
+            source: Source of the spec (default: "agent").
+
+        Returns:
+            Created spec 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 = {
+            "project_id": effective_project_id,
+            "title": title,
+            "content": content,
+            "source": source,
+        }
+
+        console.print(f"Creating spec at {self.api_base}/prd")
+        response = self.post("/prd", 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()
+
+
+def get_status_style(status: str) -> str:
+    """Get Rich style for a spec status.
+
+    Args:
+        status: Spec status value.
+
+    Returns:
+        Rich style string.
+    """
+    return {
+        "draft": "dim",
+        "analyzing": "yellow",
+        "clarifying": "cyan",
+        "planning": "blue",
+        "ready": "green",
+        "completed": "dim green",
+    }.get(status, "white")
+
+
+def display_spec(spec: dict[str, Any], title: str = "Spec") -> None:
+    """Display a spec in a formatted panel.
+
+    Args:
+        spec: Spec data dict.
+        title: Panel title.
+    """
+    linear_id = spec.get("linear_identifier", "N/A")
+    status_style = get_status_style(spec.get("status", ""))
+
+    spec_info = (
+        f"[bold cyan]Linear ID:[/bold cyan] {linear_id}\n"
+        f"[bold cyan]ID:[/bold cyan] {spec.get('id', 'N/A')}\n"
+        f"[bold cyan]Title:[/bold cyan] {spec.get('title', 'N/A')}\n"
+        f"[bold cyan]Status:[/bold cyan] [{status_style}]{spec.get('status', 'N/A')}[/{status_style}]\n"
+        f"[bold cyan]Project ID:[/bold cyan] {spec.get('project_id', 'N/A')}\n"
+        f"[bold cyan]Source:[/bold cyan] {spec.get('source', 'N/A')}"
+    )
+
+    if spec.get("source_file_name"):
+        spec_info += f"\n[bold cyan]Source File:[/bold cyan] {spec['source_file_name']}"
+
+    if spec.get("content"):
+        # Truncate content for display, show first 500 chars
+        content = spec["content"]
+        if len(content) > 500:
+            content = content[:500] + "..."
+        spec_info += f"\n\n[bold cyan]Content:[/bold cyan]\n{content}"
+
+    if spec.get("run_id"):
+        spec_info += f"\n\n[bold cyan]Run ID:[/bold cyan] {spec['run_id']}"
+
+    console.print(Panel(spec_info, title=title, border_style="green"))
+
+
+def display_spec_list(specs: list[dict[str, Any]], full_ids: bool = True) -> None:
+    """Display a list of specs in a formatted table.
+
+    Args:
+        specs: List of spec data dicts.
+        full_ids: If True, show full UUIDs. If False, truncate to 8 chars.
+    """
+    if not specs:
+        console.print("[yellow]No specs found[/yellow]")
+        return
+
+    table = Table(title="Specs")
+    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("Source", style="dim")
+    table.add_column("ID", style="dim")
+
+    for spec in specs:
+        status_style = get_status_style(spec.get("status", ""))
+        spec_id = str(spec.get("id", "N/A"))
+        linear_id = spec.get("linear_identifier", "N/A")
+
+        if not full_ids:
+            spec_id = spec_id[:8] + "..." if len(spec_id) > 8 else spec_id
+
+        table.add_row(
+            linear_id,
+            spec.get("title", "N/A")[:50],
+            f"[{status_style}]{spec.get('status', 'N/A')}[/{status_style}]",
+            spec.get("source", "N/A"),
+            spec_id,
+        )
+
+    console.print(table)
+    console.print(f"\n[dim]Total: {len(specs)} specs[/dim]")
+
+
+def display_spec_update_success(
+    spec_id: str,
+    content: str | None = None,
+    status: str | None = None,
+    title: str | None = None,
+) -> None:
+    """Display update success message.
+
+    Args:
+        spec_id: Updated spec ID.
+        content: Updated content if any.
+        status: Updated status if any.
+        title: Updated title if any.
+    """
+    updates = []
+    if content:
+        updates.append("Content updated")
+    if status:
+        updates.append(f"Status -> {status}")
+    if title:
+        updates.append("Title updated")
+
+    console.print(
+        Panel(
+            f"[bold green]Spec {spec_id} updated[/bold green]\n\n"
+            + "\n".join(f"* {u}" for u in updates),
+            title="Success",
+            border_style="green",
+        )
+    )