sin-code-bundle 0.9.2__py3-none-any.whl

sin_code_bundle/memory.py

@@ -0,0 +1,208 @@
+"""SIN-Brain memory adapter (BR-1, Issue #14).
+
+Thin, defensive bridge to the external ``sin_brain`` package. The bundle holds
+**no** memory logic itself (that lives in SIN-Brain); this module only:
+
+- detects whether ``sin_brain`` is importable and reports tier sizes for
+  ``sin status`` (:func:`detect_env`), and
+- exposes the five memory operations (:func:`recall`, :func:`remember`,
+  :func:`forget`, :func:`pin`, :func:`link_evidence`) as thin pass-throughs that
+  the MCP ``serve`` command registers as tools.
+
+Every entry point degrades gracefully: if ``sin_brain`` is absent, detection
+reports ``available=False`` and the operations raise :class:`MemoryUnavailable`,
+which the caller turns into a clean tool-level error instead of crashing the
+server.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+PACKAGE = "sin_brain"
+
+# Canonical enums (kept in lock-step with the plan + AGENTS.md guidance).
+RECALL_SCOPES = ("recall", "archival", "graph")
+REMEMBER_KINDS = ("decision", "convention", "fix", "pitfall", "preference")
+REMEMBER_SCOPES = ("repo", "user")
+EVIDENCE_SOURCES = ("oracle", "poc", "ibd", "sckg", "adw")
+
+
+class MemoryUnavailable(RuntimeError):
+    """Raised when a memory operation is attempted without ``sin_brain``."""
+
+
+@dataclass
+class MemoryEnv:
+    """Runtime availability snapshot for ``sin status``."""
+
+    available: bool
+    db_path: str | None = None
+    tiers: dict[str, int] = field(default_factory=dict)
+    detail: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "available": self.available,
+            "db_path": self.db_path,
+            "tiers": self.tiers,
+            "detail": self.detail,
+        }
+
+
+def _tools_module():
+    """Import ``sin_brain.mcp_tools`` or raise :class:`MemoryUnavailable`."""
+    try:
+        return importlib.import_module(f"{PACKAGE}.mcp_tools")
+    except ImportError as exc:  # pragma: no cover - exercised via detect_env
+        raise MemoryUnavailable(
+            "sin-brain not installed. Install with: pip install sin-brain"
+        ) from exc
+
+
+def detect_env() -> MemoryEnv:
+    """Report whether SIN-Brain is installed and, if so, its tier sizes."""
+    if importlib.util.find_spec(PACKAGE) is None:
+        return MemoryEnv(available=False, detail="sin_brain package not importable")
+    try:
+        mod = importlib.import_module(PACKAGE)
+    except ImportError as exc:  # pragma: no cover
+        return MemoryEnv(available=False, detail=f"import error: {exc}")
+
+    db_path = None
+    tiers: dict[str, int] = {}
+    # SIN-Brain exposes an optional, cheap introspection hook. Treat any failure
+    # as "available but stats unknown" rather than unavailable.
+    stats = getattr(mod, "stats", None)
+    if callable(stats):
+        try:
+            data = stats()
+            db_path = data.get("db_path")
+            tiers = data.get("tiers", {}) or {}
+        except Exception as exc:  # noqa: BLE001 - never let stats break status
+            return MemoryEnv(available=True, detail=f"stats unavailable: {exc}")
+    return MemoryEnv(available=True, db_path=db_path, tiers=tiers, detail="ok")
+
+
+# ── Operations — thin pass-throughs to sin_brain.mcp_tools (JSON-string results) ──
+def recall(query: str, scope: str = "recall", k: int = 5) -> str:
+    """Tiered memory search. Returns JSON: ids + snippets (not full docs)."""
+    if scope not in RECALL_SCOPES:
+        raise ValueError(f"scope must be one of {RECALL_SCOPES}")
+    result = _tools_module().recall(query=query, scope=scope, k=k)
+    return result if isinstance(result, str) else json.dumps(result)
+
+
+def remember(content: str, kind: str, ttl_days: int | None = None, scope: str = "repo") -> str:
+    """Self-editing memory write. Returns JSON with the new entry id."""
+    if kind not in REMEMBER_KINDS:
+        raise ValueError(f"kind must be one of {REMEMBER_KINDS}")
+    if scope not in REMEMBER_SCOPES:
+        raise ValueError(f"scope must be one of {REMEMBER_SCOPES}")
+    result = _tools_module().remember(content=content, kind=kind, ttl_days=ttl_days, scope=scope)
+    return result if isinstance(result, str) else json.dumps(result)
+
+
+def forget(id: str) -> str:
+    """Remove a memory entry. Returns JSON status."""
+    result = _tools_module().forget(id=id)
+    return result if isinstance(result, str) else json.dumps(result)
+
+
+def pin(id: str) -> str:
+    """Pin a memory entry so it is never evicted. Returns JSON status."""
+    result = _tools_module().pin(id=id)
+    return result if isinstance(result, str) else json.dumps(result)
+
+
+def link_evidence(entity: str, verdict: str, source: str) -> str:
+    """Attach a subsystem verdict to a code entity in the evidence graph."""
+    if source not in EVIDENCE_SOURCES:
+        raise ValueError(f"source must be one of {EVIDENCE_SOURCES}")
+    result = _tools_module().link_evidence(entity=entity, verdict=verdict, source=source)
+    return result if isinstance(result, str) else json.dumps(result)
+
+
+def inject() -> str:
+    """Return SIN-Brain's AGENTS.md inject block (SB-4), or '' if unavailable.
+
+    Used by `sin agents-md` to embed the project's compiled memory context. The
+    bundle owns no formatting here — SIN-Brain returns ready-to-embed Markdown.
+    """
+    if importlib.util.find_spec(PACKAGE) is None:
+        return ""
+    try:
+        mod = importlib.import_module(PACKAGE)
+    except ImportError:
+        return ""
+    fn = getattr(mod, "inject", None)
+    if not callable(fn):
+        return ""
+    try:
+        out = fn()
+    except Exception:  # noqa: BLE001 - inject must never break callers
+        return ""
+    return out if isinstance(out, str) else ""
+
+
+# ── MCP Registration (called by `sin serve`) ───────────────────────────────
+# Kept here (not in cli.py) so the wiring is unit-testable with a fake MCP
+# object and no `mcp` dependency.
+TOOL_NAMES = ("recall", "remember", "forget", "pin", "link_evidence")
+
+
+def register_tools(mcp: Any) -> list[str]:
+    """Register the five memory tools on ``mcp`` if SIN-Brain is available.
+
+    Returns the names registered (empty when sin-brain is absent) so callers and
+    tests can assert on the wiring. Never raises on a missing package — graceful
+    degradation is the contract.
+    """
+    if not detect_env().available:
+        return []
+
+    @mcp.tool()
+    def recall_tool(query: str, scope: str = "recall", k: int = 5) -> str:
+        """Search memory tiers (recall|archival|graph). Returns ids+snippets."""
+        try:
+            return recall(query, scope=scope, k=k)
+        except (MemoryUnavailable, ValueError) as exc:
+            return json.dumps({"error": str(exc)})
+
+    @mcp.tool()
+    def remember_tool(content: str, kind: str, ttl_days: int = 0, scope: str = "repo") -> str:
+        """Persist a memory. kind: decision|convention|fix|pitfall|preference."""
+        try:
+            return remember(content, kind, ttl_days=ttl_days or None, scope=scope)
+        except (MemoryUnavailable, ValueError) as exc:
+            return json.dumps({"error": str(exc)})
+
+    @mcp.tool()
+    def forget_tool(id: str) -> str:
+        """Delete a memory entry by id."""
+        try:
+            return forget(id)
+        except MemoryUnavailable as exc:
+            return json.dumps({"error": str(exc)})
+
+    @mcp.tool()
+    def pin_tool(id: str) -> str:
+        """Pin a memory entry so it is never evicted."""
+        try:
+            return pin(id)
+        except MemoryUnavailable as exc:
+            return json.dumps({"error": str(exc)})
+
+    @mcp.tool()
+    def link_evidence_tool(entity: str, verdict: str, source: str) -> str:
+        """Attach a subsystem verdict (oracle|poc|ibd|sckg|adw) to a code entity."""
+        try:
+            return link_evidence(entity, verdict, source)
+        except (MemoryUnavailable, ValueError) as exc:
+            return json.dumps({"error": str(exc)})
+
+    return list(TOOL_NAMES)

sin_code_bundle/merge_safety.py

@@ -0,0 +1,313 @@
+"""Purpose: Pre-merge / pre-PR safety gate.
+
+Docs: merge_safety.doc.md
+
+Runs a battery of checks before allowing a merge or PR open:
+- CoDocs coverage (broken .doc.md references)
+- ceo-audit grade (cached 5 minutes per profile)
+- git diff stat (large diffs flagged)
+- secret scan (cheap substring heuristic)
+
+Returns a single ``pass: bool`` plus a list of human-readable ``blockers``
+and ``warnings``. The agent can use the verdict to decide whether to
+proceed with the merge or fix issues first.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+# Coarse secret pattern: keys/tokens/passwords in added lines.
+_SECRET_LINE_PATTERN = re.compile(
+    r"(?i)(api[_-]?key|secret|token|password|passwd|pwd|access[_-]?key)\s*[:=]\s*['\"]?[A-Za-z0-9_\-\.]{16,}"
+)
+
+# Substrings that should NEVER appear in a diff (would be a leaked secret).
+_SECRET_HINTS = (
+    "BEGIN RSA PRIVATE KEY",
+    "BEGIN OPENSSH PRIVATE KEY",
+    "BEGIN PRIVATE KEY",
+    "sk-",  # OpenAI / many SaaS keys
+    "ghp_",  # GitHub PAT
+    "github_pat_",  # GitHub fine-grained PAT
+    "xoxb-",
+    "xoxp-",  # Slack tokens
+    "AIza",  # Google API keys
+    "AKIA",  # AWS access key
+    "ASIA",
+)
+
+# Hard-coded fallback for the dev-machine layout.
+_CEO_AUDIT_FALLBACK = "/Users/jeremy/.local/bin/sin"
+
+# Max lines changed before we flag a "large diff" warning.
+_LARGE_DIFF_LINES = 1000
+
+# 5min — ceo-audit is the slow part; cache to keep pre-PR hooks snappy.
+_CEO_AUDIT_CACHE_TTL = 300
+
+
+class MergeSafety:
+    """Pre-merge / pre-PR safety gate.
+
+    Each check is independent and contributes to the final verdict.
+    All checks are best-effort — a missing CLI downgrades a check
+    to a warning, not a failure.
+    """
+
+    def __init__(self, repo_root: Optional[Path] = None) -> None:
+        self.repo_root = Path(repo_root) if repo_root else Path.cwd()
+        # Per-process cache for ceo-audit results. Key: (profile, base, head).
+        self._audit_cache: Dict[Tuple[str, str, str], Tuple[float, Dict[str, Any]]] = {}
+
+    def check(
+        self,
+        base: str = "main",
+        head: str = "HEAD",
+        profile: str = "QUICK",
+    ) -> Dict[str, Any]:
+        """Run all safety checks and return a verdict.
+
+        Args:
+            base: base ref (default ``main``).
+            head: head ref (default ``HEAD``).
+            profile: ceo-audit profile (default ``QUICK``).
+
+        Returns:
+            Dict with ``pass`` (bool), ``blockers`` (list of str),
+            ``warnings`` (list of str), ``checks`` (per-check dict),
+            and ``verdict`` ("READY" or "FIX_FIRST").
+        """
+        blockers: List[str] = []
+        warnings: List[str] = []
+        checks: Dict[str, Any] = {}
+
+        # ── 1. CoDocs coverage ───────────────────────────────────────
+        codocs = self._check_codocs()
+        checks["codocs"] = codocs
+        if codocs.get("broken", 0) > 0:
+            blockers.append(
+                f"CoDocs: {codocs['broken']} broken .doc.md reference(s) — fix before merge"
+            )
+
+        # ── 2. ceo-audit (cached) ────────────────────────────────────
+        audit = self._check_ceo_audit(profile, base, head)
+        checks["ceo_audit"] = audit
+        grade = (audit.get("grade") or "").upper()
+        if grade == "F":
+            blockers.append("ceo-audit grade F — fix critical issues before merge")
+        elif grade == "D":
+            warnings.append("ceo-audit grade D — consider improving before merge")
+        elif not audit.get("ok"):
+            # ceo-audit didn't run — downgrade to warning (don't block).
+            warnings.append(
+                f"ceo-audit could not run: {audit.get('error', 'unknown')} — verify manually"
+            )
+
+        # ── 3. git diff stat (size + secrets in lines) ───────────────
+        diff = self._check_diff(base, head)
+        checks["diff"] = diff
+        if diff.get("lines_changed", 0) > _LARGE_DIFF_LINES:
+            warnings.append(
+                f"Large diff: {diff['lines_changed']} lines changed — consider splitting"
+            )
+        secret_hits = diff.get("secret_hits", [])
+        if secret_hits:
+            blockers.append(
+                f"Diff contains possible secrets ({len(secret_hits)} line(s)) — "
+                "rotate keys and re-commit before merge"
+            )
+            checks["diff"]["secret_examples"] = secret_hits[:3]
+
+        # ── 4. Working tree must be clean ────────────────────────────
+        tree = self._check_tree()
+        checks["working_tree"] = tree
+        if not tree.get("clean", False):
+            warnings.append(
+                f"Working tree is dirty ({tree.get('changes_count', '?')} change(s)) — "
+                "commit/stash before merge"
+            )
+
+        # ── Compose verdict ──────────────────────────────────────────
+        passed = len(blockers) == 0
+        verdict = "READY" if passed else "FIX_FIRST"
+
+        return {
+            "pass": passed,
+            "verdict": verdict,
+            "blockers": blockers,
+            "warnings": warnings,
+            "checks": checks,
+            "base": base,
+            "head": head,
+            "profile": profile,
+            "timestamp": _now_iso(),
+        }
+
+    # ── helpers ─────────────────────────────────────────────────────
+    def _check_codocs(self) -> Dict[str, Any]:
+        try:
+            from . import codocs
+
+            broken = codocs.find_broken(str(self.repo_root))
+            return {
+                "ok": not bool(broken),
+                "broken": len(broken),
+                "items": [b.to_dict() for b in broken][:10],
+            }
+        except Exception as exc:
+            return {"ok": True, "broken": 0, "error": str(exc)}
+
+    def _check_ceo_audit(
+        self,
+        profile: str,
+        base: str,
+        head: str,
+    ) -> Dict[str, Any]:
+        """Run ceo-audit, with a 5-minute in-process cache."""
+        cache_key = (profile, base, head)
+        now = time.time()
+
+        if cache_key in self._audit_cache:
+            ts, data = self._audit_cache[cache_key]
+            if (now - ts) < _CEO_AUDIT_CACHE_TTL:
+                return {**data, "cache_hit": True}
+            # Stale — fall through and re-run.
+
+        try:
+            sin_bin = shutil.which("sin") or _CEO_AUDIT_FALLBACK
+            if not Path(sin_bin).exists():
+                return {"ok": False, "error": "sin CLI not installed"}
+
+            proc = subprocess.run(
+                [
+                    sin_bin,
+                    "ceo-audit",
+                    "run",
+                    str(self.repo_root),
+                    f"--profile={profile}",
+                    "--json",
+                ],
+                capture_output=True,
+                text=True,
+                timeout=180,  # 3min ceiling
+            )
+            if proc.returncode == 0 and proc.stdout.strip():
+                data = json.loads(proc.stdout)
+                result = {
+                    "ok": True,
+                    "grade": data.get("grade"),
+                    "report_path": data.get("report_path"),
+                }
+                self._audit_cache[cache_key] = (now, result)
+                return result
+            return {"ok": False, "error": proc.stderr[-300:]}
+        except (subprocess.TimeoutExpired, json.JSONDecodeError) as exc:
+            return {"ok": False, "error": str(exc)}
+        except Exception as exc:
+            return {"ok": False, "error": str(exc)}
+
+    def _check_diff(self, base: str, head: str) -> Dict[str, Any]:
+        try:
+            proc = subprocess.run(
+                ["git", "diff", "--shortstat", f"{base}...{head}"],
+                cwd=self.repo_root,
+                capture_output=True,
+                text=True,
+                timeout=15,
+            )
+            shortstat = proc.stdout.strip() if proc.returncode == 0 else ""
+            # " 3 files changed, 42 insertions(+), 17 deletions(-)"
+            lines_changed = _parse_shortstat(shortstat)
+
+            # Fetch the actual diff content for secret scan.
+            content_proc = subprocess.run(
+                ["git", "diff", f"{base}...{head}"],
+                cwd=self.repo_root,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            content = content_proc.stdout if content_proc.returncode == 0 else ""
+            secret_hits = _scan_for_secrets(content)
+
+            return {
+                "ok": True,
+                "lines_changed": lines_changed,
+                "shortstat": shortstat,
+                "secret_hits": secret_hits,
+            }
+        except subprocess.TimeoutExpired:
+            return {"ok": False, "lines_changed": 0, "secret_hits": [], "error": "git diff timeout"}
+        except Exception as exc:
+            return {"ok": False, "lines_changed": 0, "secret_hits": [], "error": str(exc)}
+
+    def _check_tree(self) -> Dict[str, Any]:
+        try:
+            proc = subprocess.run(
+                ["git", "status", "--porcelain"],
+                cwd=self.repo_root,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if proc.returncode == 0:
+                changes = proc.stdout.strip().splitlines()
+                return {"ok": True, "clean": not bool(changes), "changes_count": len(changes)}
+            return {"ok": False, "clean": False, "error": proc.stderr[-200:]}
+        except Exception as exc:
+            return {"ok": False, "clean": False, "error": str(exc)}
+
+
+# ── module-level helpers ────────────────────────────────────────────
+
+
+def _parse_shortstat(shortstat: str) -> int:
+    """Parse ``3 files changed, 42 insertions(+), 17 deletions(-)`` → 59."""
+    m = re.search(r"(\d+)\s+insertion", shortstat)
+    insertions = int(m.group(1)) if m else 0
+    m = re.search(r"(\d+)\s+deletion", shortstat)
+    deletions = int(m.group(1)) if m else 0
+    return insertions + deletions
+
+
+def _scan_for_secrets(diff_content: str) -> List[str]:
+    """Return a list of human-readable hits for any secret-like content.
+
+    Two passes:
+    1. Substring scan for known SaaS key prefixes.
+    2. Regex for ``key = "value"`` / ``token: "value"`` patterns.
+    """
+    hits: List[str] = []
+
+    # Pass 1: substring hints
+    for hint in _SECRET_HINTS:
+        if hint in diff_content:
+            # Find a representative line for the report.
+            for i, line in enumerate(diff_content.splitlines(), 1):
+                if hint in line:
+                    hits.append(f"line {i}: contains '{hint}'")
+                    break
+
+    # Pass 2: regex (only added lines, not context — context can be noisy).
+    for i, line in enumerate(diff_content.splitlines(), 1):
+        if not line.startswith("+"):
+            continue
+        if _SECRET_LINE_PATTERN.search(line):
+            hits.append(f"line {i}: key=value pattern")
+            if len(hits) >= 20:
+                break
+
+    return hits
+
+
+def _now_iso() -> str:
+    from datetime import datetime, timezone
+
+    return datetime.now(timezone.utc).isoformat()

sin_code_bundle/orchestration_worktrees.py

@@ -0,0 +1,102 @@
+"""Purpose: Isolated worktree orchestration — parallel agent tasks without conflicts.
+
+Docs: orchestration_worktrees.doc.md
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import uuid
+from pathlib import Path
+from typing import Callable, Optional
+
+
+class SINWorktreeOrchestrator:
+    """Manages isolated git worktrees for parallel agent task execution."""
+
+    def __init__(self, repo_root: Optional[Path] = None):
+        self.repo_root = repo_root or Path.cwd()
+        self.active_worktrees: list[Path] = []
+
+    def is_git_repo(self) -> bool:
+        return (self.repo_root / ".git").exists()
+
+    def create_worktree(self, branch_name: Optional[str] = None) -> dict:
+        if not self.is_git_repo():
+            return {"error": "Not a git repository. Worktree isolation requires git."}
+        # Sibling-dir layout (.sin-worktrees-<name>) keeps the worktrees
+        # OUTSIDE the repo's own working tree. That matters because git
+        # refuses to checkout branches into a worktree that overlaps the
+        # main repo's `.git`-tracked files (silent failure mode).
+        branch = (
+            branch_name or f"sin-task-{uuid.uuid4().hex[:8]}"
+        )  # 8 hex chars = 32 bits, plenty unique for worktrees
+        worktree_path = self.repo_root.parent / f".sin-worktrees-{self.repo_root.name}" / branch
+        try:
+            subprocess.run(
+                ["git", "worktree", "add", str(worktree_path), "-b", branch],
+                cwd=self.repo_root,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            self.active_worktrees.append(worktree_path)
+            return {
+                "success": True,
+                "worktree_path": str(worktree_path),
+                "branch": branch,
+                "message": f"Isolated worktree created at {worktree_path}",
+            }
+        except subprocess.CalledProcessError as e:
+            return {"error": f"Git worktree creation failed: {e.stderr}"}
+
+    def execute_in_worktree(self, worktree_path: str, task_func: Callable, *args, **kwargs) -> dict:
+        original_cwd = os.getcwd()
+        try:
+            os.chdir(worktree_path)
+            result = task_func(*args, **kwargs)
+            return {"success": True, "result": result}
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+        finally:
+            os.chdir(original_cwd)
+
+    def cleanup_worktree(self, worktree_path: str, merge_back: bool = False) -> dict:
+        path = Path(worktree_path)
+        if path not in self.active_worktrees:
+            return {"error": "Worktree not managed by this orchestrator"}
+        try:
+            if merge_back:
+                branch = path.name
+                subprocess.run(
+                    ["git", "checkout", "main"], cwd=self.repo_root, check=True, capture_output=True
+                )
+                merge_result = subprocess.run(
+                    [
+                        "git",
+                        "merge",
+                        "--no-ff",
+                        branch,
+                        "-m",
+                        f"Auto-merge from SIN worktree: {branch}",
+                    ],
+                    cwd=self.repo_root,
+                    capture_output=True,
+                    text=True,
+                )
+                if merge_result.returncode != 0:
+                    return {"error": f"Merge conflict: {merge_result.stderr}"}
+            subprocess.run(
+                ["git", "worktree", "remove", str(path), "--force"],
+                cwd=self.repo_root,
+                check=True,
+                capture_output=True,
+            )
+            self.active_worktrees.remove(path)
+            if path.exists():
+                shutil.rmtree(path)
+            return {"success": True, "message": "Worktree cleaned up successfully"}
+        except subprocess.CalledProcessError as e:
+            return {"error": f"Worktree cleanup failed: {e.stderr}"}