sembl-stack 0.1.0__py3-none-any.whl

sembl_stack/presets.py

@@ -0,0 +1,114 @@
+"""Onboarding presets (C4) — a one-command path to a working config.
+
+Three presets cover the adoption ramp, lightest first:
+
+  * just-gate     — the wedge: gate a diff/PR with NO model and NO infra (CLI transport,
+                    so it shells the installed `sembl` — no uvx/MCP required).
+  * gate+sandbox  — see the whole loop with a deterministic mock executor (no keys): plan
+                    -> sandbox -> execute -> gate -> retry-on-BLOCK.
+  * full-loop     — a real agent (Claude Code on the operator's OAuth session) writes, the
+                    sandbox contains, Sembl gates. Swap `execute` for aider/opencode.
+
+Each preset is stored as ANNOTATED YAML (not a dumped dict) so the file a stranger lands on
+explains itself. `render()` returns that text; `config_dict()` parses it back for validation.
+"""
+from __future__ import annotations
+
+import yaml
+
+_JUST_GATE = """\
+# sembl-stack config — preset: just-gate
+# The adoption wedge: gate any diff/PR with zero model and zero infra.
+#   sembl-stack verify --diff change.patch --bounds bounds.json
+layers:
+  spec: sembl          # L2 bounds engine (ours)
+  execute: mock        # not used by `verify`; kept so `loop` still boots if you try it
+  sandbox: worktree    # L4 disposable sandbox
+  verify: sembl        # L5 gate (ours)
+transport:
+  spec: cli            # shell the installed `sembl` — no uvx/MCP needed
+  verify: cli
+loop:
+  max_attempts: 1
+  strict: true         # out-of-scope edits BLOCK
+tracing:
+  langfuse: false
+"""
+
+_GATE_SANDBOX = """\
+# sembl-stack config — preset: gate+sandbox
+# See the full loop with a deterministic mock executor (no API keys):
+#   plan -> sandbox -> execute -> gate -> retry-on-BLOCK
+#   sembl-stack loop task.yaml
+layers:
+  spec: sembl
+  execute: mock        # deterministic: misbehaves once (BLOCK), then complies (PASS)
+  sandbox: clone       # disposable local git clone — the source repo is never touched
+  verify: sembl
+transport:
+  spec: cli
+  verify: cli
+loop:
+  max_attempts: 3
+  strict: true
+tracing:
+  langfuse: false
+"""
+
+_FULL_LOOP = """\
+# sembl-stack config — preset: full-loop
+# A real agent writes, the sandbox contains, Sembl gates.
+#   requires `claude` on PATH (Claude Code, the operator's own login — no token handled).
+#   swap execute: aider | opencode to drive a different agent.
+#   sembl-stack loop task.yaml
+layers:
+  spec: sembl
+  execute: claude
+  sandbox: clone
+  verify: sembl
+transport:
+  spec: cli
+  verify: cli
+options:
+  execute:
+    model:             # blank = the operator's default model
+    timeout: 900       # seconds before the executor is treated as a failed attempt
+loop:
+  max_attempts: 3
+  strict: true
+tracing:
+  langfuse: false
+"""
+
+PRESETS: dict[str, str] = {
+    "just-gate": _JUST_GATE,
+    "gate+sandbox": _GATE_SANDBOX,
+    "full-loop": _FULL_LOOP,
+}
+
+DEFAULT_PRESET = "gate+sandbox"
+
+_STARTER_TASK = """\
+# A task for the short loop. Paths resolve relative to this file.
+text: "Add a VALUE constant to the app module, in scope, without touching infra."
+repo: "."
+# spec_path: "./specs/001-feature"   # optional: a Spec Kit feature dir / tasks.md
+"""
+
+
+def names() -> list[str]:
+    return list(PRESETS)
+
+
+def render(preset: str) -> str:
+    """The annotated YAML text for a preset (raises KeyError on an unknown name)."""
+    return PRESETS[preset]
+
+
+def config_dict(preset: str) -> dict:
+    """The preset parsed to a dict — used to validate it loads and wires."""
+    return yaml.safe_load(PRESETS[preset])
+
+
+def starter_task() -> str:
+    return _STARTER_TASK

sembl_stack/profile.py

@@ -0,0 +1,193 @@
+"""Phase-1 onboarding core — the BYO-credentials profile (pure, headless).
+
+sembl-stack provides orchestration, not inference: the user brings their own way of paying
+for model calls (their Claude Code login, their API key, a local model — or the no-AI mock
+preview). This module is the deterministic heart of that onboarding: a `Profile` dataclass
+persisted at `~/.sembl/profile.json` (user-level; distinct from the per-repo
+`.sembl/session.json`), auto-detection of what's already on the machine, a doctor-style
+preflight per runner, and the mapping onto the existing `StackConfig` layers.
+
+Security invariant (launch-credibility, do not weaken): **no key value is ever stored** —
+`key_source` holds only a pointer like `"env:ANTHROPIC_API_KEY"`, validated on save; the
+actual secret stays in the environment and is read only by the executor at runtime.
+No Textual imports here; fully unit-testable.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .doctor import Check
+
+# How the user pays for model calls. Order = preference during auto-detection.
+STRATEGIES = ["claude-login", "api-key", "local", "mock"]
+
+# runner -> default L3 executor adapter (user may override in Advanced).
+_RUNNER_EXECUTOR = {
+    "claude-login": "claude",
+    "api-key": "claude",
+    "local": "opencode",
+    "mock": "mock",
+}
+
+# Env vars we auto-detect for the api-key runner, preference order. The var's *presence*
+# is all we ever look at — the value is never read into a Profile or an artifact.
+_KEY_ENV_VARS = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY"]
+
+# key_source may only ever be a pointer: an env-var name or (post-launch) the keyring.
+_SAFE_KEY_SOURCE = re.compile(r"^(env:[A-Za-z_][A-Za-z0-9_]*|keyring)$")
+
+# model must look like a model id ("claude-opus-4-8", "tokenrouter/MiniMax-M3",
+# "ollama/llama3:8b") — short, from a tight charset, and never key-prefixed. This is the
+# second half of the security invariant: the free-form Model input is the one field a
+# user could paste an API key into, and a key there would otherwise reach profile.json,
+# argv (`--model`, visible in the process list), and run reports.
+_SAFE_MODEL = re.compile(r"^(?!sk-)[A-Za-z0-9][A-Za-z0-9._:/\-]{0,63}$")
+
+
+@dataclass
+class Profile:
+    runner: str = "mock"            # one of STRATEGIES
+    executor: str = "mock"          # L3 adapter name (claude|opencode|aider|mock)
+    model: str | None = None        # e.g. "claude-opus-4-8", "tokenrouter/MiniMax-M3"
+    key_source: str | None = None   # "env:ANTHROPIC_API_KEY" | "keyring" — NEVER the value
+    strict: bool = True
+    preset: str | None = None       # presets.py name, if the user picked one
+
+
+def path() -> Path:
+    return Path.home() / ".sembl" / "profile.json"
+
+
+def save(profile: Profile, p: Path | None = None) -> Path:
+    """Persist the profile. Refuses anything secret-shaped in `key_source` or `model`."""
+    if profile.key_source is not None and not _SAFE_KEY_SOURCE.match(profile.key_source):
+        raise ValueError(
+            "key_source must be a pointer ('env:VAR_NAME' or 'keyring'), never a key value")
+    if profile.model is not None and not _SAFE_MODEL.match(profile.model):
+        raise ValueError(
+            "model must be a model id (e.g. 'claude-opus-4-8'), never an API key value")
+    p = p or path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(asdict(profile), indent=2), encoding="utf-8")
+    return p
+
+
+def load(p: Path | None = None) -> Profile | None:
+    """Read the saved profile, or None if missing OR unusable.
+
+    A corrupt/old/hand-edited file must never brick the entrypoint — unusable is treated
+    exactly like absent (re-onboard), mirroring `session.load`. A profile whose stored
+    key_source fails the pointer rule is also unusable: we never trust a secret-shaped
+    value back into memory.
+    """
+    p = p or path()
+    if not p.is_file():
+        return None
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            return None
+        prof = Profile(**{k: v for k, v in data.items() if k in Profile.__dataclass_fields__})
+    except (OSError, ValueError, TypeError):
+        return None
+    if prof.runner not in STRATEGIES:
+        return None
+    if prof.key_source is not None and (
+            not isinstance(prof.key_source, str) or not _SAFE_KEY_SOURCE.match(prof.key_source)):
+        return None
+    # The remaining fields flow straight into config/registry/argv — a hand-edited file
+    # with the wrong types (or a secret-shaped model) is unusable, same as corrupt.
+    if not isinstance(prof.executor, str) or not prof.executor:
+        return None
+    if prof.model is not None and (
+            not isinstance(prof.model, str) or not _SAFE_MODEL.match(prof.model)):
+        return None
+    if not isinstance(prof.strict, bool):
+        return None
+    if prof.preset is not None and not isinstance(prof.preset, str):
+        return None
+    return prof
+
+
+def to_stack_overrides(profile: Profile) -> dict:
+    """The dict the wizard merges into the resolved stack config.
+
+    Maps the BYO choice onto layers the loop already reads — zero new core wiring:
+    `layers.execute` (which adapter), `options.execute.model`, `loop.strict`.
+    """
+    over: dict = {"layers": {"execute": profile.executor},
+                  "loop": {"strict": profile.strict}}
+    if profile.model:
+        over["options"] = {"execute": {"model": profile.model}}
+    return over
+
+
+def detect() -> Profile:
+    """Auto-detect the strongest BYO option present; onboarding preselects the result.
+
+    Preference: an existing `claude` install (their Claude Code login — token-free) >
+    a known API key in env > a local-model CLI (`opencode`) > the mock preview.
+    Detection only checks binary/env *presence* — never reads a key value.
+    """
+    if shutil.which("claude"):
+        return Profile(runner="claude-login", executor="claude")
+    for var in _KEY_ENV_VARS:
+        if os.environ.get(var):
+            executor = "claude" if var == "ANTHROPIC_API_KEY" else "opencode"
+            return Profile(runner="api-key", executor=executor, key_source=f"env:{var}")
+    if shutil.which("opencode"):
+        return Profile(runner="local", executor="opencode")
+    return Profile()   # mock — the keyless mechanics preview, never the hero path
+
+
+def preflight(profile: Profile) -> list[Check]:
+    """Doctor-style checks that this runner can actually run — before onboarding proceeds.
+
+    On failure the wizard shows `hint` (the one concrete fix) and stays on the screen;
+    a runner that can't run is never persisted as the profile.
+    """
+    checks: list[Check] = []
+    if profile.executor == "mock":
+        checks.append(Check("executor: mock", True, "no binary needed", required=False))
+    else:
+        # Checked even when runner == "mock": an Advanced executor override means a real
+        # binary will run, and a profile that can't run must never be persisted.
+        from .doctor import _EXECUTOR_BINARY   # single source of binary names + install hints
+        binary, hint = _EXECUTOR_BINARY.get(profile.executor, (profile.executor, ""))
+        found = shutil.which(binary)
+        checks.append(Check(f"executor: {profile.executor}", found is not None,
+                            found or "not found", hint))
+
+    if profile.runner == "mock":
+        checks.append(Check("runner: mock", True, "no credentials needed", required=False))
+    elif profile.runner == "api-key":
+        var = (profile.key_source or "")[len("env:"):] if (
+            profile.key_source or "").startswith("env:") else ""
+        ok = bool(var) and bool(os.environ.get(var))
+        checks.append(Check(
+            f"api key ({var or 'no env var chosen'})", ok,
+            "set in env" if ok else "not set",
+            f"set {var or 'your provider API key'} in your environment — sembl only ever "
+            "reads it from there at runtime, never stores it"))
+    elif profile.runner == "claude-login":
+        # Binary presence is the cheap proxy; an un-logged-in `claude` fails loudly on
+        # first use with its own login prompt, which is the right UX anyway. Checked
+        # against `claude` itself — the executor may be a different binary.
+        checks.append(Check(
+            "claude login", shutil.which("claude") is not None,
+            "uses your existing Claude Code session (token-free)",
+            "run `claude` once and log in", required=False))
+    return checks
+
+
+def ready(checks: list[Check]) -> tuple[bool, str]:
+    """(ok, first concrete fix) — the wizard's proceed/stay decision."""
+    for c in checks:
+        if c.required and not c.ok:
+            return False, c.hint or f"{c.name}: {c.detail}"
+    return True, ""

sembl_stack/reconciliation.py

@@ -0,0 +1,138 @@
+"""Advisory SpecGraph-to-code-graph reconciliation.
+
+This is not a gate. It gives a human a compact drift report from two already
+materialized graphs. The code graph is supplied as JSON so the current stage can
+consume codebase-memory-mcp output without making that MCP a package dependency.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import PurePosixPath
+
+from .artifacts import ReconciliationReport, SpecGraph
+
+
+def reconcile_spec_code(spec_graph: SpecGraph, code_graph: dict) -> ReconciliationReport:
+    """Compare declared spec concepts against a supplied code graph JSON payload."""
+    spec_concepts = _spec_concepts(spec_graph)
+    code_terms, code_files = _code_terms(code_graph)
+
+    findings: list[dict] = []
+    if not code_terms and not code_files:
+        return ReconciliationReport(
+            status="UNKNOWN",
+            summary="code graph had no comparable nodes or files",
+            findings=[{
+                "severity": "info",
+                "kind": "missing_code_graph",
+                "message": "No code graph concepts were supplied for reconciliation.",
+            }],
+            data=_counts(spec_graph, code_graph),
+        )
+
+    for concept in spec_concepts:
+        if concept["type"] in ("editable_path", "forbidden_area"):
+            if concept["type"] == "editable_path" and not _path_covered(
+                    concept["name"], code_files):
+                findings.append({
+                    "severity": "info",
+                    "kind": "scope_without_code_match",
+                    "spec_node": concept["id"],
+                    "message": f"Editable path not present in code graph: {concept['name']}",
+                })
+            continue
+
+        if not _term_covered(concept["name"], code_terms):
+            findings.append({
+                "severity": "warn",
+                "kind": "spec_concept_without_code_match",
+                "spec_node": concept["id"],
+                "concept_type": concept["type"],
+                "message": f"Spec concept not found in code graph: {concept['name']}",
+            })
+
+    status = "DIVERGENT" if any(f["severity"] == "warn" for f in findings) else "ALIGNED"
+    summary = (
+        "spec/code divergence found"
+        if status == "DIVERGENT"
+        else "spec concepts are represented in the supplied code graph"
+    )
+    return ReconciliationReport(
+        status=status,
+        summary=summary,
+        findings=findings,
+        data=_counts(spec_graph, code_graph),
+    )
+
+
+def _spec_concepts(spec_graph: SpecGraph) -> list[dict]:
+    keep = {"route", "entity", "data_rule", "editable_path", "forbidden_area"}
+    return [
+        {"id": n.get("id", ""), "type": n.get("type", ""), "name": n.get("name", "")}
+        for n in spec_graph.nodes
+        if n.get("type") in keep and n.get("name")
+    ]
+
+
+def _code_terms(code_graph: dict) -> tuple[set[str], set[str]]:
+    nodes = _nodes_from_payload(code_graph)
+    terms: set[str] = set()
+    files: set[str] = set()
+    for node in nodes:
+        for key in ("name", "qualified_name", "label", "route", "path"):
+            value = node.get(key)
+            if isinstance(value, str):
+                terms.update(_tokens(value))
+        for key in ("file", "file_path", "path"):
+            value = node.get(key)
+            if isinstance(value, str):
+                files.add(_norm_path(value))
+                terms.update(_tokens(value))
+    return terms, files
+
+
+def _nodes_from_payload(payload) -> list[dict]:
+    if isinstance(payload, list):
+        return [n for n in payload if isinstance(n, dict)]
+    if not isinstance(payload, dict):
+        return []
+    if isinstance(payload.get("nodes"), list):
+        return [n for n in payload["nodes"] if isinstance(n, dict)]
+    if isinstance(payload.get("results"), list):
+        return [n for n in payload["results"] if isinstance(n, dict)]
+    return []
+
+
+def _term_covered(name: str, code_terms: set[str]) -> bool:
+    tokens = _tokens(name)
+    return bool(tokens) and all(token in code_terms for token in tokens)
+
+
+def _path_covered(path: str, code_files: set[str]) -> bool:
+    needle = _norm_path(path)
+    if not needle:
+        return True
+    if needle.endswith("/"):
+        return any(p.startswith(needle) for p in code_files)
+    return needle in code_files or any(PurePosixPath(p).match(needle) for p in code_files)
+
+
+def _tokens(value: str) -> set[str]:
+    value = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", value)
+    return {
+        token
+        for token in re.split(r"[^a-z0-9]+", value.lower())
+        if token and token not in {"api", "src", "app", "py", "ts", "tsx", "js", "jsx"}
+    }
+
+
+def _norm_path(path: str) -> str:
+    return path.replace("\\", "/").strip().lstrip("./")
+
+
+def _counts(spec_graph: SpecGraph, code_graph: dict) -> dict:
+    return {
+        "spec_nodes": len(spec_graph.nodes),
+        "spec_edges": len(spec_graph.edges),
+        "code_nodes": len(_nodes_from_payload(code_graph)),
+    }

sembl_stack/registry.py

@@ -0,0 +1,91 @@
+"""Adapter registry — the swap mechanism.
+
+`sembl.stack.yaml` names an adapter per layer; the registry resolves the name to a
+class. Register a new implementation here (or via entry points later) and it becomes
+swappable with a one-line config change.
+"""
+from __future__ import annotations
+
+from .adapters.execute_aider import AiderExecutor
+from .adapters.execute_claude import ClaudeCodeExecutor
+from .adapters.execute_mock import MockExecutor
+from .adapters.execute_opencode import OpenCodeExecutor
+from .adapters.deploy_vercel import VercelDeployAdapter
+from .adapters.merge_git import GitMergeAdapter
+from .adapters.postdeploy_http import HttpPostDeployGate
+from .adapters.sandbox_worktree import WorktreeSandbox
+from .adapters.spec_sembl import SemblSpecAdapter
+from .adapters.verify_sembl import SemblVerifyAdapter
+from .adapters.codegraph_cbm import CbmCodeGraph
+from .adapters.review_mock import MockReviewAdapter
+from .adapters.review_coderabbit import CodeRabbitReviewAdapter
+from .adapters.review_llm import LLMReviewAdapter
+from .contextgraph import SymgraphGraph
+
+# layer -> { adapter name -> factory(transport, mcp_server, opts) }
+# opts is the per-layer `options:` block from sembl.stack.yaml (adapter-specific knobs
+# like which model to drive) — keeps tuning a config change, not a code change.
+_REGISTRY: dict[str, dict[str, object]] = {
+    "spec": {
+        "sembl": lambda t, s, o: SemblSpecAdapter(transport=t, mcp_server=s),
+    },
+    "execute": {
+        "mock": lambda t, s, o: MockExecutor(),
+        "opencode": lambda t, s, o: OpenCodeExecutor(
+            model=o.get("model"), timeout=o.get("timeout", 900)),
+        "claude": lambda t, s, o: ClaudeCodeExecutor(
+            model=o.get("model"), timeout=o.get("timeout", 900)),
+        "aider": lambda t, s, o: AiderExecutor(
+            model=o.get("model"), timeout=o.get("timeout", 900)),
+    },
+    "sandbox": {
+        "worktree": lambda t, s, o: WorktreeSandbox(),   # back-compat name
+        "clone": lambda t, s, o: WorktreeSandbox(),       # disposable local clone
+    },
+    "verify": {
+        "sembl": lambda t, s, o: SemblVerifyAdapter(transport=t, mcp_server=s),
+    },
+    "context": {                                          # L1 semantic graph (optional)
+        "symgraph": lambda t, s, o: SymgraphGraph(timeout=o.get("timeout", 300)),
+        "none": lambda t, s, o: None,
+    },
+    "codegraph": {                                        # L5.5 code graph for reconcile
+        "cbm": lambda t, s, o: CbmCodeGraph(
+            binary=o.get("binary", "codebase-memory-mcp"),
+            timeout=o.get("timeout", 600), limit=o.get("limit", 5000)),
+        "none": lambda t, s, o: None,
+    },
+    "review": {
+        "mock": lambda t, s, o: MockReviewAdapter(),
+        "coderabbit": lambda t, s, o: CodeRabbitReviewAdapter(
+            binary=o.get("binary", "coderabbit"), timeout=o.get("timeout", 600)),
+        "llm": lambda t, s, o: LLMReviewAdapter(          # BYO agent CLI (claude/opencode)
+            binary=o.get("binary", "claude"), model=o.get("model"),
+            timeout=o.get("timeout", 600)),
+    },
+    "merge": {
+        "git": lambda t, s, o: GitMergeAdapter(timeout=o.get("timeout", 300)),
+    },
+    "deploy": {
+        "vercel": lambda t, s, o: VercelDeployAdapter(timeout=o.get("timeout", 1800)),
+    },
+    "postdeploy": {
+        "http": lambda t, s, o: HttpPostDeployGate(
+            health_path=o.get("health_path", "/"), expect_json=o.get("expect_json")),
+    },
+}
+
+
+def build(layer: str, name: str, transport: str, mcp_server: list[str],
+          opts: dict | None = None):
+    try:
+        factory = _REGISTRY[layer][name]
+    except KeyError:
+        avail = ", ".join(_REGISTRY.get(layer, {})) or "(none)"
+        raise SystemExit(
+            f"Unknown {layer} adapter '{name}'. Available: {avail}")
+    return factory(transport, mcp_server, opts or {})
+
+
+def names(layer: str) -> list[str]:
+    return list(_REGISTRY.get(layer, {}))