anvil-dev-framework 0.1.6

package/global/lib/linear_provider.py.backup

@@ -0,0 +1,671 @@
+"""
+LinearProvider - Linear API adapter for Anvil Framework.
+
+Wraps the Linear GraphQL API to provide the IssueProvider interface.
+Uses the LINEAR_API_KEY environment variable for authentication.
+
+Usage:
+    from linear_provider import LinearProvider
+
+    provider = LinearProvider(team_key="ANV")
+    issues = provider.list_issues(status=IssueStatus.TODO)
+"""
+
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+import json
+
+try:
+    import requests
+except ImportError:
+    requests = None
+
+try:
+    from .issue_models import Issue, IssueStatus, Priority
+    from .issue_provider import BaseProvider
+except ImportError:
+    from issue_models import Issue, IssueStatus, Priority
+    from issue_provider import BaseProvider
+
+
+class LinearProvider(BaseProvider):
+    """
+    Linear API adapter implementing IssueProvider interface.
+
+    Features:
+    - Maps Linear workflow states to IssueStatus enum
+    - Caches state UUIDs for performance
+    - Transforms Linear API responses to Issue objects
+    - Supports agent assignment via issue comments (Linear convention)
+    """
+
+    API_URL = "https://api.linear.app/graphql"
+
+    # Map Linear state types to our IssueStatus enum
+    STATE_TYPE_MAP = {
+        "backlog": IssueStatus.BACKLOG,
+        "unstarted": IssueStatus.TODO,
+        "started": IssueStatus.IN_PROGRESS,
+        "completed": IssueStatus.DONE,
+        "canceled": IssueStatus.CANCELLED,
+    }
+
+    # Map Linear state names (more specific) to our IssueStatus
+    STATE_NAME_MAP = {
+        "backlog": IssueStatus.BACKLOG,
+        "todo": IssueStatus.TODO,
+        "in progress": IssueStatus.IN_PROGRESS,
+        "in review": IssueStatus.IN_REVIEW,
+        "done": IssueStatus.DONE,
+        "cancelled": IssueStatus.CANCELLED,
+        "canceled": IssueStatus.CANCELLED,
+        "duplicate": IssueStatus.CANCELLED,
+    }
+
+    # Map our IssueStatus to Linear state names (for updates)
+    STATUS_TO_STATE_NAME = {
+        IssueStatus.BACKLOG: "Backlog",
+        IssueStatus.TODO: "Todo",
+        IssueStatus.IN_PROGRESS: "In Progress",
+        IssueStatus.IN_REVIEW: "In Review",
+        IssueStatus.DONE: "Done",
+        IssueStatus.CANCELLED: "Canceled",
+    }
+
+    # Linear priority (0=urgent, 1=high, 2=medium, 3=low, 4=none)
+    # to our Priority enum
+    LINEAR_PRIORITY_MAP = {
+        0: Priority.URGENT,
+        1: Priority.HIGH,
+        2: Priority.MEDIUM,
+        3: Priority.LOW,
+        4: Priority.NONE,
+    }
+
+    PRIORITY_TO_LINEAR = {
+        Priority.URGENT: 0,
+        Priority.HIGH: 1,
+        Priority.MEDIUM: 2,
+        Priority.LOW: 3,
+        Priority.NONE: 4,
+    }
+
+    def __init__(
+        self,
+        team_key: str = "",
+        team_id: str = "",
+        api_key: Optional[str] = None
+    ):
+        """
+        Initialize LinearProvider.
+
+        Args:
+            team_key: Linear team key (e.g., "ANV")
+            team_id: Linear team UUID (optional, will be looked up from team_key)
+            api_key: Linear API key (optional, defaults to LINEAR_API_KEY env var)
+        """
+        self.team_key = team_key
+        self._team_id = team_id
+        self.api_key = api_key or os.getenv("LINEAR_API_KEY")
+
+        if not self.api_key:
+            self._available = False
+        elif requests is None:
+            self._available = False
+        else:
+            self._available = True
+
+        self.headers = {
+            "Authorization": self.api_key or "",
+            "Content-Type": "application/json"
+        }
+
+        # Cache for state UUIDs (populated on first use)
+        self._state_cache: dict[str, dict] = {}
+        self._state_cache_initialized = False
+
+        # Cache for label UUIDs (populated on first use)
+        self._label_cache: dict[str, str] = {}  # name -> id
+        self._label_cache_initialized = False
+
+    @property
+    def name(self) -> str:
+        return "linear"
+
+    @property
+    def is_available(self) -> bool:
+        if not self._available:
+            return False
+        # Quick connectivity check (cached after first call)
+        if not hasattr(self, "_connectivity_checked"):
+            try:
+                self._query("query { viewer { id } }")
+                self._connectivity_checked = True
+            except Exception:
+                self._connectivity_checked = False
+        return self._connectivity_checked
+
+    def _query(self, query: str, variables: Optional[dict] = None) -> dict:
+        """Execute GraphQL query."""
+        if requests is None:
+            raise ImportError("requests module required for Linear API")
+
+        payload = {"query": query}
+        if variables:
+            payload["variables"] = variables
+
+        response = requests.post(
+            self.API_URL,
+            headers=self.headers,
+            json=payload,
+            timeout=30
+        )
+
+        if response.status_code != 200:
+            raise Exception(f"Linear API error: {response.status_code}")
+
+        data = response.json()
+        if "errors" in data:
+            raise Exception(f"GraphQL error: {json.dumps(data['errors'])}")
+
+        return data.get("data", {})
+
+    def _get_team_id(self) -> str:
+        """Get team UUID, looking up from team_key if needed."""
+        if self._team_id:
+            return self._team_id
+
+        if not self.team_key:
+            raise ValueError("team_key or team_id required")
+
+        # Look up team by key
+        query = """
+        query {
+          teams {
+            nodes {
+              id
+              key
+            }
+          }
+        }
+        """
+        result = self._query(query)
+        for team in result.get("teams", {}).get("nodes", []):
+            if team.get("key") == self.team_key:
+                self._team_id = team.get("id")
+                return self._team_id
+
+        raise ValueError(f"Team not found: {self.team_key}")
+
+    def _ensure_state_cache(self):
+        """Initialize state cache if needed."""
+        if self._state_cache_initialized:
+            return
+
+        team_id = self._get_team_id()
+        query = """
+        query($teamId: String!) {
+          team(id: $teamId) {
+            states {
+              nodes {
+                id
+                name
+                type
+              }
+            }
+          }
+        }
+        """
+        result = self._query(query, {"teamId": team_id})
+        states = result.get("team", {}).get("states", {}).get("nodes", [])
+
+        for state in states:
+            name_lower = state.get("name", "").lower()
+            self._state_cache[name_lower] = state
+
+        self._state_cache_initialized = True
+
+    def _get_state_id(self, status: IssueStatus) -> Optional[str]:
+        """Get Linear state UUID for an IssueStatus."""
+        self._ensure_state_cache()
+
+        state_name = self.STATUS_TO_STATE_NAME.get(status, "").lower()
+        if state_name in self._state_cache:
+            return self._state_cache[state_name].get("id")
+
+        return None
+
+    def _ensure_label_cache(self):
+        """Initialize label cache if needed."""
+        if self._label_cache_initialized:
+            return
+
+        team_id = self._get_team_id()
+        query = """
+        query($teamId: String!) {
+          team(id: $teamId) {
+            labels {
+              nodes {
+                id
+                name
+              }
+            }
+          }
+        }
+        """
+        result = self._query(query, {"teamId": team_id})
+        labels = result.get("team", {}).get("labels", {}).get("nodes", [])
+
+        for label in labels:
+            name_lower = label.get("name", "").lower()
+            self._label_cache[name_lower] = label.get("id", "")
+
+        self._label_cache_initialized = True
+
+    def _get_label_ids(self, label_names: list[str]) -> list[str]:
+        """Get Linear label UUIDs for a list of label names.
+
+        Args:
+            label_names: List of label names to look up
+
+        Returns:
+            List of label UUIDs (skips labels that don't exist)
+        """
+        if not label_names:
+            return []
+
+        self._ensure_label_cache()
+
+        label_ids = []
+        for name in label_names:
+            name_lower = name.lower()
+            if name_lower in self._label_cache:
+                label_ids.append(self._label_cache[name_lower])
+            # Skip labels that don't exist rather than failing
+
+        return label_ids
+
+    def _map_state_to_status(self, state: dict) -> IssueStatus:
+        """Map Linear state to IssueStatus."""
+        # Try name first (more specific)
+        name_lower = state.get("name", "").lower()
+        if name_lower in self.STATE_NAME_MAP:
+            return self.STATE_NAME_MAP[name_lower]
+
+        # Fall back to type
+        state_type = state.get("type", "unstarted")
+        return self.STATE_TYPE_MAP.get(state_type, IssueStatus.TODO)
+
+    def _map_priority(self, linear_priority: int) -> Priority:
+        """Map Linear priority (0-4) to our Priority enum."""
+        return self.LINEAR_PRIORITY_MAP.get(linear_priority, Priority.MEDIUM)
+
+    def _parse_datetime(self, value: Optional[str]) -> Optional[datetime]:
+        """Parse ISO datetime string."""
+        if not value:
+            return None
+        try:
+            return datetime.fromisoformat(value.replace('Z', '+00:00'))
+        except (ValueError, TypeError):
+            return None
+
+    def _issue_from_linear(self, data: dict) -> Issue:
+        """Transform Linear API response to Issue object."""
+        state = data.get("state", {})
+        assignee = data.get("assignee", {})
+        parent = data.get("parent", {})
+        labels = data.get("labels", {}).get("nodes", [])
+
+        # Extract agent assignment from description or comments
+        # Convention: [agent:swift-falcon-a3f2] in description
+        description = data.get("description", "") or ""
+        agent_id = None
+        if "[agent:" in description:
+            start = description.find("[agent:") + 7
+            end = description.find("]", start)
+            if end > start:
+                agent_id = description[start:end]
+
+        return Issue(
+            id=data.get("id", ""),
+            identifier=data.get("identifier", ""),
+            title=data.get("title", ""),
+            description=description,
+            status=self._map_state_to_status(state),
+            priority=self._map_priority(data.get("priority", 2)),
+            parent_id=parent.get("identifier") if parent else None,
+            labels=[l.get("name", "") for l in labels],
+            assigned_agent=agent_id,
+            created_at=self._parse_datetime(data.get("createdAt")),
+            updated_at=self._parse_datetime(data.get("updatedAt")),
+            completed_at=self._parse_datetime(data.get("completedAt")),
+            estimate=data.get("estimate"),
+            provider="linear",
+            external_id=data.get("id")
+        )
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Read Operations
+    # ─────────────────────────────────────────────────────────────────────
+
+    def list_issues(
+        self,
+        status: Optional[IssueStatus] = None,
+        project: Optional[str] = None,
+        limit: int = 50
+    ) -> list[Issue]:
+        """List issues from Linear, optionally filtered by status."""
+        team_id = self._get_team_id()
+
+        query = """
+        query($teamId: String!, $first: Int) {
+          team(id: $teamId) {
+            issues(first: $first) {
+              nodes {
+                id
+                identifier
+                title
+                description
+                state {
+                  id
+                  name
+                  type
+                }
+                assignee {
+                  id
+                  name
+                }
+                priority
+                estimate
+                labels {
+                  nodes {
+                    name
+                  }
+                }
+                parent {
+                  identifier
+                }
+                createdAt
+                updatedAt
+                completedAt
+              }
+            }
+          }
+        }
+        """
+
+        result = self._query(query, {"teamId": team_id, "first": limit})
+        nodes = result.get("team", {}).get("issues", {}).get("nodes", [])
+
+        issues = [self._issue_from_linear(n) for n in nodes]
+
+        # Filter by status if specified
+        if status:
+            issues = [i for i in issues if i.status == status]
+
+        # Sort by priority then created_at
+        issues.sort(key=lambda i: (i.priority.value, i.created_at or datetime.min.replace(tzinfo=timezone.utc)))
+
+        return issues[:limit]
+
+    def get_issue(self, identifier: str) -> Optional[Issue]:
+        """Get a single issue by identifier (e.g., ANV-72)."""
+        query = """
+        query($id: String!) {
+          issue(id: $id) {
+            id
+            identifier
+            title
+            description
+            state {
+              id
+              name
+              type
+            }
+            assignee {
+              id
+              name
+            }
+            priority
+            estimate
+            labels {
+              nodes {
+                name
+              }
+            }
+            parent {
+              identifier
+            }
+            createdAt
+            updatedAt
+            completedAt
+          }
+        }
+        """
+
+        try:
+            result = self._query(query, {"id": identifier})
+            issue_data = result.get("issue")
+            if issue_data:
+                return self._issue_from_linear(issue_data)
+        except Exception:
+            pass
+
+        return None
+
+    # ─────────────────────────────────────────────────────────────────────
+    # 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 in Linear."""
+        team_id = self._get_team_id()
+
+        mutation = """
+        mutation($input: IssueCreateInput!) {
+          issueCreate(input: $input) {
+            success
+            issue {
+              id
+              identifier
+              title
+              description
+              state {
+                id
+                name
+                type
+              }
+              assignee {
+                id
+                name
+              }
+              priority
+              labels {
+                nodes {
+                  name
+                }
+              }
+              parent {
+                identifier
+              }
+              createdAt
+              updatedAt
+            }
+          }
+        }
+        """
+
+        input_data = {
+            "teamId": team_id,
+            "title": title,
+            "description": description,
+            "priority": self.PRIORITY_TO_LINEAR.get(priority, 2)
+        }
+
+        # Get state ID
+        state_id = self._get_state_id(status)
+        if state_id:
+            input_data["stateId"] = state_id
+
+        # Handle parent (need to resolve identifier to ID)
+        if parent_id:
+            parent = self.get_issue(parent_id)
+            if parent and parent.external_id:
+                input_data["parentId"] = parent.external_id
+
+        # Handle labels (resolve names to UUIDs)
+        if labels:
+            label_ids = self._get_label_ids(labels)
+            if label_ids:
+                input_data["labelIds"] = label_ids
+
+        result = self._query(mutation, {"input": input_data})
+        issue_data = result.get("issueCreate", {}).get("issue", {})
+
+        return self._issue_from_linear(issue_data)
+
+    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 in Linear."""
+        mutation = """
+        mutation($id: String!, $input: IssueUpdateInput!) {
+          issueUpdate(id: $id, input: $input) {
+            success
+            issue {
+              id
+              identifier
+              title
+              description
+              state {
+                id
+                name
+                type
+              }
+              assignee {
+                id
+                name
+              }
+              priority
+              labels {
+                nodes {
+                  name
+                }
+              }
+              parent {
+                identifier
+              }
+              createdAt
+              updatedAt
+              completedAt
+            }
+          }
+        }
+        """
+
+        input_data = {}
+        if title is not None:
+            input_data["title"] = title
+        if description is not None:
+            input_data["description"] = description
+        if priority is not None:
+            input_data["priority"] = self.PRIORITY_TO_LINEAR.get(priority, 2)
+        if status is not None:
+            state_id = self._get_state_id(status)
+            if state_id:
+                input_data["stateId"] = state_id
+        # Handle labels (resolve names to UUIDs)
+        # Empty list means clear all labels; None means don't change
+        if labels is not None:
+            label_ids = self._get_label_ids(labels) if labels else []
+            input_data["labelIds"] = label_ids
+
+        if not input_data:
+            # Nothing to update, just fetch current state
+            issue = self.get_issue(identifier)
+            if not issue:
+                raise KeyError(f"Issue not found: {identifier}")
+            return issue
+
+        result = self._query(mutation, {"id": identifier, "input": input_data})
+        issue_data = result.get("issueUpdate", {}).get("issue", {})
+
+        if not issue_data:
+            raise KeyError(f"Issue not found: {identifier}")
+
+        return self._issue_from_linear(issue_data)
+
+    def delete_issue(self, identifier: str) -> bool:
+        """Delete an issue (marks as cancelled in Linear)."""
+        try:
+            self.update_issue(identifier, status=IssueStatus.CANCELLED)
+            return True
+        except (KeyError, Exception):
+            return False
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Agent Integration
+    # ─────────────────────────────────────────────────────────────────────
+
+    def assign_to_agent(self, identifier: str, agent_id: str) -> Issue:
+        """
+        Assign an issue to an Anvil agent.
+
+        Uses description convention: [agent:agent-id] appended to description.
+        This is a workaround since Linear doesn't have agent assignment natively.
+        """
+        issue = self.get_issue(identifier)
+        if not issue:
+            raise KeyError(f"Issue not found: {identifier}")
+
+        # Remove existing agent tag if present
+        description = issue.description or ""
+        if "[agent:" in description:
+            start = description.find("[agent:")
+            end = description.find("]", start)
+            # Only remove if closing bracket found
+            if end > start:
+                description = description[:start] + description[end + 1:]
+
+        # Add new agent tag
+        description = description.strip() + f"\n\n[agent:{agent_id}]"
+
+        return self.update_issue(identifier, description=description)
+
+    def unassign_agent(self, identifier: str) -> Issue:
+        """Remove agent assignment from an issue."""
+        issue = self.get_issue(identifier)
+        if not issue:
+            raise KeyError(f"Issue not found: {identifier}")
+
+        description = issue.description or ""
+        if "[agent:" in description:
+            start = description.find("[agent:")
+            end = description.find("]", start)
+            # Only remove if closing bracket found
+            if end > start:
+                description = description[:start] + description[end + 1:]
+                description = description.strip()
+
+        return self.update_issue(identifier, description=description)
+
+    def get_agent_issues(self, agent_id: str) -> list[Issue]:
+        """Get all issues assigned to a specific agent."""
+        all_issues = self.list_issues()
+        return [i for i in all_issues if i.assigned_agent == agent_id]