anvil-dev-framework 0.1.6

package/global/lib/claim_service.py

@@ -0,0 +1,515 @@
+#!/usr/bin/env python3
+"""
+claim_service.py - Transactional Issue Claiming Service (ANV-224)
+
+Manages issue claims to prevent multiple agents from working on the same
+Linear issue simultaneously. Claims are session-scoped and automatically
+released when an agent terminates.
+
+Usage:
+    from claim_service import ClaimService, claim_issue, release_claim
+
+    # Claim an issue
+    success = claim_issue("ANV-100", agent_id="agent-alpha", codename="A1")
+
+    # Check if claimed
+    if is_claimed("ANV-100"):
+        claim = get_claim("ANV-100")
+        print(f"Claimed by {claim['codename']}")
+
+    # Release claim
+    release_claim("ANV-100", agent_id="agent-alpha")
+
+    # Release all claims for an agent (called on deregistration)
+    release_all_claims("agent-alpha")
+"""
+
+import fcntl
+import json
+import os
+import re
+import tempfile
+import time
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Generator, List, Optional, TypedDict
+
+
+# =============================================================================
+# Data Types
+# =============================================================================
+
+class Claim(TypedDict, total=False):
+    """A single issue claim."""
+    claimed_by: str          # Agent UUID that holds the claim
+    claimed_at: str          # ISO timestamp of when claim was made
+    codename: str            # Agent codename (A1, A2, etc.) for display
+    project: str             # Project path where claim originated
+    scope: str               # "global" or "project"
+    collaborators: List[str] # Agent IDs that have override access
+
+
+class ClaimsRegistry(TypedDict):
+    """The claims.json structure."""
+    version: str
+    lastUpdated: str
+    claims: Dict[str, Claim]  # issue_id -> Claim
+
+
+# =============================================================================
+# File Locking
+# =============================================================================
+
+CLAIMS_FILE = Path.home() / ".anvil" / "claims.json"
+CLAIMS_LOCK_FILE = Path.home() / ".anvil" / "claims.lock"
+
+
+@contextmanager
+def claims_lock(timeout: float = 5.0) -> Generator[None, None, None]:
+    """Context manager for atomic claims operations using file locking.
+
+    Args:
+        timeout: Maximum seconds to wait for lock (default 5s)
+
+    Yields:
+        None when lock is acquired
+
+    Raises:
+        TimeoutError: If lock cannot be acquired within timeout
+    """
+    CLAIMS_LOCK_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+    lock_fd = os.open(str(CLAIMS_LOCK_FILE), os.O_CREAT | os.O_RDWR)
+    try:
+        start_time = time.time()
+        while True:
+            try:
+                fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break  # Lock acquired
+            except BlockingIOError:
+                if time.time() - start_time > timeout:
+                    raise TimeoutError(f"Could not acquire claims lock within {timeout}s")
+                time.sleep(0.05)  # Wait 50ms and retry
+
+        yield
+    finally:
+        fcntl.flock(lock_fd, fcntl.LOCK_UN)
+        os.close(lock_fd)
+
+
+# =============================================================================
+# Claim Service
+# =============================================================================
+
+# Pattern to detect Linear issue IDs (e.g., ANV-123, PROJ-45)
+LINEAR_ISSUE_PATTERN = re.compile(r'^[A-Z]+-\d+$')
+
+
+class ClaimService:
+    """Service for managing transactional issue claims."""
+
+    VERSION = "1.0"
+
+    def __init__(self, base_dir: Optional[str] = None):
+        """Initialize the claim service.
+
+        Args:
+            base_dir: Override base directory (default: ~/.anvil)
+        """
+        if base_dir:
+            self.base_dir = Path(base_dir)
+        else:
+            self.base_dir = Path.home() / ".anvil"
+
+        self.claims_file = self.base_dir / "claims.json"
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+
+    def _atomic_write(self, filepath: Path, data: Dict[str, Any]) -> None:
+        """Write data to file atomically (write temp, then rename)."""
+        dir_path = filepath.parent
+        dir_path.mkdir(parents=True, exist_ok=True)
+
+        with tempfile.NamedTemporaryFile(
+            mode='w',
+            dir=str(dir_path),
+            delete=False,
+            suffix='.tmp'
+        ) as tmp:
+            json.dump(data, tmp, indent=2)
+            tmp_path = tmp.name
+
+        os.rename(tmp_path, str(filepath))
+
+    def _read_claims(self) -> ClaimsRegistry:
+        """Read the claims file, creating if it doesn't exist."""
+        if not self.claims_file.exists():
+            return {
+                "version": self.VERSION,
+                "lastUpdated": datetime.now(timezone.utc).isoformat(),
+                "claims": {}
+            }
+
+        try:
+            with open(self.claims_file, 'r') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            # Corrupted file, return fresh
+            return {
+                "version": self.VERSION,
+                "lastUpdated": datetime.now(timezone.utc).isoformat(),
+                "claims": {}
+            }
+
+    def _write_claims(self, data: ClaimsRegistry) -> None:
+        """Write the claims file atomically."""
+        data["lastUpdated"] = datetime.now(timezone.utc).isoformat()
+        self._atomic_write(self.claims_file, data)
+
+    def _determine_scope(self, issue_id: str) -> str:
+        """Determine if an issue should have global or project scope.
+
+        Linear issues (ANV-123 format) are global scope.
+        Ad-hoc work (file paths, custom IDs) are project-scoped.
+
+        Args:
+            issue_id: The issue identifier
+
+        Returns:
+            "global" or "project"
+        """
+        if LINEAR_ISSUE_PATTERN.match(issue_id):
+            return "global"
+        return "project"
+
+    def claim(
+        self,
+        issue_id: str,
+        agent_id: str,
+        codename: str,
+        project: Optional[str] = None,
+        force: bool = False,
+    ) -> Dict[str, Any]:
+        """Claim an issue for exclusive work.
+
+        Args:
+            issue_id: The issue to claim (e.g., "ANV-100")
+            agent_id: UUID of the claiming agent
+            codename: Display codename (e.g., "A1")
+            project: Project path (used for project-scoped claims)
+            force: If True, override existing claim (for collaboration)
+
+        Returns:
+            Dict with:
+                - success: bool
+                - claim: Claim data if successful
+                - error: Error message if failed
+                - existing_claim: Existing claim if conflict
+        """
+        with claims_lock():
+            registry = self._read_claims()
+            claims = registry.get("claims", {})
+            scope = self._determine_scope(issue_id)
+            now = datetime.now(timezone.utc).isoformat()
+
+            # Check existing claim
+            if issue_id in claims:
+                existing = claims[issue_id]
+
+                # Same agent reclaiming - just update timestamp
+                if existing["claimed_by"] == agent_id:
+                    existing["claimed_at"] = now
+                    self._write_claims(registry)
+                    return {
+                        "success": True,
+                        "claim": existing,
+                        "renewed": True,
+                    }
+
+                # Different agent - check if we should allow override
+                if force:
+                    # Add original claimer to collaborators list
+                    collaborators = existing.get("collaborators", [])
+                    if agent_id not in collaborators:
+                        collaborators.append(existing["claimed_by"])
+                    existing["collaborators"] = collaborators
+                    existing["claimed_by"] = agent_id
+                    existing["codename"] = codename
+                    existing["claimed_at"] = now
+                    self._write_claims(registry)
+                    return {
+                        "success": True,
+                        "claim": existing,
+                        "override": True,
+                        "previous_claimer": collaborators[-1],
+                    }
+
+                # Conflict - return info about existing claim
+                return {
+                    "success": False,
+                    "error": f"Issue {issue_id} is already claimed by {existing['codename']}",
+                    "existing_claim": existing,
+                }
+
+            # No existing claim - create new one
+            new_claim: Claim = {
+                "claimed_by": agent_id,
+                "claimed_at": now,
+                "codename": codename,
+                "project": project or os.getcwd(),
+                "scope": scope,
+                "collaborators": [],
+            }
+
+            claims[issue_id] = new_claim
+            registry["claims"] = claims
+            self._write_claims(registry)
+
+            return {
+                "success": True,
+                "claim": new_claim,
+            }
+
+    def release(self, issue_id: str, agent_id: str) -> bool:
+        """Release a claim on an issue.
+
+        Args:
+            issue_id: The issue to release
+            agent_id: UUID of the releasing agent (must match claimer)
+
+        Returns:
+            True if claim was released, False if not found or not owned
+        """
+        with claims_lock():
+            registry = self._read_claims()
+            claims = registry.get("claims", {})
+
+            if issue_id not in claims:
+                return False
+
+            claim = claims[issue_id]
+
+            # Only the claimer or a collaborator can release
+            if claim["claimed_by"] != agent_id:
+                if agent_id not in claim.get("collaborators", []):
+                    return False
+
+            del claims[issue_id]
+            registry["claims"] = claims
+            self._write_claims(registry)
+            return True
+
+    def release_all(self, agent_id: str) -> int:
+        """Release all claims held by an agent.
+
+        Called during agent deregistration to clean up claims.
+
+        Args:
+            agent_id: UUID of the agent
+
+        Returns:
+            Number of claims released
+        """
+        with claims_lock():
+            registry = self._read_claims()
+            claims = registry.get("claims", {})
+
+            released = 0
+            to_remove = []
+
+            for issue_id, claim in claims.items():
+                if claim["claimed_by"] == agent_id:
+                    to_remove.append(issue_id)
+                    released += 1
+
+            for issue_id in to_remove:
+                del claims[issue_id]
+
+            if released > 0:
+                registry["claims"] = claims
+                self._write_claims(registry)
+
+            return released
+
+    def is_claimed(self, issue_id: str, project: Optional[str] = None) -> bool:
+        """Check if an issue is claimed.
+
+        Args:
+            issue_id: The issue to check
+            project: For project-scoped claims, filter by project
+
+        Returns:
+            True if claimed, False otherwise
+        """
+        registry = self._read_claims()
+        claims = registry.get("claims", {})
+
+        if issue_id not in claims:
+            return False
+
+        claim = claims[issue_id]
+
+        # For project-scoped claims, check if it's the same project
+        if project and claim.get("scope") == "project":
+            if claim.get("project") != project:
+                return False
+
+        return True
+
+    def get_claim(self, issue_id: str) -> Optional[Claim]:
+        """Get claim details for an issue.
+
+        Args:
+            issue_id: The issue to look up
+
+        Returns:
+            Claim data or None if not claimed
+        """
+        registry = self._read_claims()
+        return registry.get("claims", {}).get(issue_id)
+
+    def get_all_claims(self) -> Dict[str, Claim]:
+        """Get all active claims.
+
+        Returns:
+            Dictionary of issue_id -> Claim
+        """
+        registry = self._read_claims()
+        return registry.get("claims", {})
+
+    def get_claims_by_agent(self, agent_id: str) -> Dict[str, Claim]:
+        """Get all claims held by a specific agent.
+
+        Args:
+            agent_id: UUID of the agent
+
+        Returns:
+            Dictionary of issue_id -> Claim for this agent
+        """
+        registry = self._read_claims()
+        claims = registry.get("claims", {})
+
+        return {
+            issue_id: claim
+            for issue_id, claim in claims.items()
+            if claim["claimed_by"] == agent_id
+        }
+
+    def get_claims_summary(self) -> List[Dict[str, Any]]:
+        """Get a summary of all claims for display.
+
+        Returns:
+            List of claim summaries with issue_id, codename, project
+        """
+        registry = self._read_claims()
+        claims = registry.get("claims", {})
+
+        return [
+            {
+                "issue_id": issue_id,
+                "codename": claim["codename"],
+                "project": Path(claim.get("project", "")).name,
+                "claimed_at": claim["claimed_at"],
+                "scope": claim.get("scope", "global"),
+            }
+            for issue_id, claim in claims.items()
+        ]
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+_service: Optional[ClaimService] = None
+
+
+def get_claim_service() -> ClaimService:
+    """Get singleton claim service instance."""
+    global _service
+    if _service is None:
+        _service = ClaimService()
+    return _service
+
+
+def claim_issue(
+    issue_id: str,
+    agent_id: str,
+    codename: str,
+    project: Optional[str] = None,
+    force: bool = False,
+) -> Dict[str, Any]:
+    """Claim an issue (convenience function)."""
+    return get_claim_service().claim(issue_id, agent_id, codename, project, force)
+
+
+def release_claim(issue_id: str, agent_id: str) -> bool:
+    """Release a claim (convenience function)."""
+    return get_claim_service().release(issue_id, agent_id)
+
+
+def release_all_claims(agent_id: str) -> int:
+    """Release all claims for an agent (convenience function)."""
+    return get_claim_service().release_all(agent_id)
+
+
+def is_claimed(issue_id: str, project: Optional[str] = None) -> bool:
+    """Check if an issue is claimed (convenience function)."""
+    return get_claim_service().is_claimed(issue_id, project)
+
+
+def get_claim(issue_id: str) -> Optional[Claim]:
+    """Get claim details (convenience function)."""
+    return get_claim_service().get_claim(issue_id)
+
+
+def get_all_claims() -> Dict[str, Claim]:
+    """Get all claims (convenience function)."""
+    return get_claim_service().get_all_claims()
+
+
+def get_claims_by_agent(agent_id: str) -> Dict[str, Claim]:
+    """Get claims for an agent (convenience function)."""
+    return get_claim_service().get_claims_by_agent(agent_id)
+
+
+if __name__ == "__main__":
+    import sys
+
+    service = ClaimService()
+
+    if len(sys.argv) > 1:
+        cmd = sys.argv[1]
+
+        if cmd == "claim":
+            issue_id = sys.argv[2]
+            agent_id = sys.argv[3] if len(sys.argv) > 3 else "test-agent"
+            codename = sys.argv[4] if len(sys.argv) > 4 else "A1"
+            result = service.claim(issue_id, agent_id, codename)
+            print(json.dumps(result, indent=2))
+
+        elif cmd == "release":
+            issue_id = sys.argv[2]
+            agent_id = sys.argv[3] if len(sys.argv) > 3 else "test-agent"
+            success = service.release(issue_id, agent_id)
+            print(f"Released: {success}")
+
+        elif cmd == "list":
+            claims = service.get_all_claims()
+            if not claims:
+                print("No active claims")
+            else:
+                for issue_id, claim in claims.items():
+                    print(f"  {issue_id}: claimed by {claim['codename']}")
+
+        elif cmd == "check":
+            issue_id = sys.argv[2]
+            claim = service.get_claim(issue_id)
+            if claim:
+                print(f"{issue_id} is claimed by {claim['codename']}")
+            else:
+                print(f"{issue_id} is not claimed")
+
+        else:
+            print(f"Unknown command: {cmd}")
+    else:
+        print("Usage: claim_service.py [claim|release|list|check] [args...]")