py-harness-cli 0.3.0__py3-none-any.whl

harness/editor_kit.py

@@ -0,0 +1,265 @@
+"""Copy drop-in editor settings into a project. No model."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from harness.paths import REPO_ROOT
+
+KINDS = ("vscode", "continue", "cursor", "zed")
+
+
+def kit_dir() -> Path:
+    packaged = Path(__file__).resolve().parent / "kit_editors"
+    if packaged.is_dir():
+        return packaged
+    return REPO_ROOT / "editors"
+
+
+def looks_like_vibe_checkout(project: Path) -> bool:
+    return (project / "src" / "harness" / "cli.py").is_file()
+
+
+def install_editors(
+    project: Path,
+    kind: str,
+    *,
+    allow_writes: bool = False,
+    user_wide: bool = False,
+) -> list[Path]:
+    """Write the drop-in files for `kind`. Returns written paths."""
+    if kind not in KINDS:
+        raise ValueError(f"kind must be one of {', '.join(KINDS)}")
+    if user_wide and kind != "cursor":
+        raise ValueError("--global is only for kind cursor")
+    root = project.expanduser().resolve()
+    if not user_wide:
+        root.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    if kind == "vscode":
+        dest = root / ".vscode" / "tasks.json"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(_merge_vscode_tasks(dest), encoding="utf-8")
+        written.append(dest)
+        return written
+    if kind == "continue":
+        dest = root / ".continue" / "config.yaml"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(
+            (kit_dir() / "vscode" / "continue.yaml").read_text(encoding="utf-8"),
+            encoding="utf-8",
+        )
+        written.append(dest)
+        return written
+    if kind == "zed":
+        dest = root / ".zed" / "settings.json"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(_zed_settings(root, dest), encoding="utf-8")
+        written.append(dest)
+        return written
+    mcp_root = Path.home() if user_wide else root
+    dest = mcp_root / ".cursor" / "mcp.json"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(
+        _merge_mcp(
+            dest,
+            _cursor_server(
+                root, allow_writes=allow_writes, user_wide=user_wide
+            ),
+        ),
+        encoding="utf-8",
+    )
+    written.append(dest)
+    if not user_wide:
+        tasks = root / ".vscode" / "tasks.json"
+        tasks.parent.mkdir(parents=True, exist_ok=True)
+        tasks.write_text(_merge_vscode_tasks(tasks), encoding="utf-8")
+        written.append(tasks)
+    return written
+
+
+def next_steps(kind: str, *, allow_writes: bool = False, user_wide: bool = False) -> str:
+    """What a person does after the files are written. Printed by the CLI."""
+    if kind != "cursor":
+        return (
+            "Reload the window, then Command Palette → Tasks: Run Task → "
+            "py-harness: ask"
+        )
+    writes = (
+        "read-write"
+        if allow_writes
+        else "read-only — re-run with --allow-writes to edit files"
+    )
+    where = "every workspace (~/.cursor/mcp.json)" if user_wide else "this folder"
+    return (
+        f"py-harness is set up for {where} ({writes}).\n"
+        "1. ollama pull llama3.1:8b\n"
+        "2. Command Palette → Developer: Reload Window\n"
+        "3. Open Customize → MCP → enable py-harness\n"
+        "4. In chat: ask py-harness what compute_total returns\n"
+        "   or Tasks: Run Task → py-harness: ask\n"
+        "Do not point Override OpenAI Base URL at 127.0.0.1. "
+        "That request often leaves this machine."
+    )
+
+
+def _vscode_tasks() -> dict:
+    """Task file that runs whichever interpreter has py-harness installed.
+
+    The tasks used to call a bare `py-harness`. An editor runs a task in a
+    plain shell, and that command is only there if the install put it on
+    PATH, which a virtual environment or a --user install often does not.
+    Naming the interpreter directly works in every case.
+    """
+    template = json.loads(
+        (kit_dir() / "vscode" / "tasks.json").read_text(encoding="utf-8")
+    )
+    runner = f'"{Path(sys.executable).as_posix()}" -m harness'
+    env = None if _harness_is_importable() else {
+        "PYTHONPATH": (REPO_ROOT / "src").as_posix()
+    }
+    for task in template["tasks"]:
+        task["command"] = task["command"].replace("__RUNNER__", runner)
+        if env:
+            task["options"] = {"env": env}
+    return template
+
+
+def _merge_vscode_tasks(dest: Path) -> str:
+    incoming = _vscode_tasks()
+    if not dest.is_file():
+        return json.dumps(incoming, indent=2) + "\n"
+    try:
+        data = json.loads(dest.read_text(encoding="utf-8") or "{}")
+    except json.JSONDecodeError:
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+    labels = {task.get("label") for task in incoming.get("tasks", [])}
+    kept = [
+        task
+        for task in data.get("tasks", [])
+        if isinstance(task, dict) and task.get("label") not in labels
+    ]
+    data["version"] = incoming.get("version", data.get("version", "2.0.0"))
+    data["tasks"] = kept + incoming["tasks"]
+    incoming_inputs = incoming.get("inputs", [])
+    incoming_ids = {item.get("id") for item in incoming_inputs}
+    kept_inputs = [
+        item
+        for item in data.get("inputs", [])
+        if isinstance(item, dict) and item.get("id") not in incoming_ids
+    ]
+    if incoming_inputs or kept_inputs:
+        data["inputs"] = kept_inputs + incoming_inputs
+    return json.dumps(data, indent=2) + "\n"
+
+
+def _harness_is_importable() -> bool:
+    """True when a bare interpreter can `import harness` with no help.
+
+    An editor starts the server as a plain subprocess, without whatever
+    PYTHONPATH the person had set when they generated the file.
+    """
+    probe = subprocess.run(
+        [sys.executable, "-c", "import harness"],
+        capture_output=True,
+        env={"PATH": os.environ.get("PATH", "")},
+        check=False,
+    )
+    return probe.returncode == 0
+
+
+def _stdio_server(project: Path) -> dict:
+    """Command an editor will spawn. Absolute interpreter + project."""
+    server = {
+        "command": Path(sys.executable).as_posix(),
+        "args": ["-m", "harness", "mcp", "--project", project.as_posix()],
+    }
+    if not _harness_is_importable():
+        server["env"] = {"PYTHONPATH": (REPO_ROOT / "src").as_posix()}
+    return server
+
+
+def _cursor_server(
+    project: Path, *, allow_writes: bool, user_wide: bool = False
+) -> dict:
+    """Portable Cursor MCP. Uses ${workspaceFolder} so the file can be shared.
+
+    Cursor interpolates that variable to the folder the person has open.
+    An absolute --project would bake in one machine and one folder.
+    """
+    args = ["-m", "harness", "mcp", "--project", "${workspaceFolder}"]
+    if allow_writes:
+        args.append("--allow-writes")
+    server: dict = {
+        "type": "stdio",
+        "command": _cursor_command(project, user_wide=user_wide),
+        "args": args,
+    }
+    env = _cursor_env(project, user_wide=user_wide)
+    if env:
+        server["env"] = env
+    return server
+
+
+def _cursor_command(project: Path, *, user_wide: bool = False) -> str:
+    """A name on PATH when that is enough. Else this process's interpreter."""
+    if user_wide:
+        return Path(sys.executable).as_posix()
+    if _harness_is_importable() or looks_like_vibe_checkout(project):
+        return "python3"
+    return Path(sys.executable).as_posix()
+
+
+def _cursor_env(project: Path, *, user_wide: bool = False) -> dict[str, str]:
+    if user_wide:
+        if _harness_is_importable():
+            return {}
+        return {"PYTHONPATH": (REPO_ROOT / "src").as_posix()}
+    if looks_like_vibe_checkout(project):
+        return {"PYTHONPATH": "${workspaceFolder}/src"}
+    if not _harness_is_importable():
+        return {"PYTHONPATH": (REPO_ROOT / "src").as_posix()}
+    return {}
+
+
+def _merge_mcp(dest: Path, server: dict) -> str:
+    """Put py-harness in mcp.json. Keep every other server."""
+    data: dict = {}
+    if dest.is_file():
+        try:
+            loaded = json.loads(dest.read_text(encoding="utf-8") or "{}")
+        except json.JSONDecodeError:
+            loaded = {}
+        if isinstance(loaded, dict):
+            data = loaded
+    servers = data.setdefault("mcpServers", {})
+    if not isinstance(servers, dict):
+        servers = {}
+        data["mcpServers"] = servers
+    servers["py-harness"] = server
+    return json.dumps(data, indent=2) + "\n"
+
+
+def _zed_settings(project: Path, dest: Path) -> str:
+    """Merge py-harness into .zed/settings.json. Do not drop other keys."""
+    incoming = _stdio_server(project)
+    data: dict = {}
+    if dest.is_file():
+        try:
+            loaded = json.loads(dest.read_text(encoding="utf-8") or "{}")
+        except json.JSONDecodeError:
+            loaded = {}
+        if isinstance(loaded, dict):
+            data = loaded
+    servers = data.setdefault("context_servers", {})
+    if not isinstance(servers, dict):
+        servers = {}
+        data["context_servers"] = servers
+    servers["py-harness"] = incoming
+    return json.dumps(data, indent=2) + "\n"

harness/guard/__init__.py

@@ -0,0 +1,6 @@
+"""Checks that decide what is allowed to be written or returned.
+
+Holds the draft guard, the generate-and-retry loop, and the checks the
+agent loop applies to a proposed action. No module in this package may
+import a package that changes files.
+"""

harness/guard/fallbacks.py

@@ -0,0 +1,6 @@
+"""Fixed reply when the guard blocks twice. Never invent a secret."""
+
+PYTHON_VIBE_FALLBACK = (
+    "I can't ship that draft. Ask for a smaller local script "
+    "(stdlib, no secrets, no curl|sh) and I will try again."
+)

harness/guard/loop_guard.py

@@ -0,0 +1,57 @@
+"""Reject an action that has already been run with the same arguments.
+
+A model that is unsure what to do next will often repeat its last search.
+The tool returns the same output, the model is no better informed, and the
+step budget is spent.
+
+Only read-only actions are checked. Running the tests again after a change
+is progress, not repetition, so `run` and `patch` are never rejected here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+EXPLORE = frozenset({"glob", "grep", "read", "map", "locate", "plan", "skill"})
+_NEXT = {
+    "grep": "Action: read Path: one file from those hits.",
+    "glob": "Action: read Path: one file from that list.",
+    "map": "Action: grep Query: a symbol from the task.",
+    "locate": "Action: read Path: the file it named, or Action: done.",
+    "read": "Action: done with the answer, or Action: patch with a fix.",
+    "plan": "Take the first explore action now.",
+    "skill": "Copy the Action: block from the skill.",
+}
+
+
+def turn_key(turn) -> tuple[str, ...]:
+    return (
+        turn.action,
+        turn.path.strip(),
+        turn.query.strip(),
+        turn.pattern.strip(),
+        turn.scope.strip(),
+        turn.name.strip(),
+    )
+
+
+@dataclass
+class LoopGuard:
+    """Remembers explore keys already served in this run."""
+
+    seen: set[tuple[str, ...]] = field(default_factory=set)
+
+    def check(self, turn) -> str:
+        if turn is None or turn.action not in EXPLORE:
+            return ""
+        key = turn_key(turn)
+        if key in self.seen:
+            hint = _NEXT.get(turn.action, "Take a different action.")
+            detail = turn.path or turn.query or turn.pattern or turn.name
+            return (
+                f"already ran that exact {turn.action}"
+                + (f" ({detail})" if detail else "")
+                + f". The result has not changed. {hint}"
+            )
+        self.seen.add(key)
+        return ""

harness/guard/python_vibe.py

@@ -0,0 +1,68 @@
+"""Deterministic guard for python-vibe drafts. No model. No network.
+
+The fine-tune owns style. This only stops a few classes of output that
+must not ship: empty, leaked secrets, pipe-to-shell, or a lesion diagnosis
+(wrong surface — this is a coding harness).
+"""
+
+from __future__ import annotations
+
+import re
+
+from harness.guard.types import Finding, Outcome
+from harness.secrets import SECRET_SHAPES
+
+RULESET_VERSION = "python-vibe-harness@0.1.0"
+MAX_CHARS = 8000
+
+_FLAGS = re.IGNORECASE
+
+_RULES: tuple[tuple[str, str, re.Pattern[str]], ...] = (
+    (
+        "PV001",
+        "block",
+        re.compile(r"^\s*$"),
+    ),
+    (
+        "PV002",
+        "block",
+        re.compile(
+            "|".join(f"(?:{p.pattern})" for _name, p in SECRET_SHAPES)
+        ),
+    ),
+    (
+        "PV003",
+        "block",
+        re.compile(r"(curl|wget)\s+[^\n|]{0,200}\|\s*(?:ba)?sh\b", _FLAGS),
+    ),
+    (
+        "PV004",
+        "block",
+        re.compile(
+            r"(\b(this|that|it)(?:'s|\s+is)\s+(a\s+|an\s+)?"
+            r"(melanoma|basal cell carcinoma|skin cancer)\b"
+            r"|\byou have\s+(a\s+|an\s+)?(melanoma|skin cancer)\b)",
+            _FLAGS,
+        ),
+    ),
+)
+
+
+class PythonVibeGuard:
+    def review(self, text: str) -> Outcome:
+        findings: list[Finding] = []
+        if len(text) > MAX_CHARS:
+            findings.append(
+                Finding("PV005", "block", f"output length {len(text)} > {MAX_CHARS}")
+            )
+        for rule_id, severity, pattern in _RULES:
+            match = pattern.search(text)
+            if match:
+                findings.append(Finding(rule_id, severity, match.group(0)[:80]))
+        if findings:
+            return Outcome("block", None, tuple(findings), RULESET_VERSION)
+        return Outcome("pass", text, (), RULESET_VERSION)
+
+    def check(self, text: str, red_flags: list[str] | None = None) -> Outcome:
+        del red_flags
+        return self.review(text)

harness/guard/run.py

@@ -0,0 +1,41 @@
+"""Generate → guard → regenerate once → fixed fallback.
+
+The guard never edits its way out of a block.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Protocol
+
+from harness.guard.types import Outcome
+
+
+class Guard(Protocol):
+    def check(self, text: str, red_flags: list[str] | None = None) -> Outcome: ...
+
+
+def complete(
+    generate: Callable[[str], str],
+    guard: Guard,
+    fallback: str,
+    prompt: str,
+    *,
+    red_flags: list[str] | None = None,
+    attempts: int = 2,
+) -> Outcome:
+    last: Outcome | None = None
+    for _ in range(attempts):
+        draft = generate(prompt)
+        outcome = guard.check(draft, red_flags)
+        if outcome.output is not None:
+            return outcome
+        last = outcome
+    assert last is not None
+    return Outcome(
+        verdict="block",
+        output=fallback,
+        findings=last.findings,
+        ruleset_version=last.ruleset_version,
+        fallback=True,
+    )

harness/guard/types.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule_id: str
+    severity: str
+    excerpt: str
+
+
+@dataclass(frozen=True)
+class Outcome:
+    verdict: str
+    output: str | None
+    findings: tuple[Finding, ...]
+    ruleset_version: str
+    fallback: bool = False