sembl-stack 0.1.0__py3-none-any.whl

sembl_stack/__init__.py

@@ -0,0 +1,3 @@
+"""sembl-stack — an open, swappable spec-driven coding factory."""
+
+__version__ = "0.1.0"

sembl_stack/adapters/_redact.py

@@ -0,0 +1,19 @@
+"""Redaction helper for adapter artifacts.
+
+Third-party process output (HTTP health bodies, CLI stdout/stderr, reviewer output) can carry
+debug pages, stack traces, env-shaped values, diff snippets, or auth errors. Persisting it raw
+into `.sembl/runs/<id>/` would violate the no-secrets-in-artifacts invariant. We keep only a
+non-reversible fingerprint: byte count + sha256. That preserves "output existed / did it change"
+signal without ever serializing the content.
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+def summarize(text) -> dict:
+    """Reduce arbitrary third-party text to {bytes, sha256} — never the content itself."""
+    if text is None:
+        return {"bytes": 0, "sha256": None}
+    raw = text if isinstance(text, bytes) else str(text).encode("utf-8", "replace")
+    return {"bytes": len(raw), "sha256": hashlib.sha256(raw).hexdigest()}

sembl_stack/adapters/base.py

@@ -0,0 +1,179 @@
+"""The platform contract.
+
+The data types are the canonical artifacts (see `sembl_stack/artifacts.py`); the
+Protocols below are what an adapter must satisfy to be swappable into a layer. Re-exported
+here so adapters import everything they need from one place.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from typing import Protocol, runtime_checkable
+
+from ..artifacts import (  # noqa: F401  (re-exported for adapters)
+    Bounds,
+    Change,
+    Context,
+    Delivery,
+    ExecutionResult,
+    MergeRecord,
+    ReconciliationReport,
+    ReviewReport,
+    SpecGraph,
+    Task,
+    Trace,
+    Verdict,
+)
+
+
+# --- Shared adapter helpers ---------------------------------------------------
+
+def changed_files_from_diff(diff: str) -> list[str]:
+    """Files touched by a unified git diff, order-preserved and de-duplicated.
+
+    Reads BOTH the `diff --git a/… b/…` headers and the `+++ b/…` markers, unioned:
+      * the `diff --git` header names a file even when it has no `+++` hunk — e.g. an
+        EMPTY new file an errored agent created. A `+++`-only parser silently drops it,
+        and the gate then flags a spurious "unreported change";
+      * the `+++ b/` marker is the fallback for a diff fragment that arrives without a
+        full header.
+    `/dev/null` (the add/delete sentinel) is skipped. Every executor adapter uses this
+    one parser so Claude/OpenCode/Aider report changed files consistently.
+    """
+    seen: set[str] = set()
+    out: list[str] = []
+
+    def add(path: str) -> None:
+        path = path.strip()
+        if path and path != "/dev/null" and path not in seen:
+            seen.add(path)
+            out.append(path)
+
+    for line in diff.splitlines():
+        if line.startswith("diff --git "):
+            _, _, tail = line.partition(" b/")
+            if tail:
+                add(tail)
+        elif line.startswith("+++ "):
+            marker = line[4:]
+            if marker.startswith("b/"):
+                marker = marker[2:]
+            add(marker.split("\t", 1)[0])     # drop a trailing tab-timestamp if present
+    return out
+
+
+# Env-var names whose values are credentials; a secret only ever lives in the
+# environment, so an executor CLI echoing one (e.g. in an auth error) is the one
+# path it could reach a persisted run artifact. Scrubbed by value below.
+_SECRET_ENV_NAME = re.compile(r"(API_KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)S?$", re.IGNORECASE)
+# Generic provider-key shapes (sk-ant-…, sk-proj-…, sk-or-v1-…) as a second net.
+_SECRET_TOKEN = re.compile(r"sk-[A-Za-z0-9_\-]{8,}")
+
+
+def scrub_secrets(text: str) -> str:
+    """Redact anything secret-shaped before it reaches a run artifact.
+
+    Executor stdout/stderr is persisted into `.sembl/runs/<id>/change.json` for
+    debuggability; the security invariant (no key value ever stored) must hold even
+    when a CLI misbehaves and echoes a credential. Env values are compared in memory
+    only — nothing read here is ever written anywhere except as its redaction marker.
+    """
+    if not text:
+        return text
+    for name, value in os.environ.items():
+        if len(value) >= 8 and _SECRET_ENV_NAME.search(name):
+            text = text.replace(value, f"[redacted:{name}]")
+    return _SECRET_TOKEN.sub("[redacted:key]", text)
+
+
+def run_executor(cmd: list[str], cwd: str, timeout: int, **run_kwargs):
+    """Run an executor subprocess, turning a timeout into a structured signal.
+
+    Returns ``(returncode, stdout, stderr, timed_out)``. A `subprocess.TimeoutExpired`
+    is caught here (its partial stdout/stderr preserved) instead of being allowed to
+    propagate and abort the whole loop — the caller records `timed_out` in the report so
+    the gate stage can convert it to a BLOCK rather than a crash.
+    """
+    try:
+        # encoding/errors explicit: agents emit UTF-8 (box-drawing, emoji, ✓). The default
+        # text=True decodes with the locale codec (cp1252 on Windows), which crashes the
+        # stdout reader thread mid-run and silently loses the output. Decode as UTF-8 and
+        # replace undecodable bytes so capture never aborts the loop.
+        proc = subprocess.run(
+            cmd, cwd=cwd, capture_output=True, text=True, timeout=timeout,
+            encoding="utf-8", errors="replace", **run_kwargs)
+        return proc.returncode, proc.stdout or "", proc.stderr or "", False
+    except subprocess.TimeoutExpired as exc:
+        out, err = exc.stdout or "", exc.stderr or ""
+        if isinstance(out, bytes):
+            out = out.decode("utf-8", "replace")
+        if isinstance(err, bytes):
+            err = err.decode("utf-8", "replace")
+        return -1, out, err, True
+
+
+# --- Layer interfaces (Protocols) ---------------------------------------------
+
+class Sandbox(Protocol):              # an open sandbox handle (from L4)
+    workdir: str
+    def diff(self) -> str: ...
+    def close(self) -> None: ...
+
+
+@runtime_checkable
+class SpecAdapter(Protocol):         # L2: Task -> Bounds
+    def plan(self, task: Task) -> Bounds: ...
+
+
+@runtime_checkable
+class SandboxAdapter(Protocol):      # L4: Change -> Change (contained)
+    def open(self, repo: str) -> Sandbox: ...
+
+
+@runtime_checkable
+class ExecuteAdapter(Protocol):      # L3: Task+Bounds(+Context) -> Change
+    def run(self, task: Task, bounds: Bounds, sandbox: Sandbox,
+            feedback: str | None) -> ExecutionResult: ...
+
+
+@runtime_checkable
+class VerifyAdapter(Protocol):       # L5: Change+Bounds -> Verdict
+    def verify(self, bounds: Bounds, result: ExecutionResult,
+               strict: bool) -> Verdict: ...
+
+
+@runtime_checkable
+class ReconcileAdapter(Protocol):    # L5.5: SpecGraph+CodeGraph -> report
+    def reconcile(self, spec_graph: SpecGraph, code_graph: dict) -> ReconciliationReport:
+        ...
+
+
+@runtime_checkable
+class MergeAdapter(Protocol):        # L6.5: Verdict(PASS) -> MergeRecord
+    def merge(self, repo: str, *, into: str = "main", source: str = "HEAD",
+              no_ff: bool = True, message: str | None = None) -> MergeRecord:
+        ...
+
+
+@runtime_checkable
+class DeployAdapter(Protocol):       # L7: Verdict(PASS) -> Delivery; rollback reverts it
+    def deploy(self, repo: str, *, production: bool = False,
+               prebuilt: bool = False) -> Delivery:
+        ...
+
+    def rollback(self, repo: str, *, to: str | None = None) -> Delivery:
+        ...
+
+
+@runtime_checkable
+class PostDeployAdapter(Protocol):   # L8: Delivery -> Verdict
+    def verify(self, delivery: Delivery, *, health_path: str = "/",
+               timeout_s: float = 10.0) -> Verdict:
+        ...
+
+
+@runtime_checkable
+class ReviewAdapter(Protocol):       # L5.5 quality: a diff -> ReviewReport (advisory)
+    def review(self, diff: str, *, reviewer_hint: str = "") -> ReviewReport:
+        ...

sembl_stack/adapters/codegraph_cbm.py

@@ -0,0 +1,95 @@
+"""L5.5 code-graph source — drive codebase-memory-mcp (CBM) headlessly.
+
+reconcile (S9) compares a SpecGraph against a code graph. Previously the code graph was a
+hand-passed JSON file; this adapter produces it LIVE from a real CBM index so a per-PR reconcile
+needs no manual step. CBM is driven via its single-shot CLI (`cbm cli <tool> <json-args>`) — the
+same subprocess containment as the symgraph adapter, never a package dependency. Advisory only: a
+failure returns an empty graph (reconcile then reports UNKNOWN), never an exception that could be
+mistaken for a gate.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class CbmCodeGraph:
+    """Drives the codebase-memory-mcp binary to export a code graph for reconciliation."""
+
+    def __init__(self, binary: str = "codebase-memory-mcp", timeout: int = 600,
+                 limit: int = 5000):
+        self.binary = binary
+        self.timeout = timeout
+        self.limit = limit
+
+    def _exe(self) -> str | None:
+        return shutil.which(self.binary)
+
+    def available(self) -> bool:
+        return self._exe() is not None
+
+    def _run(self, tool: str, payload: dict) -> dict:
+        exe = self._exe()
+        if not exe:
+            return {}
+        try:
+            proc = subprocess.run(
+                [exe, "cli", tool, json.dumps(payload)],
+                capture_output=True, text=True, encoding="utf-8", errors="replace",
+                timeout=self.timeout)
+        except (OSError, subprocess.TimeoutExpired):
+            return {}
+        return _parse_json(proc.stdout)
+
+    def _project_slug(self, repo: str) -> str | None:
+        target = _norm(str(Path(repo).resolve()))
+        listing = self._run("list_projects", {})
+        for proj in listing.get("projects", []):
+            if _norm(proj.get("root_path", "")) == target and proj.get("name"):
+                return proj["name"]
+        return None
+
+    def code_graph(self, repo: str, *, index: bool = True) -> dict:
+        """Return a CBM code-graph payload `{"results":[...]}` reconcile can consume.
+
+        Indexes the repo (idempotent refresh), resolves the project slug via CBM's own
+        list_projects mapping, then pulls every node with a broad pattern. Returns `{}` on any
+        failure — reconcile degrades to UNKNOWN, never blocks.
+        """
+        if index:
+            # CBM's tool contract requires `repo_path` (`path` is silently rejected);
+            # `mode: fast` skips similarity/semantic edges — reconcile only needs symbols.
+            self._run("index_repository",
+                      {"repo_path": str(Path(repo).resolve()), "mode": "fast"})
+        slug = self._project_slug(repo)
+        if not slug:
+            return {}
+        return self._run(
+            "search_graph",
+            {"project": slug, "name_pattern": ".", "limit": self.limit})
+
+
+def _norm(p: str) -> str:
+    return p.replace("\\", "/").strip().rstrip("/").lower()
+
+
+def _parse_json(text: str | None) -> dict:
+    """Parse CBM stdout, tolerating a leading `level=info ...` log line."""
+    if not text:
+        return {}
+    try:
+        out = json.loads(text)
+        return out if isinstance(out, dict) else {}
+    except json.JSONDecodeError:
+        pass
+    for line in text.splitlines():
+        line = line.strip()
+        if line.startswith("{"):
+            try:
+                out = json.loads(line)
+                return out if isinstance(out, dict) else {}
+            except json.JSONDecodeError:
+                continue
+    return {}

sembl_stack/adapters/deploy_vercel.py

@@ -0,0 +1,215 @@
+"""L7 deploy adapter for Vercel CLI.
+
+The stage owns the Delivery artifact, not the hosting mechanism. Credentials are
+left to the local Vercel CLI environment (`vercel login`, `VERCEL_TOKEN`, or linked
+project config) and are never copied into the artifact.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+from ._redact import summarize
+from .base import Delivery
+
+_URL_RE = re.compile(r"https://[^\s]+")
+
+
+class VercelDeployAdapter:
+    def __init__(self, timeout: int = 1800, yes: bool = True):
+        self.timeout = timeout
+        self.yes = yes
+
+    def available(self) -> bool:
+        return bool(_resolve_vercel())
+
+    def deploy(self, repo: str, *, production: bool = False,
+               prebuilt: bool = False) -> Delivery:
+        repo_path = str(Path(repo).resolve())
+        cmd = _resolve_vercel()
+        if not cmd:
+            return Delivery(target="vercel", status="failed",
+                            data={"reason": "vercel CLI not found on PATH"})
+        if prebuilt:
+            cmd.append("deploy")
+            cmd.append("--prebuilt")
+        if production:
+            cmd.append("--prod")
+        if self.yes:
+            cmd.append("--yes")
+
+        t0 = time.perf_counter()
+        try:
+            proc = subprocess.run(
+                cmd, cwd=repo_path, capture_output=True, text=True,
+                encoding="utf-8", errors="replace", timeout=self.timeout)
+        except subprocess.TimeoutExpired as exc:
+            return Delivery(
+                target="vercel",
+                status="failed",
+                data={
+                    "reason": "timeout",
+                    "latency_s": round(time.perf_counter() - t0, 3),
+                    "command": _safe_command(cmd),
+                    "stdout": summarize(exc.stdout),
+                    "stderr": summarize(exc.stderr),
+                },
+            )
+
+        stdout = proc.stdout or ""
+        stderr = proc.stderr or ""
+        url = _last_url(stdout) or _last_url(stderr)
+        status = "deployed" if proc.returncode == 0 and url else "failed"
+        return Delivery(
+            target="vercel",
+            url=url,
+            status=status,
+            data={
+                "production": production,
+                "prebuilt": prebuilt,
+                "returncode": proc.returncode,
+                "latency_s": round(time.perf_counter() - t0, 3),
+                "command": _safe_command(cmd),
+                "stdout": summarize(stdout),
+                "stderr": summarize(stderr),
+            },
+        )
+
+    def rollback(self, repo: str, *, to: str | None = None) -> Delivery:
+        """Promote the previous production deployment (Vercel rollback).
+
+        Mechanism only: the decision to roll back is the caller's (the L8 gate Verdict).
+        `to` optionally names a specific deployment URL/id to roll back to. When omitted,
+        this looks up the immediately previous production deployment and rolls back to it
+        explicitly — verified live against a real deploy: bare `vercel rollback` (no target)
+        only reports in-progress rollback *status* on current CLI versions ("No deployment
+        rollback in progress", exit 0) rather than performing one, so the old
+        target-less/omitted call silently never rolled anything back.
+        """
+        repo_path = str(Path(repo).resolve())
+        if not _resolve_vercel():
+            return Delivery(target="vercel", status="rollback_failed",
+                            data={"reason": "vercel CLI not found on PATH"})
+        if not to:
+            to = self._previous_production_url(repo_path)
+            if not to:
+                return Delivery(
+                    target="vercel",
+                    status="rollback_failed",
+                    data={"reason": "no previous production deployment found"},
+                )
+        cmd = _resolve_vercel() + ["rollback", to]
+        if self.yes:
+            cmd.append("--yes")
+
+        t0 = time.perf_counter()
+        try:
+            proc = subprocess.run(
+                cmd, cwd=repo_path, capture_output=True, text=True,
+                encoding="utf-8", errors="replace", timeout=self.timeout)
+        except subprocess.TimeoutExpired as exc:
+            return Delivery(
+                target="vercel",
+                status="rollback_failed",
+                data={
+                    "reason": "timeout",
+                    "latency_s": round(time.perf_counter() - t0, 3),
+                    "command": _safe_command(cmd),
+                    "stdout": summarize(exc.stdout),
+                    "stderr": summarize(exc.stderr),
+                },
+            )
+
+        stdout = proc.stdout or ""
+        stderr = proc.stderr or ""
+        url = _last_url(stdout) or _last_url(stderr)
+        status = "rolled_back" if proc.returncode == 0 else "rollback_failed"
+        return Delivery(
+            target="vercel",
+            url=url,
+            status=status,
+            data={
+                "rolled_back_to": to,
+                "returncode": proc.returncode,
+                "latency_s": round(time.perf_counter() - t0, 3),
+                "command": _safe_command(cmd),
+                "stdout": summarize(stdout),
+                "stderr": summarize(stderr),
+            },
+        )
+
+    def _previous_production_url(self, repo_path: str) -> str | None:
+        """The production deployment immediately before the current one.
+
+        `vercel ls --prod` prints a scriptable bare-URL list at the end of its output,
+        newest first — index 0 is the (bad) deployment we're rolling back FROM, index 1 is
+        the one to roll back TO. Returns None if there's no prior production deployment.
+        """
+        try:
+            proc = subprocess.run(
+                _resolve_vercel() + ["ls", "--prod"], cwd=repo_path,
+                capture_output=True, text=True, encoding="utf-8", errors="replace",
+                timeout=self.timeout)
+        except subprocess.TimeoutExpired:
+            return None
+        urls = [ln.strip() for ln in (proc.stdout or "").splitlines()
+                if ln.strip().startswith("https://")]
+        return urls[1] if len(urls) > 1 else None
+
+
+def _resolve_vercel() -> list[str]:
+    """Return the argv prefix that actually launches the Vercel CLI.
+
+    On Windows, npm installs `vercel` as a `.cmd`/`.ps1` shim (pure-JS package, no vendored
+    native binary like opencode has) — `subprocess.run(["vercel", ...])` without a shell
+    raises `FileNotFoundError` because CreateProcess can't launch a batch file directly.
+    Route through the shim's own interpreter instead. On POSIX `which` already returns the
+    real (shebang'd) executable, so it needs no wrapping.
+    """
+    exe = shutil.which("vercel")
+    if not exe:
+        return []
+    low = exe.lower()
+    if low.endswith((".cmd", ".bat")):
+        return ["cmd", "/c", exe]
+    if low.endswith(".ps1"):
+        return ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", exe]
+    return [exe]
+
+
+_DEPLOYMENT_HOST_RE = re.compile(r"^https://[^/\s]+\.vercel\.app(?:/|$)")
+
+
+def _last_url(text: str | None) -> str | None:
+    """The last *deployment* URL Vercel CLI printed — never a dashboard/API link.
+
+    Live-proof finding: the CLI interleaves other `https://` links into stdout alongside
+    the human-facing deployment URL — an `https://vercel.com/<team>/<project>/<id>`
+    dashboard "Inspect" link, and on some versions an `https://api.vercel.com/v13/
+    deployments/...` internal status-poll call. Picking the textually-last URL without
+    filtering returns one of those instead, which then silently breaks every downstream
+    health check against it. Every real deployment/preview/production URL Vercel serves
+    lives on the `*.vercel.app` domain (never `vercel.com`/`api.vercel.com`), so prefer
+    matches on that host; fall back to any match only if that's all there is.
+    """
+    urls = _URL_RE.findall(text or "")
+    preferred = [u for u in urls if _DEPLOYMENT_HOST_RE.match(u)]
+    picked = preferred or urls
+    return picked[-1].rstrip(".,)\"'") if picked else None
+
+
+def _safe_command(cmd: list[str]) -> list[str]:
+    safe: list[str] = []
+    redact_next = False
+    for part in cmd:
+        if redact_next:
+            safe.append("<redacted>")
+            redact_next = False
+            continue
+        safe.append(part)
+        if part == "--token":
+            redact_next = True
+    return safe

sembl_stack/adapters/execute_aider.py

@@ -0,0 +1,115 @@
+"""L3 executor: Aider (OSS) driven headless in the sandbox.
+
+Hands the task (plus the gate's feedback on retry, and the in-scope file list) to a
+non-interactive `aider --message ...` run inside the worktree, then reads back the diff.
+Aider resolves its own model credentials from the environment (e.g. OPENAI_API_BASE +
+OPENAI_API_KEY for an OpenAI-compatible router, or ANTHROPIC_API_KEY) — sembl-stack never
+handles a token. Requires `aider` on PATH.
+
+Why the flags:
+  --message <prompt>      run one instruction non-interactively and exit (headless).
+  --yes-always            auto-confirm (create files, apply edits) — no TTY prompts.
+  --no-auto-commits       leave edits in the WORKING TREE so the sandbox's `git diff`
+                          captures them; otherwise aider commits and the diff looks empty.
+  --no-stream / --no-check-update / --no-show-model-warnings
+                          quiet, deterministic, non-blocking startup.
+The model is a one-line config (`options.execute.model`), e.g. an `openai/<name>` route.
+"""
+from __future__ import annotations
+
+import glob
+import shutil
+import subprocess
+from pathlib import Path
+
+from .base import (
+    Bounds,
+    ExecutionResult,
+    Sandbox,
+    Task,
+    changed_files_from_diff as _changed_files,
+    run_executor,
+    scrub_secrets,
+)
+
+
+class AiderExecutor:
+    def __init__(self, model: str | None = None, timeout: int = 900):
+        self.model = model
+        self.timeout = timeout
+
+    def run(self, task: Task, bounds: Bounds, sandbox: Sandbox,
+            feedback: str | None) -> ExecutionResult:
+        exe = shutil.which("aider")
+        if not exe:
+            raise RuntimeError(
+                "L3: `aider` not found on PATH. `pip install aider-chat`, or set execute: mock.")
+
+        prompt = self._prompt(task, bounds, feedback)
+        cmd = [exe, "--yes-always", "--no-auto-commits", "--no-stream",
+               "--no-check-update", "--no-show-model-warnings", "--no-gitignore"]
+        if self.model:
+            cmd += ["--model", self.model]
+        cmd += ["--message", prompt]
+        cmd += _file_targets(bounds)          # focus aider on the in-scope files
+        rc, out, err, timed_out = run_executor(
+            cmd, cwd=sandbox.workdir, timeout=self.timeout, stdin=subprocess.DEVNULL)
+
+        _clean_aider_scratch(sandbox.workdir)   # drop aider's own .aider* artifacts
+        diff = sandbox.diff()
+        report = {
+            "files_modified": _changed_files(diff),
+            "agent": "aider",
+            "model": self.model,
+            "exit_code": rc,
+            "output": scrub_secrets(out)[-2000:],
+            "stderr": scrub_secrets(err)[-1000:],
+        }
+        if timed_out:                          # surfaced to the gate as a BLOCK, not a crash
+            report["error"] = "timeout"
+            report["timed_out"] = True
+        return ExecutionResult(diff=diff, report=report, workdir=sandbox.workdir)
+
+    @staticmethod
+    def _prompt(task: Task, bounds: Bounds, feedback: str | None) -> str:
+        lines = [task.text, ""]
+        if bounds.editable_paths:
+            lines.append("You may ONLY edit these paths: "
+                         + ", ".join(bounds.editable_paths))
+        if bounds.forbidden_areas:
+            lines.append("Never touch: " + ", ".join(bounds.forbidden_areas))
+        if feedback:
+            lines += ["", feedback]
+        return "\n".join(lines)
+
+
+def _clean_aider_scratch(workdir: str) -> None:
+    """Remove aider's own working files (`.aider*`) before the diff is captured.
+
+    Aider writes `.aider.chat.history.md`, `.aider.input.history`, and a
+    `.aider.tags.cache.v4/` dir into the working directory. With `--no-gitignore` these are
+    untracked clutter that the sandbox diff would otherwise pick up as out-of-scope edits.
+    They are aider internals, never part of the change, so we delete them in the disposable
+    cage before gating. Best-effort; failures are non-fatal.
+    """
+    for p in glob.glob(str(Path(workdir) / ".aider*")):
+        path = Path(p)
+        try:
+            if path.is_dir():
+                shutil.rmtree(path, ignore_errors=True)
+            else:
+                path.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+
+def _file_targets(bounds: Bounds) -> list[str]:
+    """The concrete files aider should add to the chat (skip directory bounds)."""
+    out = []
+    for p in bounds.editable_paths:
+        p = p.replace("\\", "/")
+        if p.endswith("/"):
+            continue                          # a directory prefix, not a file target
+        if "." in p.rsplit("/", 1)[-1]:       # looks like a file (has an extension)
+            out.append(p)
+    return out