anvil-dev-framework 0.1.7 → 0.1.9

package/global/lib/ralph_webhooks.py

@@ -0,0 +1,470 @@
+#!/usr/bin/env python3
+"""
+ralph_webhooks.py - Webhook Integration for Ralph Notifications (ANV-304, ANV-305, ANV-306)
+
+Sends Ralph events to external webhook endpoints (Slack, Discord).
+
+Usage:
+    python3 ralph_webhooks.py --dispatch              # Dispatch pending events
+    python3 ralph_webhooks.py --test-slack URL        # Test Slack webhook
+    python3 ralph_webhooks.py --test-discord URL      # Test Discord webhook
+"""
+
+import json
+import os
+import time
+import urllib.request
+import urllib.error
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+DEFAULT_CONFIG_PATH = os.path.expanduser("~/.anvil/notifications.yaml")
+PROJECT_CONFIG_PATH = ".anvil/notifications.yaml"
+DEFAULT_EVENTS_DIR = os.path.expanduser("~/.anvil/events")
+WEBHOOK_STATE_FILE = os.path.expanduser("~/.anvil/events/.webhook-state.json")
+
+# Rate limiting
+MIN_REQUEST_INTERVAL = 1.0  # seconds between requests
+MAX_RETRIES = 3
+RETRY_DELAY = 2.0
+
+
+# =============================================================================
+# Configuration Data Classes
+# =============================================================================
+
+@dataclass
+class SlackConfig:
+    enabled: bool = False
+    webhook_url: str = ""
+    events: List[str] = field(default_factory=lambda: [
+        "session_complete", "error_occurred"
+    ])
+    mention_on_error: bool = True
+    channel_override: str = ""
+
+
+@dataclass
+class DiscordConfig:
+    enabled: bool = False
+    webhook_url: str = ""
+    events: List[str] = field(default_factory=lambda: [
+        "session_complete", "error_occurred"
+    ])
+    mention_role: str = ""
+
+
+@dataclass
+class WebhookConfig:
+    slack: SlackConfig = field(default_factory=SlackConfig)
+    discord: DiscordConfig = field(default_factory=DiscordConfig)
+
+    @classmethod
+    def load(cls) -> "WebhookConfig":
+        config = cls()
+        for config_path in [PROJECT_CONFIG_PATH, DEFAULT_CONFIG_PATH]:
+            if Path(config_path).exists():
+                try:
+                    import yaml
+                    with open(config_path) as f:
+                        data = yaml.safe_load(f)
+                    if data and "notifications" in data:
+                        channels = data["notifications"].get("channels", {})
+
+                        if "slack" in channels:
+                            slack = channels["slack"]
+                            config.slack.enabled = slack.get("enabled", False)
+                            config.slack.webhook_url = os.path.expandvars(
+                                slack.get("webhook_url", "")
+                            )
+                            config.slack.events = slack.get("events", config.slack.events)
+                            config.slack.mention_on_error = slack.get("mention_on_error", True)
+
+                        if "discord" in channels:
+                            discord = channels["discord"]
+                            config.discord.enabled = discord.get("enabled", False)
+                            config.discord.webhook_url = os.path.expandvars(
+                                discord.get("webhook_url", "")
+                            )
+                            config.discord.events = discord.get("events", config.discord.events)
+                            config.discord.mention_role = discord.get("mention_role", "")
+                        break
+                except ImportError:
+                    pass
+                except Exception:
+                    pass
+        return config
+
+
+# =============================================================================
+# Webhook State Management
+# =============================================================================
+
+@dataclass
+class WebhookState:
+    last_request_time: float = 0.0
+    dispatched_event_ids: List[str] = field(default_factory=list)
+
+    @classmethod
+    def load(cls) -> "WebhookState":
+        if not Path(WEBHOOK_STATE_FILE).exists():
+            return cls()
+        try:
+            with open(WEBHOOK_STATE_FILE) as f:
+                data = json.load(f)
+            return cls(
+                last_request_time=data.get("last_request_time", 0.0),
+                dispatched_event_ids=data.get("dispatched_event_ids", [])[-200:],
+            )
+        except Exception:
+            return cls()
+
+    def save(self) -> None:
+        Path(WEBHOOK_STATE_FILE).parent.mkdir(parents=True, exist_ok=True)
+        with open(WEBHOOK_STATE_FILE, "w") as f:
+            json.dump({
+                "last_request_time": self.last_request_time,
+                "dispatched_event_ids": self.dispatched_event_ids[-200:],
+            }, f, indent=2)
+
+    def mark_dispatched(self, event_id: str) -> None:
+        self.dispatched_event_ids.append(event_id)
+        self.last_request_time = time.time()
+
+    def is_dispatched(self, event_id: str) -> bool:
+        return event_id in self.dispatched_event_ids
+
+    def wait_for_rate_limit(self) -> None:
+        elapsed = time.time() - self.last_request_time
+        if elapsed < MIN_REQUEST_INTERVAL:
+            time.sleep(MIN_REQUEST_INTERVAL - elapsed)
+
+
+# =============================================================================
+# HTTP Utilities
+# =============================================================================
+
+def send_webhook(url: str, payload: Dict, retries: int = MAX_RETRIES) -> bool:
+    """Send a webhook request with retry logic."""
+    data = json.dumps(payload).encode("utf-8")
+    headers = {"Content-Type": "application/json"}
+
+    for attempt in range(retries):
+        try:
+            req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+            with urllib.request.urlopen(req, timeout=10) as response:
+                return response.status in (200, 201, 204)
+        except urllib.error.HTTPError as e:
+            if e.code == 429:  # Rate limited
+                time.sleep(RETRY_DELAY * (attempt + 1))
+                continue
+            if attempt == retries - 1:
+                return False
+        except Exception:
+            if attempt == retries - 1:
+                return False
+            time.sleep(RETRY_DELAY)
+
+    return False
+
+
+# =============================================================================
+# Slack Formatting
+# =============================================================================
+
+def format_slack_message(event: Dict) -> Dict:
+    """Format event as Slack Block Kit message."""
+    event_type = event.get("event_type", "")
+    progress = event.get("progress", {})
+    payload = event.get("payload", {})
+    task_name = event.get("task_name", "Unknown")
+    completed = progress.get("completed", 0)
+    total = progress.get("total", 0)
+    percent = progress.get("percent", 0)
+
+    # Status emoji
+    emoji_map = {
+        "session_started": ":rocket:",
+        "subtask_complete": ":white_check_mark:",
+        "session_complete": ":tada:",
+        "error_occurred": ":x:",
+        "circuit_breaker": ":warning:",
+    }
+    emoji = emoji_map.get(event_type, ":robot_face:")
+
+    # Build blocks
+    blocks = []
+
+    # Header
+    if event_type == "session_complete":
+        status = payload.get("final_status", "completed")
+        if status == "completed":
+            header_text = f"{emoji} Ralph Session Complete!"
+        else:
+            header_text = f"{emoji} Ralph Session Ended: {status}"
+    elif event_type == "subtask_complete":
+        subtask_id = payload.get("subtask_identifier", "")
+        header_text = f"{emoji} Subtask Complete: {subtask_id}"
+    elif event_type == "error_occurred":
+        header_text = f"{emoji} Ralph Error"
+    elif event_type == "session_started":
+        header_text = f"{emoji} Ralph Session Started"
+    else:
+        header_text = f"{emoji} Ralph: {event_type}"
+
+    blocks.append({
+        "type": "header",
+        "text": {"type": "plain_text", "text": header_text, "emoji": True}
+    })
+
+    # Task info
+    blocks.append({
+        "type": "section",
+        "fields": [
+            {"type": "mrkdwn", "text": f"*Task:*\n{task_name}"},
+            {"type": "mrkdwn", "text": f"*Progress:*\n{completed}/{total} ({percent:.0f}%)"},
+        ]
+    })
+
+    # Progress bar
+    if total > 0:
+        filled = int(20 * completed / total)
+        bar = "█" * filled + "░" * (20 - filled)
+        blocks.append({
+            "type": "section",
+            "text": {"type": "mrkdwn", "text": f"`{bar}`"}
+        })
+
+    # Error details
+    if event_type == "error_occurred":
+        error_msg = payload.get("message", "Unknown error")
+        blocks.append({
+            "type": "section",
+            "text": {"type": "mrkdwn", "text": f"*Error:*\n```{error_msg}```"}
+        })
+
+    # Linear link if available
+    linear = event.get("linear", {})
+    if linear and linear.get("url"):
+        blocks.append({
+            "type": "context",
+            "elements": [
+                {"type": "mrkdwn", "text": f"<{linear['url']}|View in Linear>"}
+            ]
+        })
+
+    # Timestamp
+    blocks.append({
+        "type": "context",
+        "elements": [
+            {"type": "mrkdwn", "text": f"_{event.get('timestamp', '')[:19]}_"}
+        ]
+    })
+
+    return {"blocks": blocks}
+
+
+# =============================================================================
+# Discord Formatting
+# =============================================================================
+
+def format_discord_message(event: Dict) -> Dict:
+    """Format event as Discord embed message."""
+    event_type = event.get("event_type", "")
+    progress = event.get("progress", {})
+    payload = event.get("payload", {})
+    task_name = event.get("task_name", "Unknown")
+    completed = progress.get("completed", 0)
+    total = progress.get("total", 0)
+    percent = progress.get("percent", 0)
+
+    # Color by event type
+    color_map = {
+        "session_started": 0x3498DB,  # Blue
+        "subtask_complete": 0x2ECC71,  # Green
+        "session_complete": 0x9B59B6,  # Purple
+        "error_occurred": 0xE74C3C,    # Red
+        "circuit_breaker": 0xF39C12,   # Orange
+    }
+    color = color_map.get(event_type, 0x95A5A6)
+
+    # Build embed
+    if event_type == "session_complete":
+        status = payload.get("final_status", "completed")
+        title = f"🏁 Ralph Session {'Complete' if status == 'completed' else 'Ended'}"
+    elif event_type == "subtask_complete":
+        subtask_id = payload.get("subtask_identifier", "")
+        title = f"✅ Subtask Complete: {subtask_id}"
+    elif event_type == "error_occurred":
+        title = "❌ Ralph Error"
+    elif event_type == "session_started":
+        title = "🚀 Ralph Session Started"
+    else:
+        title = f"🤖 Ralph: {event_type}"
+
+    # Progress bar
+    if total > 0:
+        filled = int(10 * completed / total)
+        bar = "█" * filled + "░" * (10 - filled)
+        progress_text = f"`{bar}` {completed}/{total} ({percent:.0f}%)"
+    else:
+        progress_text = "No progress data"
+
+    embed = {
+        "title": title,
+        "color": color,
+        "fields": [
+            {"name": "Task", "value": task_name[:100], "inline": True},
+            {"name": "Progress", "value": progress_text, "inline": True},
+        ],
+        "timestamp": event.get("timestamp", datetime.now(timezone.utc).isoformat()),
+    }
+
+    # Error details
+    if event_type == "error_occurred":
+        error_msg = payload.get("message", "Unknown error")[:500]
+        embed["fields"].append({
+            "name": "Error",
+            "value": f"```{error_msg}```",
+            "inline": False
+        })
+
+    # Linear link
+    linear = event.get("linear", {})
+    if linear and linear.get("url"):
+        embed["url"] = linear["url"]
+
+    return {"embeds": [embed]}
+
+
+# =============================================================================
+# Webhook Dispatcher
+# =============================================================================
+
+class WebhookDispatcher:
+    def __init__(self, config: Optional[WebhookConfig] = None):
+        self.config = config or WebhookConfig.load()
+        self.state = WebhookState.load()
+
+    def dispatch_event(self, event: Dict) -> Dict[str, bool]:
+        event_type = event.get("event_type", "")
+        event_id = event.get("event_id", "")
+
+        if event_id and self.state.is_dispatched(event_id):
+            return {}
+
+        results = {}
+
+        # Slack
+        if self.config.slack.enabled and self.config.slack.webhook_url:
+            if event_type in self.config.slack.events:
+                self.state.wait_for_rate_limit()
+                payload = format_slack_message(event)
+                results["slack"] = send_webhook(self.config.slack.webhook_url, payload)
+                self.state.last_request_time = time.time()
+
+        # Discord
+        if self.config.discord.enabled and self.config.discord.webhook_url:
+            if event_type in self.config.discord.events:
+                self.state.wait_for_rate_limit()
+                payload = format_discord_message(event)
+                results["discord"] = send_webhook(self.config.discord.webhook_url, payload)
+                self.state.last_request_time = time.time()
+
+        if event_id:
+            self.state.mark_dispatched(event_id)
+            self.state.save()
+
+        return results
+
+    def dispatch_pending(self) -> int:
+        events_file = Path(DEFAULT_EVENTS_DIR) / "current-session.jsonl"
+        if not events_file.exists():
+            return 0
+
+        events = []
+        with open(events_file) as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        events.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        continue
+
+        dispatched = 0
+        for event in events:
+            event_id = event.get("event_id", "")
+            if not self.state.is_dispatched(event_id):
+                results = self.dispatch_event(event)
+                if results:
+                    dispatched += 1
+
+        return dispatched
+
+
+# =============================================================================
+# CLI Entry Point
+# =============================================================================
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="Ralph Webhook Dispatcher")
+    parser.add_argument("--dispatch", action="store_true", help="Dispatch pending events")
+    parser.add_argument("--test-slack", metavar="URL", help="Test Slack webhook")
+    parser.add_argument("--test-discord", metavar="URL", help="Test Discord webhook")
+    parser.add_argument("--config", action="store_true", help="Show configuration")
+    args = parser.parse_args()
+
+    if args.config:
+        config = WebhookConfig.load()
+        print(f"Slack: enabled={config.slack.enabled}, url={'set' if config.slack.webhook_url else 'not set'}")
+        print(f"Discord: enabled={config.discord.enabled}, url={'set' if config.discord.webhook_url else 'not set'}")
+        return
+
+    if args.test_slack:
+        test_event = {
+            "event_id": "test-slack",
+            "event_type": "session_complete",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "task_name": "Webhook Test",
+            "progress": {"completed": 5, "total": 5, "percent": 100},
+            "payload": {"final_status": "completed"},
+        }
+        payload = format_slack_message(test_event)
+        success = send_webhook(args.test_slack, payload)
+        print(f"Slack webhook: {'sent' if success else 'failed'}")
+        return
+
+    if args.test_discord:
+        test_event = {
+            "event_id": "test-discord",
+            "event_type": "session_complete",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "task_name": "Webhook Test",
+            "progress": {"completed": 5, "total": 5, "percent": 100},
+            "payload": {"final_status": "completed"},
+        }
+        payload = format_discord_message(test_event)
+        success = send_webhook(args.test_discord, payload)
+        print(f"Discord webhook: {'sent' if success else 'failed'}")
+        return
+
+    if args.dispatch:
+        dispatcher = WebhookDispatcher()
+        count = dispatcher.dispatch_pending()
+        print(f"Dispatched {count} event(s) to webhooks")
+        return
+
+    parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

package/global/lib/state_manager.py

@@ -321,6 +321,91 @@ def on_doc_coverage(
     _write_state(state)
 
 
+def on_code_review(
+    issue_count: int,
+    result: str,
+    tool: str = "coderabbit",
+) -> None:
+    """Called when code review runs (from /evidence or /coderabbit-fix).
+
+    Stores review results for statusline display.
+
+    Note: This function directly manipulates state rather than using update_state()
+    because code review is a quality gate (not a workflow phase change) and
+    requires storing structured data (codeReview object) not supported by update_state().
+    Registry sync is intentionally skipped since review status is project-local.
+
+    Args:
+        issue_count: Number of issues found (0 = clean review)
+        result: Review result status (pass, issues, error)
+        tool: Review tool name (default: coderabbit)
+    """
+    state = _read_state()
+
+    state["codeReview"] = {
+        "issueCount": issue_count,
+        "lastResult": result,
+        "tool": tool,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+
+    _write_state(state)
+
+
+def clear_code_review() -> None:
+    """Clear code review data from state.
+
+    Called when starting fresh work to remove stale review indicators.
+    """
+    state = _read_state()
+
+    if "codeReview" in state:
+        del state["codeReview"]
+        _write_state(state)
+
+
+def on_pr_created(
+    url: str,
+    number: str,
+) -> None:
+    """Called when a PR is created (from PostToolUse hook or /commit-push-pr).
+
+    Stores PR info for statusline and workflow tracking.
+
+    Args:
+        url: Full GitHub PR URL
+        number: PR number
+    """
+    state = _read_state()
+    session = state.setdefault("session", {})
+
+    state["prCreation"] = {
+        "url": url,
+        "number": number,
+        "createdAt": datetime.now(timezone.utc).isoformat(),
+    }
+
+    # Also update session phase to "review"
+    session["phase"] = "review"
+    session["lastCommand"] = "gh pr create"
+    session["lastCommandAt"] = datetime.now(timezone.utc).isoformat()
+
+    _write_state(state)
+    _sync_to_registry(session)
+
+
+def clear_pr_creation() -> None:
+    """Clear PR creation data from state.
+
+    Called when starting fresh work or after PR is merged.
+    """
+    state = _read_state()
+
+    if "prCreation" in state:
+        del state["prCreation"]
+        _write_state(state)
+
+
 # =============================================================================
 # CLI Interface
 # =============================================================================
@@ -343,6 +428,10 @@ if __name__ == "__main__":
         print("  evidence               - Run evidence handler")
         print("  handoff                - Run handoff handler")
         print("  doc-coverage <p> <t> <d> <s> - Store coverage snapshot")
+        print("  code-review <count> <result> - Store code review result")
+        print("  clear-code-review            - Clear code review data")
+        print("  pr-created <url> <number>    - Store PR creation info")
+        print("  clear-pr-creation            - Clear PR creation data")
         sys.exit(1)
 
     cmd = sys.argv[1]
@@ -412,6 +501,38 @@ if __name__ == "__main__":
         )
         print(f"Doc coverage recorded: {sys.argv[2]}%")
 
+    elif cmd == "code-review":
+        if len(sys.argv) < 4:
+            print("Error: code-review requires count and result")
+            print("Usage: state_manager.py code-review <count> <result>")
+            print("  count: Number of issues found (0 = clean)")
+            print("  result: pass, issues, or error")
+            sys.exit(1)
+        on_code_review(
+            issue_count=int(sys.argv[2]),
+            result=sys.argv[3],
+        )
+        print(f"Code review recorded: {sys.argv[2]} issues ({sys.argv[3]})")
+
+    elif cmd == "clear-code-review":
+        clear_code_review()
+        print("Code review data cleared")
+
+    elif cmd == "pr-created":
+        if len(sys.argv) < 4:
+            print("Error: pr-created requires url and number")
+            print("Usage: state_manager.py pr-created <url> <number>")
+            sys.exit(1)
+        on_pr_created(
+            url=sys.argv[2],
+            number=sys.argv[3],
+        )
+        print(f"PR creation recorded: #{sys.argv[3]}")
+
+    elif cmd == "clear-pr-creation":
+        clear_pr_creation()
+        print("PR creation data cleared")
+
     else:
         print(f"Unknown command: {cmd}")
         sys.exit(1)