ground-control-cli 0.2.0__py3-none-any.whl

client/probes/gh.py

@@ -0,0 +1,126 @@
+"""The gh probes: a pull request, and its checks once none is pending or the wait ends.
+
+Each runs the `gh` CLI in the repo and returns the fact as plain values, the fields of its facts
+in app/method/facts.py. A gh that is missing or fails says only which error stopped it.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+from . import errors
+
+PR_FIELDS = "headRefOid,state,mergeable,mergeCommit"
+CHECK_FIELDS = "name,bucket,startedAt,completedAt"
+
+
+class Failed(Exception):
+    """A gh command failed; `error` is which of errors.ERRORS it stands for."""
+
+    def __init__(self, error: str):
+        """Keep the error."""
+        super().__init__(error)
+        self.error = error
+
+
+def _gh(root, *args, timeout=None) -> subprocess.CompletedProcess:
+    """Run gh in the repo; Failed with tool_missing when gh is not installed."""
+    try:
+        return subprocess.run(
+            ["gh", *args], cwd=root, capture_output=True, text=True, timeout=timeout
+        )
+    except FileNotFoundError:
+        raise Failed(errors.TOOL_MISSING) from None
+
+
+def _json(out: subprocess.CompletedProcess):
+    """Gh's JSON output; Failed with the error its failure stands for."""
+    if out.returncode != 0:
+        raise Failed(errors.failed(out.stderr))
+    try:
+        return json.loads(out.stdout or "null")
+    except json.JSONDecodeError:
+        raise Failed(errors.REFUSED) from None
+
+
+def pr(params: dict, root) -> dict:
+    """gh.pr: a pull request's head, state, mergeability and merge commit.
+
+    Args:
+        params: {"url"}.
+        root: The repo, where gh runs.
+
+    Returns:
+        The PrFacts fields.
+
+    Company: assumes none.
+    """
+    try:
+        found = _json(_gh(root, "pr", "view", params["url"], "--json", PR_FIELDS))
+    except Failed as e:
+        return {"error": e.error}
+    if not isinstance(found, dict):
+        return {"error": errors.REFUSED}
+    merged = found.get("mergeCommit")
+    return {
+        "head": found.get("headRefOid") or None,
+        "state": found.get("state") or None,
+        "mergeable": found.get("mergeable") or None,
+        "merge_commit": (merged.get("oid") if isinstance(merged, dict) else None) or None,
+    }
+
+
+def _listed(url: str, root, *flags) -> list:
+    """The PR's checks as gh lists them; none when gh says there are none."""
+    out = _gh(root, "pr", "checks", url, *flags, "--json", CHECK_FIELDS)
+    if out.returncode != 0 and "no " in out.stderr and "checks reported" in out.stderr:
+        return []
+    found = _json(out)
+    if not isinstance(found, list):
+        raise Failed(errors.REFUSED)
+    return [c for c in found if isinstance(c, dict) and c.get("name")]
+
+
+def checks(params: dict, root) -> dict:
+    """gh.checks: the PR's checks, after waiting up to wait_seconds for none to be pending.
+
+    The wait is `gh pr checks --watch`, ended when the time is up; how it exits is not read,
+    since it exits non-zero when a check failed. Whether a check is required is read with
+    `--required`.
+
+    Args:
+        params: {"url", "wait_seconds"}.
+        root: The repo, where gh runs.
+
+    Returns:
+        The ChecksFacts fields, the checks sorted by name; waited_out when checks were still
+        pending as the wait ended.
+
+    Company: assumes none.
+    """
+    url, wait = params["url"], params.get("wait_seconds") or 0
+    waited_out = False
+    try:
+        if wait > 0:
+            try:
+                _gh(root, "pr", "checks", url, "--watch", timeout=wait)
+            except subprocess.TimeoutExpired:
+                waited_out = True
+        found = _listed(url, root)
+        required = {c["name"] for c in _listed(url, root, "--required")}
+    except Failed as e:
+        return {"waited_out": waited_out, "error": e.error}
+    return {
+        "checks": [
+            {
+                "name": c["name"],
+                "bucket": c.get("bucket") or "",
+                "required": c["name"] in required,
+                "started_at": c.get("startedAt") or None,
+                "completed_at": c.get("completedAt") or None,
+            }
+            for c in sorted(found, key=lambda c: c["name"])
+        ],
+        "waited_out": waited_out,
+    }

client/probes/git.py

@@ -0,0 +1,280 @@
+"""The git probes: a branch and its worktree, commits, what changed, and whether two commits merge.
+
+Each runs git in the repo and returns the fact as plain values, the fields of its facts in
+app/method/facts.py. A git that fails says only which error stopped it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from pathlib import Path
+
+from . import errors, settings
+
+CONFIG = ".claude/method.json"
+# A hunk's header in `git diff -U0`: where its lines start on the new side, and how many.
+HUNK_RE = re.compile(r"^@@ -\S+ \+(\d+)(?:,(\d+))? @@")
+
+
+class Failed(Exception):
+    """A git command failed; `error` is which of errors.ERRORS it stands for."""
+
+    def __init__(self, error: str):
+        """Keep the error."""
+        super().__init__(error)
+        self.error = error
+
+
+def _git(root, *args) -> subprocess.CompletedProcess:
+    """Run git in the repo; Failed with tool_missing when git is not installed."""
+    try:
+        return subprocess.run(["git", *args], cwd=root, capture_output=True, text=True)
+    except FileNotFoundError:
+        raise Failed(errors.TOOL_MISSING) from None
+
+
+def _out(root, *args) -> str:
+    """Git's output; Failed with the error its failure stands for."""
+    out = _git(root, *args)
+    if out.returncode != 0:
+        raise Failed(errors.failed(out.stderr))
+    return out.stdout
+
+
+def main_checkout(root) -> Path:
+    """The repo's main checkout: the folder of git's common .git, wherever root is."""
+    root = Path(root).resolve()
+    out = _git(root, "rev-parse", "--git-common-dir")
+    common = out.stdout.strip() if out.returncode == 0 else ""
+    if not common:
+        return root
+    common = (root / common).resolve()
+    return common.parent if common.name == ".git" else root
+
+
+def logs_dir(root) -> Path:
+    """The method's log folder: METHOD_LOGS; else `logs` in the repo's config; else _logs beside.
+
+    Args:
+        root: A folder inside the repo, the main checkout or a linked worktree.
+
+    Returns:
+        The folder, resolved.
+
+    Company: assumes none.
+    """
+    found = settings.logs()
+    if found:
+        return found
+    main = main_checkout(root)
+    try:
+        config = json.loads((main / CONFIG).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        config = {}
+    logs = config.get("logs") if isinstance(config, dict) else None
+    if logs:
+        return (main / Path(logs).expanduser()).resolve()
+    return (main.parent / "_logs").resolve()
+
+
+def _inside(path: Path, folder: Path) -> bool:
+    return path == folder or folder in path.parents
+
+
+def worktree(root, branch: str) -> Path | None:
+    """The folder where the branch is checked out, or None."""
+    folder = None
+    for line in _out(root, "worktree", "list", "--porcelain").splitlines():
+        if line.startswith("worktree "):
+            folder = Path(line[len("worktree ") :])
+        elif line == f"branch refs/heads/{branch}" and folder is not None:
+            return folder.resolve()
+    return None
+
+
+def branch(params: dict, root) -> dict:
+    """git.branch: whether the branch exists, its worktree, and its paths there.
+
+    Args:
+        params: {"name", "paths"}.
+        root: The repo.
+
+    Returns:
+        The BranchFacts fields.
+
+    Company: assumes none.
+    """
+    name, paths = params["name"], list(params.get("paths") or [])
+    try:
+        if _git(root, "rev-parse", "--verify", "-q", f"refs/heads/{name}").returncode != 0:
+            return {"exists": False}
+        tree = worktree(root, name)
+        if tree is None:
+            return {"exists": True}
+        found = []
+        for path in paths:
+            present = (tree / path).is_file()
+            last = (
+                _out(tree, "log", "-1", "--format=%H", name, "--", path).strip() if present else ""
+            )
+            found.append({"path": path, "present": present, "last_commit": last or None})
+        return {
+            "exists": True,
+            "worktree": str(tree),
+            "main_checkout": tree == main_checkout(root),
+            "paths": found,
+        }
+    except Failed as e:
+        return {"exists": False, "error": e.error}
+
+
+def _sha(root, *args) -> dict:
+    """The sha git prints, or None when it names none."""
+    try:
+        out = _git(root, *args)
+    except Failed as e:
+        return {"sha": None, "error": e.error}
+    sha = out.stdout.strip() if out.returncode == 0 else ""
+    return {"sha": sha or None}
+
+
+def commit(params: dict, root) -> dict:
+    """git.commit: the full sha a ref names, or None.
+
+    Args:
+        params: {"ref"}.
+        root: The repo.
+
+    Returns:
+        The CommitFacts fields.
+
+    Company: assumes none.
+    """
+    return _sha(root, "rev-parse", "--verify", "-q", f"{params.get('ref') or 'HEAD'}^{{commit}}")
+
+
+def merge_base(params: dict, root) -> dict:
+    """git.merge_base: the best common ancestor of two commits, or None.
+
+    Args:
+        params: {"a", "b"}.
+        root: The repo.
+
+    Returns:
+        The CommitFacts fields.
+
+    Company: assumes none.
+    """
+    try:
+        out = _git(root, "merge-base", params.get("a") or "main", params.get("b") or "HEAD")
+    except Failed as e:
+        return {"sha": None, "error": e.error}
+    if out.returncode == 0:
+        return {"sha": out.stdout.strip() or None}
+    if out.returncode == 1 and not out.stderr.strip():
+        return {"sha": None}
+    return {"sha": None, "error": errors.failed(out.stderr)}
+
+
+def _untracked(root) -> list:
+    return [n for n in _out(root, "ls-files", "--others", "--exclude-standard").splitlines() if n]
+
+
+def changed(params: dict, root) -> dict:
+    """git.changed: the files that differ from a commit, and the untracked ones git keeps.
+
+    The method's own log folder is left out, wherever it is.
+
+    Args:
+        params: {"since"}.
+        root: The repo.
+
+    Returns:
+        The ChangedFacts fields.
+
+    Company: assumes none.
+    """
+    try:
+        tracked = _out(root, "diff", "--name-only", params["since"], "--").splitlines()
+        untracked = _untracked(root)
+    except Failed as e:
+        return {"error": e.error}
+    logs = logs_dir(root)
+    keep = [n for n in dict.fromkeys(tracked + untracked) if n]
+    keep = [n for n in keep if not _inside((Path(root) / n).resolve(), logs)]
+    new = set(untracked)
+    return {
+        "changed": sorted(n for n in keep if n not in new),
+        "untracked": sorted(n for n in keep if n in new),
+    }
+
+
+def lines(params: dict, root) -> dict:
+    """git.lines: the changed lines of each file against a commit, untracked files whole.
+
+    The lines are the working tree's. A deletion marks the lines on both sides of it.
+
+    Args:
+        params: {"since"}.
+        root: The repo.
+
+    Returns:
+        The LinesFacts fields.
+
+    Company: assumes none.
+    """
+    found, current = {}, None
+    try:
+        diff = _out(root, "diff", "-U0", "--no-color", "--no-renames", params["since"], "--")
+        untracked = _untracked(root)
+    except Failed as e:
+        return {"error": e.error}
+    for line in diff.splitlines():
+        if line.startswith("+++ "):
+            current = line[6:] if line.startswith("+++ b/") else None
+        elif current and (hunk := HUNK_RE.match(line)):
+            start, count = int(hunk.group(1)), int(hunk.group(2) or 1)
+            marked = range(start, start + count) if count else (start, start + 1)
+            found.setdefault(current, set()).update(marked)
+    for name in untracked:
+        target = Path(root) / name
+        if target.is_file():
+            total = len(target.read_text(encoding="utf-8", errors="replace").splitlines())
+            found[name] = set(range(1, total + 1))
+    return {
+        "files": [
+            {"path": name, "lines": sorted(found[name])} for name in sorted(found) if found[name]
+        ]
+    }
+
+
+def conflicts(params: dict, root) -> dict:
+    """git.conflicts: whether two commits merge, tried in git's object store only.
+
+    `git merge-tree --write-tree` writes objects only: no working tree, branch or index is
+    touched. A conflict prints the merged tree, then the conflicting paths; a commit that is not
+    there prints nothing.
+
+    Args:
+        params: {"a", "b"}.
+        root: The repo.
+
+    Returns:
+        The ConflictFacts fields.
+
+    Company: assumes none.
+    """
+    a, b = params.get("a") or "main", params.get("b") or "HEAD"
+    try:
+        out = _git(root, "merge-tree", "--write-tree", "--name-only", "--no-messages", a, b)
+    except Failed as e:
+        return {"error": e.error}
+    if out.returncode == 0:
+        return {"conflicts": False}
+    if out.returncode == 1 and out.stdout.strip():
+        return {"conflicts": True, "paths": sorted(set(out.stdout.splitlines()[1:]) - {""})}
+    if "not something we can merge" in out.stderr:
+        return {"error": errors.NOT_FOUND}
+    return {"error": errors.failed(out.stderr)}

client/probes/health.py

@@ -0,0 +1,128 @@
+"""The health probe: what the repo's running environment answers, after bringing it up or down.
+
+`environment` in the repo's .claude/method.json is `{"up", "down", "health", "timeout"}`: the
+command that brings the branch up, the one that takes it down, a local URL that says the
+environment is healthy, and how many seconds to wait (settings.ENVIRONMENT_TIMEOUT when not
+given). The service names only what to do; the commands and the address are the repo's own.
+Commands run through the shell in the repo root, in their own session, and are not waited on:
+`up` may keep running as the environment itself.
+
+Health answers when it gives any HTTP reply; it does not answer when there is no reply at all.
+It is healthy when the reply is 2xx.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from . import errors, settings
+
+CONFIG = ".claude/method.json"
+KEY = "environment"
+# The keys each way of bringing needs.
+NEEDS = {"none": ("health",), "up": ("up", "health"), "down": ("down", "health")}
+
+
+def status(health: str):
+    """The HTTP status health replies with, or None when nothing replies."""
+    try:
+        with urllib.request.urlopen(health, timeout=settings.ENVIRONMENT_PROBE) as reply:
+            return reply.status
+    except urllib.error.HTTPError as e:
+        return e.code
+    except (urllib.error.URLError, OSError, ValueError):
+        return None
+
+
+def healthy(code) -> bool:
+    """Whether a status is 2xx; no reply is not healthy."""
+    return code is not None and 200 <= code < 300
+
+
+def _config(root, keys) -> tuple:
+    """`environment` from the repo's config, and the error that stops reading it, or None."""
+    try:
+        path = Path(root) / CONFIG
+        found = json.loads(path.read_text(encoding="utf-8")) if path.is_file() else {}
+    except (OSError, json.JSONDecodeError):
+        return {}, errors.UNREADABLE
+    env = found.get(KEY) if isinstance(found, dict) else None
+    if not isinstance(env, dict):
+        return {}, errors.NO_COMMAND
+    if not all(isinstance(env.get(k), str) and env[k].strip() for k in keys):
+        return env, errors.NO_COMMAND
+    timeout = env.get("timeout", settings.ENVIRONMENT_TIMEOUT)
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or timeout <= 0:
+        return env, errors.UNREADABLE
+    return env, None
+
+
+def _start(command: str, root) -> subprocess.Popen:
+    """Start a command through the shell in its own session, without waiting on it."""
+    return subprocess.Popen(
+        command,
+        shell=True,
+        cwd=root,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+
+
+def _wait(until, seconds: float, started) -> str | None:
+    """Ask until `until()` holds; the error that ended the wait, or None when it held."""
+    end = time.monotonic() + seconds
+    while True:
+        if until():
+            return None
+        if started is not None and started.poll():
+            return errors.COMMAND_FAILED
+        if time.monotonic() >= end:
+            return errors.TIMED_OUT
+        time.sleep(settings.ENVIRONMENT_POLL)
+
+
+def health(params: dict, root) -> dict:
+    """health: what the health address answers, bringing the environment up or down first.
+
+    bring=up runs `up` unless something already answers, then waits for 2xx; bring=down runs
+    `down`, then waits until nothing answers; bring=none only asks.
+
+    Args:
+        params: {"bring"}: none, up or down.
+        root: The repo, whose config names the commands and the address.
+
+    Returns:
+        The HealthFacts fields.
+
+    Company: assumes none.
+    """
+    bring = params.get("bring") or "none"
+    env, error = _config(root, NEEDS[bring])
+    if error:
+        return {"error": error}
+    address = env["health"]
+    before = status(address)
+    if bring == "none":
+        return {"before": before, "after": before}
+    timeout = env.get("timeout", settings.ENVIRONMENT_TIMEOUT)
+
+    def until() -> bool:
+        code = status(address)
+        return healthy(code) if bring == "up" else code is None
+
+    if bring == "up":
+        started = _start(env["up"], root) if before is None else None
+    else:
+        started = _start(env["down"], root)
+    start = time.monotonic()
+    error = _wait(until, timeout, started)
+    waited = timeout if error == errors.TIMED_OUT else round(time.monotonic() - start, 2)
+    found = {"before": before, "after": status(address), "seconds": waited}
+    return dict(found, error=error) if error else found

client/probes/settings.py

@@ -0,0 +1,72 @@
+"""The client's own technical numbers, each read once from the environment, with its default.
+
+The same variables the server's settings name for the method (app/config.py, .env.example), read
+here because the client imports nothing of the server. A value is a number of seconds or an ISO
+8601 duration, such as PT60S, as .env.example writes them.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+DURATION_RE = re.compile(
+    r"^P(?:(?P<days>\d+(?:\.\d+)?)D)?"
+    r"(?:T(?:(?P<hours>\d+(?:\.\d+)?)H)?(?:(?P<minutes>\d+(?:\.\d+)?)M)?"
+    r"(?:(?P<seconds>\d+(?:\.\d+)?)S)?)?$"
+)
+SECONDS_IN = {"days": 86400, "hours": 3600, "minutes": 60, "seconds": 1}
+
+
+def seconds(name: str, default: float) -> float:
+    """A duration from the environment, in seconds.
+
+    Args:
+        name: The variable, such as METHOD_ENVIRONMENT_TIMEOUT.
+        default: The seconds when it is unset, empty or not a duration.
+
+    Returns:
+        The seconds.
+
+    Company: assumes none.
+    """
+    value = os.environ.get(name, "").strip()
+    if not value:
+        return default
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    found = DURATION_RE.match(value.upper())
+    if not found or value.upper() in ("P", "PT"):
+        return default
+    return sum(float(v) * SECONDS_IN[k] for k, v in found.groupdict().items() if v)
+
+
+def method_data() -> Path:
+    """METHOD_DATA, the method's own folder on this machine, where the readers' tools are.
+
+    Read each time it is asked for, so a change to the environment counts.
+
+    Returns:
+        The folder, resolved; ~/.method when METHOD_DATA is unset, as app/config.py has it.
+
+    Company: assumes none.
+    """
+    value = os.environ.get("METHOD_DATA", "").strip() or "~/.method"
+    return Path(value).expanduser().resolve()
+
+
+def logs() -> Path | None:
+    """METHOD_LOGS, the folder that holds the method's log, or None when unset."""
+    value = os.environ.get("METHOD_LOGS", "").strip()
+    return Path(value).expanduser().resolve() if value else None
+
+
+# How long to wait for the environment to come up or down, unless the repo says otherwise.
+ENVIRONMENT_TIMEOUT = seconds("METHOD_ENVIRONMENT_TIMEOUT", 60)
+# How often to ask whether the environment is up.
+ENVIRONMENT_POLL = seconds("METHOD_ENVIRONMENT_POLL", 0.25)
+# The longest one health question may take.
+ENVIRONMENT_PROBE = seconds("METHOD_ENVIRONMENT_PROBE", 2)