ground-control-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{ground_control_cli-0.2.0 → ground_control_cli-0.4.0}/PKG-INFO

@@ -1,5 +1,5 @@
 Metadata-Version: 2.4
 Name: ground-control-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: What runs on a developer's machine: the command line and the agent's plugin.
 Requires-Python: >=3.12

ground_control_cli-0.4.0/actions.py

@@ -0,0 +1,271 @@
+"""The actions: what the method changes on the developer's machine, each with its fixed command.
+
+The service names an action from the closed set (app/method/facts.py, ACTIONS) with typed values;
+the client runs it here with its own command, so the service never sends a command line. Git and
+gh run in the repo, as the developer, with their own access. An action that cannot be done says
+which of the probes' errors stopped it, never what a command printed.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+from .probes import errors, request, workspace
+from .probes.git import main_checkout, worktree
+
+MAIN = "main"
+
+
+class Failed(Exception):
+    """A 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 _run(tool: str, root, *args, data: str | None = None) -> str:
+    """Run git or gh in the folder; its output, or Failed with what its failure stands for."""
+    try:
+        out = subprocess.run([tool, *args], cwd=root, input=data, capture_output=True, text=True)
+    except FileNotFoundError:
+        raise Failed(errors.TOOL_MISSING) from None
+    if out.returncode != 0:
+        raise Failed(errors.failed(out.stderr))
+    return out.stdout.strip()
+
+
+def _git(root, *args) -> str:
+    return _run("git", root, *args)
+
+
+def _gh(root, *args, data: str | None = None) -> str:
+    return _run("gh", root, *args, data=data)
+
+
+def _done(work: Callable[[], dict | None]) -> dict:
+    try:
+        return work() or {}
+    except Failed as e:
+        return {"error": e.error}
+
+
+def worktree_add(params: dict, root) -> dict:
+    """git.worktree_add: the branch and its worktree, beside the repo in `<repo>.worktrees`."""
+    main = main_checkout(root)
+    branch, base = params["branch"], params.get("base") or MAIN
+    tree = main.parent / f"{main.name}.worktrees" / branch
+
+    def work():
+        if _git_ok(main, "rev-parse", "--verify", "-q", f"refs/heads/{branch}"):
+            raise Failed(errors.REFUSED)
+        _git(main, "worktree", "add", "-q", "-b", branch, str(tree), base)
+        return {"path": str(tree)}
+
+    return _done(work)
+
+
+def _git_ok(root, *args) -> bool:
+    try:
+        _git(root, *args)
+    except Failed:
+        return False
+    return True
+
+
+def worktree_remove(params: dict, root) -> dict:
+    """git.worktree_remove: the branch's worktree, when it has one; the main checkout's folder."""
+    main, branch = main_checkout(root), params["branch"]
+
+    def work():
+        tree = worktree(main, branch)
+        if tree is not None and tree != main:
+            _git(main, "worktree", "remove", "--force", str(tree))
+        return {"path": str(main)}
+
+    return _done(work)
+
+
+def branch_delete(params: dict, root) -> dict:
+    """git.branch_delete: the local branch, unless it is gone or the main checkout's."""
+    main, branch = main_checkout(root), params["branch"]
+
+    def work():
+        if not _git_ok(main, "rev-parse", "--verify", "-q", f"refs/heads/{branch}"):
+            return
+        if worktree(main, branch) == main:
+            return
+        _git(main, "branch", "-D", branch)
+
+    return _done(work)
+
+
+def fetch(params: dict, root) -> dict:
+    """git.fetch: from origin, everything, main only, or the tags."""
+    what = params.get("what") or "all"
+    args = {"all": (), "main": ("main",), "tags": ("--tags",)}[what]
+    return _done(lambda: _git(root, "fetch", "-q", "origin", *args) and None)
+
+
+def tag(params: dict, root) -> dict:
+    """git.tag: tag the commit and push the tag to origin."""
+
+    def work():
+        _git(root, "tag", params["tag"], params["commit"])
+        _git(root, "push", "-q", "origin", f"refs/tags/{params['tag']}")
+
+    return _done(work)
+
+
+def delete_remote_branch(params: dict, root) -> dict:
+    """git.delete_remote_branch: the branch on origin."""
+    return _done(lambda: _git(root, "push", "-q", "origin", "--delete", params["branch"]) and None)
+
+
+def move_onto_main(params: dict, root) -> dict:
+    """git.move_onto_main: the branch checked out onto origin's main: fast-forward, or reset."""
+    if params["method"] == "merge":
+        return _done(lambda: _git(root, "merge", "-q", "--ff-only", "origin/main") and None)
+    return _done(lambda: _git(root, "reset", "-q", "--hard", "origin/main") and None)
+
+
+def comment(params: dict, root) -> dict:
+    """gh.comment: comment on the request, as the developer; the comment's address."""
+
+    def work():
+        out = _gh(root, "issue", "comment", params["url"], "--body-file", "-", data=params["text"])
+        links = [line.strip() for line in out.splitlines() if line.strip().startswith("https://")]
+        if not links:
+            raise Failed(errors.REFUSED)
+        return {"url": links[-1]}
+
+    return _done(work)
+
+
+def label(params: dict, root) -> dict:
+    """gh.label: add a label to the request."""
+    url, name = params["url"], params["label"]
+    return _done(lambda: _gh(root, "issue", "edit", url, "--add-label", name) and None)
+
+
+def close(params: dict, root) -> dict:
+    """gh.close: close the request."""
+    return _done(lambda: _gh(root, "issue", "close", params["url"]) and None)
+
+
+def issue(params: dict, root) -> dict:
+    """gh.issue: open an issue in the repo, as the developer; its address."""
+
+    def work():
+        out = _gh(
+            root,
+            "issue",
+            "create",
+            "--title",
+            params["title"],
+            "--body-file",
+            "-",
+            data=params["body"],
+        )
+        return {"url": out.splitlines()[-1].strip()}
+
+    return _done(work)
+
+
+def _title(params: dict, root) -> str:
+    """The PR's title: the one given, else the request's own, read here."""
+    if params.get("title"):
+        return params["title"]
+    found = request.read_title(params["request"], root)
+    if not found:
+        raise Failed(errors.NOT_FOUND)
+    return found
+
+
+def pr_open(params: dict, root) -> dict:
+    """gh.pr_open: push the branch and open its PR, or update the body of the one open for it."""
+    branch, base = params["branch"], params["base"]
+    body = Path(params["body_file"]).expanduser()
+    if not body.is_absolute():
+        body = Path(root).resolve() / body
+    if not body.is_file():
+        return {"no_body": True}
+
+    def work():
+        if branch == base:
+            raise Failed(errors.REFUSED)
+        _git(root, "push", "-q", "-u", "origin", f"refs/heads/{branch}:refs/heads/{branch}")
+        try:
+            found = json.loads(_gh(root, "pr", "view", branch, "--json", "url,state") or "{}")
+        except Failed:
+            found = {}
+        if found.get("state") == "OPEN":
+            _gh(root, "pr", "edit", found["url"], "--body-file", str(body))
+            return {"url": found["url"], "opened": False}
+        title = _title(params, root) + (params.get("suffix") or "")
+        out = _gh(
+            root,
+            "pr",
+            "create",
+            "--base",
+            base,
+            "--head",
+            branch,
+            "--title",
+            title,
+            "--body-file",
+            str(body),
+        )
+        return {"url": out.splitlines()[-1].strip(), "opened": True}
+
+    return _done(work)
+
+
+def pr_merge(params: dict, root) -> dict:
+    """gh.pr_merge: merge the PR, by merge or squash."""
+    return _done(lambda: _gh(root, "pr", "merge", params["url"], f"--{params['method']}") and None)
+
+
+# Every action the client runs: its name -> the function of (params, root) that runs it.
+RUNS: dict[str, Callable[[dict, object], dict]] = {
+    "git.worktree_add": worktree_add,
+    "git.worktree_remove": worktree_remove,
+    "git.branch_delete": branch_delete,
+    "git.fetch": fetch,
+    "git.tag": tag,
+    "git.delete_remote_branch": delete_remote_branch,
+    "git.move_onto_main": move_onto_main,
+    "gh.comment": comment,
+    "gh.label": label,
+    "gh.close": close,
+    "gh.issue": issue,
+    "gh.pr_open": pr_open,
+    "gh.pr_merge": pr_merge,
+    "workspace.record": workspace.record,
+    "workspace.put_back": workspace.put_back,
+}
+
+
+def run(name: str, params: dict, root) -> dict:
+    """Run one action and return what it did, as plain values.
+
+    Args:
+        name: The action, one of RUNS.
+        params: Its values.
+        root: Where on the machine it runs.
+
+    Returns:
+        What it did: the fields of its result.
+
+    Raises:
+        ValueError: If the client runs no action of that name.
+
+    Company: assumes none.
+    """
+    if name not in RUNS:
+        raise ValueError(f"the client runs no action `{name}`; it runs {', '.join(RUNS)}")
+    return RUNS[name](dict(params or {}), root)