anvil-dev-framework 0.1.6

package/global/lib/state_manager.py

@@ -0,0 +1,417 @@
+#!/usr/bin/env python3
+"""
+state_manager.py - Anvil Session State Management (ANV-176)
+
+Manages the local .claude/anvil-state.json file and syncs changes
+to the global agent registry for multi-agent visibility.
+
+This module solves the "stale statusline" problem where issue/phase
+indicators show outdated information. By calling update_state() from
+workflow commands (/orient, /explore, /spec, etc.), the statusline
+always reflects the current workflow state.
+
+Usage:
+    from global.lib.state_manager import update_state, get_state
+
+    # Update phase when running /explore
+    update_state(phase="explore", last_command="/explore")
+
+    # Update issue when claiming Linear work
+    update_state(active_issue="ANV-180", phase="implement")
+
+    # Clear issue when starting fresh
+    update_state(active_issue=None, phase="orient")
+
+    # Read current state
+    state = get_state()
+    print(state.get("session", {}).get("phase"))
+"""
+
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# Try to import agent registry for sync
+try:
+    from agent_registry import update_agent
+    REGISTRY_AVAILABLE = True
+except ImportError:
+    try:
+        # Try relative import for when run as module
+        from .agent_registry import update_agent
+        REGISTRY_AVAILABLE = True
+    except ImportError:
+        REGISTRY_AVAILABLE = False
+
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+STATE_FILE = Path(".claude/anvil-state.json")
+
+
+# =============================================================================
+# State Operations
+# =============================================================================
+
+def _atomic_write(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_state() -> Dict[str, Any]:
+    """Read state file, creating default structure if missing."""
+    if not STATE_FILE.exists():
+        return {
+            "version": "1.0",
+            "session": {},
+            "cache": {"git": {}},
+            "meta": {
+                "createdAt": datetime.now(timezone.utc).isoformat(),
+                "updatedAt": datetime.now(timezone.utc).isoformat(),
+            }
+        }
+
+    try:
+        with open(STATE_FILE, 'r') as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        # Corrupted file, return fresh
+        return {
+            "version": "1.0",
+            "session": {},
+            "cache": {"git": {}},
+            "meta": {
+                "createdAt": datetime.now(timezone.utc).isoformat(),
+                "updatedAt": datetime.now(timezone.utc).isoformat(),
+            }
+        }
+
+
+def _write_state(state: Dict[str, Any]) -> None:
+    """Write state file atomically."""
+    state.setdefault("meta", {})
+    state["meta"]["updatedAt"] = datetime.now(timezone.utc).isoformat()
+    _atomic_write(STATE_FILE, state)
+
+
+def _sync_to_registry(session: Dict[str, Any]) -> None:
+    """Sync session state to agent registry for HUD visibility."""
+    if not REGISTRY_AVAILABLE:
+        return
+
+    agent_id = session.get("agentId")
+    if not agent_id:
+        return
+
+    try:
+        update_agent(
+            agent_id=agent_id,
+            phase=session.get("phase"),
+            issue=session.get("activeIssue"),
+        )
+    except Exception:
+        # Don't fail if registry update fails
+        pass
+
+
+def get_state() -> Dict[str, Any]:
+    """Get the current state.
+
+    Returns:
+        Complete state dictionary
+    """
+    return _read_state()
+
+
+def get_session() -> Dict[str, Any]:
+    """Get the session portion of state.
+
+    Returns:
+        Session dictionary with agentId, phase, activeIssue, etc.
+    """
+    state = _read_state()
+    return state.get("session", {})
+
+
+def update_state(
+    phase: Optional[str] = None,
+    active_issue: Optional[str] = None,
+    active_spec: Optional[str] = None,
+    active_plan: Optional[str] = None,
+    last_command: Optional[str] = None,
+    clear_issue: bool = False,
+) -> None:
+    """Update anvil-state.json with new values and sync to registry.
+
+    Args:
+        phase: Workflow phase (orient, explore, spec, plan, tasks, implement, verify, handoff)
+        active_issue: Linear issue key (e.g., "ANV-180") or None to clear
+        active_spec: Active spec file path or None to clear
+        active_plan: Active plan file path or None to clear
+        last_command: Name of command that triggered this update
+        clear_issue: If True, explicitly clears activeIssue (vs None meaning no change)
+
+    Example:
+        # When running /explore
+        update_state(phase="explore", last_command="/explore")
+
+        # When claiming an issue
+        update_state(active_issue="ANV-180", phase="implement")
+
+        # When starting fresh with /orient
+        update_state(phase="orient", clear_issue=True)
+    """
+    state = _read_state()
+    session = state.setdefault("session", {})
+
+    # Update fields if provided
+    if phase is not None:
+        session["phase"] = phase
+
+    if active_issue is not None:
+        session["activeIssue"] = active_issue
+    elif clear_issue:
+        session["activeIssue"] = None
+
+    if active_spec is not None:
+        session["activeSpec"] = active_spec if active_spec else None
+
+    if active_plan is not None:
+        session["activePlan"] = active_plan if active_plan else None
+
+    if last_command is not None:
+        session["lastCommand"] = last_command
+        session["lastCommandAt"] = datetime.now(timezone.utc).isoformat()
+
+    # Write state and sync to registry
+    _write_state(state)
+    _sync_to_registry(session)
+
+
+def set_issue(issue_key: str) -> None:
+    """Convenience function to set the active issue.
+
+    Args:
+        issue_key: Linear issue key (e.g., "ANV-180")
+    """
+    update_state(active_issue=issue_key)
+
+
+def clear_issue() -> None:
+    """Convenience function to clear the active issue."""
+    update_state(clear_issue=True)
+
+
+def set_phase(phase: str) -> None:
+    """Convenience function to set the workflow phase.
+
+    Args:
+        phase: Workflow phase name
+    """
+    update_state(phase=phase)
+
+
+# =============================================================================
+# Command-specific helpers
+# =============================================================================
+
+def on_orient() -> None:
+    """Called when /orient command runs."""
+    update_state(phase="orient", clear_issue=True, last_command="/orient")
+
+
+def on_explore() -> None:
+    """Called when /explore command runs."""
+    update_state(phase="explore", last_command="/explore")
+
+
+def on_spec(spec_path: Optional[str] = None) -> None:
+    """Called when /spec command runs.
+
+    Args:
+        spec_path: Path to the created spec file
+    """
+    update_state(phase="spec", active_spec=spec_path, last_command="/spec")
+
+
+def on_plan(plan_path: Optional[str] = None) -> None:
+    """Called when /plan command runs.
+
+    Args:
+        plan_path: Path to the created plan file
+    """
+    update_state(phase="plan", active_plan=plan_path, last_command="/plan")
+
+
+def on_tasks() -> None:
+    """Called when /tasks command runs."""
+    update_state(phase="tasks", last_command="/tasks")
+
+
+def on_evidence() -> None:
+    """Called when /evidence command runs."""
+    update_state(phase="verify", last_command="/evidence")
+
+
+def on_handoff() -> None:
+    """Called when /handoff command runs."""
+    update_state(phase="handoff", last_command="/handoff")
+
+
+def on_claim_issue(issue_key: str) -> None:
+    """Called when an issue is claimed from Linear.
+
+    Args:
+        issue_key: Linear issue key (e.g., "ANV-180")
+    """
+    update_state(active_issue=issue_key, phase="implement")
+
+
+def on_doc_coverage(
+    percent: float,
+    total: int,
+    documented: int,
+    status: str,
+) -> None:
+    """Called when /doc-coverage command runs.
+
+    Stores coverage snapshot for tracking over time.
+
+    Note: This function directly manipulates state rather than using update_state()
+    because doc-coverage is a reporting command (not a workflow phase change) and
+    requires storing structured data (docCoverage object) not supported by update_state().
+    Registry sync is intentionally skipped since coverage reports don't affect agent status.
+
+    Args:
+        percent: Coverage percentage (0-100)
+        total: Total number of exports
+        documented: Number of documented exports
+        status: Coverage status (healthy, warning, critical)
+    """
+    state = _read_state()
+    session = state.setdefault("session", {})
+
+    session["docCoverage"] = {
+        "percent": percent,
+        "total": total,
+        "documented": documented,
+        "status": status,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+    session["lastCommand"] = "/doc-coverage"
+    session["lastCommandAt"] = datetime.now(timezone.utc).isoformat()
+
+    _write_state(state)
+
+
+# =============================================================================
+# CLI Interface
+# =============================================================================
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 2:
+        print("Usage: state_manager.py <command> [args...]")
+        print("Commands:")
+        print("  get                    - Show current state")
+        print("  set-phase <phase>      - Set workflow phase")
+        print("  set-issue <key>        - Set active issue")
+        print("  clear-issue            - Clear active issue")
+        print("  orient                 - Run orient handler")
+        print("  explore                - Run explore handler")
+        print("  spec [path]            - Run spec handler")
+        print("  plan [path]            - Run plan handler")
+        print("  tasks                  - Run tasks handler")
+        print("  evidence               - Run evidence handler")
+        print("  handoff                - Run handoff handler")
+        print("  doc-coverage <p> <t> <d> <s> - Store coverage snapshot")
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+
+    if cmd == "get":
+        state = get_state()
+        print(json.dumps(state, indent=2))
+
+    elif cmd == "set-phase":
+        if len(sys.argv) < 3:
+            print("Error: phase required")
+            sys.exit(1)
+        set_phase(sys.argv[2])
+        print(f"Phase set to: {sys.argv[2]}")
+
+    elif cmd == "set-issue":
+        if len(sys.argv) < 3:
+            print("Error: issue key required")
+            sys.exit(1)
+        set_issue(sys.argv[2])
+        print(f"Active issue set to: {sys.argv[2]}")
+
+    elif cmd == "clear-issue":
+        clear_issue()
+        print("Active issue cleared")
+
+    elif cmd == "orient":
+        on_orient()
+        print("Orient handler executed")
+
+    elif cmd == "explore":
+        on_explore()
+        print("Explore handler executed")
+
+    elif cmd == "spec":
+        path = sys.argv[2] if len(sys.argv) > 2 else None
+        on_spec(path)
+        print(f"Spec handler executed{f' with path: {path}' if path else ''}")
+
+    elif cmd == "plan":
+        path = sys.argv[2] if len(sys.argv) > 2 else None
+        on_plan(path)
+        print(f"Plan handler executed{f' with path: {path}' if path else ''}")
+
+    elif cmd == "tasks":
+        on_tasks()
+        print("Tasks handler executed")
+
+    elif cmd == "evidence":
+        on_evidence()
+        print("Evidence handler executed")
+
+    elif cmd == "handoff":
+        on_handoff()
+        print("Handoff handler executed")
+
+    elif cmd == "doc-coverage":
+        if len(sys.argv) < 6:
+            print("Error: doc-coverage requires percent total documented status")
+            print("Usage: state_manager.py doc-coverage <percent> <total> <documented> <status>")
+            sys.exit(1)
+        on_doc_coverage(
+            percent=float(sys.argv[2]),
+            total=int(sys.argv[3]),
+            documented=int(sys.argv[4]),
+            status=sys.argv[5],
+        )
+        print(f"Doc coverage recorded: {sys.argv[2]}%")
+
+    else:
+        print(f"Unknown command: {cmd}")
+        sys.exit(1)