anvil-dev-framework 0.1.6

package/global/lib/issue_models.py

@@ -0,0 +1,257 @@
+"""
+Issue data models for Anvil Framework.
+
+Provides a common data model for issue tracking that works with both
+Linear and local JSON storage backends.
+
+Usage:
+    from issue_models import Issue, IssueStatus, Priority
+
+    issue = Issue(
+        id="local-001",
+        identifier="LOCAL-001",
+        title="Implement feature X",
+        status=IssueStatus.TODO,
+        priority=Priority.MEDIUM
+    )
+"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional
+import json
+
+
+class IssueStatus(Enum):
+    """Issue workflow states, compatible with Linear."""
+    BACKLOG = "backlog"
+    TODO = "todo"
+    IN_PROGRESS = "in_progress"
+    IN_REVIEW = "in_review"
+    DONE = "done"
+    CANCELLED = "cancelled"
+
+    @classmethod
+    def from_linear_state(cls, state_name: str) -> "IssueStatus":
+        """Map Linear state name to IssueStatus."""
+        mapping = {
+            "backlog": cls.BACKLOG,
+            "todo": cls.TODO,
+            "in progress": cls.IN_PROGRESS,
+            "in review": cls.IN_REVIEW,
+            "done": cls.DONE,
+            "canceled": cls.CANCELLED,
+            "cancelled": cls.CANCELLED,
+            "duplicate": cls.CANCELLED,
+        }
+        return mapping.get(state_name.lower(), cls.BACKLOG)
+
+    def to_display(self) -> str:
+        """Human-readable display name."""
+        return self.value.replace("_", " ").title()
+
+
+class Priority(Enum):
+    """Issue priority levels, compatible with Linear."""
+    URGENT = 0   # P0 - Drop everything
+    HIGH = 1     # P1 - Next up
+    MEDIUM = 2   # P2 - This sprint
+    LOW = 3      # P3 - Backlog
+    NONE = 4     # No priority set
+
+    @classmethod
+    def from_linear_priority(cls, priority: int) -> "Priority":
+        """Map Linear priority (0-4) to Priority enum."""
+        try:
+            return cls(priority)
+        except ValueError:
+            return cls.NONE
+
+    def to_display(self) -> str:
+        """Short display format (P0, P1, etc.)."""
+        if self == Priority.NONE:
+            return "—"
+        return f"P{self.value}"
+
+
+@dataclass
+class Issue:
+    """
+    Core issue model, compatible with Linear schema.
+
+    Attributes:
+        id: Internal unique identifier (UUID or generated ID)
+        identifier: Human-readable identifier (e.g., "ANV-72", "LOCAL-001")
+        title: Issue title
+        description: Detailed description (markdown supported)
+        status: Current workflow status
+        priority: Priority level (P0-P4)
+        parent_id: Parent issue ID for sub-issues
+        labels: List of label names
+        assigned_agent: Anvil agent ID if claimed
+        created_at: Creation timestamp
+        updated_at: Last modification timestamp
+        completed_at: Completion timestamp (if done)
+        estimate: Time estimate string (e.g., "2h", "1d")
+        provider: Source provider ("local" or "linear")
+        external_id: External system ID (Linear UUID if synced)
+    """
+    id: str
+    identifier: str
+    title: str
+    description: str = ""
+    status: IssueStatus = IssueStatus.TODO
+    priority: Priority = Priority.MEDIUM
+
+    # Relationships
+    parent_id: Optional[str] = None
+    labels: list[str] = field(default_factory=list)
+    assigned_agent: Optional[str] = None
+
+    # Metadata
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    completed_at: Optional[datetime] = None
+
+    # Estimates
+    estimate: Optional[str] = None
+
+    # Source tracking
+    provider: str = "local"
+    external_id: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        data = asdict(self)
+        # Convert enums to values
+        data["status"] = self.status.value
+        data["priority"] = self.priority.value
+        # Convert datetimes to ISO strings
+        data["created_at"] = self.created_at.isoformat() if self.created_at else None
+        data["updated_at"] = self.updated_at.isoformat() if self.updated_at else None
+        data["completed_at"] = self.completed_at.isoformat() if self.completed_at else None
+        return data
+
+    def to_json(self) -> str:
+        """Convert to JSON string."""
+        return json.dumps(self.to_dict(), indent=2)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Issue":
+        """Create Issue from dictionary."""
+        # Parse status
+        status_val = data.get("status", "todo")
+        if isinstance(status_val, str):
+            status = IssueStatus(status_val)
+        else:
+            status = status_val
+
+        # Parse priority
+        priority_val = data.get("priority", 2)
+        if isinstance(priority_val, int):
+            priority = Priority(priority_val)
+        elif isinstance(priority_val, str):
+            priority = Priority(int(priority_val))
+        else:
+            priority = priority_val
+
+        # Parse datetimes
+        def parse_dt(val) -> Optional[datetime]:
+            if val is None:
+                return None
+            if isinstance(val, datetime):
+                return val
+            return datetime.fromisoformat(val.replace('Z', '+00:00'))
+
+        return cls(
+            id=data["id"],
+            identifier=data["identifier"],
+            title=data["title"],
+            description=data.get("description", ""),
+            status=status,
+            priority=priority,
+            parent_id=data.get("parent_id"),
+            labels=data.get("labels", []),
+            assigned_agent=data.get("assigned_agent"),
+            created_at=parse_dt(data.get("created_at")) or datetime.now(timezone.utc),
+            updated_at=parse_dt(data.get("updated_at")) or datetime.now(timezone.utc),
+            completed_at=parse_dt(data.get("completed_at")),
+            estimate=data.get("estimate"),
+            provider=data.get("provider", "local"),
+            external_id=data.get("external_id"),
+        )
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "Issue":
+        """Create Issue from JSON string."""
+        return cls.from_dict(json.loads(json_str))
+
+    @classmethod
+    def from_linear(cls, linear_data: dict) -> "Issue":
+        """Create Issue from Linear API response."""
+        state = linear_data.get("state", {})
+        state_name = state.get("name", "Backlog") if isinstance(state, dict) else "Backlog"
+
+        return cls(
+            id=linear_data.get("id", ""),
+            identifier=linear_data.get("identifier", ""),
+            title=linear_data.get("title", ""),
+            description=linear_data.get("description", ""),
+            status=IssueStatus.from_linear_state(state_name),
+            priority=Priority.from_linear_priority(linear_data.get("priority", 4)),
+            parent_id=linear_data.get("parent", {}).get("id") if linear_data.get("parent") else None,
+            labels=[lbl.get("name", "") for lbl in linear_data.get("labels", {}).get("nodes", [])],
+            assigned_agent=None,  # Linear doesn't track Anvil agents
+            created_at=datetime.fromisoformat(
+                linear_data.get("createdAt", "").replace('Z', '+00:00')
+            ) if linear_data.get("createdAt") else datetime.now(timezone.utc),
+            updated_at=datetime.fromisoformat(
+                linear_data.get("updatedAt", "").replace('Z', '+00:00')
+            ) if linear_data.get("updatedAt") else datetime.now(timezone.utc),
+            completed_at=datetime.fromisoformat(
+                linear_data.get("completedAt", "").replace('Z', '+00:00')
+            ) if linear_data.get("completedAt") else None,
+            estimate=linear_data.get("estimate"),
+            provider="linear",
+            external_id=linear_data.get("id"),
+        )
+
+    def is_ready(self) -> bool:
+        """Check if issue is ready to work on (Todo, no blocking deps)."""
+        return self.status == IssueStatus.TODO
+
+    def is_active(self) -> bool:
+        """Check if issue is actively being worked on."""
+        return self.status in (IssueStatus.IN_PROGRESS, IssueStatus.IN_REVIEW)
+
+    def is_complete(self) -> bool:
+        """Check if issue is finished."""
+        return self.status in (IssueStatus.DONE, IssueStatus.CANCELLED)
+
+    def claim(self, agent_id: str) -> None:
+        """Assign this issue to an agent."""
+        self.assigned_agent = agent_id
+        self.updated_at = datetime.now(timezone.utc)
+
+    def unclaim(self) -> None:
+        """Remove agent assignment."""
+        self.assigned_agent = None
+        self.updated_at = datetime.now(timezone.utc)
+
+    def transition_to(self, new_status: IssueStatus) -> None:
+        """Transition issue to a new status."""
+        self.status = new_status
+        self.updated_at = datetime.now(timezone.utc)
+        if new_status == IssueStatus.DONE:
+            self.completed_at = datetime.now(timezone.utc)
+        elif self.completed_at and new_status != IssueStatus.CANCELLED:
+            self.completed_at = None  # Reopen
+
+    def __str__(self) -> str:
+        """String representation for display."""
+        agent_str = f" [{self.assigned_agent}]" if self.assigned_agent else ""
+        return f"{self.identifier}: {self.title} ({self.status.to_display()}){agent_str}"
+
+    def __repr__(self) -> str:
+        return f"Issue(identifier={self.identifier!r}, title={self.title!r}, status={self.status})"

package/global/lib/issue_provider.py

@@ -0,0 +1,339 @@
+"""
+IssueProvider protocol for Anvil Framework.
+
+Defines the abstract interface for issue tracking backends.
+Implementations include LocalJsonProvider and LinearProvider.
+
+Usage:
+    from issue_provider import IssueProvider, get_provider
+
+    # Auto-detect provider based on project config
+    provider = get_provider(Path.cwd())
+
+    # List issues
+    issues = provider.list_issues(status=IssueStatus.TODO)
+
+    # Create issue
+    issue = provider.create_issue(title="New feature", priority=Priority.HIGH)
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional, Protocol, runtime_checkable
+try:
+    import yaml
+except ImportError:
+    yaml = None  # YAML is optional for config loading
+
+try:
+    from .issue_models import Issue, IssueStatus, Priority
+except ImportError:
+    from issue_models import Issue, IssueStatus, Priority
+
+
+@runtime_checkable
+class IssueProvider(Protocol):
+    """
+    Abstract interface for issue tracking backends.
+
+    This protocol defines the contract that all issue providers must implement.
+    Currently supported providers:
+    - LocalJsonProvider: File-based storage in ~/.anvil/issues/
+    - LinearProvider: Adapter for Linear API via linear-skill
+
+    The provider pattern allows Anvil commands (/orient, /sprint, /ready)
+    to work identically regardless of the underlying storage backend.
+    """
+
+    @property
+    def name(self) -> str:
+        """Provider identifier (e.g., 'local', 'linear')."""
+        ...
+
+    @property
+    def is_available(self) -> bool:
+        """Check if provider is configured and accessible."""
+        ...
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Read Operations
+    # ─────────────────────────────────────────────────────────────────────
+
+    def list_issues(
+        self,
+        status: Optional[IssueStatus] = None,
+        project: Optional[str] = None,
+        limit: int = 50
+    ) -> list[Issue]:
+        """
+        List issues, optionally filtered by status.
+
+        Args:
+            status: Filter to specific status (None = all)
+            project: Filter to specific project (provider-dependent)
+            limit: Maximum number of issues to return
+
+        Returns:
+            List of Issue objects, sorted by priority then updated_at
+        """
+        ...
+
+    def get_issue(self, identifier: str) -> Optional[Issue]:
+        """
+        Get a single issue by identifier.
+
+        Args:
+            identifier: Human-readable identifier (e.g., 'ANV-72', 'LOCAL-001')
+
+        Returns:
+            Issue object or None if not found
+        """
+        ...
+
+    def get_ready_issues(self) -> list[Issue]:
+        """
+        Get issues that are ready to work on.
+
+        Returns issues in Todo status with no blocking dependencies.
+        Sorted by priority (P0 first) then by age (oldest first).
+
+        Returns:
+            List of Issue objects ready to be claimed
+        """
+        ...
+
+    def get_in_progress_issues(self) -> list[Issue]:
+        """
+        Get issues currently being worked on.
+
+        Returns:
+            List of Issue objects with In Progress or In Review status
+        """
+        ...
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Write Operations
+    # ─────────────────────────────────────────────────────────────────────
+
+    def create_issue(
+        self,
+        title: str,
+        description: str = "",
+        status: IssueStatus = IssueStatus.TODO,
+        priority: Priority = Priority.MEDIUM,
+        parent_id: Optional[str] = None,
+        labels: Optional[list[str]] = None
+    ) -> Issue:
+        """
+        Create a new issue.
+
+        Args:
+            title: Issue title
+            description: Detailed description (markdown supported)
+            status: Initial status (default: Todo)
+            priority: Priority level (default: Medium/P2)
+            parent_id: Parent issue identifier for sub-issues
+            labels: List of label names
+
+        Returns:
+            Created Issue object with generated ID
+        """
+        ...
+
+    def update_issue(
+        self,
+        identifier: str,
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        status: Optional[IssueStatus] = None,
+        priority: Optional[Priority] = None,
+        labels: Optional[list[str]] = None
+    ) -> Issue:
+        """
+        Update an existing issue.
+
+        Args:
+            identifier: Issue identifier to update
+            title: New title (None = no change)
+            description: New description (None = no change)
+            status: New status (None = no change)
+            priority: New priority (None = no change)
+            labels: New labels (None = no change)
+
+        Returns:
+            Updated Issue object
+
+        Raises:
+            KeyError: If issue not found
+        """
+        ...
+
+    def delete_issue(self, identifier: str) -> bool:
+        """
+        Delete an issue.
+
+        For most providers, this is a soft delete (marks as cancelled).
+
+        Args:
+            identifier: Issue identifier to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        ...
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Agent Integration
+    # ─────────────────────────────────────────────────────────────────────
+
+    def assign_to_agent(self, identifier: str, agent_id: str) -> Issue:
+        """
+        Assign an issue to an Anvil agent.
+
+        Args:
+            identifier: Issue identifier
+            agent_id: Anvil agent ID (e.g., 'swift-falcon-a3f2')
+
+        Returns:
+            Updated Issue object
+
+        Raises:
+            KeyError: If issue not found
+        """
+        ...
+
+    def unassign_agent(self, identifier: str) -> Issue:
+        """
+        Remove agent assignment from an issue.
+
+        Args:
+            identifier: Issue identifier
+
+        Returns:
+            Updated Issue object
+
+        Raises:
+            KeyError: If issue not found
+        """
+        ...
+
+    def get_agent_issues(self, agent_id: str) -> list[Issue]:
+        """
+        Get all issues assigned to a specific agent.
+
+        Args:
+            agent_id: Anvil agent ID
+
+        Returns:
+            List of Issue objects assigned to this agent
+        """
+        ...
+
+
+class BaseProvider(ABC):
+    """
+    Base class for issue providers with common functionality.
+
+    Provides default implementations for some methods and
+    shared utilities for concrete providers.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Provider identifier."""
+        pass
+
+    @property
+    def is_available(self) -> bool:
+        """Default: always available. Override for remote providers."""
+        return True
+
+    def get_ready_issues(self) -> list[Issue]:
+        """Default implementation: Todo issues sorted by priority."""
+        issues = self.list_issues(status=IssueStatus.TODO)
+        # Sort by priority (lower = higher priority), then by age
+        return sorted(issues, key=lambda i: (i.priority.value, i.created_at))
+
+    def get_in_progress_issues(self) -> list[Issue]:
+        """Default implementation: In Progress + In Review issues."""
+        in_progress = self.list_issues(status=IssueStatus.IN_PROGRESS)
+        in_review = self.list_issues(status=IssueStatus.IN_REVIEW)
+        return in_progress + in_review
+
+    def get_agent_issues(self, agent_id: str) -> list[Issue]:
+        """Default implementation: filter all issues by agent."""
+        all_issues = self.list_issues()
+        return [i for i in all_issues if i.assigned_agent == agent_id]
+
+
+def get_provider(project_path: Optional[Path] = None) -> IssueProvider:
+    """
+    Get the appropriate issue provider for a project.
+
+    Auto-detection logic:
+    1. If .claude/linear.yaml exists → LinearProvider
+    2. Otherwise → LocalJsonProvider
+
+    Args:
+        project_path: Project root directory (default: current directory)
+
+    Returns:
+        Configured IssueProvider instance
+    """
+    if project_path is None:
+        project_path = Path.cwd()
+
+    linear_config = project_path / ".claude" / "linear.yaml"
+
+    if linear_config.exists():
+        try:
+            if yaml is None:
+                raise ImportError("PyYAML required for Linear config")
+            config = yaml.safe_load(linear_config.read_text())
+            # Import here to avoid circular imports
+            try:
+                from .linear_provider import LinearProvider
+            except ImportError:
+                from linear_provider import LinearProvider
+            return LinearProvider(
+                team_key=config.get("team_key", ""),
+                team_id=config.get("team_id", "")
+            )
+        except Exception:
+            pass  # Fall through to local provider
+
+    # Default to local provider
+    try:
+        from .local_provider import LocalJsonProvider
+    except ImportError:
+        from local_provider import LocalJsonProvider
+    return LocalJsonProvider(project_path)
+
+
+def get_provider_name(project_path: Optional[Path] = None) -> str:
+    """
+    Get the name of the provider that would be used for a project.
+
+    Useful for displaying provider info without fully initializing it.
+
+    Args:
+        project_path: Project root directory (default: current directory)
+
+    Returns:
+        Provider name string ('linear' or 'local')
+    """
+    if project_path is None:
+        project_path = Path.cwd()
+
+    linear_config = project_path / ".claude" / "linear.yaml"
+
+    if linear_config.exists():
+        try:
+            config = yaml.safe_load(linear_config.read_text())
+            team_key = config.get("team_key", "")
+            return f"linear:{team_key}" if team_key else "linear"
+        except Exception:
+            pass
+
+    return "local"