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

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

@@ -1,5 +1,5 @@
 Metadata-Version: 2.4
 Name: ground-control-cli
-Version: 0.2.0
+Version: 0.3.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.3.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)

{ground_control_cli-0.2.0 → ground_control_cli-0.3.0}/claude.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import io
 import json
+import os
 import re
 import shutil
 import subprocess
@@ -238,3 +239,112 @@ def remove() -> list[str]:
                 done.append(str(e))
     shutil.rmtree(store_dir(), ignore_errors=True)
     return done
+
+
+# The plugin before this one, from the engineering-methods store; it goes at the cutover.
+OLD_PLUGIN, OLD_STORE = "engineering@engineering-methods", "engineering-methods"
+
+
+def remove_old() -> list[str]:
+    """Remove the old engineering plugin and its store, wherever Claude Code installed it.
+
+    Returns:
+        What was done, a line each; none when it was not there.
+
+    Company: assumes none.
+    """
+    try:
+        listed = json.loads(_ran("plugin", "list", "--json") or "[]")
+    except (ClaudeError, ValueError):
+        return []
+    done = []
+    for plugin in listed:
+        if plugin.get("id") != OLD_PLUGIN:
+            continue
+        scope = plugin.get("scope", "user")
+        args = ["plugin", "uninstall", OLD_PLUGIN, "--scope", scope]
+        where = plugin.get("projectPath") if scope != "user" else None
+        try:
+            if where:
+                _in(where, *args)
+            else:
+                _ran(*args)
+            done.append(f"removed the old plugin {OLD_PLUGIN} ({scope})")
+        except ClaudeError as e:
+            done.append(str(e))
+    try:
+        stores = json.loads(_ran("plugin", "marketplace", "list", "--json") or "[]")
+        if any(m.get("name") == OLD_STORE for m in stores):
+            _ran("plugin", "marketplace", "remove", OLD_STORE)
+            done.append(f"removed the old store {OLD_STORE}")
+    except (ClaudeError, ValueError) as e:
+        done.append(str(e))
+    return [line for line in done if line]
+
+
+def _in(folder: str, *args: str) -> str:
+    """Run one `claude` command in a project's folder, for a plugin installed for it."""
+    try:
+        done = subprocess.run(
+            ["claude", *args],
+            cwd=folder,
+            capture_output=True,
+            text=True,
+            timeout=TIMEOUT,
+            stdin=subprocess.DEVNULL,
+        )
+    except (FileNotFoundError, NotADirectoryError, subprocess.TimeoutExpired) as e:
+        raise ClaudeError(f"`claude {' '.join(args)}` could not run in {folder}: {e}") from None
+    if done.returncode != 0:
+        said = (done.stderr or done.stdout).strip().splitlines()
+        raise ClaudeError(f"`claude {' '.join(args)}` failed: {said[-1] if said else ''}")
+    return ""
+
+
+# The settings files whose `disableAllHooks` turns every hook off, and the managed one, whose
+# `allowManagedHooksOnly` turns the plugin's off.
+MANAGED_SETTINGS = Path("/Library/Application Support/ClaudeCode/managed-settings.json")
+
+
+def config_dir() -> Path:
+    """Claude Code's own folder for the person: CLAUDE_CONFIG_DIR, else ~/.claude."""
+    found = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
+    return Path(found).expanduser() if found else Path.home() / ".claude"
+
+
+def _read(target: Path) -> dict:
+    try:
+        found = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return found if isinstance(found, dict) else {}
+
+
+def hooks_off(root) -> list[str]:
+    """The settings file that turns Claude Code's hooks off for the repo at root, if any.
+
+    `disableAllHooks` is read where Claude Code reads it first: the managed settings, then the
+    repo's local settings, its settings, and the person's; the managed settings'
+    `allowManagedHooksOnly` turns the plugin's hooks off too.
+
+    Args:
+        root: The repo's top folder.
+
+    Returns:
+        The file that does, by its path; empty when the hooks run.
+
+    Company: assumes none.
+    """
+    managed = _read(MANAGED_SETTINGS)
+    if managed.get("allowManagedHooksOnly") is True:
+        return [str(MANAGED_SETTINGS)]
+    for target in (
+        MANAGED_SETTINGS,
+        Path(root) / ".claude" / "settings.local.json",
+        Path(root) / ".claude" / "settings.json",
+        config_dir() / "settings.json",
+    ):
+        found = _read(target)
+        if "disableAllHooks" in found:
+            return [str(target)] if found["disableAllHooks"] is True else []
+    return []

{ground_control_cli-0.2.0 → ground_control_cli-0.3.0}/cli.py

@@ -1,11 +1,15 @@
-"""The groundcontrol command (and its alias, gctl): init, the session's start, repo, remove.
+"""The groundcontrol command (and its alias, gctl): init, the method, the hooks, repo, remove.
 
 `groundcontrol init <address>` connects the machine to a company and installs the plugin,
 saying in one line what it does at each step; the person only approves in the browser.
-`groundcontrol session-start` is what the plugin's hook runs when a Claude Code session
-starts: the client updates itself and the plugin, and finds the repo's company; it is silent
-unless something needs the person. `groundcontrol repo` says which company the repo here is
-of, or what is missing. `groundcontrol remove` removes it all from the machine.
+`gctl method <command>` runs one of the method's commands on the repo's company's service
+(client.service: Service.method). `gctl hook <event>` is what the plugin's hooks run
+(client/hooks.py); at a session's start (`hook session-start`, or `session-start`) the client
+updates itself and the plugin, removes the old engineering plugin, finds the repo's company,
+and sends its queue; it is silent unless something needs the person. `groundcontrol repo` says
+which company the repo here is of, or what is missing. `groundcontrol remove` removes it all
+from the machine. `send` and `down` run in the background, started by the hooks: the queue's
+sender, and the environments a session brought up taken down.
 """
 
 from __future__ import annotations
@@ -17,7 +21,8 @@ import subprocess
 import sys
 from pathlib import Path
 
-from client import claude, connect, machine, system, update
+from client import claude, connect, hooks, machine, queue, system, tools, update
+from client.probes import health
 from client.service import PACKAGE, VERSION, Service, ServiceError
 
 TIMEOUT = 30
@@ -89,8 +94,17 @@ def init(given: str, store_file: str | None = None, door: str | None = None) ->
         f"{called.address} knows you: {person['name']} ({person['email']}) at {company['name']}, "
         f"on the machine {me['machine']['name']}."
     )
+    for line in claude.remove_old():
+        say(line[:1].upper() + line[1:] + ".")
     if not _plugin(called, store_file):
         return 1
+    say("Installing the code readers' tools: Node, the TypeScript compiler and shfmt.")
+    try:
+        done = tools.install(here.processor())
+    except tools.ToolsError as e:
+        say(f"Stopped: {e}.")
+        return 1
+    say(f"The tools: {', '.join(done) or 'current'}.")
     say(f"Done. Open Claude Code in a repo of {company['name']}.")
     return 0
 
@@ -149,9 +163,9 @@ def session_start(event: dict) -> list[str]:
     """What runs when a Claude Code session starts; what the person needs to know, if anything.
 
     The client updates itself when it is behind, before anything else; then the plugin, when
-    it is behind or missing; then reads the managed lists and finds the repo's company.
-    Nothing is left running, and nothing is written into the repo. Silent in a repo that is
-    not managed, or on a machine connected to no company.
+    it is behind or missing, and the old engineering plugin goes; then it reads the managed
+    lists and finds the repo's company. Nothing is written into the repo. Silent in a repo
+    that is not managed, or on a machine connected to no company.
 
     Args:
         event: The SessionStart event Claude Code sends, with its cwd.
@@ -190,6 +204,11 @@ def session_start(event: dict) -> list[str]:
             claude.install(claude.unpack(called.store()))
     except (ServiceError, claude.ClaudeError, OSError) as e:
         said.append(f"The plugin needs updating to {held['plugin']}: {e}.")
+    claude.remove_old()
+    try:
+        tools.install(here.processor())
+    except tools.ToolsError as e:
+        said.append(f"The code readers' tools need installing: {e}.")
     cwd = event.get("cwd")
     if cwd:
         machine.find(Path(cwd), here, refresh=True)
@@ -238,6 +257,8 @@ def remove() -> int:
         machine.forget_company(address)
     for line in claude.remove():
         say(line[:1].upper() + line[1:] + ".")
+    if tools.remove():
+        say("Removed the code readers' tools.")
     shutil.rmtree(machine.home(), ignore_errors=True)
     if update.installed_by_uv():
         subprocess.run(["uv", "tool", "uninstall", "--quiet", PACKAGE], check=False)
@@ -264,6 +285,73 @@ def save_store(target: str) -> int:
     return 0
 
 
+HOOKS = (
+    "session-start",
+    "session-end",
+    "pre-tool-use",
+    "post-tool-use",
+    "post-tool-use-failure",
+    "user-prompt-submit",
+    "subagent-start",
+    "subagent-stop",
+    "stop",
+)
+
+
+def _event() -> dict:
+    """The hook's event, from standard input; {} when there is none."""
+    try:
+        found = json.load(sys.stdin)
+    except ValueError:
+        return {}
+    return found if isinstance(found, dict) else {}
+
+
+def _service_for(address: str) -> Service | None:
+    """The service at a company's address with this machine's key, for the queue's sender."""
+    try:
+        return machine.service(address, _system())
+    except system.Unsupported:
+        return None
+
+
+def method(argv: list[str], root: Path) -> int:
+    """`gctl method <command>`: run one of the method's commands on the repo's company's service.
+
+    The repo is found from the folder; its company's service runs the command and has this
+    machine run what it needs; what the command prints is printed here.
+
+    Args:
+        argv: The command and its arguments.
+        root: The folder it is run in.
+
+    Returns:
+        The command's exit code.
+
+    Company: the repo's.
+    """
+    try:
+        found = machine.find(root, _system(), known_only=True)
+        if isinstance(found, machine.Missing):
+            found = machine.find(root, _system(), refresh=True)
+    except system.Unsupported as e:
+        print(f"refused: {e}", file=sys.stderr)
+        return 1
+    if isinstance(found, machine.Missing):
+        print(f"refused: not managed here: {found.why}", file=sys.stderr)
+        return 1
+    top = hooks._git(str(root), "rev-parse", "--show-toplevel") or str(root)
+    try:
+        queue.flush(_service_for, found.service.address)
+        done = found.service.method(found.repo, argv, str(root), claude.hooks_off(top))
+    except ServiceError as e:
+        print(f"refused: {found.service.address}: {e.detail}", file=sys.stderr)
+        return 1
+    sys.stdout.write(done.get("out") or "")
+    sys.stderr.write(done.get("err") or "")
+    return int(done.get("code") or 0)
+
+
 def main(argv: list[str] | None = None) -> int:
     """Run one command of groundcontrol.
 
@@ -283,23 +371,45 @@ def main(argv: list[str] | None = None) -> int:
     started.add_argument("--store", help="install the plugin from this archive")
     started.add_argument("--door", help="the door's address, as the install line gives it")
     commands.add_parser("session-start", help="what the plugin's hook runs as a session starts")
+    hooked = commands.add_parser("hook", help="what the plugin's hooks run")
+    hooked.add_argument("event", choices=HOOKS)
+    method_p = commands.add_parser(
+        "method", help="run one of the method's commands", add_help=False
+    )
+    method_p.add_argument("argv", nargs=argparse.REMAINDER)
+    commands.add_parser("send", help="send the queue to the service, in the background")
+    down_p = commands.add_parser("down", help="take down what sessions brought up under a folder")
+    down_p.add_argument("folder")
     commands.add_parser("repo", help="say which company the repo here is of")
     commands.add_parser("remove", help="remove it all from this machine")
     saved = commands.add_parser("store", help="save the plugin's store as an archive")
     saved.add_argument("file")
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv[:1] == ["method"]:
+        return method(argv[1:], Path.cwd())
     args = parser.parse_args(argv)
     try:
         if args.command == "init":
             return init(args.address, args.store, args.door)
-        if args.command == "session-start":
-            try:
-                event = json.load(sys.stdin)
-            except ValueError:
-                event = {}
-            lines = session_start(event if isinstance(event, dict) else {})
+        if args.command == "session-start" or (
+            args.command == "hook" and args.event == "session-start"
+        ):
+            event = _event()
+            lines = hooks.session_start(event, session_start(event))
             if lines:
                 print(json.dumps({"systemMessage": " ".join(lines)}))
             return 0
+        if args.command == "hook":
+            code, out = hooks.run(args.event, _event())
+            if out:
+                print(out)
+            return code
+        if args.command == "send":
+            queue.send_until_empty(_service_for)
+            return 0
+        if args.command == "down":
+            health.down_all(args.folder)
+            return 0
         if args.command == "repo":
             return repo(Path.cwd())
         if args.command == "remove":