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

harness/server.py

@@ -0,0 +1,199 @@
+"""Serve the agent over HTTP on the local machine only.
+
+An HTTP request that reaches the agent can change files on the machine the
+server runs on. Because of that, file changes are disabled unless the
+person starting the server passes `--allow-writes`. The path restriction,
+the draft guard and the `.bak` backup all still apply; this flag is an
+additional outer control, not a replacement for them.
+
+    python -m harness serve --project ~/app
+    curl -s localhost:8090/health
+    curl -s localhost:8090/v1/layout -d '{}'
+"""
+
+from __future__ import annotations
+
+import json
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from harness.agent import Agent, AgentOptions
+from harness.openai_api import (
+    chat_completion_payload,
+    last_user_text,
+    models_payload,
+    parse_chat_body,
+)
+from harness.scan.layout import render_layout
+from harness.scan.project_brief import classify_project, render_brief
+from harness.task import looks_like_add_feature, looks_like_bugfix
+
+HOST = "127.0.0.1"
+MAX_BODY = 64 * 1024
+READ_ONLY_ROUTES = ("/v1/brief", "/v1/layout", "/v1/ask")
+WRITE_ROUTES = ("/v1/run",)
+CHAT_ROUTES = ("/v1/chat/completions", "/chat/completions")
+
+
+def make_handler(project: Path, *, allow_writes: bool, model: str):
+    class Handler(BaseHTTPRequestHandler):
+        server_version = "py-harness"
+        protocol_version = "HTTP/1.1"
+
+        def _send(self, code: int, payload: dict) -> None:
+            body = json.dumps(payload).encode("utf-8")
+            self.send_response(code)
+            self.send_header("content-type", "application/json")
+            self.send_header("content-length", str(len(body)))
+            # Say the connection is finished. A client left waiting for more
+            # blocks until its own timeout, which is what happened on Windows.
+            self.send_header("connection", "close")
+            self.end_headers()
+            self.wfile.write(body)
+            self.wfile.flush()
+            self.close_connection = True
+
+        def _body(self) -> dict | None:
+            length = int(self.headers.get("content-length") or 0)
+            if length > MAX_BODY:
+                self._send(413, {"error": "body too large"})
+                return None
+            raw = self.rfile.read(length) if length else b"{}"
+            try:
+                parsed = json.loads(raw or b"{}")
+            except json.JSONDecodeError:
+                self._send(400, {"error": "invalid json"})
+                return None
+            if not isinstance(parsed, dict):
+                self._send(400, {"error": "object required"})
+                return None
+            return parsed
+
+        def do_GET(self) -> None:  # noqa: N802
+            path = self.path.split("?", 1)[0]
+            if path in {"/v1/models", "/models"}:
+                self._send(200, models_payload(model or "llama3.1:8b"))
+                return
+            if path != "/health":
+                self._send(404, {"error": "no such route"})
+                return
+            self._send(
+                200,
+                {
+                    "ok": True,
+                    "project": str(project),
+                    "allow_writes": allow_writes,
+                    "model": model,
+                    "routes": list(READ_ONLY_ROUTES)
+                    + list(CHAT_ROUTES)
+                    + (list(WRITE_ROUTES) if allow_writes else []),
+                },
+            )
+
+        def do_POST(self) -> None:  # noqa: N802
+            path = self.path.split("?", 1)[0]
+            if path in CHAT_ROUTES:
+                self._chat()
+                return
+            if path not in READ_ONLY_ROUTES + WRITE_ROUTES:
+                self._send(404, {"error": "no such route"})
+                return
+            if path in WRITE_ROUTES and not allow_writes:
+                self._send(
+                    403,
+                    {
+                        "error": "this server is read-only",
+                        "fix": "restart it with --allow-writes",
+                    },
+                )
+                return
+            payload = self._body()
+            if payload is None:
+                return
+            scope = str(payload.get("scope") or "")
+            if path == "/v1/brief":
+                brief = classify_project(project, scope)
+                self._send(200, {"brief": render_brief(brief, scope=scope)})
+                return
+            if path == "/v1/layout":
+                self._send(200, {"layout": render_layout(project)})
+                return
+            task = str(payload.get("task") or "").strip()
+            if not task:
+                self._send(400, {"error": "task required"})
+                return
+            options = AgentOptions(
+                project=project,
+                task=task,
+                model=str(payload.get("model") or model),
+                scope=scope,
+                steps=int(payload.get("steps") or 20),
+                allow_writes=allow_writes and path in WRITE_ROUTES,
+            )
+            try:
+                result = Agent(options).run()
+            except (ValueError, OSError) as exc:
+                self._send(400, {"error": str(exc)})
+                return
+            self._send(200, result.as_dict())
+
+        def _chat(self) -> None:
+            payload = self._body()
+            if payload is None:
+                return
+            try:
+                parsed = parse_chat_body(json.dumps(payload).encode("utf-8"))
+            except ValueError as exc:
+                self._send(400, {"error": str(exc)})
+                return
+            if parsed["stream"]:
+                self._send(400, {"error": "stream is not supported; set stream false"})
+                return
+            task = last_user_text(parsed["messages"])
+            if not task:
+                self._send(400, {"error": "messages required"})
+                return
+            wants_write = looks_like_add_feature(task) or looks_like_bugfix(task)
+            if wants_write and not allow_writes:
+                self._send(
+                    403,
+                    {
+                        "error": "this server is read-only",
+                        "fix": "restart it with --allow-writes, or run "
+                        "py-harness run <project> \"<task>\" in the editor terminal",
+                    },
+                )
+                return
+            options = AgentOptions(
+                project=project,
+                task=task,
+                model=str(parsed["model"] or model),
+                allow_writes=allow_writes and wants_write,
+            )
+            try:
+                result = Agent(options).run()
+            except (ValueError, OSError) as exc:
+                self._send(400, {"error": str(exc)})
+                return
+            self._send(200, chat_completion_payload(result.summary, options.model))
+
+        def log_message(self, fmt: str, *args) -> None:
+            print(f"{self.address_string()} - {fmt % args}")
+
+    return Handler
+
+
+def serve(
+    project: Path, *, port: int = 8090, allow_writes: bool = False, model: str = ""
+) -> int:
+    handler = make_handler(project, allow_writes=allow_writes, model=model)
+    httpd = ThreadingHTTPServer((HOST, port), handler)
+    mode = "read-write" if allow_writes else "read-only"
+    print(f"py-harness on http://{HOST}:{port}  project {project}  {mode}")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        httpd.server_close()
+    return 0

harness/ship/__init__.py

@@ -0,0 +1 @@
+"""Layer: limited git / gh. Deterministic. No model."""

harness/ship/bot_pr.py

@@ -0,0 +1,221 @@
+"""Whether a pull request opened by a bot may be merged without a reader.
+
+Dependency bots open the same pull request shape every week, and most of
+them are dull enough to merge on sight. The one that is not dull looks
+exactly like the ones that are.
+
+`Bump actions/github-script from 7 to 9` reads like the rest. Its
+release notes say `require('@actions/github')` stops working and that
+`getOctokit` becomes an injected parameter, so a workflow that used
+either breaks on merge. The title carries none of that. What it does
+carry is `7` and `9`, and a first number that changed is the whole
+signal: a major bump is where breaking changes are allowed to live.
+
+So this refuses on the shape of the version, on a red or unfinished
+check, and on anything GitHub already says is not mergeable. It never
+approves; it only fails to object.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+# The bot writes two shapes, and reading only one of them missed a
+# major bump entirely. Actions get "bump x from 7 to 9"; Python
+# requirements get "update x requirement from >=0.26.0 to >=1.29.0".
+_BUMP = re.compile(
+    r"\b(?:bump|update)\s+(?P<what>\S+)"
+    r"(?:\s+requirement)?"
+    r"\s+from\s+(?P<old>[<>=~^!]*\s*v?[\w.\-]+)"
+    r"\s+to\s+(?P<new>[<>=~^!]*\s*v?[\w.\-]+)",
+    re.I,
+)
+# A requirement carries its comparator: `>=0.26.0` is version 0, not a
+# string starting with a bracket.
+_LEADING_NUMBER = re.compile(r"^[<>=~^!\s]*v?(\d+)")
+
+
+def bump_in(title: str) -> tuple[str, str, str] | None:
+    """(what, old version, new version) from a bot's title, or None."""
+    found = _BUMP.search(title or "")
+    if not found:
+        return None
+    return found.group("what"), found.group("old"), found.group("new")
+
+
+def is_a_major_bump(old: str, new: str) -> bool:
+    """Did the first number change?
+
+    Unparseable versions are not called major. Refusing everything this
+    cannot read would make the check about the parser rather than about
+    the risk, and the other reasons still apply.
+    """
+    before, after = _LEADING_NUMBER.match(old), _LEADING_NUMBER.match(new)
+    if not before or not after:
+        return False
+    return before.group(1) != after.group(1)
+
+
+# CANCELLED, SKIPPED and STALE are deliberately absent from both sets
+# below. A cancelled run did not fail; it gave no answer, usually
+# because a newer push superseded it. Naming it as a failure refused two
+# pull requests whose checks had passed.
+_FAILED = {"FAILURE", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE"}
+_RUNNING = {"PENDING", "IN_PROGRESS", "QUEUED", "EXPECTED", "WAITING", ""}
+
+
+def latest_of_each(pull: dict) -> list[dict]:
+    """One entry per check name: the most recent run of it.
+
+    A pull request keeps every run of a check, not just the current one.
+    Pushing again cancels the run in flight and starts another, so the
+    rollup holds a cancelled entry and a successful entry under the same
+    name. Reading them all as equal reported "checks are failing: readme"
+    on two pull requests whose readme check had passed forty seconds
+    after being superseded.
+    """
+    newest: dict[str, dict] = {}
+    for check in pull.get("statusCheckRollup") or []:
+        name = str(check.get("name") or check.get("context") or "a check")
+        when = str(check.get("completedAt") or check.get("startedAt") or "")
+        seen = newest.get(name)
+        if seen is None or when >= str(
+            seen.get("completedAt") or seen.get("startedAt") or ""
+        ):
+            newest[name] = check
+    return [newest[name] for name in sorted(newest)]
+
+
+def _check_state(pull: dict) -> tuple[list[str], list[str]]:
+    """(failing, unfinished) check names, counting each check once."""
+    failing, unfinished = [], []
+    for check in latest_of_each(pull):
+        name = str(check.get("name") or check.get("context") or "a check")
+        conclusion = (check.get("conclusion") or "").upper()
+        state = (check.get("state") or check.get("status") or "").upper()
+        if conclusion in _FAILED:
+            failing.append(name)
+        elif conclusion in {"", "NEUTRAL"} and state in _RUNNING:
+            unfinished.append(name)
+    return sorted(set(failing)), sorted(set(unfinished))
+
+
+def refuse_bot_merge(pull: dict, project: Path | None = None) -> str:
+    """Why this pull request needs a person. "" when nothing objects.
+
+    `project` lets a major bump be answered rather than only refused.
+    Refusing every one of them scored nought for five here: five action
+    bumps were merged, every workflow stayed green, and the rule caught
+    nothing. A refusal nobody needs is a refusal that gets switched off.
+
+    What the pull request's own checks prove is that the workflows they
+    ran still work. If every workflow using the bumped action ran green
+    here, the thing that would break has already been exercised. If some
+    did not — `Pages` is skipped on a pull request, `Celebrate merge`
+    only runs on merge — then nothing was proved and a person reads it.
+    """
+    failing, unfinished = _check_state(pull)
+    if failing:
+        return f"checks are failing: {', '.join(failing)}"
+    if unfinished:
+        return f"checks have not finished: {', '.join(unfinished)}"
+    mergeable = (pull.get("mergeable") or "").upper()
+    if mergeable == "CONFLICTING":
+        return "this branch conflicts with the base branch"
+    # The durable reason comes before the transient one. A major bump is
+    # true whatever GitHub is still working out, and it is the answer the
+    # person needs; being told to ask again would waste the trip.
+    bump = bump_in(str(pull.get("title") or ""))
+    if bump and is_a_major_bump(bump[1], bump[2]):
+        what, was, now = bump
+        unproven = (
+            unproven_workflows(project, pull, what) if project is not None else None
+        )
+        if unproven == []:
+            # Every workflow that uses it ran green on this very pull
+            # request. There is nothing left for a person to check.
+            return ""
+        where = f" It is used by {', '.join(unproven)}, which this pull " \
+                "request did not run." if unproven else ""
+        return (
+            f"{what} {was} to {now} is a major version bump. That is where "
+            "breaking changes are allowed to live, and the title never "
+            f"says so.{where} Read the release notes and merge it by hand."
+        )
+    state = (pull.get("mergeStateStatus") or "").upper()
+    if state in {"BLOCKED", "DIRTY", "BEHIND", "DRAFT"}:
+        return f"GitHub will not merge it yet: {state.lower()}"
+    # GitHub works mergeability out when asked, not in advance, so the
+    # first read of a fresh pull request often says nothing. Nothing is
+    # not the same as yes.
+    if mergeable in {"", "UNKNOWN"} or state in {"", "UNKNOWN"}:
+        return "GitHub has not worked out yet whether this merges; ask again"
+    return ""
+
+
+# Where a repository keeps the workflows a bumped action might appear in.
+WORKFLOW_DIR = Path(".github/workflows")
+_WORKFLOW_NAME = re.compile(r"^name:\s*(.+?)\s*$", re.M)
+
+
+def workflows_using(project: Path, action: str) -> dict[str, str]:
+    """{workflow name: file name} for every workflow naming this action.
+
+    An action is bumped by its repository path, `actions/checkout`, and
+    that is exactly the string a workflow writes in its `uses:` line.
+    """
+    found: dict[str, str] = {}
+    root = Path(project) / WORKFLOW_DIR
+    if not root.is_dir():
+        return found
+    for path in sorted(root.glob("*.y*ml")):
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        if action not in text:
+            continue
+        named = _WORKFLOW_NAME.search(text)
+        found[named.group(1) if named else path.stem] = path.name
+    return found
+
+
+def workflows_that_passed(pull: dict) -> set[str]:
+    """Workflows this pull request actually ran green.
+
+    A check that was skipped or cancelled proves nothing about the
+    workflow it belongs to, which is the whole point: `Pages / build`
+    comes back SKIPPED on a pull request, so a green run says nothing
+    about whether the page still deploys.
+    """
+    passed: set[str] = set()
+    failed: set[str] = set()
+    for check in latest_of_each(pull):
+        name = str(check.get("workflowName") or "")
+        if not name:
+            continue
+        if (check.get("conclusion") or "").upper() == "SUCCESS":
+            passed.add(name)
+        else:
+            failed.add(name)
+    return passed - failed
+
+
+def unproven_workflows(project: Path, pull: dict, action: str) -> list[str] | None:
+    """Workflows using this action that the pull request did not exercise.
+
+    Empty means every workflow touching the action ran green here, so
+    the bump is already tested by the thing that would break.
+
+    **None means no workflow uses it at all**, which is not the same
+    thing and must not be read as one. A Python dependency appears in no
+    workflow, so an empty list would have waved through every
+    `huggingface-hub 0 to 1` on the grounds that nothing it touches
+    failed — when nothing it touches was looked at.
+    """
+    using = workflows_using(project, action)
+    if not using:
+        return None
+    green = workflows_that_passed(pull)
+    return sorted(name for name in using if name not in green)

harness/ship/git_ship.py

@@ -0,0 +1,262 @@
+"""Limited git and gh. Deterministic. No model. No force. No main."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+from harness.paths import SECRET_NAMES
+from harness.ship.bot_pr import refuse_bot_merge
+from harness.ship.identity import co_author_line, with_co_author
+from harness.ship.ticket import identity_from_user_json, parse_ticket, render_ticket
+
+PROTECTED = frozenset({"main", "master"})
+_BRANCH = re.compile(r"^[A-Za-z0-9._][A-Za-z0-9._/-]{0,79}$")
+CO_AUTHOR = co_author_line()
+# Says on the pull request itself which tool did the work, the way a
+# commit trailer does for a commit.
+PR_FOOTER = (
+    "\n\n---\nOpened with [py-harness](https://github.com/YauhenBichel/py-harness).\n"
+    f"{CO_AUTHOR}\n"
+)
+_TIMEOUT = 45
+
+
+def _run(
+    project: Path,
+    argv: list[str],
+    *,
+    env: dict[str, str] | None = None,
+    keep_all: bool = False,
+) -> tuple[int, str]:
+    merged = os.environ.copy()
+    if env:
+        merged.update(env)
+    # The person stays the author, so the commit is theirs and appears in
+    # their history. python-vibe is recorded as a co-author instead, which
+    # GitHub renders on the commit, so it is visible where it was used.
+    try:
+        proc = subprocess.run(
+            argv,
+            cwd=project,
+            capture_output=True,
+            text=True,
+            timeout=_TIMEOUT,
+            check=False,
+            env=merged,
+        )
+    except FileNotFoundError:
+        return 127, f"{argv[0]} is not on PATH"
+    except subprocess.TimeoutExpired:
+        return 124, "timed out"
+    out = ((proc.stdout or "") + (proc.stderr or "")).strip()
+    if keep_all:
+        return proc.returncode, out
+    # Command output is cut from the front, because the end of a git or gh
+    # message is the part that says what happened. JSON has to be kept
+    # whole or it will not parse, which is what `keep_all` is for.
+    return proc.returncode, out[-4000:]
+
+
+def git_root(project: Path) -> Path | None:
+    code, out = _run(project, ["git", "rev-parse", "--show-toplevel"])
+    if code != 0:
+        return None
+    try:
+        return Path(out.splitlines()[0]).resolve()
+    except (IndexError, OSError):
+        return None
+
+
+def _in_project(project: Path) -> str:
+    root = git_root(project)
+    if root is None:
+        return "not a git repository"
+    if root != project.resolve():
+        return f"git root is {root}, not {project} — refuse"
+    return ""
+
+
+def current_branch(project: Path) -> str:
+    code, out = _run(project, ["git", "rev-parse", "--abbrev-ref", "HEAD"])
+    return out.splitlines()[0] if code == 0 and out else ""
+
+
+def github_viewer(project: Path) -> str:
+    """The signed-in `gh` login, or empty when gh is missing or logged out."""
+    code, out = _run(project, ["gh", "api", "user"], keep_all=True)
+    if code != 0:
+        return ""
+    login, _name, _email = identity_from_user_json(out)
+    return login
+
+
+def _view(project: Path, kind: str, number: str) -> str:
+    """Read one issue or pull request, and say where it points in this project.
+
+    Uses the signed-in gh user so comments from other users on the same
+    ticket are visible — the same account that can see them in the browser.
+    """
+    if not number.isdigit():
+        return f"{kind} needs Number: (digits)"
+    fields = "number,title,body,state,comments"
+    if kind == "pr":
+        fields += ",files,reviews"
+    code, out = _run(
+        project, ["gh", kind, "view", number, "--json", fields], keep_all=True
+    )
+    if code != 0:
+        return out or f"gh {kind} view {number} failed"
+    ticket = parse_ticket(
+        out,
+        project,
+        kind="pull request" if kind == "pr" else "issue",
+        viewer=github_viewer(project),
+    )
+    if ticket is None:
+        return out[:3500]
+    return render_ticket(ticket)[:3500]
+
+
+def read_issue(project: Path, number: str) -> str:
+    return _view(project, "issue", number)
+
+
+def read_pr(project: Path, number: str) -> str:
+    return _view(project, "pr", number)
+
+
+def read_ticket(project: Path, number: str, *, prefer: str = "issue") -> str:
+    """Read an issue, or a pull request when the task named a PR."""
+    first = read_pr if prefer == "pr" else read_issue
+    second = read_issue if prefer == "pr" else read_pr
+    out = first(project, number)
+    failed = "failed" in out.lower() or "could not" in out.lower() or "needs Number" in out
+    if failed:
+        other = second(project, number)
+        if "failed" not in other.lower() and "could not" not in other.lower():
+            return other
+    return out
+
+
+def make_branch(project: Path, name: str) -> str:
+    blocked = _in_project(project)
+    if blocked:
+        return blocked
+    name = name.strip().lstrip("/")
+    if not _BRANCH.match(name) or name in PROTECTED or name.startswith("-"):
+        return (
+            "bad branch name. Use proceed/short-slug "
+            "(letters, digits, . _ / -). Not main or master."
+        )
+    code, out = _run(project, ["git", "checkout", "-B", name])
+    return out or f"now on {name}" if code == 0 else out
+
+
+def commit_changes(project: Path, summary: str) -> str:
+    blocked = _in_project(project)
+    if blocked:
+        return blocked
+    message = " ".join(summary.strip().split())
+    if len(message) < 8:
+        return "commit needs Summary: of at least 8 characters (why, not what)"
+    _run(project, ["git", "add", "-A"])
+    for rel in SECRET_NAMES:
+        path = project / rel
+        if path.exists() or path.is_symlink():
+            _run(project, ["git", "reset", "-q", "--", rel])
+    code, staged = _run(project, ["git", "diff", "--cached", "--name-only"])
+    names = [line for line in staged.splitlines() if line.strip()] if code == 0 else []
+    if any(Path(name).name in SECRET_NAMES for name in names):
+        return "refusing to commit secret filenames"
+    if not names:
+        return "nothing to commit"
+    code, out = _run(project, ["git", "commit", "-m", with_co_author(message)])
+    return out or "committed" if code == 0 else out
+
+
+def push_branch(project: Path) -> str:
+    blocked = _in_project(project)
+    if blocked:
+        return blocked
+    branch = current_branch(project)
+    if not branch or branch in PROTECTED:
+        return f"refusing to push {branch or 'detached'} (not main/master)"
+    code, remotes = _run(project, ["git", "remote"])
+    if code != 0 or "origin" not in remotes.split():
+        return "no origin remote. Add origin or push yourself."
+    code, out = _run(project, ["git", "push", "-u", "origin", "HEAD"])
+    return out or "pushed" if code == 0 else out
+
+
+def create_pr(project: Path, title: str, body: str) -> str:
+    blocked = _in_project(project)
+    if blocked:
+        return blocked
+    branch = current_branch(project)
+    if branch in PROTECTED:
+        return "refusing to open a PR from main/master. Action: branch first."
+    title = " ".join(title.strip().split())
+    if len(title) < 8:
+        return "pr needs Title: of at least 8 characters"
+    text = (body.strip() or title) + PR_FOOTER
+    code, out = _run(
+        project,
+        ["gh", "pr", "create", "--title", title, "--body", text],
+    )
+    return out or "opened pull request" if code == 0 else out
+
+
+PR_FIELDS = "title,mergeable,mergeStateStatus,statusCheckRollup,author"
+
+
+def read_pr_state(project: Path, number: str) -> dict:
+    """What GitHub currently says about this pull request. {} when unknown."""
+    code, out = _run(
+        project,
+        ["gh", "pr", "view", number, "--json", PR_FIELDS],
+        keep_all=True,
+    )
+    if code != 0:
+        return {}
+    try:
+        loaded = json.loads(out)
+    except json.JSONDecodeError:
+        return {}
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def merge_pr(project: Path, number: str, *, allowed: bool) -> str:
+    if not allowed:
+        return "merge only when the task says merge"
+    if not number.isdigit():
+        return "merge needs Number: (PR digits)"
+    blocked = _in_project(project)
+    if blocked:
+        return blocked
+    state = read_pr_state(project, number)
+    # An empty read means gh could not answer. Merging anyway would make
+    # every check here optional the moment the network hiccups.
+    if not state:
+        return f"cannot read #{number} from GitHub, so not merging it"
+    refused = refuse_bot_merge(state, project)
+    if refused:
+        return f"not merging #{number}: {refused}"
+    code, out = _run(
+        project,
+        [
+            "gh",
+            "pr",
+            "merge",
+            number,
+            "--merge",
+            "--subject",
+            f"Merge pull request #{number}",
+            "--body",
+            with_co_author(f"Merged #{number}."),
+        ],
+    )
+    return out or f"merged #{number}" if code == 0 else out