devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/github/__init__.py

@@ -0,0 +1,35 @@
+"""
+devtorch_core.github — GitHub App + CI/CD integration (Sprint 12).
+
+Public API:
+    parse_pr_body     — parse a PR body string into PRMetadata
+    PRMetadata        — dataclass holding extracted governance metadata
+    build_pr_comment  — render a GovernanceSummary as a GitHub PR comment
+    GovernanceSummary — dataclass holding governance state for comment rendering
+"""
+
+from .pr_parser import PRMetadata, parse_pr_body
+from .comment_builder import GovernanceSummary, build_pr_comment
+from .pat import GitHubPATStore
+from .app import GitHubAppHandler
+from .pr_reporter import (
+    MergeGateResult,
+    build_reasoning_delta_comment,
+    check_merge_gate,
+    post_pr_comment,
+    run_pr_reporter,
+)
+
+__all__ = [
+    "parse_pr_body",
+    "PRMetadata",
+    "build_pr_comment",
+    "GovernanceSummary",
+    "GitHubPATStore",
+    "GitHubAppHandler",
+    "MergeGateResult",
+    "build_reasoning_delta_comment",
+    "check_merge_gate",
+    "post_pr_comment",
+    "run_pr_reporter",
+]

devtorch_core/github/app.py

@@ -0,0 +1,240 @@
+"""
+GitHub App webhook receiver for DevTorch.
+
+Receives GitHub webhook events, validates HMAC signatures, and extracts
+DevTorch governance metadata from PR bodies.
+
+FastAPI is optional — the module degrades gracefully when it is not installed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+import os
+import time
+import urllib.request
+from typing import Any, Dict, Optional
+
+from .pr_parser import parse_pr_body
+
+logger = logging.getLogger(__name__)
+
+# ── Optional FastAPI import ───────────────────────────────────────────────────
+try:
+    from fastapi import FastAPI, Request, Response
+
+    HAS_FASTAPI = True
+except ImportError:  # pragma: no cover
+    HAS_FASTAPI = False
+
+_WEBHOOK_SECRET_ENV = "DEVTORCH_GITHUB_WEBHOOK_SECRET"
+
+
+def _verify_signature(payload: bytes, signature_header: str, secret: str) -> bool:
+    """Validate the X-Hub-Signature-256 HMAC header."""
+    if not signature_header or not signature_header.startswith("sha256="):
+        return False
+    expected = (
+        "sha256="
+        + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
+    )
+    return hmac.compare_digest(expected, signature_header)
+
+
+def _build_app() -> "FastAPI":  # type: ignore[name-defined]
+    """Construct and return the FastAPI application instance."""
+    if not HAS_FASTAPI:
+        raise RuntimeError(
+            "FastAPI is not installed. Install it with: pip install fastapi uvicorn"
+        )
+
+    app = FastAPI(title="DevTorch GitHub Webhook Receiver")
+
+    @app.post("/webhook/github")
+    async def github_webhook(request: Request) -> Dict[str, Any]:
+        secret = os.environ.get(_WEBHOOK_SECRET_ENV, "")
+        if not secret:
+            logger.warning("DEVTORCH_GITHUB_WEBHOOK_SECRET is not set; ignoring event.")
+            return {"status": "webhook_secret_not_configured"}
+
+        payload = await request.body()
+        sig_header = request.headers.get("X-Hub-Signature-256", "")
+
+        if not _verify_signature(payload, sig_header, secret):
+            logger.warning("Invalid webhook signature received.")
+            return Response(content='{"error":"invalid signature"}', status_code=401, media_type="application/json")  # type: ignore[return-value]
+
+        event_type = request.headers.get("X-GitHub-Event", "")
+
+        if event_type != "pull_request":
+            logger.debug("Ignoring non-PR event: %s", event_type)
+            return {"status": "ignored"}
+
+        import json as _json
+
+        event: Dict[str, Any] = _json.loads(payload)
+        action = event.get("action", "")
+
+        if action not in ("opened", "synchronize"):
+            logger.debug("Ignoring PR action: %s", action)
+            return {"status": "ignored"}
+
+        pr = event.get("pull_request", {})
+        body = pr.get("body") or ""
+        metadata = parse_pr_body(body)
+
+        logger.info(
+            "PR #%s (%s) DevTorch metadata: branch=%r commits=%d sensitivities=%d concepts=%d mcs=%s",
+            pr.get("number", "?"),
+            action,
+            metadata.branch,
+            len(metadata.commit_ids),
+            len(metadata.sensitivity_refs),
+            len(metadata.concept_refs),
+            metadata.mcs_score,
+        )
+
+        return {
+            "status": "ok",
+            "metadata": {
+                "branch": metadata.branch,
+                "commit_ids": metadata.commit_ids,
+                "sensitivity_refs": metadata.sensitivity_refs,
+                "concept_refs": metadata.concept_refs,
+                "mcs_score": metadata.mcs_score,
+                "has_devtorch_section": metadata.has_devtorch_section,
+            },
+        }
+
+    return app
+
+
+# Module-level app instance — only created when FastAPI is available.
+if HAS_FASTAPI:
+    app = _build_app()
+
+
+# ---------------------------------------------------------------------------
+# GitHubAppHandler — installation webhooks + access token issuance
+# ---------------------------------------------------------------------------
+
+_APP_KEY = ".devtorch/github_app.json"
+
+
+class GitHubAppHandler:
+    """
+    Handles GitHub App installation webhooks and issues installation access tokens.
+
+    Requires env vars when get_installation_token() is called:
+      GITHUB_APP_ID         — numeric GitHub App ID
+      GITHUB_APP_PRIVATE_KEY — PEM-format RSA private key (the .pem file contents)
+    """
+
+    def __init__(self, backend: Any, webhook_secret: bytes) -> None:
+        self._backend = backend
+        self._webhook_secret = webhook_secret
+
+    # ------------------------------------------------------------------
+    # Webhook handling
+    # ------------------------------------------------------------------
+
+    def handle_webhook(self, body: bytes, signature: str, event_type: str) -> dict:
+        if not self._verify_signature(body, signature):
+            return {"status": "forbidden", "reason": "invalid signature"}
+
+        try:
+            payload = json.loads(body)
+        except json.JSONDecodeError:
+            return {"status": "error", "reason": "invalid JSON"}
+
+        action = payload.get("action", "")
+        installation = payload.get("installation", {})
+        installation_id = installation.get("id")
+
+        if event_type == "installation":
+            if action == "created":
+                repos = [r["full_name"] for r in payload.get("repositories", [])]
+                self._store_installation(installation_id=installation_id, repositories=repos)
+            elif action == "deleted":
+                self._clear_installation()
+
+        elif event_type == "installation_repositories":
+            existing = self._load()
+            repos_added = [r["full_name"] for r in payload.get("repositories_added", [])]
+            repos_removed = {r["full_name"] for r in payload.get("repositories_removed", [])}
+            current = set(existing.get("repositories", []))
+            current = (current | set(repos_added)) - repos_removed
+            existing["repositories"] = sorted(current)
+            self._save(existing)
+
+        return {"status": "ok"}
+
+    def _verify_signature(self, body: bytes, signature: str) -> bool:
+        if not signature.startswith("sha256="):
+            return False
+        expected = "sha256=" + hmac.new(self._webhook_secret, body, hashlib.sha256).hexdigest()
+        return hmac.compare_digest(expected, signature)
+
+    def _load(self) -> dict:
+        try:
+            return json.loads(self._backend.read_bytes(_APP_KEY))
+        except (FileNotFoundError, json.JSONDecodeError):
+            return {}
+
+    def _save(self, data: dict) -> None:
+        self._backend.write_bytes(_APP_KEY, json.dumps(data, indent=2).encode())
+
+    def _store_installation(self, installation_id: int, repositories: list[str]) -> None:
+        data = self._load()
+        data["installation_id"] = installation_id
+        data["repositories"] = sorted(set(data.get("repositories", [])) | set(repositories))
+        self._save(data)
+
+    def _clear_installation(self) -> None:
+        self._save({})
+
+    # ------------------------------------------------------------------
+    # Installation token issuance
+    # ------------------------------------------------------------------
+
+    def get_installation_id(self) -> Optional[int]:
+        return self._load().get("installation_id")
+
+    def get_installation_token(self) -> Optional[str]:
+        """Issue a short-lived installation access token (valid 1 hour)."""
+        installation_id = self.get_installation_id()
+        if installation_id is None:
+            return None
+
+        jwt_token = self._make_jwt()
+        url = f"https://api.github.com/app/installations/{installation_id}/access_tokens"
+        req = urllib.request.Request(
+            url,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {jwt_token}",
+                "Accept": "application/vnd.github+json",
+                "User-Agent": "DevTorch-App",
+                "Content-Length": "0",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read())
+        return data.get("token")
+
+    def _make_jwt(self) -> str:
+        """Create a signed JWT for the GitHub App (RS256, 10-minute expiry)."""
+        try:
+            import jwt as _jwt
+        except ImportError:
+            raise RuntimeError("PyJWT not installed. Install with: pip install 'devtorch-core[cloud]'")
+
+        app_id = os.environ["GITHUB_APP_ID"]
+        private_key = os.environ["GITHUB_APP_PRIVATE_KEY"]
+
+        now = int(time.time())
+        payload = {"iat": now - 60, "exp": now + 600, "iss": int(app_id)}
+        return _jwt.encode(payload, private_key, algorithm="RS256")

devtorch_core/github/comment_builder.py

@@ -0,0 +1,113 @@
+"""
+Builds GitHub PR comment markdown for DevTorch governance summaries.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+from .pr_parser import PRMetadata
+
+
+@dataclass
+class GovernanceSummary:
+    """Governance state to be surfaced in a PR comment."""
+
+    branch: str
+    node_state: str
+    top_concepts: List[Tuple[str, float]] = field(default_factory=list)
+    sensitivity_count: int = 0
+    high_disclosure_count: int = 0
+    mcs_score: Optional[float] = None
+    invariants_ok: bool = True
+    lock_status: str = "unlocked"
+
+
+def build_pr_comment(
+    summary: GovernanceSummary,
+    pr_metadata: Optional[PRMetadata] = None,
+) -> str:
+    """
+    Build a GitHub PR comment in Markdown that summarises DevTorch governance state.
+
+    Args:
+        summary: Governance summary data (typically from devtorch doctor output).
+        pr_metadata: Optional parsed PR metadata; included in output when provided.
+
+    Returns:
+        A Markdown string suitable for posting as a GitHub PR comment.
+    """
+    lines: List[str] = []
+
+    # ── Header ────────────────────────────────────────────────────────────────
+    lines.append("## 🛡️ DevTorch Governance Report")
+    lines.append("")
+
+    # ── Main table ────────────────────────────────────────────────────────────
+    top_concepts_str = (
+        ", ".join(f"{name} ({conf:.2f})" for name, conf in summary.top_concepts)
+        if summary.top_concepts
+        else "—"
+    )
+
+    mcs_display = f"{summary.mcs_score:.2f}" if summary.mcs_score is not None else "N/A"
+    invariants_display = "✅ OK" if summary.invariants_ok else "❌ FAILED"
+
+    lines.append("| Field | Value |")
+    lines.append("|---|---|")
+    lines.append(f"| **Branch** | `{summary.branch}` |")
+    lines.append(f"| **Node State** | {summary.node_state} |")
+    lines.append(f"| **Top Concepts** | {top_concepts_str} |")
+    lines.append(f"| **Sensitivity Events** | {summary.sensitivity_count} |")
+    lines.append(f"| **MCS Score** | {mcs_display} |")
+    lines.append(f"| **Invariants** | {invariants_display} |")
+    lines.append(f"| **Lock Status** | {summary.lock_status} |")
+    lines.append("")
+
+    # ── Warnings ──────────────────────────────────────────────────────────────
+    if not summary.invariants_ok:
+        lines.append("> ⚠️ **Invariant check failed.** One or more DevTorch invariants")
+        lines.append("> (I1 commit-backed, I3 semantic grounding) did not pass.")
+        lines.append("> Review the invariant trace before merging.")
+        lines.append("")
+
+    if summary.high_disclosure_count > 0:
+        lines.append(
+            f"> 🔒 **{summary.high_disclosure_count} high-disclosure sensitivity"
+            f" event(s) detected.** Ensure downstream consumers comply with"
+            f" disclosure policy before merging."
+        )
+        lines.append("")
+
+    if summary.lock_status and summary.lock_status.lower() not in ("unlocked", ""):
+        lines.append(
+            f"> 🔐 **Consensus lock is active** (`{summary.lock_status}`). "
+            "Merge may be restricted by governance policy."
+        )
+        lines.append("")
+
+    # ── PR metadata section (optional) ────────────────────────────────────────
+    if pr_metadata is not None and pr_metadata.has_devtorch_section:
+        lines.append("### DevTorch PR Metadata")
+        lines.append("")
+        if pr_metadata.sensitivity_refs:
+            lines.append(
+                f"- **Sensitivity refs**: {', '.join(pr_metadata.sensitivity_refs)}"
+            )
+        if pr_metadata.concept_refs:
+            lines.append(f"- **Concept refs**: {', '.join(pr_metadata.concept_refs)}")
+        if pr_metadata.commit_ids:
+            short_ids = [c[:7] for c in pr_metadata.commit_ids]
+            lines.append(f"- **Commits**: {', '.join(short_ids)}")
+        if pr_metadata.mcs_score is not None:
+            lines.append(f"- **PR MCS Score**: {pr_metadata.mcs_score:.2f}")
+        lines.append("")
+
+    # ── Footer ────────────────────────────────────────────────────────────────
+    lines.append(
+        "---\n_Generated by DevTorch | "
+        "[docs](https://github.com/flotorch-ai/devtorch)_"
+    )
+
+    return "\n".join(lines)

devtorch_core/github/pat.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any, Optional
+
+
+_PATS_KEY = ".devtorch/github_pats.json"
+
+
+def _fernet_key(raw: bytes) -> bytes:
+    """Derive a 32-byte Fernet key from arbitrary bytes via SHA-256."""
+    import hashlib
+    digest = hashlib.sha256(raw).digest()  # always 32 bytes
+    return base64.urlsafe_b64encode(digest)
+
+
+class GitHubPATStore:
+    """
+    Stores GitHub Personal Access Tokens encrypted with Fernet (AES-128-CBC + HMAC).
+    PATs are stored at {prefix}/.devtorch/github_pats.json in the backend.
+
+    encryption_key: any bytes — hashed to 32 bytes via SHA-256 internally.
+    Generate a stable key with: python -c "import os; print(os.urandom(32).hex())"
+    Store as DEVTORCH_PAT_ENCRYPTION_KEY env var (hex string).
+    """
+
+    def __init__(self, backend: Any, encryption_key: bytes) -> None:
+        self._backend = backend
+        self._fernet_key = _fernet_key(encryption_key)
+
+    def _fernet(self):
+        from cryptography.fernet import Fernet
+        return Fernet(self._fernet_key)
+
+    def _load(self) -> dict:
+        try:
+            return json.loads(self._backend.read_bytes(_PATS_KEY))
+        except (FileNotFoundError, json.JSONDecodeError):
+            return {}
+
+    def _save(self, data: dict) -> None:
+        self._backend.write_bytes(_PATS_KEY, json.dumps(data, indent=2).encode())
+
+    def store_pat(self, repo_id: str, pat: str, github_repo: str) -> None:
+        """Encrypt and store the PAT for a repo_id → github_repo mapping."""
+        data = self._load()
+        encrypted = self._fernet().encrypt(pat.encode()).decode()
+        data[repo_id] = {
+            "github_repo": github_repo,
+            "pat_encrypted": encrypted,
+        }
+        self._save(data)
+
+    def get_pat(self, repo_id: str) -> Optional[dict[str, str]]:
+        """Return {"pat": "<decrypted>", "github_repo": "<owner/repo>"} or None."""
+        data = self._load()
+        entry = data.get(repo_id)
+        if not entry:
+            return None
+        try:
+            decrypted = self._fernet().decrypt(entry["pat_encrypted"].encode()).decode()
+        except Exception:
+            return None
+        return {"pat": decrypted, "github_repo": entry["github_repo"]}
+
+    def list_repos(self) -> list[str]:
+        """Return all repo_ids with stored PATs."""
+        return list(self._load().keys())
+
+    def delete_pat(self, repo_id: str) -> None:
+        """Remove the PAT for a repo_id."""
+        data = self._load()
+        if repo_id in data:
+            del data[repo_id]
+            self._save(data)

devtorch_core/github/pr_parser.py

@@ -0,0 +1,82 @@
+"""
+Parses GitHub PR bodies for DevTorch governance metadata.
+Extracts structured data without requiring a .GCC/ directory.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class PRMetadata:
+    """Structured DevTorch governance metadata extracted from a PR body."""
+
+    branch: str = ""
+    commit_ids: List[str] = field(default_factory=list)
+    sensitivity_refs: List[str] = field(default_factory=list)
+    concept_refs: List[str] = field(default_factory=list)
+    mcs_score: Optional[float] = None
+    has_devtorch_section: bool = False
+
+
+# Patterns
+_BRANCH_PATTERN = re.compile(r"Branch:\s*`([^`]+)`")
+_COMMIT_PATTERN = re.compile(r"\b([0-9a-f]{40})\b", re.IGNORECASE)
+_SENSITIVITY_PATTERN = re.compile(r"\[SENSITIVITY:([^\]]+)\]")
+_CONCEPT_PATTERN = re.compile(r"\[CONCEPT:([^\]]+)\]")
+_MCS_PATTERN = re.compile(r"MCS:\s*([\d]+\.[\d]+)")
+_DEVTORCH_HEADING_PATTERN = re.compile(r"^#{2,3}\s+DevTorch\b", re.MULTILINE)
+
+
+def parse_pr_body(body: str) -> PRMetadata:
+    """
+    Parse a GitHub PR body string and extract DevTorch governance metadata.
+
+    Args:
+        body: The full text of the PR description/body.
+
+    Returns:
+        A PRMetadata instance populated from whatever was found in the body.
+        Fields default to empty lists, None, or False when not found.
+    """
+    if not body:
+        return PRMetadata()
+
+    # Branch
+    branch = ""
+    branch_match = _BRANCH_PATTERN.search(body)
+    if branch_match:
+        branch = branch_match.group(1)
+
+    # Commit IDs (40-char lowercase hex strings)
+    commit_ids = list(dict.fromkeys(m.lower() for m in _COMMIT_PATTERN.findall(body)))
+
+    # Sensitivity refs
+    sensitivity_refs = list(dict.fromkeys(_SENSITIVITY_PATTERN.findall(body)))
+
+    # Concept refs
+    concept_refs = list(dict.fromkeys(_CONCEPT_PATTERN.findall(body)))
+
+    # MCS score
+    mcs_score: Optional[float] = None
+    mcs_match = _MCS_PATTERN.search(body)
+    if mcs_match:
+        try:
+            mcs_score = float(mcs_match.group(1))
+        except ValueError:
+            mcs_score = None
+
+    # DevTorch section heading
+    has_devtorch_section = bool(_DEVTORCH_HEADING_PATTERN.search(body))
+
+    return PRMetadata(
+        branch=branch,
+        commit_ids=commit_ids,
+        sensitivity_refs=sensitivity_refs,
+        concept_refs=concept_refs,
+        mcs_score=mcs_score,
+        has_devtorch_section=has_devtorch_section,
+    )