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

client/__init__.py

@@ -0,0 +1 @@
+"""The client: what runs on a developer's machine (the groundcontrol command, the probes)."""

client/claude.py

@@ -0,0 +1,240 @@
+"""Claude Code, as the client drives it: its version, and the plugin through its own commands.
+
+The service serves the plugin's store as a zip; the client unpacks it into the machine's own
+folder (~/.groundcontrol/store), registers that folder with Claude Code as a store, and installs
+or updates the plugin from it with Claude Code's plugin commands. An organisation that blocks
+the network or commands installs the same store from an archive (`groundcontrol init
+--store <zip>`). The client never edits Claude Code's own files.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import re
+import shutil
+import subprocess
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from client import machine
+
+# The oldest Claude Code whose failed hook can block an action (onFailure).
+MINIMUM = (2, 1, 295)
+TIMEOUT = 120
+
+
+class ClaudeError(Exception):
+    """Claude Code is missing, too old, or refused a plugin command; the message says which."""
+
+
+def _claude(*args: str) -> subprocess.CompletedProcess:
+    """Run one `claude` command, never in the middle of anything it asks."""
+    try:
+        return subprocess.run(
+            ["claude", *args],
+            capture_output=True,
+            text=True,
+            timeout=TIMEOUT,
+            stdin=subprocess.DEVNULL,
+        )
+    except FileNotFoundError:
+        raise ClaudeError("Claude Code is not installed: install it first") from None
+    except subprocess.TimeoutExpired:
+        raise ClaudeError(f"`claude {' '.join(args)}` took too long") from None
+
+
+def _ran(*args: str) -> str:
+    """Run one `claude` command; its output, or ClaudeError saying what it said."""
+    done = _claude(*args)
+    if done.returncode != 0:
+        said = (done.stderr or done.stdout).strip().splitlines()
+        raise ClaudeError(
+            f"`claude {' '.join(args)}` failed: {said[-1] if said else done.returncode}"
+        )
+    return done.stdout
+
+
+def version() -> tuple[int, int, int]:
+    """Claude Code's version, at least MINIMUM.
+
+    Returns:
+        Its three numbers.
+
+    Raises:
+        ClaudeError: If it is missing, unreadable, or older than MINIMUM.
+
+    Company: assumes none.
+    """
+    found = re.search(r"(\d+)\.(\d+)\.(\d+)", _ran("--version"))
+    if not found:
+        raise ClaudeError("Claude Code did not say its version")
+    numbers = (int(found[1]), int(found[2]), int(found[3]))
+    if numbers < MINIMUM:
+        need = ".".join(map(str, MINIMUM))
+        have = ".".join(map(str, numbers))
+        raise ClaudeError(f"Claude Code is {have}; {need} or later is needed: run `claude update`")
+    return numbers
+
+
+def store_dir() -> Path:
+    """Where the plugin's store is unpacked.
+
+    Company: assumes none.
+    """
+    return machine.home() / "store"
+
+
+@dataclass(frozen=True)
+class Store:
+    """An unpacked store: its name in Claude Code, its one plugin, and the plugin's version.
+
+    Attributes:
+        name: The store's (marketplace's) name.
+        plugin: The plugin's name.
+        version: The plugin's version.
+    """
+
+    name: str
+    plugin: str
+    version: str
+
+    @property
+    def id(self) -> str:
+        """The plugin as Claude Code names it, plugin@store."""
+        return f"{self.plugin}@{self.name}"
+
+
+def read_store(folder: Path | None = None) -> Store | None:
+    """The store unpacked on the machine, or None.
+
+    Company: assumes none.
+    """
+    try:
+        found = json.loads(
+            ((folder or store_dir()) / ".claude-plugin" / "marketplace.json").read_text()
+        )
+        plugin = found["plugins"][0]
+        return Store(found["name"], plugin["name"], plugin.get("version", ""))
+    except (OSError, ValueError, KeyError, IndexError):
+        return None
+
+
+def unpack(archive: bytes) -> Store:
+    """Unpack a store's zip into the machine's store folder, replacing what was there.
+
+    Args:
+        archive: The zip, as the service serves it.
+
+    Returns:
+        The Store.
+
+    Raises:
+        ClaudeError: If the zip is no store.
+
+    Company: assumes none.
+    """
+    target = store_dir()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fresh = Path(tempfile.mkdtemp(prefix="store-", dir=target.parent))
+    try:
+        with zipfile.ZipFile(io.BytesIO(archive)) as packed:
+            for name in packed.namelist():
+                if name.startswith("/") or ".." in Path(name).parts:
+                    raise ClaudeError(f"the store holds a path outside it: {name}")
+            packed.extractall(fresh)
+    except zipfile.BadZipFile:
+        shutil.rmtree(fresh, ignore_errors=True)
+        raise ClaudeError("the store is not a zip") from None
+    except ClaudeError:
+        shutil.rmtree(fresh, ignore_errors=True)
+        raise
+    found = read_store(fresh)
+    if found is None:
+        shutil.rmtree(fresh, ignore_errors=True)
+        raise ClaudeError("the archive holds no store")
+    old = target.with_name("store-old")
+    shutil.rmtree(old, ignore_errors=True)
+    if target.exists():
+        target.rename(old)
+    fresh.rename(target)
+    shutil.rmtree(old, ignore_errors=True)
+    return found
+
+
+def installed(store: Store) -> str | None:
+    """The version of the store's plugin Claude Code has installed for the user, or None.
+
+    Company: assumes none.
+    """
+    try:
+        listed = json.loads(_ran("plugin", "list", "--json") or "[]")
+    except ValueError:
+        return None
+    for plugin in listed:
+        if plugin.get("id") == store.id and plugin.get("scope", "user") == "user":
+            return plugin.get("version") or ""
+    return None
+
+
+def _registered(store: Store) -> bool:
+    """Whether Claude Code knows the store."""
+    try:
+        listed = json.loads(_ran("plugin", "marketplace", "list", "--json") or "[]")
+    except ValueError:
+        return False
+    return any(m.get("name") == store.name for m in listed)
+
+
+def install(store: Store) -> str:
+    """Register the unpacked store with Claude Code and install or update its plugin.
+
+    Args:
+        store: The store unpacked on the machine.
+
+    Returns:
+        What was done, in a few words.
+
+    Raises:
+        ClaudeError: If a command of Claude Code fails.
+
+    Company: assumes none.
+    """
+    if _registered(store):
+        _ran("plugin", "marketplace", "update", store.name)
+    else:
+        _ran("plugin", "marketplace", "add", str(store_dir()))
+    had = installed(store)
+    if had is None:
+        _ran("plugin", "install", store.id)
+        return f"installed {store.id} {store.version}"
+    if had != store.version:
+        _ran("plugin", "update", store.id)
+        return f"updated {store.id} from {had} to {store.version}"
+    return f"{store.id} {store.version} is current"
+
+
+def remove() -> list[str]:
+    """Remove the plugin and its store from Claude Code, and the store's folder.
+
+    Returns:
+        What was done, a line each.
+
+    Company: assumes none.
+    """
+    done = []
+    store = read_store()
+    if store is not None:
+        for args, said in (
+            (("plugin", "uninstall", store.id), f"removed the plugin {store.id}"),
+            (("plugin", "marketplace", "remove", store.name), f"removed the store {store.name}"),
+        ):
+            try:
+                _ran(*args)
+                done.append(said)
+            except ClaudeError as e:
+                done.append(str(e))
+    shutil.rmtree(store_dir(), ignore_errors=True)
+    return done

client/cli.py

@@ -0,0 +1,314 @@
+"""The groundcontrol command (and its alias, gctl): init, the session's start, 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.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from client import claude, connect, machine, system, update
+from client.service import PACKAGE, VERSION, Service, ServiceError
+
+TIMEOUT = 30
+
+
+def say(line: str) -> None:
+    """One line of what the client is doing, for the person."""
+    print(line, flush=True)
+
+
+def _system() -> system.System:
+    """The operating system's side; refused with its reason on any other system."""
+    return system.current()
+
+
+def init(given: str, store_file: str | None = None, door: str | None = None) -> int:
+    """Connect this machine to a company and install the plugin; see the module's docstring.
+
+    Args:
+        given: The company's address, as the install line carries it.
+        store_file: A store's zip to install the plugin from, instead of the service's.
+        door: The door's origin, as the install line gives it; beside the address when not.
+
+    Returns:
+        The exit code.
+
+    Company: the one at the address.
+    """
+    try:
+        address = machine.address_of(given)
+        door = machine.address_of(door) if door else machine.door_of(address)
+        here = _system()
+    except (ValueError, system.Unsupported) as e:
+        say(f"Stopped: {e}.")
+        return 1
+    say(f"Setting up this machine for {address}.")
+    try:
+        found = claude.version()
+    except claude.ClaudeError as e:
+        say(f"Stopped: {e}.")
+        return 1
+    say(f"Claude Code is {'.'.join(map(str, found))}: it can block an action when a check fails.")
+    missing = here.keychain_ready()
+    if missing:
+        say(f"Stopped: {missing}.")
+        return 1
+    say("The keychain is ready to keep the key.")
+    try:
+        held = update.held_to(door)
+    except ServiceError as e:
+        say(f"Stopped: {door} cannot be reached: {e.detail}.")
+        return 1
+    if update.needed(held) == "required":
+        say(f"This client is {VERSION}; {address} needs {held['minimum']} or later.")
+        say("Run the install line again to update it.")
+        return 1
+    called = _connected(address, here)
+    if called is None:
+        called = _connect(door, address, here)
+        if called is None:
+            return 1
+    try:
+        me = called.who_am_i()
+    except ServiceError as e:
+        say(f"Stopped: {called.address} does not know this key: {e.detail}.")
+        return 1
+    person, company = me["person"], me["company"]
+    say(
+        f"{called.address} knows you: {person['name']} ({person['email']}) at {company['name']}, "
+        f"on the machine {me['machine']['name']}."
+    )
+    if not _plugin(called, store_file):
+        return 1
+    say(f"Done. Open Claude Code in a repo of {company['name']}.")
+    return 0
+
+
+def _connected(address: str, here: system.System) -> Service | None:
+    """The company's service when this machine already holds a working key for it."""
+    called = machine.service(address, here)
+    if called is None:
+        return None
+    try:
+        called.who_am_i()
+    except ServiceError:
+        return None
+    say(f"This machine is already connected to {address}.")
+    return called
+
+
+def _connect(door: str, address: str, here: system.System) -> Service | None:
+    """Connect by the device flow; the company's service with its new key, or None."""
+    try:
+        code = connect.ask(door, address, here)
+        say("Approve this machine in your browser: one click, the code is filled in.")
+        say(f"The page: {code.page} (code {code.user_code}).")
+        if not here.open_browser(code.page):
+            say("The browser did not open: open the page yourself.")
+        say("Waiting for your approval.")
+        key, company_address = connect.collect(door, code)
+    except (connect.Refused, ServiceError) as e:
+        say(f"Stopped: {e}.")
+        return None
+    company_address = machine.address_of(company_address)
+    try:
+        here.set_key(company_address, key)
+    except OSError as e:
+        say(f"Stopped: {e}.")
+        return None
+    machine.remember_company(company_address, door)
+    say("Approved. The key is in the keychain, and in no file.")
+    return Service(company_address, key, TIMEOUT)
+
+
+def _plugin(called: Service, store_file: str | None) -> bool:
+    """Install or update the plugin from the service's store, or from an archive."""
+    try:
+        archive = Path(store_file).read_bytes() if store_file else called.store()
+        store = claude.unpack(archive)
+        say(f"Installing the plugin in Claude Code: {store.id} {store.version}.")
+        say(f"The plugin: {claude.install(store)}.")
+    except (OSError, ServiceError, claude.ClaudeError) as e:
+        say(f"Stopped: the plugin needs installing: {e}.")
+        return False
+    return True
+
+
+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.
+
+    Args:
+        event: The SessionStart event Claude Code sends, with its cwd.
+
+    Returns:
+        The lines to show the person; none when all is well.
+
+    Company: each connected one.
+    """
+    state = machine.load()
+    if not state["companies"]:
+        return []
+    try:
+        here = _system()
+    except system.Unsupported:
+        return []
+    said: list[str] = []
+    try:
+        held = update.held_to(state["door"] or machine.door_of(state["companies"][0]))
+    except ServiceError:
+        return []
+    if update.needed(held):
+        try:
+            update.update()
+        except RuntimeError as e:
+            said.append(f"The client needs updating to {held['latest']}: {e}.")
+    store = claude.read_store()
+    try:
+        current = claude.installed(store) if store else None
+        if store is None or current != held["plugin"] or store.version != held["plugin"]:
+            called = next(
+                (s for s in (machine.service(a, here) for a in state["companies"]) if s), None
+            )
+            if called is None:
+                raise claude.ClaudeError("no key for any connected company")
+            claude.install(claude.unpack(called.store()))
+    except (ServiceError, claude.ClaudeError, OSError) as e:
+        said.append(f"The plugin needs updating to {held['plugin']}: {e}.")
+    cwd = event.get("cwd")
+    if cwd:
+        machine.find(Path(cwd), here, refresh=True)
+    return said
+
+
+def repo(root: Path) -> int:
+    """Say which company the repo here is of, and with which key; or the one thing missing.
+
+    Company: each connected one, until the repo's is found.
+    """
+    try:
+        found = machine.find(root, _system(), refresh=True)
+    except system.Unsupported as e:
+        say(f"Stopped: {e}.")
+        return 1
+    if isinstance(found, machine.Missing):
+        say(f"Not managed here: {found.why}.")
+        return 1
+    say(f"{found.repo} is managed at {found.service.address}; its key is in the keychain.")
+    return 0
+
+
+def remove() -> int:
+    """Remove it all from the machine: each connection, each key, the plugin, the store, the client.
+
+    Company: each connected one.
+    """
+    try:
+        here = _system()
+    except system.Unsupported as e:
+        say(f"Stopped: {e}.")
+        return 1
+    for address in machine.load()["companies"]:
+        called = machine.service(address, here)
+        if called is not None:
+            try:
+                called.disconnect()
+                say(f"Disconnected this machine from {address}: its key is refused from now on.")
+            except ServiceError as e:
+                say(
+                    f"{address} did not disconnect this machine ({e.detail}): do it in My settings."
+                )
+        if here.delete_key(address):
+            say(f"Deleted the key for {address} from the keychain.")
+        machine.forget_company(address)
+    for line in claude.remove():
+        say(line[:1].upper() + line[1:] + ".")
+    shutil.rmtree(machine.home(), ignore_errors=True)
+    if update.installed_by_uv():
+        subprocess.run(["uv", "tool", "uninstall", "--quiet", PACKAGE], check=False)
+        say("Removed the client.")
+    say("Nothing of it is left on this machine.")
+    return 0
+
+
+def save_store(target: str) -> int:
+    """Save the plugin's store as a zip, for a machine that installs it from an archive.
+
+    Company: the first connected one.
+    """
+    here = _system()
+    called = next(
+        (s for s in (machine.service(a, here) for a in machine.load()["companies"]) if s), None
+    )
+    if called is None:
+        say(f"Stopped: {machine.NOT_CONNECTED}.")
+        return 1
+    Path(target).write_bytes(called.store())
+    say(f"Saved the plugin's store to {target}.")
+    say(f"Install it with: groundcontrol init <address> --store {target}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run one command of groundcontrol.
+
+    Args:
+        argv: The arguments, without the program's name; the process's own when None.
+
+    Returns:
+        The exit code.
+
+    Company: as the command says.
+    """
+    parser = argparse.ArgumentParser(prog="groundcontrol")
+    parser.add_argument("--version", action="version", version=VERSION)
+    commands = parser.add_subparsers(dest="command", required=True)
+    started = commands.add_parser("init", help="connect this machine to a company")
+    started.add_argument("address", help="the company's address, as the invitation shows it")
+    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")
+    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")
+    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 lines:
+                print(json.dumps({"systemMessage": " ".join(lines)}))
+            return 0
+        if args.command == "repo":
+            return repo(Path.cwd())
+        if args.command == "remove":
+            return remove()
+        return save_store(args.file)
+    except KeyboardInterrupt:
+        say("Stopped.")
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

client/connect.py

@@ -0,0 +1,128 @@
+"""Connecting the machine to a company: the device flow's machine side (RFC 8628).
+
+The client asks the door for a code, saying the machine's name, a hash of its hardware's id,
+its model and OS; opens the company's approval page in the browser with the code already in
+it, where the person, signed in from the invitation, approves with one click; and polls the
+door until the key comes, with the company's address. The key goes into the keychain.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from urllib.parse import urlencode
+
+from client.service import VERSION, VERSION_HEADER, ServiceError, fetch
+from client.system import System
+
+DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+
+
+class Refused(Exception):
+    """The connection was not made; the message says why, for a person."""
+
+
+@dataclass(frozen=True)
+class Code:
+    """A code to approve: the poll's secret, the code the person sees, the page, the pace.
+
+    Attributes:
+        device_code: The client's secret, to poll with.
+        user_code: The code, as XXXX-XXXX.
+        page: The company's approval page, with the code in it.
+        interval: The least seconds between polls.
+        expires_in: Seconds until the code stops working.
+    """
+
+    device_code: str
+    user_code: str
+    page: str
+    interval: int
+    expires_in: int
+
+
+def _post(url: str, form: dict) -> tuple[int, dict]:
+    """POST form fields to the door; (status, the answer's JSON)."""
+    headers = {
+        VERSION_HEADER: VERSION,
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Accept": "application/json",
+    }
+    status, _, body = fetch("POST", url, headers, urlencode(form).encode())
+    try:
+        return status, json.loads(body or b"{}")
+    except ValueError:
+        return status, {}
+
+
+def ask(door: str, address: str, system: System) -> Code:
+    """Ask the door for a code, saying what the machine is.
+
+    Args:
+        door: The door's origin.
+        address: The company's origin, whose approval page the person opens.
+        system: The operating system's side.
+
+    Returns:
+        The Code.
+
+    Raises:
+        Refused: If the door refuses.
+        ServiceError: If the door cannot be reached.
+
+    Company: none; the door belongs to no company.
+    """
+    form = {
+        "name": system.machine_name(),
+        "hardware_id": system.hardware_id(),
+        "model": system.model(),
+        "os": system.os(),
+    }
+    status, answer = _post(f"{door}/api/device/code", form)
+    if status != 200:
+        raise Refused(answer.get("detail") or f"the door refused, {status}")
+    page = f"{address}/connect?{urlencode({'code': answer['user_code']})}"
+    return Code(
+        answer["device_code"], answer["user_code"], page, answer["interval"], answer["expires_in"]
+    )
+
+
+def collect(door: str, code: Code, sleep: Callable[[float], None] = time.sleep) -> tuple[str, str]:
+    """Poll the door until the person approves, and collect the key once.
+
+    Args:
+        door: The door's origin.
+        code: The Code asked for.
+        sleep: How to wait between polls.
+
+    Returns:
+        (the key, the company's address).
+
+    Raises:
+        Refused: If the person denied it, or the code expired.
+        ServiceError: If the door cannot be reached.
+
+    Company: none until the key comes; then the one approval named.
+    """
+    interval = code.interval
+    deadline = time.monotonic() + code.expires_in
+    while time.monotonic() < deadline:
+        sleep(interval)
+        status, answer = _post(
+            f"{door}/api/device/token",
+            {"grant_type": DEVICE_GRANT, "device_code": code.device_code},
+        )
+        if status == 200:
+            return answer["access_token"], answer["company_address"]
+        error = answer.get("error", "")
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            interval += 5
+            continue
+        if status == 426:
+            raise ServiceError(426, answer.get("detail", "update the client"))
+        raise Refused(answer.get("error_description") or answer.get("detail") or error)
+    raise Refused("the code expired before it was approved; run init again")