sid-harness 0.3.0__py3-none-any.whl

sid_harness/git_write.py

@@ -0,0 +1,598 @@
+"""Opt-in git write path (SUB-95): branch, commit the approved diff, open a PR.
+
+The harness is read-only by default. This module is the explicit opt-in that
+finishes the everyday coder loop after a run: create a branch, commit only the
+approved diff, push that branch, and open a pull request through ``gh``.
+
+Every mutating step needs its own human approval. If no approver is supplied
+each step fails closed; a falsy decision or a raising approver refuses the step
+and stops the sequence. A partly completed sequence is reported honestly (the
+branch and any commit already made stay named in the result).
+
+Hard guards, enforced here rather than by convention:
+
+* the write target may never be ``main``/``master`` (or a sub-ref of either) —
+  validated before any approval prompt or git command is issued;
+* no force is ever built into a command (no ``-f``/``--force``/``--force-with-lease``);
+* no commit happens without an explicit approval for the commit step;
+* only the explicit approved paths are staged and committed.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .local_workspace import git_info
+
+PROTECTED_BRANCHES = frozenset({"main", "master"})
+PROTECTED_REF_PREFIX = "refs/heads/"
+
+_GIT_TIMEOUT = 60.0
+_GH_TIMEOUT = 120.0
+
+_BRANCH_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]*$")
+_REMOTE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+_WINDOWS_ABSOLUTE = re.compile(r"^[A-Za-z]:")
+_URL_RE = re.compile(r"https?://[^\s]+")
+
+_FORCE_FLAGS = frozenset(
+    {"-f", "--force", "--force-with-lease", "--force-if-includes"}
+)
+
+_MAX_DETAIL_CHARS = 2000
+
+
+class GitWriteError(RuntimeError):
+    """A git write step was refused or could not complete."""
+
+
+class _Refused(GitWriteError):
+    """An approval gate refused the step; no further mutation may happen."""
+
+
+class _Failed(GitWriteError):
+    """A git/gh command failed; the sequence stops and reports what completed."""
+
+
+Approver = Callable[["GitWriteStep"], bool]
+GitRunner = Callable[[Path, list[str]], subprocess.CompletedProcess]
+GhRunner = Callable[[list[str], Path], subprocess.CompletedProcess]
+
+
+# --------------------------------------------------------------------------- #
+# Validation helpers (pure — testable without a repo)
+# --------------------------------------------------------------------------- #
+def normalize_branch(value: object) -> str:
+    """Return a branch name without the ``refs/heads/`` prefix."""
+    text = str(value or "").strip()
+    if text.startswith(PROTECTED_REF_PREFIX):
+        text = text[len(PROTECTED_REF_PREFIX) :]
+    return text
+
+
+def is_protected_branch(value: object) -> bool:
+    """True when ``value`` names main/master or a sub-ref of either."""
+    name = normalize_branch(value).lower()
+    if not name:
+        return False
+    if name in PROTECTED_BRANCHES:
+        return True
+    return name.split("/", 1)[0] in PROTECTED_BRANCHES
+
+
+def assert_writable_branch(value: object) -> str:
+    """Validate a branch the harness may commit/push to; refuse protected refs."""
+    name = normalize_branch(value)
+    if not name:
+        raise GitWriteError("a branch name is required")
+    if is_protected_branch(name):
+        raise GitWriteError(
+            f"refusing to write to protected branch {name!r}: the git-write path "
+            "never commits or pushes main/master"
+        )
+    if (
+        not _BRANCH_RE.fullmatch(name)
+        or ".." in name
+        or name.endswith(("/", ".", ".lock"))
+        or "//" in name
+    ):
+        raise GitWriteError(f"invalid branch name: {value!r}")
+    return name
+
+
+def assert_safe_remote(value: object) -> str:
+    remote = str(value or "").strip()
+    if not remote or not _REMOTE_RE.fullmatch(remote) or is_protected_branch(remote):
+        raise GitWriteError(f"invalid remote name: {value!r}")
+    return remote
+
+
+def contains_force_flag(argv: Iterable[str]) -> bool:
+    """True when an argv carries a force-push flag (it never should)."""
+    return any(
+        token in _FORCE_FLAGS or token.startswith("--force")
+        for token in argv
+    )
+
+
+def _assert_no_force(argv: list[str]) -> list[str]:
+    if contains_force_flag(argv):
+        raise GitWriteError(f"refusing a force argument: {argv!r}")
+    return argv
+
+
+def _validate_paths(paths: Iterable[object]) -> tuple[str, ...]:
+    validated: list[str] = []
+    for raw in paths:
+        text = str(raw or "").strip()
+        if not text:
+            raise GitWriteError("an approved path may not be empty")
+        normalized = text.replace("\\", "/")
+        if (
+            normalized.startswith("/")
+            or _WINDOWS_ABSOLUTE.match(normalized)
+            or ".." in normalized.split("/")
+        ):
+            raise GitWriteError(f"approved path escapes the workspace: {text!r}")
+        if normalized not in validated:
+            validated.append(normalized)
+    return tuple(validated)
+
+
+# --------------------------------------------------------------------------- #
+# Command builders (pure; the guards live here, not at the call sites)
+# --------------------------------------------------------------------------- #
+def branch_command(branch: str) -> list[str]:
+    return ["checkout", "-b", assert_writable_branch(branch)]
+
+
+def add_command(paths: Iterable[object]) -> list[str]:
+    validated = _validate_paths(paths)
+    if not validated:
+        raise GitWriteError("no approved paths to stage")
+    return ["add", "--", *validated]
+
+
+def commit_command(message: str, paths: Iterable[object]) -> list[str]:
+    text = str(message or "").strip()
+    if not text:
+        raise GitWriteError("a commit message is required")
+    if "\x00" in text:
+        raise GitWriteError("commit message must not contain NUL bytes")
+    validated = _validate_paths(paths)
+    if not validated:
+        raise GitWriteError("no approved paths to commit")
+    return ["commit", "-m", text, "--", *validated]
+
+
+def push_command(remote: str, branch: str) -> list[str]:
+    target = assert_writable_branch(branch)
+    safe_remote = assert_safe_remote(remote)
+    return _assert_no_force(
+        ["push", "--set-upstream", safe_remote, target]
+    )
+
+
+def pr_command(
+    branch: str,
+    *,
+    base: str,
+    title: str,
+    body: str,
+) -> list[str]:
+    head = assert_writable_branch(branch)
+    base_name = normalize_branch(base)
+    if not base_name:
+        raise GitWriteError("a pull-request base branch is required")
+    return _assert_no_force(
+        [
+            "pr",
+            "create",
+            "--head",
+            head,
+            "--base",
+            base_name,
+            "--title",
+            str(title or "").strip() or head,
+            "--body",
+            str(body or "").strip(),
+        ]
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Plan / result shapes
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class GitWriteStep:
+    """One mutating step, shown to the approver before it runs."""
+
+    name: str
+    description: str
+    command: str | None = None
+
+    def render(self) -> str:
+        if self.command:
+            return f"{self.name}: {self.description}\n  $ {self.command}"
+        return f"{self.name}: {self.description}"
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "command": self.command,
+        }
+
+
+@dataclass(frozen=True)
+class GitWritePlan:
+    """What the opt-in path will do, decided before anything mutates."""
+
+    directory: Path
+    branch: str
+    message: str
+    paths: tuple[str, ...]
+    remote: str = "origin"
+    base_branch: str = "main"
+    open_pr: bool = True
+    pr_title: str | None = None
+    pr_body: str | None = None
+
+
+@dataclass
+class GitWriteResult:
+    """Honest outcome: names the branch, commit, and PR (plus what was refused)."""
+
+    status: str = "refused"
+    branch: str | None = None
+    commit: str | None = None
+    pr_url: str | None = None
+    pushed: bool = False
+    reason: str | None = None
+    steps: list[dict[str, Any]] = field(default_factory=list)
+    commands: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "branch": self.branch,
+            "commit": self.commit,
+            "pr_url": self.pr_url,
+            "pr": self.pr_url,
+            "pushed": self.pushed,
+            "reason": self.reason,
+            "steps": list(self.steps),
+            "commands": list(self.commands),
+        }
+
+
+# --------------------------------------------------------------------------- #
+# Defaults for the runner/CLI
+# --------------------------------------------------------------------------- #
+def default_branch_name(run_id: str) -> str:
+    safe = re.sub(r"[^A-Za-z0-9._/-]+", "-", str(run_id or "run").strip())
+    return f"sid/{safe or 'run'}"
+
+
+def default_commit_message(task: str, run_id: str) -> str:
+    first_line = " ".join(str(task or "").split())
+    if not first_line:
+        return f"sid: apply approved changes ({run_id})"
+    if len(first_line) > 72:
+        first_line = first_line[:69].rstrip() + "..."
+    return first_line
+
+
+# --------------------------------------------------------------------------- #
+# Command execution
+# --------------------------------------------------------------------------- #
+def _run_git(root: Path, args: list[str]) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", str(root), *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=_GIT_TIMEOUT,
+    )
+
+
+def _run_gh(args: list[str], cwd: Path) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["gh", *args],
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=_GH_TIMEOUT,
+    )
+
+
+def _display(argv: list[str]) -> str:
+    return " ".join(argv)
+
+
+def _detail(proc: subprocess.CompletedProcess | None) -> str:
+    if proc is None:
+        return "no process result"
+    text = (getattr(proc, "stderr", "") or "").strip()
+    if not text:
+        text = (getattr(proc, "stdout", "") or "").strip()
+    if len(text) > _MAX_DETAIL_CHARS:
+        text = text[:_MAX_DETAIL_CHARS] + "..."
+    return text or f"exit {getattr(proc, 'returncode', '?')}"
+
+
+def _check(
+    proc: subprocess.CompletedProcess | None,
+    action: str,
+    result: GitWriteResult,
+) -> None:
+    if proc is None or proc.returncode != 0:
+        raise _Failed(f"{action} failed: {_detail(proc)}")
+
+
+def _record(result: GitWriteResult, argv: list[str], proc: subprocess.CompletedProcess) -> None:
+    result.commands.append(_display(argv))
+
+
+def _git(
+    root: Path,
+    args: list[str],
+    run: GitRunner,
+    result: GitWriteResult,
+) -> subprocess.CompletedProcess:
+    argv = ["git", "-C", str(root), *args]
+    try:
+        proc = run(root, args)
+    except FileNotFoundError as exc:
+        raise _Failed(f"git is not available: {exc}") from exc
+    _record(result, argv, proc)
+    return proc
+
+
+def _gh(
+    root: Path,
+    argv: list[str],
+    run: GhRunner,
+    result: GitWriteResult,
+) -> subprocess.CompletedProcess:
+    try:
+        proc = run(argv, root)
+    except FileNotFoundError as exc:
+        raise _Failed(f"gh CLI is not available: {exc}") from exc
+    _record(result, ["gh", *argv], proc)
+    return proc
+
+
+def _current_branch(root: Path, run: GitRunner, result: GitWriteResult) -> str:
+    proc = _git(root, ["rev-parse", "--abbrev-ref", "HEAD"], run, result)
+    _check(proc, "read current branch", result)
+    return normalize_branch(proc.stdout)
+
+
+def _branch_exists(root: Path, branch: str, run: GitRunner, result: GitWriteResult) -> bool:
+    proc = _git(
+        root,
+        ["rev-parse", "--verify", "--quiet", f"{PROTECTED_REF_PREFIX}{branch}"],
+        run,
+        result,
+    )
+    return proc.returncode == 0
+
+
+def _require_approval(step: GitWriteStep, approve: Approver | None) -> None:
+    if approve is None:
+        raise _Refused(
+            f"no approver supplied; {step.name} requires explicit human approval"
+        )
+    try:
+        decision = bool(approve(step))
+    except Exception as exc:  # a broken approver must fail closed
+        raise _Refused(
+            f"approver raised {type(exc).__name__}: {exc}"
+        ) from exc
+    if not decision:
+        raise _Refused(f"{step.name} refused by reviewer")
+
+
+def _gate(
+    result: GitWriteResult,
+    approve: Approver | None,
+    step: GitWriteStep,
+) -> None:
+    entry = step.as_dict()
+    entry["approved"] = False
+    result.steps.append(entry)
+    try:
+        _require_approval(step, approve)
+    except _Refused as exc:
+        entry["detail"] = str(exc)
+        raise
+    entry["approved"] = True
+
+
+def _extract_url(text: str) -> str | None:
+    matches = _URL_RE.findall(text or "")
+    return matches[-1] if matches else None
+
+
+# --------------------------------------------------------------------------- #
+# Execute
+# --------------------------------------------------------------------------- #
+def execute_git_write(
+    plan: GitWritePlan,
+    *,
+    approve: Approver | None,
+    git_runner: GitRunner | None = None,
+    gh_runner: GhRunner | None = None,
+) -> GitWriteResult:
+    """Run the opt-in sequence: branch -> commit -> push -> PR.
+
+    Returns a result even on refusal/failure, so a receipt always names what
+    happened. Hard guards are checked before the first approval prompt.
+    """
+    run_git = git_runner or _run_git
+    run_gh = gh_runner or _run_gh
+    result = GitWriteResult()
+
+    try:
+        branch = assert_writable_branch(plan.branch)
+        base_branch = normalize_branch(plan.base_branch or "main")
+        if not base_branch:
+            raise GitWriteError("a pull-request base branch is required")
+        paths = _validate_paths(plan.paths)
+        if not paths:
+            raise GitWriteError("no approved changes to commit")
+        message = str(plan.message or "").strip()
+        if not message:
+            raise GitWriteError("a commit message is required")
+        safe_remote = assert_safe_remote(plan.remote)
+    except GitWriteError as exc:
+        result.reason = str(exc)
+        return result
+
+    result.branch = branch
+    info = git_info(plan.directory)
+    if not info.is_repo or info.root is None:
+        result.reason = f"not a git repository: {plan.directory}"
+        return result
+    root = info.root
+
+    try:
+        # 1 — branch ------------------------------------------------------- #
+        current = _current_branch(root, run_git, result)
+        if normalize_branch(current) == branch and _branch_exists(
+            root, branch, run_git, result
+        ):
+            result.steps.append(
+                {
+                    "name": "branch",
+                    "description": f"already on branch {branch!r}",
+                    "command": None,
+                    "approved": True,
+                    "detail": "no branch creation needed",
+                }
+            )
+        else:
+            if _branch_exists(root, branch, run_git, result):
+                raise _Refused(
+                    f"branch {branch!r} already exists; refusing to move an "
+                    "existing branch"
+                )
+            args = branch_command(branch)
+            _gate(
+                result,
+                approve,
+                GitWriteStep(
+                    "branch",
+                    f"create branch {branch!r} from {current or 'HEAD'}",
+                    _display(["git", "-C", str(root), *args]),
+                ),
+            )
+            _check(_git(root, args, run_git, result), "create branch", result)
+
+        # 2 — commit only the approved paths ------------------------------- #
+        add_args = add_command(paths)
+        commit_args = commit_command(message, paths)
+        _gate(
+            result,
+            approve,
+            GitWriteStep(
+                "commit",
+                f"commit {len(paths)} approved path(s): {', '.join(paths)}",
+                _display(["git", "-C", str(root), *commit_args]),
+            ),
+        )
+        _check(_git(root, add_args, run_git, result), "stage approved paths", result)
+        _check(
+            _git(root, commit_args, run_git, result),
+            "commit approved paths",
+            result,
+        )
+        head = _git(root, ["rev-parse", "HEAD"], run_git, result)
+        _check(head, "read commit sha", result)
+        result.commit = head.stdout.strip() or None
+
+        # 3 — push the branch (never main/master, never forced) ------------ #
+        push_args = push_command(safe_remote, branch)
+        _gate(
+            result,
+            approve,
+            GitWriteStep(
+                "push",
+                f"push branch {branch!r} to {safe_remote!r} (no force)",
+                _display(["git", "-C", str(root), *push_args]),
+            ),
+        )
+        _check(
+            _git(root, push_args, run_git, result),
+            "push branch",
+            result,
+        )
+        result.pushed = True
+
+        # 4 — open the pull request via gh --------------------------------- #
+        if plan.open_pr:
+            title = (plan.pr_title or message.splitlines()[0])[:120]
+            body = plan.pr_body if plan.pr_body is not None else message
+            args = pr_command(branch, base=base_branch, title=title, body=body)
+            _gate(
+                result,
+                approve,
+                GitWriteStep(
+                    "pr",
+                    f"open a pull request {branch!r} -> {base_branch!r}",
+                    _display(["gh", *args]),
+                ),
+            )
+            proc = _gh(root, args, run_gh, result)
+            _check(proc, "open pull request", result)
+            url = _extract_url(proc.stdout)
+            if not url:
+                raise _Failed("gh pr create returned no pull-request URL")
+            result.pr_url = url
+
+        result.status = "completed"
+        return result
+    except _Refused as exc:
+        result.status = "refused"
+        result.reason = str(exc)
+        return result
+    except _Failed as exc:
+        result.status = "failed"
+        result.reason = str(exc)
+        return result
+    except GitWriteError as exc:  # defensive: a builder guard tripped mid-way
+        result.status = "failed"
+        result.reason = str(exc)
+        return result
+
+
+__all__ = [
+    "PROTECTED_BRANCHES",
+    "Approver",
+    "GitWriteError",
+    "GitWritePlan",
+    "GitWriteResult",
+    "GitWriteStep",
+    "add_command",
+    "assert_safe_remote",
+    "assert_writable_branch",
+    "branch_command",
+    "commit_command",
+    "contains_force_flag",
+    "default_branch_name",
+    "default_commit_message",
+    "execute_git_write",
+    "is_protected_branch",
+    "normalize_branch",
+    "pr_command",
+    "push_command",
+]