anvil-dev-framework 0.1.6

package/global/lib/orient_fast.py

@@ -0,0 +1,457 @@
+#!/usr/bin/env python3
+"""
+orient_fast.py - Fast-path orientation script for Claude Code sessions.
+
+Runs all orientation checks in parallel to minimize latency, outputs structured
+JSON that Claude can format without re-querying.
+
+Performance target: <500ms for local checks, <2s with Linear API.
+
+Usage:
+    python3 global/lib/orient_fast.py              # Full orientation
+    python3 global/lib/orient_fast.py --fast       # Skip Linear (fastest)
+    python3 global/lib/orient_fast.py --json       # Output raw JSON
+
+Output format (JSON):
+{
+    "linear_team": {"key": "ANV", "name": "Project Anvil"},
+    "git": {"branch": "main", "clean": true, "recent_commits": [...]},
+    "handoff": {"found": true, "path": "...", "summary": "..."},
+    "active_agents": [],
+    "open_prs": [...],
+    "in_progress_issues": [...],
+    "ready_work": [...],
+    "recommendations": [...]
+}
+"""
+
+import json
+import os
+import subprocess
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass, asdict
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# Cache configuration
+CACHE_DIR = Path.home() / ".anvil" / "cache"
+LINEAR_CACHE_TTL = 60  # seconds
+
+
+@dataclass
+class OrientResult:
+    """Complete orientation result."""
+    linear_team: Optional[Dict[str, str]]
+    git: Dict[str, Any]
+    handoff: Optional[Dict[str, Any]]
+    active_agents: List[Dict[str, Any]]
+    open_prs: List[Dict[str, Any]]
+    in_progress_issues: List[Dict[str, Any]]
+    ready_work: List[Dict[str, Any]]
+    recommendations: List[str]
+    timing_ms: int
+
+
+def run_command(cmd: str, timeout: int = 5) -> tuple[str, bool]:
+    """Run a shell command and return (output, success)."""
+    try:
+        result = subprocess.run(
+            cmd,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=Path.cwd()
+        )
+        return result.stdout.strip(), result.returncode == 0
+    except subprocess.TimeoutExpired:
+        return "", False
+    except Exception as e:
+        return str(e), False
+
+
+def check_linear_yaml() -> Optional[Dict[str, str]]:
+    """Read Linear configuration from .claude/linear.yaml."""
+    yaml_path = Path.cwd() / ".claude" / "linear.yaml"
+    if not yaml_path.exists():
+        return None
+
+    try:
+        content = yaml_path.read_text()
+        config = {}
+        for line in content.split("\n"):
+            line = line.strip()
+            if line.startswith("team_key:"):
+                config["key"] = line.split('"')[1] if '"' in line else line.split(":")[1].strip()
+            elif line.startswith("team_name:"):
+                config["name"] = line.split('"')[1] if '"' in line else line.split(":")[1].strip()
+            elif line.startswith("team_id:"):
+                config["id"] = line.split('"')[1] if '"' in line else line.split(":")[1].strip()
+        return config if config.get("key") else None
+    except Exception:
+        return None
+
+
+def check_git_state() -> Dict[str, Any]:
+    """Get git status, branch, and recent commits."""
+    result = {"branch": "unknown", "clean": False, "recent_commits": []}
+
+    # Get branch
+    branch_out, ok = run_command("git branch --show-current")
+    if ok:
+        result["branch"] = branch_out or "main"
+
+    # Get status
+    status_out, ok = run_command("git status --porcelain")
+    if ok:
+        result["clean"] = len(status_out.strip()) == 0
+
+    # Get recent commits
+    log_out, ok = run_command("git log --oneline -5")
+    if ok and log_out:
+        result["recent_commits"] = log_out.split("\n")[:5]
+
+    return result
+
+
+def check_handoff() -> Optional[Dict[str, Any]]:
+    """Find and summarize most recent handoff."""
+    handoff_dir = Path.cwd() / ".claude" / "handoffs"
+    if not handoff_dir.exists():
+        return None
+
+    # Find recent handoffs (last 48 hours)
+    cutoff = datetime.now() - timedelta(hours=48)
+    handoffs = []
+
+    for f in handoff_dir.glob("*.md"):
+        try:
+            mtime = datetime.fromtimestamp(f.stat().st_mtime)
+            if mtime > cutoff:
+                handoffs.append((mtime, f))
+        except Exception:
+            continue
+
+    if not handoffs:
+        return None
+
+    # Get most recent
+    handoffs.sort(reverse=True)
+    latest_path = handoffs[0][1]
+
+    try:
+        content = latest_path.read_text()
+        # Extract first 500 chars for summary
+        lines = content.split("\n")
+        summary_lines = []
+        for line in lines[:20]:
+            summary_lines.append(line)
+            if len("\n".join(summary_lines)) > 500:
+                break
+
+        return {
+            "found": True,
+            "path": str(latest_path.relative_to(Path.cwd())),
+            "date": handoffs[0][0].strftime("%Y-%m-%d %H:%M"),
+            "summary": "\n".join(summary_lines)
+        }
+    except Exception:
+        return {"found": True, "path": str(latest_path), "date": "", "summary": ""}
+
+
+def check_active_agents() -> List[Dict[str, Any]]:
+    """Check agent registry for active agents."""
+    agents_file = Path.home() / ".anvil" / "agents.json"
+    if not agents_file.exists():
+        return []
+
+    try:
+        data = json.loads(agents_file.read_text())
+        active = []
+        now = time.time()
+
+        for agent_id, agent in data.get("agents", {}).items():
+            # Consider active if last seen within 2 minutes
+            last_seen = agent.get("last_seen", 0)
+            if now - last_seen < 120:
+                active.append({
+                    "id": agent_id[:8],
+                    "codename": agent.get("codename", "unknown"),
+                    "project": agent.get("project", ""),
+                    "phase": agent.get("phase", ""),
+                    "issue": agent.get("active_issue", "")
+                })
+
+        return active
+    except Exception:
+        return []
+
+
+def check_open_prs() -> List[Dict[str, Any]]:
+    """Get open PRs from GitHub."""
+    out, ok = run_command("gh pr list --state open --limit 10 --json number,title,headRefName,state", timeout=10)
+    if not ok or not out:
+        return []
+
+    try:
+        prs = json.loads(out)
+        return [{
+            "number": pr.get("number"),
+            "title": pr.get("title"),
+            "branch": pr.get("headRefName"),
+            "state": pr.get("state", "open")
+        } for pr in prs]
+    except json.JSONDecodeError:
+        return []
+
+
+def get_cached_linear_data() -> Optional[Dict[str, Any]]:
+    """Get Linear data from cache if fresh."""
+    cache_file = CACHE_DIR / "linear-issues.json"
+    if not cache_file.exists():
+        return None
+
+    try:
+        data = json.loads(cache_file.read_text())
+        cached_at = data.get("cached_at", 0)
+        if time.time() - cached_at < LINEAR_CACHE_TTL:
+            return data
+    except Exception:
+        pass
+
+    return None
+
+
+def fetch_linear_issues(team_id: str) -> Dict[str, Any]:
+    """Fetch issues from Linear API using the linear-skill script."""
+    # First check cache
+    cached = get_cached_linear_data()
+    if cached:
+        return cached
+
+    # Check if LINEAR_API_KEY is available
+    if not os.environ.get("LINEAR_API_KEY"):
+        return {"in_progress": [], "ready": [], "blocked": [], "error": "No LINEAR_API_KEY"}
+
+    # Use the linear-skill script
+    linear_script = Path.home() / ".claude" / "skills" / "linear-skill" / "scripts" / "linear.py"
+    if not linear_script.exists():
+        return {"in_progress": [], "ready": [], "blocked": [], "error": "Linear skill not found"}
+
+    try:
+        # Add the script directory to path and import
+        sys.path.insert(0, str(linear_script.parent))
+        from linear import LinearClient
+
+        client = LinearClient()
+        issues = client.list_issues(team_id=team_id, limit=50)
+
+        # Categorize issues by state type
+        in_progress = []
+        ready = []  # Todo + Backlog without blockers
+        blocked = []
+
+        for issue in issues:
+            state = issue.get("state", {})
+            state_type = state.get("type", "")
+            state_name = state.get("name", "").lower()
+
+            issue_data = {
+                "identifier": issue.get("identifier"),
+                "title": issue.get("title"),
+                "state": state_name,
+                "state_type": state_type,
+                "priority": issue.get("priority", 4),
+                "created_at": issue.get("createdAt", "")
+            }
+
+            if state_type == "started" or state_name == "in progress":
+                in_progress.append(issue_data)
+            elif state_type in ("unstarted", "backlog") or state_name in ("todo", "backlog"):
+                # For now, treat all unstarted as ready (blocker check would need more API calls)
+                ready.append(issue_data)
+
+        # Sort by priority (0 = urgent, 4 = none)
+        ready.sort(key=lambda x: (x.get("priority", 4), x.get("created_at", "")))
+
+        result = {
+            "in_progress": in_progress,
+            "ready": ready[:10],  # Top 10 ready
+            "blocked": blocked
+        }
+
+        # Cache the result
+        save_linear_cache(result)
+        return result
+
+    except Exception as e:
+        return {"in_progress": [], "ready": [], "blocked": [], "error": str(e)}
+
+
+def save_linear_cache(data: Dict[str, Any]) -> None:
+    """Save Linear data to cache."""
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    cache_file = CACHE_DIR / "linear-issues.json"
+    data["cached_at"] = time.time()
+    cache_file.write_text(json.dumps(data, indent=2))
+
+
+def generate_recommendations(
+    handoff: Optional[Dict],
+    open_prs: List[Dict],
+    in_progress: List[Dict],
+    ready_work: List[Dict]
+) -> List[str]:
+    """Generate session recommendations based on state."""
+    recs = []
+
+    if handoff and handoff.get("found"):
+        recs.append(f"Recent handoff found from {handoff.get('date', 'recently')} - review for context")
+
+    if len(open_prs) >= 3:
+        recs.append(f"{len(open_prs)} open PRs - consider reviewing/merging before new work")
+
+    if ready_work:
+        top = ready_work[0]
+        recs.append(f"Top ready work: {top.get('identifier', 'unknown')} - {top.get('title', '')}")
+
+    if not recs:
+        recs.append("No specific recommendations - awaiting direction")
+
+    return recs
+
+
+def run_orient(skip_linear: bool = False) -> OrientResult:
+    """Run all orientation checks in parallel."""
+    start = time.time()
+
+    # Run checks in parallel
+    with ThreadPoolExecutor(max_workers=6) as executor:
+        futures = {
+            executor.submit(check_linear_yaml): "linear_yaml",
+            executor.submit(check_git_state): "git",
+            executor.submit(check_handoff): "handoff",
+            executor.submit(check_active_agents): "agents",
+            executor.submit(check_open_prs): "prs",
+        }
+
+        results = {}
+        for future in as_completed(futures):
+            key = futures[future]
+            try:
+                results[key] = future.result()
+            except Exception as e:
+                results[key] = None
+
+    # Process Linear data (separate to allow caching)
+    linear_config = results.get("linear_yaml")
+    in_progress = []
+    ready_work = []
+
+    if not skip_linear and linear_config and linear_config.get("id"):
+        linear_data = fetch_linear_issues(linear_config["id"])
+        in_progress = linear_data.get("in_progress", [])
+        ready_work = linear_data.get("ready", [])
+
+    # Generate recommendations
+    recommendations = generate_recommendations(
+        results.get("handoff"),
+        results.get("prs", []),
+        in_progress,
+        ready_work
+    )
+
+    timing_ms = int((time.time() - start) * 1000)
+
+    return OrientResult(
+        linear_team=linear_config,
+        git=results.get("git", {}),
+        handoff=results.get("handoff"),
+        active_agents=results.get("agents", []),
+        open_prs=results.get("prs", []),
+        in_progress_issues=in_progress,
+        ready_work=ready_work,
+        recommendations=recommendations,
+        timing_ms=timing_ms
+    )
+
+
+def format_output(result: OrientResult, as_json: bool = False) -> str:
+    """Format orientation result for display."""
+    if as_json:
+        return json.dumps(asdict(result), indent=2)
+
+    lines = []
+    lines.append("## Session Orientation (fast-path)\n")
+
+    # Linear team
+    if result.linear_team:
+        lines.append(f"**Linear Team**: {result.linear_team.get('key', '?')} - {result.linear_team.get('name', '?')}")
+    else:
+        lines.append("**Linear Team**: Not configured")
+
+    # Git state
+    git = result.git
+    clean_str = "clean" if git.get("clean") else "uncommitted changes"
+    lines.append(f"**Git**: {git.get('branch', '?')} ({clean_str})")
+
+    # Active agents
+    if result.active_agents:
+        lines.append(f"**Active Agents**: {len(result.active_agents)}")
+        for agent in result.active_agents:
+            lines.append(f"  - {agent.get('codename', '?')}: {agent.get('issue', 'unknown')}")
+    else:
+        lines.append("**Active Agents**: None")
+
+    # Handoff
+    if result.handoff and result.handoff.get("found"):
+        lines.append(f"**Handoff**: Found ({result.handoff.get('date', 'recent')})")
+    else:
+        lines.append("**Handoff**: None")
+
+    # Open PRs
+    lines.append(f"**Open PRs**: {len(result.open_prs)}")
+    for pr in result.open_prs[:5]:
+        lines.append(f"  - #{pr.get('number', '?')}: {pr.get('title', '?')}")
+
+    # Recommendations
+    lines.append("\n**Recommendations**:")
+    for rec in result.recommendations:
+        lines.append(f"  - {rec}")
+
+    # Timing
+    lines.append(f"\n_Completed in {result.timing_ms}ms_")
+
+    return "\n".join(lines)
+
+
+def main():
+    """CLI entry point."""
+    import argparse
+    parser = argparse.ArgumentParser(description="Fast-path session orientation")
+    parser.add_argument("--fast", action="store_true", help="Skip Linear API calls")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    args = parser.parse_args()
+
+    result = run_orient(skip_linear=args.fast)
+    output = format_output(result, as_json=args.json)
+    print(output)
+
+    # Also update state manager
+    try:
+        state_manager_path = Path.cwd() / "global" / "lib" / "state_manager.py"
+        if state_manager_path.exists():
+            subprocess.run(
+                [sys.executable, str(state_manager_path), "orient"],
+                capture_output=True,
+                timeout=5
+            )
+    except Exception:
+        pass  # Non-critical
+
+
+if __name__ == "__main__":
+    main()