codeframe-ai 0.9.0__py3-none-any.whl

codeframe/notifications/webhook.py

@@ -0,0 +1,380 @@
+"""Webhook notification service.
+
+Originally built for SYNC blocker alerts (049-human-in-loop, Phase 7), now also
+powers outbound event webhooks for batch completion / blocker creation / PR
+merge (issue #560).
+
+Delivery is fire-and-forget with a configurable timeout — failures are logged
+but never break the triggering operation.
+"""
+
+import asyncio
+import logging
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Optional
+
+import aiohttp
+
+from codeframe.core.models import BlockerType
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class WebhookSendResult:
+    """Result of a single ``send_event`` call.
+
+    ``ok`` mirrors HTTP 2xx semantics. ``status_code`` is ``None`` when the
+    request never completed (timeout, DNS failure, connection refused, …) —
+    the ``error`` field carries a short human-readable reason in that case.
+    """
+
+    ok: bool
+    status_code: Optional[int]
+    error: Optional[str] = None
+
+
+def _utc_iso_now() -> str:
+    """ISO-8601 UTC timestamp for webhook payloads (``Z`` suffix).
+
+    Slack/Discord/Zapier-style consumers expect ``Z``, not ``+00:00``.
+    Drops sub-second precision for the same reason — consumers vary widely
+    in fractional-second handling.
+    """
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def format_batch_payload(batch_id: str, task_count: int) -> dict:
+    # ``status`` is always "completed" today (the dispatcher gates on
+    # BATCH_COMPLETED only) but is included so consumers can self-document
+    # and so a future PARTIAL/FAILED extension is forward-compatible.
+    return {
+        "event": "batch.completed",
+        "batch_id": batch_id,
+        "task_count": task_count,
+        "status": "completed",
+        "timestamp": _utc_iso_now(),
+    }
+
+
+def format_blocker_payload(blocker_id: str, task_id: Optional[str]) -> dict:
+    return {
+        "event": "blocker.created",
+        "blocker_id": blocker_id,
+        "task_id": task_id,
+        "timestamp": _utc_iso_now(),
+    }
+
+
+def format_pr_payload(pr_number: int, pr_url: Optional[str] = None) -> dict:
+    # ``pr_number`` is always present so consumers can branch on it.
+    # ``pr_url`` is the canonical github.com URL when GITHUB_REPO is set,
+    # ``None`` otherwise (an unparseable sentinel like ``"pr#42"`` was
+    # actively confusing for downstream handlers).
+    return {
+        "event": "pr.merged",
+        "pr_number": pr_number,
+        "pr_url": pr_url,
+        "timestamp": _utc_iso_now(),
+    }
+
+
+def format_test_payload() -> dict:
+    return {"event": "test", "timestamp": _utc_iso_now()}
+
+
+class WebhookNotificationService:
+    """Async outbound webhook service.
+
+    Originally built for SYNC blocker alerts (``send_blocker_notification``);
+    now also powers the issue #560 outbound event webhooks (batch / blocker /
+    PR / test) via ``send_event``. Delivery is fire-and-forget with a
+    configurable timeout — failures are logged but never break the triggering
+    operation.
+    """
+
+    def __init__(
+        self,
+        webhook_url: Optional[str] = None,
+        timeout: int = 5,
+        dashboard_base_url: str = "http://localhost:3000",
+    ):
+        """Initialize webhook notification service.
+
+        Args:
+            webhook_url: Target webhook endpoint URL (e.g., Zapier, webhook.site)
+            timeout: HTTP request timeout in seconds (default: 5)
+            dashboard_base_url: Base URL for dashboard links (default: http://localhost:3000)
+        """
+        self.webhook_url = webhook_url
+        self.timeout = timeout
+        self.dashboard_base_url = dashboard_base_url
+
+    def is_enabled(self) -> bool:
+        """Check if webhook notifications are enabled.
+
+        Returns:
+            True if webhook_url is configured, False otherwise
+        """
+        return self.webhook_url is not None and self.webhook_url.strip() != ""
+
+    def format_payload(
+        self,
+        blocker_id: int,
+        question: str,
+        agent_id: str,
+        task_id: int,
+        blocker_type: BlockerType,
+        created_at: datetime,
+    ) -> dict:
+        """Format webhook payload with blocker details.
+
+        Args:
+            blocker_id: Blocker database ID
+            question: Blocker question text
+            agent_id: Agent that created the blocker
+            task_id: Associated task ID
+            blocker_type: SYNC or ASYNC
+            created_at: Blocker creation timestamp
+
+        Returns:
+            Dictionary payload ready for JSON serialization
+        """
+        dashboard_url = f"{self.dashboard_base_url}/#blocker-{blocker_id}"
+
+        return {
+            "blocker_id": blocker_id,
+            "question": question,
+            "agent_id": agent_id,
+            "task_id": task_id,
+            "type": blocker_type.value,
+            "created_at": created_at.isoformat(),
+            "dashboard_url": dashboard_url,
+        }
+
+    async def send_blocker_notification(
+        self,
+        blocker_id: int,
+        question: str,
+        agent_id: str,
+        task_id: int,
+        blocker_type: BlockerType,
+        created_at: datetime,
+    ) -> bool:
+        """Send async webhook notification for a blocker.
+
+        Fire-and-forget delivery with timeout. Logs errors but doesn't block execution.
+        Only sends notifications for SYNC blockers.
+
+        Args:
+            blocker_id: Blocker database ID
+            question: Blocker question text
+            agent_id: Agent that created the blocker
+            task_id: Associated task ID
+            blocker_type: SYNC or ASYNC
+            created_at: Blocker creation timestamp
+
+        Returns:
+            True if notification sent successfully, False on failure
+        """
+        # Only send notifications for SYNC blockers
+        if blocker_type != BlockerType.SYNC:
+            logger.debug(f"Skipping webhook notification for ASYNC blocker {blocker_id}")
+            return False
+
+        # Check if webhooks are enabled
+        if not self.is_enabled():
+            logger.debug(f"Webhook notifications disabled, skipping blocker {blocker_id}")
+            return False
+
+        # Format payload
+        payload = self.format_payload(
+            blocker_id=blocker_id,
+            question=question,
+            agent_id=agent_id,
+            task_id=task_id,
+            blocker_type=blocker_type,
+            created_at=created_at,
+        )
+
+        try:
+            # Send HTTP POST with timeout
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    self.webhook_url,
+                    json=payload,
+                    timeout=aiohttp.ClientTimeout(total=self.timeout),
+                ) as response:
+                    response.raise_for_status()
+
+                    logger.info(
+                        f"Webhook notification sent for blocker {blocker_id} "
+                        f"(status: {response.status})"
+                    )
+                    return True
+
+        except asyncio.TimeoutError:
+            logger.error(
+                f"Webhook notification timeout for blocker {blocker_id} "
+                f"(exceeded {self.timeout}s)"
+            )
+            return False
+
+        except aiohttp.ClientError as e:
+            logger.error(f"Webhook notification failed for blocker {blocker_id}: {e}")
+            return False
+
+        except Exception as e:
+            logger.error(
+                f"Unexpected error sending webhook for blocker {blocker_id}: {e}", exc_info=True
+            )
+            return False
+
+    async def send_event(
+        self, payload: dict, url: Optional[str] = None
+    ) -> WebhookSendResult:
+        """Generic webhook POST for outbound event notifications (issue #560).
+
+        Unlike ``send_blocker_notification``, this method:
+
+        * Accepts an arbitrary JSON payload (the caller composes the event).
+        * Returns rich status information so the Settings ``Test`` endpoint
+          can surface the HTTP status code or error to the user.
+        * Accepts an optional ``url`` override so the same service instance
+          can dispatch to a freshly-configured URL without rebuilding state.
+
+        Failures (timeout, network, non-2xx) are logged but never raised —
+        the caller can react via the returned ``WebhookSendResult``.
+        """
+        target_url = url or self.webhook_url
+        if not target_url or not target_url.strip():
+            return WebhookSendResult(
+                ok=False, status_code=None, error="No webhook URL configured"
+            )
+
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    target_url,
+                    json=payload,
+                    timeout=aiohttp.ClientTimeout(total=self.timeout),
+                ) as response:
+                    ok = 200 <= response.status < 300
+                    if not ok:
+                        logger.warning(
+                            "Webhook returned non-2xx status %s for event %s",
+                            response.status,
+                            payload.get("event"),
+                        )
+                    return WebhookSendResult(ok=ok, status_code=response.status)
+        except asyncio.TimeoutError:
+            logger.error(
+                "Webhook timeout for event %s (exceeded %ss)",
+                payload.get("event"),
+                self.timeout,
+            )
+            return WebhookSendResult(
+                ok=False, status_code=None, error=f"Timeout after {self.timeout}s"
+            )
+        except aiohttp.ClientError as e:
+            logger.error("Webhook ClientError for event %s: %s", payload.get("event"), e)
+            return WebhookSendResult(ok=False, status_code=None, error=str(e))
+        except Exception as e:
+            logger.error(
+                "Unexpected webhook error for event %s: %s",
+                payload.get("event"),
+                e,
+                exc_info=True,
+            )
+            return WebhookSendResult(ok=False, status_code=None, error=str(e))
+
+    def send_event_background(self, payload: dict, url: Optional[str] = None) -> None:
+        """Fire-and-forget wrapper for ``send_event``.
+
+        Works in both contexts:
+
+        * **Async** (FastAPI request handler): schedules the send on the
+          current event loop via ``loop.create_task`` and returns
+          immediately.
+        * **Sync** (CLI batch run, sync test): spawns a daemon thread that
+          runs the send in a fresh event loop. The thread is daemon so it
+          never blocks process exit; ``timeout`` still applies inside the
+          loop, so the thread lives at most ``self.timeout`` seconds.
+
+        Either way, the triggering operation never blocks on webhook
+        delivery and never sees an exception from this method.
+        """
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            # No running loop — we're in sync context (CLI). Run the send
+            # in a daemon thread so we don't block the caller and so the
+            # process can exit cleanly even if the webhook hangs.
+            thread = threading.Thread(
+                target=self._run_send_event_sync,
+                args=(payload, url),
+                daemon=True,
+                name="webhook-send-event",
+            )
+            thread.start()
+            return
+        task = loop.create_task(self.send_event(payload, url=url))
+        # ``send_event`` already swallows all exceptions, but Python 3.11+
+        # warns ``Task exception was never retrieved`` if a task ends with
+        # an unhandled exception and nobody awaited / called .exception().
+        # Add a no-op callback so the result is always consumed.
+        task.add_done_callback(
+            lambda t: t.exception() if not t.cancelled() else None
+        )
+
+    def _run_send_event_sync(self, payload: dict, url: Optional[str]) -> None:
+        """Run ``send_event`` to completion in a fresh event loop.
+
+        Used only by the sync branch of ``send_event_background`` — never
+        raises into the calling thread (the daemon thread is meant to die
+        quietly).
+        """
+        try:
+            asyncio.run(self.send_event(payload, url=url))
+        except Exception:
+            logger.warning(
+                "Sync webhook dispatch failed for event %s",
+                payload.get("event"),
+                exc_info=True,
+            )
+
+    def send_blocker_notification_background(
+        self,
+        blocker_id: int,
+        question: str,
+        agent_id: str,
+        task_id: int,
+        blocker_type: BlockerType,
+        created_at: datetime,
+    ) -> None:
+        """Fire-and-forget wrapper for send_blocker_notification.
+
+        Launches notification task in background without awaiting result.
+        Use this method to avoid blocking blocker creation.
+
+        Args:
+            blocker_id: Blocker database ID
+            question: Blocker question text
+            agent_id: Agent that created the blocker
+            task_id: Associated task ID
+            blocker_type: SYNC or ASYNC
+            created_at: Blocker creation timestamp
+        """
+        # Create background task
+        asyncio.create_task(
+            self.send_blocker_notification(
+                blocker_id=blocker_id,
+                question=question,
+                agent_id=agent_id,
+                task_id=task_id,
+                blocker_type=blocker_type,
+                created_at=created_at,
+            )
+        )

codeframe/planning/__init__.py

@@ -0,0 +1,30 @@
+"""Planning module for CodeFRAME.
+
+This module handles PRD-to-Issue-to-Task decomposition:
+- Issue generation from PRD features
+- Task decomposition from issues
+- Work breakdown planning
+- PRD template system for customizable output formats
+"""
+
+from codeframe.planning.issue_generator import (
+    IssueGenerator,
+    parse_prd_features,
+    assign_priority,
+)
+from codeframe.planning.prd_templates import (
+    PrdTemplate,
+    PrdTemplateSection,
+    PrdTemplateManager,
+    BUILTIN_TEMPLATES,
+)
+
+__all__ = [
+    "IssueGenerator",
+    "parse_prd_features",
+    "assign_priority",
+    "PrdTemplate",
+    "PrdTemplateSection",
+    "PrdTemplateManager",
+    "BUILTIN_TEMPLATES",
+]

codeframe/planning/issue_generator.py

@@ -0,0 +1,219 @@
+"""Issue Generator - Extract high-level features from PRD and create Issues.
+
+This module implements the hierarchical work breakdown for CodeFRAME:
+PRD → Issues → Tasks
+
+Issues are high-level work items (e.g., "2.1", "2.2") that can parallelize.
+Each issue will later be decomposed into sequential tasks (e.g., "2.1.1", "2.1.2").
+
+Algorithm:
+1. Parse PRD markdown for "Features & Requirements" section
+2. Each major feature (### header) becomes an Issue
+3. Number issues sequentially: {sprint}.1, {sprint}.2, etc.
+4. Extract title and description from feature text
+5. Assign priority based on feature importance keywords
+6. Set status='pending', workflow_step=0
+"""
+
+import re
+import logging
+from typing import List, Dict, Any
+from codeframe.core.models import Issue, TaskStatus
+
+
+logger = logging.getLogger(__name__)
+
+
+def parse_prd_features(prd_content: str) -> List[Dict[str, Any]]:
+    """Parse PRD markdown and extract features from Features & Requirements section.
+
+    Args:
+        prd_content: Full PRD content as markdown string
+
+    Returns:
+        List of feature dictionaries with 'title', 'description', and 'raw_text'
+    """
+    if not prd_content or not prd_content.strip():
+        logger.warning("Empty PRD content provided")
+        return []
+
+    features = []
+
+    # Find the Features & Requirements section
+    # Look for ## Features & Requirements, then capture everything until next ## or end
+    features_section_pattern = r"##\s+Features\s*&\s*Requirements(.*?)(?=\n##[^#]|\Z)"
+    features_match = re.search(features_section_pattern, prd_content, re.IGNORECASE | re.DOTALL)
+
+    if not features_match:
+        logger.warning("No 'Features & Requirements' section found in PRD")
+        return []
+
+    features_section = features_match.group(1).strip()
+
+    # Extract individual features using ### headers (but not #### or deeper)
+    # Match ### followed by title, then capture everything until next ### or end of section
+    # Use negative lookahead to ensure we don't match #### or more
+    feature_pattern = r"###(?!#)\s+([^\n]+)\n(.*?)(?=\n###(?!#)|\Z)"
+    feature_matches = re.finditer(feature_pattern, features_section, re.DOTALL)
+
+    for match in feature_matches:
+        raw_title = match.group(1).strip()
+        description = match.group(2).strip()
+
+        # Remove priority keywords from title (Critical:, High:, etc.)
+        title = re.sub(r"^(Critical|High|Medium|Low)\s*:\s*", "", raw_title, flags=re.IGNORECASE)
+
+        features.append(
+            {
+                "title": title.strip(),
+                "description": description.strip(),
+                "raw_text": raw_title + "\n" + description,  # Keep original for priority detection
+            }
+        )
+
+    logger.info(f"Extracted {len(features)} features from PRD")
+    return features
+
+
+def assign_priority(text: str) -> int:
+    """Assign priority based on keywords in text.
+
+    Priority levels:
+    - 0: Critical
+    - 1: High
+    - 2: Medium (default)
+    - 3: Low
+    - 4: Nice-to-have
+
+    Args:
+        text: Feature text to analyze for priority keywords
+
+    Returns:
+        Priority level (0-4)
+    """
+    text_lower = text.lower()
+
+    # Check for priority keywords (case-insensitive, first match wins)
+    if "critical" in text_lower or "urgent" in text_lower or "must have" in text_lower:
+        return 0
+    elif "high" in text_lower or "important" in text_lower:
+        return 1
+    elif "low" in text_lower or "optional" in text_lower:
+        return 3
+    elif "nice to have" in text_lower or "nice-to-have" in text_lower:
+        return 4
+    else:
+        # Default to medium priority
+        return 2
+
+
+class IssueGenerator:
+    """Generator for creating Issues from PRD features."""
+
+    def __init__(self):
+        """Initialize the issue generator."""
+        self.logger = logging.getLogger(__name__)
+
+    def generate_issues_from_prd(self, prd_content: str, sprint_number: int) -> List[Issue]:
+        """Generate issues from PRD content.
+
+        Main entry point for issue generation. Parses PRD, creates issues,
+        validates them, and returns the list.
+
+        Args:
+            prd_content: Full PRD markdown content
+            sprint_number: Sprint number for issue numbering (e.g., 2 for Sprint 2)
+
+        Returns:
+            List of Issue objects with sequential numbering
+        """
+        self.logger.info(f"Generating issues from PRD for sprint {sprint_number}")
+
+        # Parse features from PRD
+        features = parse_prd_features(prd_content)
+
+        if not features:
+            self.logger.warning("No features found in PRD, returning empty list")
+            return []
+
+        # Create issues from features
+        issues = self._create_issues(features, sprint_number)
+
+        # Validate all issues
+        for issue in issues:
+            self._validate_issue(issue)
+
+        self.logger.info(f"Generated {len(issues)} issues successfully")
+        return issues
+
+    def _create_issues(self, features: List[Dict[str, Any]], sprint_number: int) -> List[Issue]:
+        """Create Issue objects from parsed features.
+
+        Args:
+            features: List of feature dictionaries from parse_prd_features()
+            sprint_number: Sprint number for issue numbering
+
+        Returns:
+            List of Issue objects
+        """
+        issues = []
+
+        for idx, feature in enumerate(features, start=1):
+            # Generate issue number: {sprint}.{idx}
+            issue_number = f"{sprint_number}.{idx}"
+
+            # Assign priority based on raw text (includes keywords)
+            priority = assign_priority(feature["raw_text"])
+
+            # Create issue
+            issue = Issue(
+                issue_number=issue_number,
+                title=feature["title"],
+                description=feature["description"],
+                priority=priority,
+                status=TaskStatus.PENDING,
+                workflow_step=0,
+            )
+
+            issues.append(issue)
+            self.logger.debug(
+                f"Created issue {issue_number}: {feature['title']} (priority={priority})"
+            )
+
+        return issues
+
+    def _validate_issue(self, issue: Issue) -> None:
+        """Validate issue meets requirements.
+
+        Args:
+            issue: Issue to validate
+
+        Raises:
+            ValueError: If issue is invalid
+        """
+        # Validate title
+        if not issue.title or not issue.title.strip():
+            raise ValueError(f"Issue {issue.issue_number} must have a title")
+
+        # Validate issue number format (X.Y)
+        issue_number_pattern = r"^\d+\.\d+$"
+        if not re.match(issue_number_pattern, issue.issue_number):
+            raise ValueError(
+                f"Issue number '{issue.issue_number}' must match format X.Y "
+                f"(e.g., '2.1', '3.5')"
+            )
+
+        # Validate priority range
+        if not (0 <= issue.priority <= 4):
+            raise ValueError(
+                f"Issue {issue.issue_number} priority must be 0-4, got {issue.priority}"
+            )
+
+        # Validate status
+        if not isinstance(issue.status, TaskStatus):
+            raise ValueError(
+                f"Issue {issue.issue_number} status must be TaskStatus enum, "
+                f"got {type(issue.status)}"
+            )
+
+        self.logger.debug(f"Validated issue {issue.issue_number}")