anvil-dev-framework 0.1.6

package/global/lib/linear_data_service.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""
+linear_data_service.py - Linear issue data fetching and caching for HUD
+
+Provides cached access to Linear issue data for the Anvil HUD dashboard.
+Uses the linear-skill scripts for API access with 60-second TTL caching.
+
+Usage:
+    from linear_data_service import LinearDataService
+
+    service = LinearDataService()
+    issue = service.get_issue("ANV-42")
+    print(issue["title"], issue["state"])
+"""
+
+import json
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+class IssueData(TypedDict, total=False):
+    """Linear issue data structure."""
+    id: str                 # Issue UUID
+    identifier: str         # Issue key (e.g., "ANV-42")
+    title: str              # Issue title
+    state: str              # Workflow state name
+    state_type: str         # State type (backlog, unstarted, started, completed, canceled)
+    assignee: Optional[str] # Assignee name
+    priority: Optional[int] # Priority (0-4)
+    url: str                # Linear issue URL
+    project: Optional[str]  # Project name
+    labels: List[str]       # Label names
+    fetched_at: float       # Timestamp when fetched
+
+
+class CacheEntry(TypedDict):
+    """Cache entry with TTL tracking."""
+    data: IssueData
+    expires_at: float
+
+
+class LinearDataService:
+    """Service for fetching and caching Linear issue data (ANV-100)."""
+
+    DEFAULT_TTL = 60.0  # 60 seconds cache TTL
+    LINEAR_SCRIPT = Path.home() / ".claude" / "skills" / "linear-skill" / "scripts" / "linear.py"
+
+    def __init__(self, ttl: float = DEFAULT_TTL):
+        """Initialize the service.
+
+        Args:
+            ttl: Cache time-to-live in seconds
+        """
+        self.ttl = ttl
+        self._cache: Dict[str, CacheEntry] = {}
+
+    def get_issue(self, issue_id: str) -> Optional[IssueData]:
+        """Fetch a single issue, using cache if available.
+
+        Args:
+            issue_id: Issue identifier (e.g., "ANV-42")
+
+        Returns:
+            Issue data or None if not found/error
+        """
+        # Check cache first
+        cached = self._get_cached(issue_id)
+        if cached is not None:
+            return cached
+
+        # Fetch from API
+        issue = self._fetch_issue(issue_id)
+        if issue:
+            self._set_cached(issue_id, issue)
+        return issue
+
+    def get_issues(self, issue_ids: List[str]) -> Dict[str, IssueData]:
+        """Fetch multiple issues.
+
+        Args:
+            issue_ids: List of issue identifiers
+
+        Returns:
+            Dictionary mapping issue_id -> IssueData
+        """
+        results: Dict[str, IssueData] = {}
+
+        for issue_id in issue_ids:
+            if not issue_id:
+                continue
+            issue = self.get_issue(issue_id)
+            if issue:
+                results[issue_id] = issue
+
+        return results
+
+    def get_issues_for_agents(self, agents: Dict[str, Any]) -> Dict[str, IssueData]:
+        """Fetch issues for all agents with assigned issues.
+
+        Args:
+            agents: Agent registry data
+
+        Returns:
+            Dictionary mapping issue_id -> IssueData
+        """
+        issue_ids = set()
+        for agent in agents.values():
+            issue_id = agent.get("issue")
+            if issue_id:
+                issue_ids.add(issue_id)
+
+        return self.get_issues(list(issue_ids))
+
+    def clear_cache(self) -> None:
+        """Clear all cached data."""
+        self._cache.clear()
+
+    def _get_cached(self, issue_id: str) -> Optional[IssueData]:
+        """Get issue from cache if not expired."""
+        entry = self._cache.get(issue_id)
+        if entry and entry["expires_at"] > time.time():
+            return entry["data"]
+        return None
+
+    def _set_cached(self, issue_id: str, data: IssueData) -> None:
+        """Store issue in cache."""
+        self._cache[issue_id] = {
+            "data": data,
+            "expires_at": time.time() + self.ttl,
+        }
+
+    def _fetch_issue(self, issue_id: str) -> Optional[IssueData]:
+        """Fetch issue from Linear API using linear-skill script."""
+        if not self.LINEAR_SCRIPT.exists():
+            return None
+
+        try:
+            result = subprocess.run(
+                ["python3", str(self.LINEAR_SCRIPT), "get-issue", "--id", issue_id],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+
+            if result.returncode != 0:
+                return None
+
+            data = json.loads(result.stdout)
+            return self._parse_issue(data)
+
+        except (subprocess.TimeoutExpired, json.JSONDecodeError, Exception):
+            # Return stale data if available
+            entry = self._cache.get(issue_id)
+            if entry:
+                return entry["data"]
+            return None
+
+    def _parse_issue(self, data: Dict[str, Any]) -> IssueData:
+        """Parse Linear API response into IssueData."""
+        state = data.get("state", {})
+        assignee = data.get("assignee", {})
+        project = data.get("project", {})
+        labels = data.get("labels", {}).get("nodes", [])
+
+        return {
+            "id": data.get("id", ""),
+            "identifier": data.get("identifier", ""),
+            "title": data.get("title", ""),
+            "state": state.get("name", "Unknown"),
+            "state_type": state.get("type", ""),
+            "assignee": assignee.get("name") if assignee else None,
+            "priority": data.get("priority"),
+            "url": data.get("url", ""),
+            "project": project.get("name") if project else None,
+            "labels": [lbl.get("name", "") for lbl in labels],
+            "fetched_at": time.time(),
+        }
+
+
+# Singleton instance
+_service: Optional[LinearDataService] = None
+
+
+def get_linear_service() -> LinearDataService:
+    """Get singleton service instance."""
+    global _service
+    if _service is None:
+        _service = LinearDataService()
+    return _service
+
+
+if __name__ == "__main__":
+    # Simple test
+    import sys
+
+    if len(sys.argv) > 1:
+        issue_id = sys.argv[1]
+        service = LinearDataService()
+        issue = service.get_issue(issue_id)
+        if issue:
+            print(f"Issue: {issue['identifier']}")
+            print(f"Title: {issue['title']}")
+            print(f"State: {issue['state']}")
+            print(f"Assignee: {issue['assignee'] or 'Unassigned'}")
+        else:
+            print(f"Could not fetch {issue_id}")
+    else:
+        print("Usage: linear_data_service.py <issue-id>")