devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/gitlab/__init__.py

@@ -0,0 +1,177 @@
+"""
+GitLab MR webhook handler for DevTorch.
+
+Mirrors the GitHub App flow for GitLab:
+- Validates X-Gitlab-Token signature
+- Parses MR descriptions for DevTorch reasoning metadata
+- Provides merge gate logic (I3 critical concepts unresolved)
+
+Actual GitLab API calls to post comments require a project access token and
+are left to the caller or a future connector.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MRMetadata:
+    """Governance metadata extracted from an MR description."""
+    branch: str
+    commit_ids: List[str]
+    sensitivity_refs: List[str]
+    concept_refs: List[str]
+    mcs_score: Optional[float]
+    has_devtorch_section: bool
+
+
+class GitLabWebhookHandler:
+    """Handles GitLab Merge Request webhook events."""
+
+    def __init__(self, webhook_secret: bytes) -> None:
+        self._webhook_secret = webhook_secret
+
+    def handle_event(self, body: bytes, token_header: str, event_type: str) -> Dict[str, Any]:
+        """Validate and process a GitLab webhook event."""
+        if not self._verify_token(token_header):
+            return {"status": "forbidden", "reason": "invalid token"}
+
+        try:
+            payload: Dict[str, Any] = json.loads(body)
+        except json.JSONDecodeError:
+            return {"status": "error", "reason": "invalid JSON"}
+
+        if event_type != "Merge Request Hook":
+            logger.debug("Ignoring non-MR event: %s", event_type)
+            return {"status": "ignored"}
+
+        attrs = payload.get("object_attributes", {})
+        action = attrs.get("action", "")
+        if action not in ("open", "update", "reopen"):
+            logger.debug("Ignoring MR action: %s", action)
+            return {"status": "ignored"}
+
+        description = attrs.get("description") or ""
+        metadata = self._parse_description(description)
+
+        # Merge gate: block if critical concepts are unresolved
+        gate_result = self._evaluate_merge_gate(metadata)
+
+        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,
+            },
+            "merge_gate": gate_result,
+        }
+
+    def _verify_token(self, token_header: str) -> bool:
+        """GitLab sends a plain secret token; compare in constant time."""
+        if not token_header:
+            return False
+        return hmac.compare_digest(
+            self._webhook_secret.decode("utf-8"),
+            token_header,
+        )
+
+    def _parse_description(self, description: str) -> MRMetadata:
+        """Parse a DevTorch reasoning section from an MR description."""
+        branch = ""
+        commit_ids: List[str] = []
+        sensitivity_refs: List[str] = []
+        concept_refs: List[str] = []
+        mcs_score: Optional[float] = None
+        has_devtorch_section = False
+
+        in_section = False
+        for line in description.splitlines():
+            stripped = line.strip()
+            if stripped == "<!-- DevTorch Reasoning Delta -->":
+                in_section = True
+                has_devtorch_section = True
+                continue
+            if stripped == "<!-- End DevTorch Reasoning Delta -->":
+                in_section = False
+                continue
+
+            if not in_section:
+                continue
+
+            if stripped.startswith("- Branch:"):
+                branch = stripped.split(":", 1)[1].strip()
+            elif stripped.startswith("- Commits:"):
+                commits_str = stripped.split(":", 1)[1].strip()
+                commit_ids = [c.strip() for c in commits_str.split(",") if c.strip()]
+            elif stripped.startswith("- Sensitivities:"):
+                refs_str = stripped.split(":", 1)[1].strip()
+                sensitivity_refs = [r.strip() for r in refs_str.split(",") if r.strip()]
+            elif stripped.startswith("- Concepts:"):
+                concepts_str = stripped.split(":", 1)[1].strip()
+                concept_refs = [c.strip() for c in concepts_str.split(",") if c.strip()]
+            elif stripped.startswith("- MCS:"):
+                mcs_str = stripped.split(":", 1)[1].strip()
+                try:
+                    mcs_score = float(mcs_str)
+                except ValueError:
+                    mcs_score = None
+
+        return MRMetadata(
+            branch=branch,
+            commit_ids=commit_ids,
+            sensitivity_refs=sensitivity_refs,
+            concept_refs=concept_refs,
+            mcs_score=mcs_score,
+            has_devtorch_section=has_devtorch_section,
+        )
+
+    def _evaluate_merge_gate(self, metadata: MRMetadata) -> Dict[str, Any]:
+        """Evaluate merge gate: block if I3 critical concepts unresolved."""
+        # For now, a simple policy: block if no DevTorch section and there are
+        # critical concepts referenced but no sensitivity entries.
+        blocked = False
+        reasons: List[str] = []
+
+        if not metadata.has_devtorch_section:
+            blocked = True
+            reasons.append("Missing DevTorch Reasoning Delta")
+
+        if metadata.mcs_score is not None and metadata.mcs_score < 0.5:
+            blocked = True
+            reasons.append(f"MCS score {metadata.mcs_score:.2f} below threshold 0.5")
+
+        return {
+            "blocked": blocked,
+            "reasons": reasons,
+        }
+
+    def build_mr_comment(self, metadata: MRMetadata) -> str:
+        """Build a Markdown comment to post on the MR."""
+        gate = self._evaluate_merge_gate(metadata)
+        status = "🟢 Merge gate passed" if not gate["blocked"] else "🔴 Merge gate blocked"
+        lines = [
+            "## DevTorch Reasoning Delta",
+            "",
+            f"**Branch:** `{metadata.branch}`" if metadata.branch else "**Branch:** (not specified)",
+            f"**MCS:** {metadata.mcs_score:.2f}" if metadata.mcs_score is not None else "**MCS:** (not provided)",
+            "",
+            f"**{status}**",
+        ]
+        if gate["reasons"]:
+            lines.append("")
+            lines.append("Reasons:")
+            for reason in gate["reasons"]:
+                lines.append(f"- {reason}")
+        return "\n".join(lines)

devtorch_core/hitl/__init__.py

@@ -0,0 +1,4 @@
+from .channels import HITLRequest, HITLChannel, CLIHITLChannel, SlackHITLChannel
+from .orchestrator import HITLOrchestrator
+
+__all__ = ["HITLRequest", "HITLChannel", "CLIHITLChannel", "SlackHITLChannel", "HITLOrchestrator"]

devtorch_core/hitl/channels.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import json
+import uuid
+from collections import deque
+from pathlib import Path
+from typing import Deque, List, Optional
+
+
+@dataclasses.dataclass
+class HITLRequest:
+    """
+    A request for human (or arbiter agent) input on a divergence.
+
+    options provides suggested resolution choices; the human may pick one
+    or write free-form text in their response.
+    """
+    request_id: str
+    concept: str
+    consolidation_record_id: str
+    signals: List[dict]
+    prompt: str
+    options: List[str]
+    state: str               # "pending" | "responded" | "timeout"
+    created_at: str
+    response: Optional[str] = None
+    responded_at: Optional[str] = None
+    responder: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        return dataclasses.asdict(self)
+
+
+class HITLChannel:
+    """Base class for HITL notification + response channels."""
+    channel_name: str = "base"
+
+    def send(self, request: HITLRequest) -> None:
+        raise NotImplementedError
+
+    def poll(self, request_id: str) -> Optional[str]:
+        """Return response text if available, else None."""
+        raise NotImplementedError
+
+
+class CLIHITLChannel(HITLChannel):
+    """
+    CLI-based HITL channel for development and testing.
+
+    In tests, pass a `response_queue` list — responses are dequeued in order.
+    In interactive use (response_queue=None), reads from stdin.
+    """
+    channel_name = "cli"
+
+    def __init__(self, response_queue: Optional[List[str]] = None) -> None:
+        self._queue: Deque[str] = deque(response_queue or [])
+        self._responses: dict[str, str] = {}
+
+    def send(self, request: HITLRequest) -> None:
+        if self._queue:
+            response = self._queue.popleft()
+            self._responses[request.request_id] = response
+        else:
+            print(f"\n[DevTorch HITL] Concept: {request.concept}")
+            print(f"  {request.prompt}")
+            for i, opt in enumerate(request.options, 1):
+                print(f"  {i}. {opt}")
+            answer = input("  Your response: ").strip()
+            self._responses[request.request_id] = answer
+
+    def poll(self, request_id: str) -> Optional[str]:
+        return self._responses.get(request_id)
+
+
+class SlackHITLChannel(HITLChannel):
+    """
+    Slack-based HITL channel.
+
+    Sends a Block Kit message via webhook. Responses are written to
+    .GCC/hitl/<request_id>.response.json by an external Slack action handler;
+    poll() reads from that file.
+    """
+    channel_name = "slack"
+
+    def __init__(self, webhook_url: str, gcc_dir: Path) -> None:
+        self._webhook_url = webhook_url
+        self._gcc_dir = gcc_dir
+
+    def send(self, request: HITLRequest) -> None:
+        import urllib.request
+        options_text = "\n".join(f"  {i+1}. {opt}" for i, opt in enumerate(request.options))
+        payload = {
+            "blocks": [
+                {
+                    "type": "header",
+                    "text": {"type": "plain_text", "text": f"[DevTorch HITL] Concept: {request.concept}"},
+                },
+                {
+                    "type": "section",
+                    "text": {"type": "mrkdwn", "text": f"*{request.prompt}*\n{options_text}"},
+                },
+                {
+                    "type": "context",
+                    "elements": [{"type": "mrkdwn",
+                                  "text": f"Record ID: `{request.consolidation_record_id}` | Request: `{request.request_id}`"}],
+                },
+            ]
+        }
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            self._webhook_url, data=data,
+            headers={"Content-Type": "application/json"},
+        )
+        try:
+            urllib.request.urlopen(req, timeout=5)
+        except Exception:
+            pass  # Non-blocking; Slack delivery failure does not block the workflow
+
+    def poll(self, request_id: str) -> Optional[str]:
+        response_file = self._gcc_dir / "hitl" / f"{request_id}.response.json"
+        if not response_file.exists():
+            return None
+        try:
+            d = json.loads(response_file.read_text(encoding="utf-8"))
+            return d.get("response")
+        except (json.JSONDecodeError, OSError):
+            return None

devtorch_core/hitl/orchestrator.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import uuid
+from pathlib import Path
+from typing import List, Optional
+
+from devtorch_core.divergence import DivergenceDetector
+from devtorch_core.consolidation import ConsolidationWorkflow, ConsolidationRecord
+from .channels import HITLChannel, HITLRequest
+
+_HITL_DIR = "hitl"
+
+
+class HITLOrchestrator:
+    """
+    Detects divergence, starts a ConsolidationWorkflow, and triggers HITL
+    when the severity requires human input.
+
+    Flow:
+      1. Detect divergence for concept.
+      2. If no divergence → return None.
+      3. Start ConsolidationWorkflow → get ConsolidationRecord.
+      4. If state is pending_human/blocked → build HITLRequest, send to channels.
+      5. Poll channels for response; if found → add_human_comment to record.
+      6. Return ConsolidationRecord.
+    """
+
+    def __init__(self, repo, channels: List[HITLChannel], poll_attempts: int = 1) -> None:
+        self._repo = repo
+        self._channels = channels
+        self._poll_attempts = poll_attempts
+        self._hitl_dir = repo.gcc_dir / _HITL_DIR
+        self._hitl_dir.mkdir(exist_ok=True)
+
+    def run(self, concept: str) -> Optional[ConsolidationRecord]:
+        signals = DivergenceDetector(self._repo).detect(concept=concept)
+        if not signals:
+            return None
+
+        workflow = ConsolidationWorkflow(self._repo)
+        record = workflow.start(concept=concept, signals=signals)
+
+        if record.state in ("pending_human", "blocked"):
+            request = self._build_request(record)
+            self._persist_request(request)
+            for channel in self._channels:
+                channel.send(request)
+
+            response = self._collect_response(request)
+            if response:
+                workflow.add_human_comment(
+                    record_id=record.record_id,
+                    author=response.get("responder", "human"),
+                    comment=response.get("text", ""),
+                    decision=response.get("text"),
+                )
+                record = workflow.get(record.record_id)
+
+        return record
+
+    def _build_request(self, record: ConsolidationRecord) -> HITLRequest:
+        signal_descs = [s.get("description", "")[:100] for s in record.signals[:3]]
+        options = [
+            f"Accept highest-disclosure level (most restrictive)",
+            f"Accept lowest-disclosure level (most permissive)",
+            f"Defer — mark concept '{record.concept}' as requiring manual review",
+        ]
+        return HITLRequest(
+            request_id=str(uuid.uuid4()),
+            concept=record.concept,
+            consolidation_record_id=record.record_id,
+            signals=record.signals,
+            prompt=(
+                f"Divergence detected on '{record.concept}': "
+                + "; ".join(signal_descs)
+                + "\nPlease provide a resolution or select an option."
+            ),
+            options=options,
+            state="pending",
+            created_at=_dt.datetime.now(tz=_dt.timezone.utc).isoformat(),
+        )
+
+    def _persist_request(self, request: HITLRequest) -> None:
+        path = self._hitl_dir / f"{request.request_id}.json"
+        path.write_text(json.dumps(request.to_dict(), indent=2) + "\n", encoding="utf-8")
+
+    def _collect_response(self, request: HITLRequest) -> Optional[dict]:
+        for _ in range(self._poll_attempts):
+            for channel in self._channels:
+                text = channel.poll(request.request_id)
+                if text:
+                    return {"text": text, "responder": channel.channel_name}
+        return None

devtorch_core/hooks/__init__.py

@@ -0,0 +1,17 @@
+"""
+DevTorch hooks package.
+
+Provides Claude Code hook handlers and git commit-msg hook integration.
+"""
+
+from .claude_code import handle_pre_tool_use, handle_post_tool_use, handle_session_end
+from .git_commit import handle_commit_msg, install_hook, extract_sensitivity_from_commit
+
+__all__ = [
+    "handle_pre_tool_use",
+    "handle_post_tool_use",
+    "handle_session_end",
+    "handle_commit_msg",
+    "install_hook",
+    "extract_sensitivity_from_commit",
+]

devtorch_core/hooks/claude_code.py

@@ -0,0 +1,228 @@
+"""
+S7 Claude Code hooks — intercept Claude Code tool-use events.
+
+Claude Code hooks are shell commands that receive JSON on stdin and write
+JSON to stdout.  This module implements three hook handlers:
+
+  handle_pre_tool_use()   — PreToolUse event; records session start; always approves
+  handle_post_tool_use()  — PostToolUse event; auto-commits for write tools
+  handle_session_end()    — Stop event; finalises session metrics
+
+Dispatch is done by main() based on argv[1]:
+  pre-tool-use | post-tool-use | session-end
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+# Tools whose use we want to capture as GCC commits.
+_WRITE_TOOLS = frozenset({"Write", "Edit", "MultiEdit", "Bash"})
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_event() -> dict:
+    """Read the JSON event from stdin."""
+    return json.loads(sys.stdin.read())
+
+
+def _write_response(payload: dict) -> None:
+    """Write JSON response to stdout."""
+    sys.stdout.write(json.dumps(payload) + "\n")
+    sys.stdout.flush()
+
+
+def _find_gcc_repo() -> Optional[Any]:
+    """Walk upward from cwd to find an initialised .GCC/ repository."""
+    from devtorch_core import GCCRepository
+
+    for parent in [Path.cwd()] + list(Path.cwd().parents):
+        r = GCCRepository.at(parent)
+        if r.is_initialized():
+            return r
+    return None
+
+
+def _gcc_root() -> Optional[Path]:
+    """Return the root path containing .GCC/ or None."""
+    from devtorch_core.gcc import GCC_DIR_NAME
+
+    for parent in [Path.cwd()] + list(Path.cwd().parents):
+        if (parent / GCC_DIR_NAME).is_dir():
+            return parent
+    return None
+
+
+def _metrics_path(gcc_root: Path, session_id: str) -> Path:
+    metrics_dir = gcc_root / ".GCC" / "metrics" / "session"
+    metrics_dir.mkdir(parents=True, exist_ok=True)
+    return metrics_dir / f"{session_id}.json"
+
+
+def _load_session_metrics(path: Path) -> dict:
+    if path.exists():
+        try:
+            return json.loads(path.read_text())
+        except Exception:
+            pass
+    return {}
+
+
+def _save_session_metrics(path: Path, data: dict) -> None:
+    path.write_text(json.dumps(data, indent=2))
+
+
+def _tool_summary(tool_name: str, tool_input: dict) -> str:
+    """Extract a one-line summary from tool_input for commit messages."""
+    if tool_name in ("Write", "Edit", "MultiEdit"):
+        return tool_input.get("file_path", tool_input.get("path", "unknown"))
+    elif tool_name == "Bash":
+        cmd = tool_input.get("command", "")
+        # Truncate long commands
+        return cmd[:80] if len(cmd) > 80 else cmd
+    return str(tool_input)[:80]
+
+
+# ---------------------------------------------------------------------------
+# Hook handlers
+# ---------------------------------------------------------------------------
+
+
+def handle_pre_tool_use() -> None:
+    """
+    PreToolUse hook handler.
+
+    - Records session start timestamp to .GCC/metrics/session/<session_id>.json
+      if a .GCC/ repo is found.
+    - Always approves.
+    """
+    try:
+        event = _read_event()
+        session_id = event.get("session_id", "unknown")
+
+        gcc_root = _gcc_root()
+        if gcc_root:
+            path = _metrics_path(gcc_root, session_id)
+            metrics = _load_session_metrics(path)
+            if "start_ts" not in metrics:
+                # First tool call this session — record start
+                metrics = {
+                    "session_id": session_id,
+                    "start_ts": time.time(),
+                    "tool_calls": 0,
+                    "commits": 0,
+                }
+            metrics["tool_calls"] = metrics.get("tool_calls", 0) + 1
+            try:
+                _save_session_metrics(path, metrics)
+            except Exception:
+                pass  # never fail
+    except Exception:
+        pass  # never fail the hook
+
+    _write_response({"decision": "approve"})
+
+
+def handle_post_tool_use() -> None:
+    """
+    PostToolUse hook handler.
+
+    Captures write tools (Write, Edit, MultiEdit, Bash) and auto-commits
+    them to .GCC/.  Read-only tools (Read, Glob, Grep, etc.) are ignored.
+    Always approves.
+    """
+    try:
+        event = _read_event()
+        tool_name = event.get("tool_name", "")
+        tool_input = event.get("tool_input") or {}
+        session_id = event.get("session_id", "unknown")
+
+        if tool_name in _WRITE_TOOLS:
+            repo = _find_gcc_repo()
+            if repo is not None:
+                summary = _tool_summary(tool_name, tool_input)
+                commit_msg = f"auto: {tool_name} {summary}"
+                try:
+                    repo.commit(message=commit_msg)
+
+                    # Update session metrics
+                    gcc_root = _gcc_root()
+                    if gcc_root:
+                        path = _metrics_path(gcc_root, session_id)
+                        metrics = _load_session_metrics(path)
+                        metrics["commits"] = metrics.get("commits", 0) + 1
+                        _save_session_metrics(path, metrics)
+                except Exception:
+                    pass  # never fail the hook
+    except Exception:
+        pass  # never fail the hook
+
+    _write_response({"decision": "approve"})
+
+
+def handle_session_end() -> None:
+    """
+    Stop hook handler.
+
+    Reads session start timestamp from .GCC/metrics/session/<session_id>.json,
+    computes session duration, and writes final session metrics.
+    Always approves.
+    """
+    try:
+        event = _read_event()
+        session_id = event.get("session_id", "unknown")
+
+        gcc_root = _gcc_root()
+        if gcc_root:
+            path = _metrics_path(gcc_root, session_id)
+            metrics = _load_session_metrics(path)
+            if metrics:
+                metrics["end_ts"] = time.time()
+                try:
+                    _save_session_metrics(path, metrics)
+                except Exception:
+                    pass
+    except Exception:
+        pass  # never fail the hook
+
+    _write_response({"decision": "approve"})
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    """
+    Dispatcher for Claude Code hooks.
+
+    Usage:
+      devtorch hooks pre-tool-use
+      devtorch hooks post-tool-use
+      devtorch hooks session-end
+    """
+    if len(sys.argv) < 2:
+        # Fallback: attempt to read event and determine hook type
+        _write_response({"decision": "approve"})
+        return
+
+    hook_type = sys.argv[1]
+
+    if hook_type == "pre-tool-use":
+        handle_pre_tool_use()
+    elif hook_type == "post-tool-use":
+        handle_post_tool_use()
+    elif hook_type == "session-end":
+        handle_session_end()
+    else:
+        # Unknown hook — always approve
+        _write_response({"decision": "approve"})