anvil-dev-framework 0.1.6

package/global/lib/local_provider.py

@@ -0,0 +1,486 @@
+"""
+LocalJsonProvider - File-based issue tracking for Anvil Framework.
+
+Stores issues as JSON files for users who don't use Linear.
+Provides the same IssueProvider interface for seamless integration.
+
+Storage Structure:
+    ~/.anvil/issues/
+    ├── index.json          # Issue index with metadata
+    └── LOCAL-001.json      # Individual issue files (optional detail storage)
+
+    <project>/.claude/
+    └── issues.json         # Project-specific issues (optional)
+
+Usage:
+    from local_provider import LocalJsonProvider
+
+    provider = LocalJsonProvider()
+    issue = provider.create_issue(title="New feature", priority=Priority.HIGH)
+    issues = provider.list_issues(status=IssueStatus.TODO)
+"""
+
+import fcntl
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+import uuid
+
+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 LocalJsonProvider(BaseProvider):
+    """
+    File-based issue provider using JSON storage.
+
+    Features:
+    - Atomic writes (temp file + rename)
+    - File locking for concurrent access
+    - Auto-generated identifiers (LOCAL-001, LOCAL-002, etc.)
+    - Support for both global and project-specific issues
+    """
+
+    def __init__(
+        self,
+        project_path: Optional[Path] = None,
+        prefix: str = "LOCAL",
+        storage_path: Optional[Path] = None
+    ):
+        """
+        Initialize LocalJsonProvider.
+
+        Args:
+            project_path: Project root for project-specific issues (optional)
+            prefix: Identifier prefix (default: "LOCAL")
+            storage_path: Custom storage path (default: ~/.anvil/issues)
+        """
+        self.project_path = project_path or Path.cwd()
+        self.prefix = prefix
+
+        # Global storage location
+        if storage_path:
+            self.storage_path = storage_path
+        else:
+            self.storage_path = Path.home() / ".anvil" / "issues"
+
+        # Ensure storage directory exists
+        self.storage_path.mkdir(parents=True, exist_ok=True)
+
+        # Index file path
+        self.index_path = self.storage_path / "index.json"
+
+        # Initialize index if needed
+        self._ensure_index()
+
+    @property
+    def name(self) -> str:
+        return "local"
+
+    @property
+    def is_available(self) -> bool:
+        return True  # Always available for local storage
+
+    def _ensure_index(self) -> None:
+        """Create index file if it doesn't exist."""
+        if not self.index_path.exists():
+            self._write_index({
+                "version": "1.0",
+                "prefix": self.prefix,
+                "next_id": 1,
+                "issues": {}
+            })
+
+    def _read_index(self) -> dict:
+        """Read index file with file locking."""
+        try:
+            with open(self.index_path, 'r') as f:
+                fcntl.flock(f.fileno(), fcntl.LOCK_SH)
+                try:
+                    return json.load(f)
+                finally:
+                    fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+        except (FileNotFoundError, json.JSONDecodeError):
+            return {
+                "version": "1.0",
+                "prefix": self.prefix,
+                "next_id": 1,
+                "issues": {}
+            }
+
+    def _write_index(self, data: dict) -> None:
+        """Write index file atomically with file locking."""
+        # Write to temp file first
+        fd, temp_path = tempfile.mkstemp(
+            dir=self.storage_path,
+            prefix=".index_",
+            suffix=".json"
+        )
+        try:
+            with os.fdopen(fd, 'w') as f:
+                fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+                try:
+                    json.dump(data, f, indent=2, default=str)
+                finally:
+                    fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+            # Atomic rename
+            os.rename(temp_path, self.index_path)
+        except Exception:
+            # Clean up temp file on error
+            try:
+                os.unlink(temp_path)
+            except OSError:
+                pass
+            raise
+
+    def _generate_identifier(self, index: dict) -> tuple[str, int]:
+        """Generate next identifier and increment counter."""
+        next_id = index.get("next_id", 1)
+        prefix = index.get("prefix", self.prefix)
+        identifier = f"{prefix}-{next_id:03d}"
+        return identifier, next_id + 1
+
+    def _issue_to_index_entry(self, issue: Issue) -> dict:
+        """Convert Issue to compact index entry."""
+        return {
+            "id": issue.id,
+            "title": issue.title,
+            "status": issue.status.value,
+            "priority": issue.priority.value,
+            "parent_id": issue.parent_id,
+            "assigned_agent": issue.assigned_agent,
+            "labels": issue.labels,
+            "estimate": issue.estimate,
+            "created_at": issue.created_at.isoformat() if issue.created_at else None,
+            "updated_at": issue.updated_at.isoformat() if issue.updated_at else None,
+            "completed_at": issue.completed_at.isoformat() if issue.completed_at else None,
+        }
+
+    def _index_entry_to_issue(self, identifier: str, entry: dict) -> Issue:
+        """Convert index entry back to Issue object."""
+        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 Issue(
+            id=entry.get("id", identifier),
+            identifier=identifier,
+            title=entry.get("title", ""),
+            description=entry.get("description", ""),
+            status=IssueStatus(entry.get("status", "todo")),
+            priority=Priority(entry.get("priority", 2)),
+            parent_id=entry.get("parent_id"),
+            labels=entry.get("labels", []),
+            assigned_agent=entry.get("assigned_agent"),
+            created_at=parse_dt(entry.get("created_at")) or datetime.now(timezone.utc),
+            updated_at=parse_dt(entry.get("updated_at")) or datetime.now(timezone.utc),
+            completed_at=parse_dt(entry.get("completed_at")),
+            estimate=entry.get("estimate"),
+            provider="local",
+            external_id=None
+        )
+
+    # ─────────────────────────────────────────────────────────────────────
+    # 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."""
+        index = self._read_index()
+        issues = []
+
+        for identifier, entry in index.get("issues", {}).items():
+            issue = self._index_entry_to_issue(identifier, entry)
+
+            # Filter by status if specified
+            if status and issue.status != status:
+                continue
+
+            issues.append(issue)
+
+        # Sort by priority (lower = higher priority), then by created_at
+        issues.sort(key=lambda i: (i.priority.value, i.created_at))
+
+        return issues[:limit]
+
+    def get_issue(self, identifier: str) -> Optional[Issue]:
+        """Get a single issue by identifier."""
+        index = self._read_index()
+        entry = index.get("issues", {}).get(identifier)
+
+        if entry is None:
+            # Try case-insensitive match
+            for key, val in index.get("issues", {}).items():
+                if key.upper() == identifier.upper():
+                    return self._index_entry_to_issue(key, val)
+            return None
+
+        return self._index_entry_to_issue(identifier, entry)
+
+    def get_ready_issues(self) -> list[Issue]:
+        """Get issues ready to work on (Todo, no blocking deps)."""
+        issues = self.list_issues(status=IssueStatus.TODO)
+        # Sort by priority (lower = higher), then by age (oldest first)
+        return sorted(issues, key=lambda i: (i.priority.value, i.created_at))
+
+    def get_in_progress_issues(self) -> list[Issue]:
+        """Get issues currently being worked on."""
+        in_progress = self.list_issues(status=IssueStatus.IN_PROGRESS)
+        in_review = self.list_issues(status=IssueStatus.IN_REVIEW)
+        return in_progress + in_review
+
+    # ─────────────────────────────────────────────────────────────────────
+    # 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."""
+        index = self._read_index()
+
+        # Generate identifier
+        identifier, next_id = self._generate_identifier(index)
+
+        # Create issue object
+        now = datetime.now(timezone.utc)
+        issue = Issue(
+            id=str(uuid.uuid4()),
+            identifier=identifier,
+            title=title,
+            description=description,
+            status=status,
+            priority=priority,
+            parent_id=parent_id,
+            labels=labels or [],
+            assigned_agent=None,
+            created_at=now,
+            updated_at=now,
+            completed_at=None,
+            estimate=None,
+            provider="local",
+            external_id=None
+        )
+
+        # Add to index
+        index["issues"][identifier] = self._issue_to_index_entry(issue)
+        index["next_id"] = next_id
+
+        # Write index
+        self._write_index(index)
+
+        return issue
+
+    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."""
+        index = self._read_index()
+
+        # Find issue (case-insensitive)
+        actual_identifier = None
+        for key in index.get("issues", {}).keys():
+            if key.upper() == identifier.upper():
+                actual_identifier = key
+                break
+
+        if actual_identifier is None:
+            raise KeyError(f"Issue not found: {identifier}")
+
+        entry = index["issues"][actual_identifier]
+        issue = self._index_entry_to_issue(actual_identifier, entry)
+
+        # Apply updates
+        if title is not None:
+            issue.title = title
+        if description is not None:
+            issue.description = description
+        if status is not None:
+            issue.transition_to(status)
+        if priority is not None:
+            issue.priority = priority
+        if labels is not None:
+            issue.labels = labels
+
+        issue.updated_at = datetime.now(timezone.utc)
+
+        # Update index
+        index["issues"][actual_identifier] = self._issue_to_index_entry(issue)
+        self._write_index(index)
+
+        return issue
+
+    def delete_issue(self, identifier: str) -> bool:
+        """Delete an issue (soft delete - marks as cancelled)."""
+        try:
+            self.update_issue(identifier, status=IssueStatus.CANCELLED)
+            return True
+        except KeyError:
+            return False
+
+    def hard_delete_issue(self, identifier: str) -> bool:
+        """Permanently delete an issue from storage."""
+        index = self._read_index()
+
+        # Find issue (case-insensitive)
+        actual_identifier = None
+        for key in index.get("issues", {}).keys():
+            if key.upper() == identifier.upper():
+                actual_identifier = key
+                break
+
+        if actual_identifier is None:
+            return False
+
+        del index["issues"][actual_identifier]
+        self._write_index(index)
+        return True
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Agent Integration
+    # ─────────────────────────────────────────────────────────────────────
+
+    def assign_to_agent(self, identifier: str, agent_id: str) -> Issue:
+        """Assign an issue to an Anvil agent."""
+        index = self._read_index()
+
+        # Find issue
+        actual_identifier = None
+        for key in index.get("issues", {}).keys():
+            if key.upper() == identifier.upper():
+                actual_identifier = key
+                break
+
+        if actual_identifier is None:
+            raise KeyError(f"Issue not found: {identifier}")
+
+        entry = index["issues"][actual_identifier]
+        issue = self._index_entry_to_issue(actual_identifier, entry)
+
+        issue.claim(agent_id)
+
+        # Update index
+        index["issues"][actual_identifier] = self._issue_to_index_entry(issue)
+        self._write_index(index)
+
+        return issue
+
+    def unassign_agent(self, identifier: str) -> Issue:
+        """Remove agent assignment from an issue."""
+        index = self._read_index()
+
+        # Find issue
+        actual_identifier = None
+        for key in index.get("issues", {}).keys():
+            if key.upper() == identifier.upper():
+                actual_identifier = key
+                break
+
+        if actual_identifier is None:
+            raise KeyError(f"Issue not found: {identifier}")
+
+        entry = index["issues"][actual_identifier]
+        issue = self._index_entry_to_issue(actual_identifier, entry)
+
+        issue.unclaim()
+
+        # Update index
+        index["issues"][actual_identifier] = self._issue_to_index_entry(issue)
+        self._write_index(index)
+
+        return issue
+
+    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]
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Bulk Operations
+    # ─────────────────────────────────────────────────────────────────────
+
+    def import_issues(self, issues: list[Issue]) -> int:
+        """Import multiple issues at once."""
+        index = self._read_index()
+        imported = 0
+
+        for issue in issues:
+            # Use existing identifier or generate new one
+            if issue.identifier and issue.identifier not in index.get("issues", {}):
+                identifier = issue.identifier
+            else:
+                identifier, next_id = self._generate_identifier(index)
+                index["next_id"] = next_id
+                issue.identifier = identifier
+
+            issue.provider = "local"
+            index["issues"][identifier] = self._issue_to_index_entry(issue)
+            imported += 1
+
+        self._write_index(index)
+        return imported
+
+    def export_issues(self, status: Optional[IssueStatus] = None) -> list[dict]:
+        """Export issues as list of dictionaries."""
+        issues = self.list_issues(status=status, limit=9999)
+        return [issue.to_dict() for issue in issues]
+
+    def get_statistics(self) -> dict:
+        """Get issue statistics."""
+        all_issues = self.list_issues(limit=9999)
+
+        by_status = {}
+        by_priority = {}
+        assigned = 0
+        unassigned = 0
+
+        for issue in all_issues:
+            # Count by status
+            status_name = issue.status.value
+            by_status[status_name] = by_status.get(status_name, 0) + 1
+
+            # Count by priority
+            priority_name = issue.priority.to_display()
+            by_priority[priority_name] = by_priority.get(priority_name, 0) + 1
+
+            # Count assigned
+            if issue.assigned_agent:
+                assigned += 1
+            else:
+                unassigned += 1
+
+        return {
+            "total": len(all_issues),
+            "by_status": by_status,
+            "by_priority": by_priority,
+            "assigned": assigned,
+            "unassigned": unassigned
+        }