patchi 0.7.5__py3-none-any.whl

patchi/core/notifications/channels.py

@@ -0,0 +1,192 @@
+"""
+Channel configuration models and Apprise URL builders for Patchi notifications.
+
+Each channel type stores its config in the project's config.json under the
+`notifications` list as a plain dict. This module converts those dicts to
+validated models and builds the Apprise URL strings required to send alerts.
+
+Supported types: email, slack, discord, webhook, telegram
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+from urllib.parse import quote
+
+
+class ChannelType(StrEnum):
+    EMAIL = "email"
+    SLACK = "slack"
+    DISCORD = "discord"
+    WEBHOOK = "webhook"
+    TELEGRAM = "telegram"
+
+
+# Severity levels that each channel is willing to receive.
+# Channels with min_severity="high" skip MEDIUM/LOW alerts.
+_SEVERITY_RANK: dict[str, int] = {
+    "critical": 0,
+    "high": 1,
+    "medium": 2,
+    "low": 3,
+    "info": 4,
+}
+
+
+@dataclass
+class ChannelConfig:
+    """Parsed, validated representation of one entry in config `notifications`."""
+
+    name: str
+    channel_type: ChannelType
+    apprise_url: str  # ready-to-use Apprise URL
+    min_severity: str = "medium"  # alerts below this rank are skipped
+    in_digest: bool = False  # if True, always batch regardless of severity
+
+    def accepts_severity(self, severity: str) -> bool:
+        """Return True if this channel should receive an alert at the given severity."""
+        channel_rank = _SEVERITY_RANK.get(self.min_severity, 2)
+        alert_rank = _SEVERITY_RANK.get(severity, 4)
+        return alert_rank <= channel_rank
+
+
+# ── Apprise URL builders ───────────────────────────────────────────────────────
+
+
+def _build_email_url(cfg: dict) -> str:
+    """
+    Build an Apprise mailto:// URL from email config dict.
+    Required keys: user, password, host
+    Optional: port, to, from_addr, secure (bool)
+    """
+    user = cfg["user"]
+    password = quote(cfg["password"], safe="")
+    host = cfg["host"]
+    port = cfg.get("port", "")
+    to = cfg.get("to", user)
+    secure = cfg.get("secure", True)
+    schema = "mailtos" if secure else "mailto"
+    port_str = f":{port}" if port else ""
+    return f"{schema}://{user}:{password}@{host}{port_str}?to={quote(to, safe='@.')}"
+
+
+def _build_slack_url(cfg: dict) -> str:
+    """
+    Build an Apprise slack:// URL.
+    Accepts either a raw webhook URL (webhook_url key) or
+    tokenA/tokenB/tokenC format (token_a, token_b, token_c keys).
+    """
+    if "webhook_url" in cfg:
+        # Slack incoming webhook — extract path tokens from URL
+        # Format: https://hooks.slack.com/services/T.../B.../xxx
+        path = cfg["webhook_url"].split("hooks.slack.com/services/")[-1]
+        parts = path.strip("/").split("/")
+        if len(parts) == 3:
+            return f"slack://{parts[0]}/{parts[1]}/{parts[2]}"
+        # Non-standard — pass raw URL through Apprise's https:// handler
+        return cfg["webhook_url"]
+    return "slack://{token_a}/{token_b}/{token_c}".format(**cfg)
+
+
+def _build_discord_url(cfg: dict) -> str:
+    """
+    Build an Apprise discord:// URL.
+    Required: webhook_id, webhook_token
+    (Discord webhook URL format: .../webhooks/{id}/{token})
+    """
+    if "webhook_url" in cfg:
+        parts = cfg["webhook_url"].rstrip("/").split("/")
+        # Last two segments are id and token
+        return f"discord://{parts[-2]}/{parts[-1]}"
+    return "discord://{webhook_id}/{webhook_token}".format(**cfg)
+
+
+def _build_webhook_url(cfg: dict) -> str:
+    """
+    Custom HTTP webhook — just pass the URL through directly.
+    Apprise supports json:// and xml:// schemas; plain https:// also works.
+    """
+    url = cfg["url"]
+    # If already an apprise-style schema, use as-is
+    if any(url.startswith(s) for s in ("json://", "xml://", "form://")):
+        return url
+    # Convert plain https:// to json:// so Apprise sends JSON body
+    return url.replace("https://", "json://", 1).replace("http://", "json://", 1)
+
+
+def _build_telegram_url(cfg: dict) -> str:
+    """
+    Build an Apprise tgram:// URL.
+    Required: bot_token, chat_id
+    """
+    return "tgram://{bot_token}/{chat_id}".format(**cfg)
+
+
+_URL_BUILDERS = {
+    ChannelType.EMAIL: _build_email_url,
+    ChannelType.SLACK: _build_slack_url,
+    ChannelType.DISCORD: _build_discord_url,
+    ChannelType.WEBHOOK: _build_webhook_url,
+    ChannelType.TELEGRAM: _build_telegram_url,
+}
+
+
+# ── Public API ─────────────────────────────────────────────────────────────────
+
+
+def from_config(raw: dict) -> ChannelConfig:
+    """
+    Parse one raw dict from config `notifications` list into a ChannelConfig.
+    Raises ValueError for missing required fields or unknown channel type.
+    """
+    try:
+        channel_type = ChannelType(raw["type"])
+    except (KeyError, ValueError) as exc:
+        valid = ", ".join(t.value for t in ChannelType)
+        raise ValueError(f"Channel type must be one of: {valid}") from exc
+
+    if "name" not in raw:
+        raise ValueError("Channel config missing required key: name")
+
+    builder = _URL_BUILDERS[channel_type]
+    try:
+        apprise_url = builder(raw.get("credentials", raw))
+    except KeyError as exc:
+        raise ValueError(
+            f"Channel '{raw['name']}' ({channel_type.value}) missing required field: {exc}"
+        ) from exc
+
+    return ChannelConfig(
+        name=raw["name"],
+        channel_type=channel_type,
+        apprise_url=apprise_url,
+        min_severity=raw.get("min_severity", "medium"),
+        in_digest=raw.get("in_digest", False),
+    )
+
+
+def load_channels(config: dict) -> list[ChannelConfig]:
+    """
+    Load and validate all channels from a config dict.
+    Skips entries that fail validation (logs name for debugging).
+    """
+    channels: list[ChannelConfig] = []
+    for raw in config.get("notifications", []):
+        try:
+            channels.append(from_config(raw))
+        except ValueError:
+            # Corrupt/incomplete entry — skip silently in runtime, surface in `p notify list`
+            pass
+    return channels
+
+
+def channel_to_dict(ch: ChannelConfig) -> dict[str, Any]:
+    """Serialise a ChannelConfig back for display (never exposes the full apprise_url)."""
+    return {
+        "name": ch.name,
+        "type": ch.channel_type.value,
+        "min_severity": ch.min_severity,
+        "in_digest": ch.in_digest,
+    }

patchi/core/notifications/digest.py

@@ -0,0 +1,141 @@
+"""
+Digest queue for Patchi notifications.
+
+MEDIUM, LOW, and INFO alerts are batched here instead of firing immediately.
+The queue persists to .patchi/digest.json so alerts survive restarts.
+Flushing sends all queued alerts as a single digest notification per channel.
+
+Flush is triggered either:
+  - Manually via `p notify flush`
+  - Automatically when Notifier.send() is called and the digest window has elapsed
+"""
+
+from __future__ import annotations
+
+import json
+import time as _time
+from pathlib import Path
+from typing import Any
+
+# Severities that feed the digest queue (not immediate)
+DIGEST_SEVERITIES: frozenset[str] = frozenset({"medium", "low", "info"})
+
+# Frequency → seconds mapping
+_FREQUENCY_SECONDS: dict[str, int] = {
+    "hourly": 3600,
+    "6h": 21600,
+    "daily": 86400,
+    "weekly": 604800,
+}
+
+_DIGEST_FILE = ".patchi/digest.json"
+
+
+def _load_queue(root: Path) -> dict:
+    path = root / _DIGEST_FILE
+    if not path.exists():
+        return {"items": [], "last_flushed": 0.0}
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {"items": [], "last_flushed": 0.0}
+
+
+def _save_queue(root: Path, data: dict) -> None:
+    path = root / _DIGEST_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+
+
+def _frequency_to_seconds(frequency: str) -> int:
+    return _FREQUENCY_SECONDS.get(frequency, _FREQUENCY_SECONDS["daily"])
+
+
+class DigestQueue:
+    """
+    Persistent queue for batched (MEDIUM/LOW/INFO) notifications.
+
+    Usage:
+        dq = DigestQueue(project_root)
+        dq.enqueue("medium", "Title", "Body text")
+        if dq.should_flush(digest_frequency):
+            items = dq.flush(channels)   # returns list of (channel, message) tuples
+    """
+
+    def __init__(self, root: Path) -> None:
+        self._root = root
+
+    def enqueue(self, severity: str, title: str, body: str, data: dict | None = None) -> None:
+        """Add one alert to the persistent queue."""
+        queue = _load_queue(self._root)
+        queue["items"].append(
+            {
+                "severity": severity,
+                "title": title,
+                "body": body,
+                "data": data or {},
+                "queued_at": _time.time(),
+            }
+        )
+        _save_queue(self._root, queue)
+
+    def should_flush(self, frequency: str) -> bool:
+        """Return True if enough time has elapsed since the last flush."""
+        queue = _load_queue(self._root)
+        elapsed = _time.time() - queue.get("last_flushed", 0.0)
+        interval = _frequency_to_seconds(frequency)
+        return elapsed >= interval
+
+    def flush(self) -> list[dict[str, Any]]:
+        """
+        Drain the queue and return all pending items.
+        Resets the queue and updates last_flushed timestamp.
+        Returns an empty list if nothing was queued.
+        """
+        queue = _load_queue(self._root)
+        items = queue.get("items", [])
+        if not items:
+            return []
+        _save_queue(self._root, {"items": [], "last_flushed": _time.time()})
+        return items
+
+    def peek(self) -> list[dict[str, Any]]:
+        """Return queued items without draining."""
+        return _load_queue(self._root).get("items", [])
+
+    def clear(self) -> int:
+        """Remove all queued items without sending. Returns count cleared."""
+        queue = _load_queue(self._root)
+        count = len(queue.get("items", []))
+        _save_queue(self._root, {"items": [], "last_flushed": _time.time()})
+        return count
+
+    @staticmethod
+    def build_digest_body(items: list[dict]) -> str:
+        """
+        Render a human-readable digest body from a list of queued items.
+        Groups by severity, most critical first.
+        """
+        if not items:
+            return "No alerts."
+
+        order = ["medium", "low", "info"]
+        grouped: dict[str, list[dict]] = {s: [] for s in order}
+        for item in items:
+            sev = item.get("severity", "info")
+            if sev in grouped:
+                grouped[sev].append(item)
+
+        lines: list[str] = [f"Patchi digest — {len(items)} alert(s)\n"]
+        labels = {"medium": "⚠ Medium", "low": "✓ Low", "info": "ℹ Info"}
+        for sev in order:
+            group = grouped[sev]
+            if not group:
+                continue
+            lines.append(f"\n{labels[sev]} ({len(group)})")
+            for item in group:
+                lines.append(f"  • {item['title']}: {item['body']}")
+
+        return "\n".join(lines)

patchi/core/notifications/escalation.py

@@ -0,0 +1,158 @@
+"""
+Escalation tracking for CRITICAL and HIGH Patchi alerts.
+
+When an alert fires, it is registered here with a unique ID.
+If the user does not acknowledge it within the configured window,
+escalation fires to the next channel in the notification list.
+
+Ack store persists to .patchi/escalation.json.
+`p notify ack [id]` calls EscalationTracker.acknowledge(id).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time as _time
+from pathlib import Path
+from typing import Any
+
+# Severities that require acknowledgement tracking
+ESCALATION_SEVERITIES: frozenset[str] = frozenset({"critical", "high"})
+
+_ESCALATION_FILE = ".patchi/escalation.json"
+_DEFAULT_ESCALATION_MINS = 30  # escalate after 30 min if unacknowledged
+_POLL_INTERVAL_SECS = 60  # check every 60 seconds
+
+
+_log = logging.getLogger("patchi.core.escalation")
+
+
+def _load_store(root: Path) -> dict:
+    path = root / _ESCALATION_FILE
+    if not path.exists():
+        return {"alerts": {}}
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {"alerts": {}}
+
+
+def _save_store(root: Path, data: dict) -> None:
+    path = root / _ESCALATION_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+
+
+class EscalationTracker:
+    """
+    Tracks unacknowledged CRITICAL/HIGH alerts and escalates them.
+
+    The background thread polls every 60 seconds and fires escalation
+    callbacks for overdue unacknowledged alerts.
+
+    escalation_fn signature: (alert_id: str, alert: dict, channels: list) -> None
+    """
+
+    def __init__(
+        self,
+        root: Path,
+        escalation_fn: Any,
+        escalation_minutes: int = _DEFAULT_ESCALATION_MINS,
+    ) -> None:
+        self._root = root
+        self._escalation_fn = escalation_fn
+        self._escalation_secs = escalation_minutes * 60
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def register(self, alert_id: str, severity: str, title: str, body: str) -> None:
+        """Register a new alert as requiring acknowledgement."""
+        if severity not in ESCALATION_SEVERITIES:
+            return
+        store = _load_store(self._root)
+        store["alerts"][alert_id] = {
+            "severity": severity,
+            "title": title,
+            "body": body,
+            "fired_at": _time.time(),
+            "acked": False,
+            "escalated": False,
+        }
+        _save_store(self._root, store)
+
+    def acknowledge(self, alert_id: str) -> bool:
+        """Mark an alert as acknowledged. Returns True if the ID was found."""
+        store = _load_store(self._root)
+        if alert_id not in store["alerts"]:
+            return False
+        store["alerts"][alert_id]["acked"] = True
+        _save_store(self._root, store)
+        return True
+
+    def pending(self) -> list[dict]:
+        """Return all alerts that are unacknowledged and not yet escalated."""
+        store = _load_store(self._root)
+        return [
+            {"id": aid, **alert}
+            for aid, alert in store["alerts"].items()
+            if not alert.get("acked") and not alert.get("escalated")
+        ]
+
+    def list_all(self) -> list[dict]:
+        """Return all tracked alerts (acked and unacked)."""
+        store = _load_store(self._root)
+        return [{"id": aid, **alert} for aid, alert in store["alerts"].items()]
+
+    def start(self) -> None:
+        """Start the background escalation polling thread."""
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._poll_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the background polling thread."""
+        self._stop_event.set()
+
+    def _poll_loop(self) -> None:
+        while not self._stop_event.is_set():
+            self._check_overdue()
+            self._stop_event.wait(timeout=_POLL_INTERVAL_SECS)
+
+    def _check_overdue(self) -> None:
+        """Fire escalation for any alert past the window."""
+        store = _load_store(self._root)
+        now = _time.time()
+        changed = False
+
+        for alert_id, alert in store["alerts"].items():
+            if alert.get("acked") or alert.get("escalated"):
+                continue
+            age = now - alert.get("fired_at", now)
+            if age >= self._escalation_secs:
+                alert["escalated"] = True
+                changed = True
+                try:
+                    self._escalation_fn(alert_id, alert)
+                except Exception as e:
+                    _log.warning("EscalationTracker._check_overdue failed: %s", e)
+
+        if changed:
+            _save_store(self._root, store)
+
+    def purge_old(self, max_age_hours: int = 72) -> int:
+        """Remove acked/escalated alerts older than max_age_hours. Returns count removed."""
+        store = _load_store(self._root)
+        cutoff = _time.time() - (max_age_hours * 3600)
+        before = len(store["alerts"])
+        store["alerts"] = {
+            aid: a
+            for aid, a in store["alerts"].items()
+            if not (a.get("acked") or a.get("escalated")) or a.get("fired_at", 0) >= cutoff
+        }
+        _save_store(self._root, store)
+        return before - len(store["alerts"])

patchi/core/notifications/notifier.py

@@ -0,0 +1,182 @@
+"""
+Central notification dispatcher for Patchi.
+
+Single entry point: Notifier.send(severity, title, body, data)
+
+Routing rules:
+  CRITICAL  → immediate, all channels, bypass quiet hours, start escalation
+  HIGH      → immediate, bypass quiet hours, start escalation
+  MEDIUM    → digest queue unless quiet hours bypassed, respects quiet hours
+  LOW/INFO  → digest queue only, respects quiet hours
+
+Usage:
+    notifier = Notifier(project_root)
+    notifier.send("critical", "SQL injection found", "in routes/user.py:44")
+"""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+from typing import Any
+
+import apprise
+from apprise import NotifyType
+
+from patchi.core.notifications.channels import ChannelConfig, load_channels
+from patchi.core.notifications.digest import DIGEST_SEVERITIES, DigestQueue
+from patchi.core.notifications.escalation import ESCALATION_SEVERITIES, EscalationTracker
+from patchi.core.notifications.quiet_hours import should_suppress
+
+# Severity → Apprise NotifyType mapping
+_APPRISE_TYPE: dict[str, str] = {
+    "critical": NotifyType.FAILURE,
+    "high": NotifyType.WARNING,
+    "medium": NotifyType.INFO,
+    "low": NotifyType.SUCCESS,
+    "info": NotifyType.SUCCESS,
+}
+
+
+class Notifier:
+    """
+    Dispatch Patchi alerts to configured channels.
+
+    Instantiate once per command invocation or keep alive in watch mode.
+    Thread-safe for the escalation background thread.
+    """
+
+    def __init__(self, root: Path, config: dict) -> None:
+        self._root = root
+        self._config = config
+        self._channels = load_channels(config)
+        self._digest = DigestQueue(root)
+        self._tracker = EscalationTracker(
+            root,
+            escalation_fn=self._escalate,
+            escalation_minutes=config.get("escalation_minutes", 30),
+        )
+
+    def send(
+        self,
+        severity: str,
+        title: str,
+        body: str,
+        data: dict[str, Any] | None = None,
+    ) -> int:
+        """
+        Route one alert by severity.
+        Returns the number of channels that received the alert immediately.
+        """
+        data = data or {}
+        channels = self._eligible_channels(severity)
+
+        if not channels:
+            return 0
+
+        in_digest_mode = severity in DIGEST_SEVERITIES
+        suppressed = should_suppress(severity, self._config.get("quiet_hours", {}))
+
+        if suppressed or in_digest_mode:
+            self._digest.enqueue(severity, title, body, data)
+            return 0
+
+        # Immediate fire
+        sent = self._fire(channels, severity, title, body)
+
+        # Register for escalation if CRITICAL or HIGH
+        if severity in ESCALATION_SEVERITIES and sent > 0:
+            alert_id = str(uuid.uuid4())[:8]
+            self._tracker.register(alert_id, severity, title, body)
+
+        # Auto-flush digest if window has elapsed
+        freq = self._config.get("digest_frequency", "daily")
+        if self._digest.should_flush(freq):
+            self.flush_digest()
+
+        return sent
+
+    def flush_digest(self) -> int:
+        """
+        Flush the digest queue to all channels configured with in_digest=True
+        or that accept MEDIUM severity. Returns number of channels notified.
+        """
+        items = self._digest.flush()
+        if not items:
+            return 0
+
+        body = DigestQueue.build_digest_body(items)
+        title = f"Patchi digest — {len(items)} alert(s)"
+        channels = [ch for ch in self._channels if ch.accepts_severity("medium")]
+        return self._fire(channels, "medium", title, body)
+
+    def test(self, channel_name: str | None = None) -> list[tuple[str, bool]]:
+        """
+        Send a test alert to one or all channels.
+        Returns list of (channel_name, success) tuples.
+        """
+        targets = (
+            [ch for ch in self._channels if ch.name == channel_name]
+            if channel_name
+            else self._channels
+        )
+        results: list[tuple[str, bool]] = []
+        for ch in targets:
+            ok = _apprise_send(
+                ch.apprise_url,
+                "info",
+                "Patchi test alert",
+                "If you see this, the channel is working.",
+            )
+            results.append((ch.name, ok))
+        return results
+
+    def acknowledge(self, alert_id: str) -> bool:
+        """Acknowledge a CRITICAL/HIGH alert by its short ID."""
+        return self._tracker.acknowledge(alert_id)
+
+    def pending_escalations(self) -> list[dict]:
+        """Return all unacknowledged, unescalated alerts."""
+        return self._tracker.pending()
+
+    # ── Internal helpers ───────────────────────────────────────────────────────
+
+    def _eligible_channels(self, severity: str) -> list[ChannelConfig]:
+        return [ch for ch in self._channels if ch.accepts_severity(severity)]
+
+    def _fire(
+        self,
+        channels: list[ChannelConfig],
+        severity: str,
+        title: str,
+        body: str,
+    ) -> int:
+        notify_type = _APPRISE_TYPE.get(severity, NotifyType.INFO)
+        sent = 0
+        for ch in channels:
+            if _apprise_send(ch.apprise_url, notify_type, title, body):
+                sent += 1
+        return sent
+
+    def _escalate(self, alert_id: str, alert: dict) -> None:
+        """
+        Escalation callback — fires remaining channels that haven't received the alert.
+        Called by EscalationTracker on the background thread.
+        """
+        channels = self._eligible_channels(alert.get("severity", "high"))
+        # Skip first channel (already fired) — escalate to the rest
+        escalation_targets = channels[1:] if len(channels) > 1 else channels
+        if escalation_targets:
+            self._fire(
+                escalation_targets,
+                alert.get("severity", "high"),
+                f"[ESCALATED] {alert.get('title', 'Alert')}",
+                alert.get("body", ""),
+            )
+
+
+def _apprise_send(url: str, notify_type: str, title: str, body: str) -> bool:
+    """Send one notification via Apprise. Returns True on success."""
+    ap = apprise.Apprise()
+    ap.add(url)
+    return bool(ap.notify(title=title, body=body, notify_type=notify_type))