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

client/service.py

@@ -0,0 +1,398 @@
+"""The plugin's calls to the service: a step's checks, and a feature's plan, all decided there.
+
+The client decides nothing. To enter or exit a step it asks the service to run the step's
+checks; the service answers with the probes it needs, the client runs them in the repo
+(client.probes) and calls again with what each found, until the service has decided every check.
+Only facts leave the machine, never a file's contents or a command's output. Every call goes to
+the company's address with the machine's key and the plugin's version, over https (plain http
+only to this machine itself, for the mock service and local work).
+
+The plan lives on the service: it is made, written and read only through these calls, and the
+service decides who may write or read which part of it. The hooks call this once they move to
+the service (#69, #71, #74); until then the method runs on the machine (client/local.py), with
+the plan in its own store there (LOCAL-PLAN), and the plugin is tested against the mock service
+(client/mock/).
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+import urllib.error
+import urllib.request
+from importlib import metadata
+from pathlib import Path
+from urllib.parse import urlencode, urlsplit, urlunsplit
+
+from client import probes
+
+PACKAGE = "ground-control-cli"
+VERSION_HEADER = "Plugin-Version"
+LOCAL = ("127.0.0.1", "localhost", "::1")
+# Every name under .localhost is this machine (RFC 6761), whatever the resolver says.
+LOOPBACK = "127.0.0.1"
+
+
+def _version() -> str:
+    """The client's version: from its pyproject.toml in a clone, else as installed."""
+    pyproject = Path(__file__).resolve().parent / "pyproject.toml"
+    if pyproject.is_file():
+        return tomllib.loads(pyproject.read_text())["project"]["version"]
+    return metadata.version(PACKAGE)
+
+
+VERSION = _version()
+
+
+def is_local(host: str | None) -> bool:
+    """Whether a host is this machine: localhost, a loopback address, or under .localhost.
+
+    Company: assumes none.
+    """
+    host = (host or "").lower()
+    return host in LOCAL or host.endswith(".localhost")
+
+
+def fetch(
+    method: str,
+    url: str,
+    headers: dict | None = None,
+    data: bytes | None = None,
+    timeout: float = 30,
+) -> tuple[int, dict, bytes]:
+    """One https call (plain http only to this machine), its answer whatever its status.
+
+    A plain http call to a name under .localhost goes to this machine's loopback address,
+    carrying the name as its Host, so a company's local address works without the resolver.
+
+    Args:
+        method: GET, POST or DELETE.
+        url: The address.
+        headers: The headers.
+        data: The body.
+        timeout: How long it may take, in seconds.
+
+    Returns:
+        (status, headers, body).
+
+    Raises:
+        ValueError: If the address is not https, and not this machine.
+        ServiceError: With None when the address cannot be reached.
+
+    Company: the one at the address, if any.
+    """
+    parts = urlsplit(url)
+    if parts.scheme != "https" and not (parts.scheme == "http" and is_local(parts.hostname)):
+        raise ValueError(f"{url}: the service is reached over https only")
+    headers = dict(headers or {})
+    if parts.scheme == "http" and (parts.hostname or "").endswith(".localhost"):
+        headers["Host"] = parts.netloc
+        netloc = LOOPBACK + (f":{parts.port}" if parts.port else "")
+        url = urlunsplit(parts._replace(netloc=netloc))
+    request = urllib.request.Request(url, data=data, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as answer:
+            return answer.status, dict(answer.headers), answer.read()
+    except urllib.error.HTTPError as refused:
+        return refused.code, dict(refused.headers or {}), refused.read()
+    except (urllib.error.URLError, TimeoutError, OSError) as e:
+        raise ServiceError(None, f"{parts.netloc} cannot be reached: {e}") from None
+
+
+class ServiceError(Exception):
+    """The service refused or could not be reached; `status` is its answer's, or None.
+
+    Company: assumes none.
+    """
+
+    def __init__(self, status: int | None, detail: str, refusal: str = ""):
+        """Keep the status, what the service said, and which refusal it named, if any."""
+        super().__init__(detail)
+        self.status, self.detail, self.refusal = status, detail, refusal
+
+
+class Service:
+    """The service at one company's address, called with one machine's key.
+
+    Args:
+        address: The company's address, such as https://acme.<domain>.
+        key: The machine's key.
+        timeout: How long one call may take, in seconds.
+
+    Raises:
+        ValueError: If the address is not https, and not this machine.
+
+    Company: the one at the address.
+    """
+
+    def __init__(self, address: str, key: str, timeout: float):
+        """Refuse an address that is neither https nor this machine."""
+        parts = urlsplit(address)
+        if parts.scheme != "https" and not (parts.scheme == "http" and is_local(parts.hostname)):
+            raise ValueError(f"{address}: the service is reached over https only")
+        self.address, self.key, self.timeout = address.rstrip("/"), key, timeout
+
+    def raw(self, method: str, path: str, body: dict | None = None) -> bytes:
+        """One call to the service, its answer's body as it came.
+
+        Args:
+            method: GET, POST or DELETE.
+            path: The route, with its query.
+            body: The JSON body, for a POST.
+
+        Returns:
+            The answer's body.
+
+        Raises:
+            ServiceError: With the status, the service's detail and the Refusal header when
+                it refuses, or with None when it cannot be reached.
+
+        Company: the one at the address.
+        """
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {
+            "Authorization": f"Bearer {self.key}",
+            VERSION_HEADER: VERSION,
+            "Content-Type": "application/json",
+        }
+        status, answered, content = fetch(method, self.address + path, headers, data, self.timeout)
+        if status >= 400:
+            try:
+                detail = json.loads(content).get("detail", "")
+            except (json.JSONDecodeError, AttributeError, UnicodeDecodeError):
+                detail = ""
+            refusal = next((v for k, v in answered.items() if k.lower() == "refusal"), "")
+            raise ServiceError(status, str(detail) or f"refused, {status}", refusal)
+        return content
+
+    def call(self, method: str, path: str, body: dict | None = None) -> dict:
+        """One call to the service.
+
+        Args:
+            method: GET, POST or DELETE.
+            path: The route, with its query.
+            body: The JSON body, for a POST.
+
+        Returns:
+            The answer's JSON.
+
+        Raises:
+            ServiceError: With the status and the service's detail when it refuses, or with
+                None when it cannot be reached.
+
+        Company: the one at the address.
+        """
+        return json.loads(self.raw(method, path, body) or b"null")
+
+    def run_checks(
+        self, repo: str, feature: str, step: str, moment: str, root, entering=None
+    ) -> list[dict]:
+        """Have a step's checks run on the service, running here the probes it asks for.
+
+        Args:
+            repo: The repo, as its host writes it, such as owner/repo.
+            feature: The feature, `<lane>/<name>`.
+            step: The step entered or exited.
+            moment: entry or exit.
+            root: The checkout the probes run in.
+            entering: The fields of the step_enter row being entered, for the entry checks.
+
+        Returns:
+            Every check of the step, as the service decided it, in run order.
+
+        Raises:
+            ServiceError: If the service refuses, cannot be reached, or asks again for a probe
+                it was given.
+
+        Company: the one at the address.
+        """
+        body = {"repo": repo, "feature": feature, "step": step, "moment": moment}
+        body["entering"] = dict(entering or {})
+        found: list[dict] = []
+        ran: set[str] = set()
+        while True:
+            answer = self.call("POST", "/api/plugin/check", body | {"facts": found})
+            if not answer["need"]:
+                return answer["checks"]
+            for probe in answer["need"]:
+                key = json.dumps(probe, sort_keys=True)
+                if key in ran:
+                    raise ServiceError(None, f"the service asked again for {probe['name']}")
+                ran.add(key)
+                fact = probes.run(probe["name"], probe["params"], root)
+                found.append(probe | {"fact": fact})
+
+    def create_plan(self, repo: str, feature: str, role: str, issue: str = "") -> int:
+        """Have the service make a feature's plan, as its first version.
+
+        Args:
+            repo: The repo, as its host writes it, such as owner/repo.
+            feature: The feature, `<lane>/<name>`.
+            role: Who makes it.
+            issue: The request's address, or "".
+
+        Returns:
+            The version kept.
+
+        Raises:
+            ServiceError: If the service refuses or cannot be reached.
+
+        Company: the one at the address.
+        """
+        body = {"repo": repo, "feature": feature, "issue": issue, "role": role}
+        return self.call("POST", "/api/plugin/plan", body)["version"]
+
+    def write_plan(
+        self,
+        repo: str,
+        feature: str,
+        role: str,
+        section: str,
+        operation: str,
+        row: str = "",
+        cells: dict | None = None,
+        text: str = "",
+        subsection: str = "",
+    ) -> tuple[str, int]:
+        """Have the service apply one write to a feature's plan.
+
+        Args:
+            repo: The repo, as its host writes it, such as owner/repo.
+            feature: The feature, `<lane>/<name>`.
+            role: Who writes.
+            section: The plan's section.
+            operation: set, add, update or remove.
+            row: The row, for update and remove.
+            cells: The row's cells, for add and update.
+            text: The text, for set.
+            subsection: `Server side` of Flow, with set.
+
+        Returns:
+            What was done, and the version kept.
+
+        Raises:
+            ServiceError: If the service refuses the write or cannot be reached.
+
+        Company: the one at the address.
+        """
+        body = {
+            "repo": repo,
+            "feature": feature,
+            "role": role,
+            "section": section,
+            "operation": operation,
+            "row": row,
+            "cells": {k: str(v) for k, v in (cells or {}).items()},
+            "text": text,
+            "subsection": subsection,
+        }
+        answer = self.call("POST", "/api/plugin/plan/write", body)
+        return answer["done"], answer["version"]
+
+    def read_plan(
+        self, repo: str, feature: str, role: str, sections=(), whole: bool = False
+    ) -> tuple[int, str]:
+        """Read sections of a feature's latest plan from the service.
+
+        Args:
+            repo: The repo, as its host writes it, such as owner/repo.
+            feature: The feature, `<lane>/<name>`.
+            role: Who reads.
+            sections: The sections asked for.
+            whole: Whether the whole plan is asked for.
+
+        Returns:
+            The version read, and the sections as Markdown.
+
+        Raises:
+            ServiceError: If the service refuses the read or cannot be reached.
+
+        Company: the one at the address.
+        """
+        query = {"repo": repo, "feature": feature, "role": role, "section": list(sections)}
+        if whole:
+            query["whole"] = "true"
+        answer = self.call("GET", "/api/plugin/plan?" + urlencode(query, doseq=True))
+        return answer["version"], answer["text"]
+
+    def request(self, repo: str, request: str) -> dict:
+        """What `method start` needs of a request, read by the service from the company's GitHub.
+
+        Args:
+            repo: The repo, as its host writes it, such as owner/repo.
+            request: The request's number in the repo, or its address.
+
+        Returns:
+            {url, name, lane, priority}: never the request's words.
+
+        Raises:
+            ServiceError: 409 when the company has not connected GitHub (the machine reads it
+                itself) or the request cannot be read; or if the service cannot be reached.
+
+        Company: the one at the address.
+        """
+        return self.call(
+            "GET", "/api/plugin/request?" + urlencode({"repo": repo, "request": request})
+        )
+
+    def acceptance_report(self, repo: str, feature: str) -> dict:
+        """A feature's last acceptance run, as the service builds it from the run's facts.
+
+        Args:
+            repo: The repo, as its host writes it, such as owner/repo.
+            feature: The feature, `<lane>/<name>`.
+
+        Returns:
+            {commit, proven, total, promises: [{id, proven, rows: [{id, test, state}]}]}.
+
+        Raises:
+            ServiceError: 409 when the feature has no run yet; or if the service refuses or
+                cannot be reached.
+
+        Company: the one at the address.
+        """
+        query = urlencode({"repo": repo, "feature": feature})
+        return self.call("GET", "/api/plugin/acceptance-report?" + query)
+
+    def who_am_i(self) -> dict:
+        """Who the key belongs to: {machine, person, company}, as the service knows them.
+
+        Raises:
+            ServiceError: If the service refuses the key or cannot be reached.
+
+        Company: the one at the address.
+        """
+        return self.call("GET", "/api/machine/me")
+
+    def managed(self) -> list[dict]:
+        """The repos the method guards in the company, each with every identifier a clone may know.
+
+        Returns:
+            [{github_id, name, previous_names, https_url, ssh_url}].
+
+        Raises:
+            ServiceError: If the service refuses or cannot be reached.
+
+        Company: the one at the address.
+        """
+        return self.call("GET", "/api/plugin/repos/managed")
+
+    def store(self) -> bytes:
+        """The plugin's store, a zip, as the service serves it at its own version.
+
+        Raises:
+            ServiceError: If the service refuses or cannot be reached.
+
+        Company: the one at the address.
+        """
+        return self.raw("GET", "/api/plugin/store")
+
+    def disconnect(self) -> None:
+        """Disconnect this machine on the service: its key is refused from now on.
+
+        Raises:
+            ServiceError: If the service refuses or cannot be reached.
+
+        Company: the one at the address.
+        """
+        self.raw("DELETE", "/api/machine/me")

client/system/__init__.py

@@ -0,0 +1,73 @@
+"""What depends on the machine's operating system, behind one interface: `System`.
+
+The keychain that keeps each company's key, the machine's own facts (its name, a hash of its
+hardware's id, its model and OS), and opening the browser. A Mac only, for now: another system
+is one more module here, picked by `current`, and nothing else changes.
+"""
+
+from __future__ import annotations
+
+import platform
+import sys
+from typing import Protocol
+
+# The keychain's service name for the keys: one item per company, its account the address.
+KEYCHAIN_SERVICE = "groundcontrol"
+
+
+class Unsupported(Exception):
+    """This operating system, or this machine, cannot run the client; the message says why."""
+
+
+class System(Protocol):
+    """The operating system's side of the client.
+
+    Company: assumes none.
+    """
+
+    name: str
+
+    def keychain_ready(self) -> str:
+        """Why the keychain cannot keep a key, or "" when it can."""
+
+    def get_key(self, address: str) -> str | None:
+        """The company's key, from the keychain, or None."""
+
+    def set_key(self, address: str, key: str) -> None:
+        """Keep the company's key in the keychain, replacing any."""
+
+    def delete_key(self, address: str) -> bool:
+        """Delete the company's key from the keychain; whether there was one."""
+
+    def machine_name(self) -> str:
+        """The machine's own name, such as Dana's MacBook Pro."""
+
+    def hardware_id(self) -> str:
+        """A hash of the operating system's id for the hardware: the same machine, the same hash."""
+
+    def model(self) -> str:
+        """The machine's model, such as MacBookPro18,3."""
+
+    def os(self) -> str:
+        """The operating system and its version, such as macOS 15.6."""
+
+    def open_browser(self, url: str) -> bool:
+        """Open a page in the person's browser; whether it opened."""
+
+
+def current() -> System:
+    """The running operating system's System.
+
+    Returns:
+        The System.
+
+    Raises:
+        Unsupported: On any system but a Mac.
+
+    Company: assumes none.
+    """
+    if sys.platform == "darwin":
+        from client.system.macos import MacOS
+
+        return MacOS()
+    raise Unsupported(f"the client runs on a Mac only, for now; this is {platform.system()}")

client/system/macos.py

@@ -0,0 +1,92 @@
+"""A Mac's side of the client: the login keychain through `security`, and the machine's facts.
+
+A key never touches a file, and never a command's arguments: it reaches `security` on its
+standard input (`security -i`), where no other process sees it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import subprocess
+
+from client.system import KEYCHAIN_SERVICE
+
+NO_KEYCHAIN = "this Mac has no keychain to keep the key in: open Keychain Access and make one"
+
+
+def _run(*args: str, stdin: str | None = None) -> subprocess.CompletedProcess:
+    """Run a command of the system, its output as text; never raises for its exit code."""
+    try:
+        return subprocess.run(args, input=stdin, capture_output=True, text=True, timeout=30)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        return subprocess.CompletedProcess(args, 1, "", str(e))
+
+
+def _quoted(value: str) -> str:
+    """A value as `security -i` reads one argument."""
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+class MacOS:
+    """The Mac's System.
+
+    Company: assumes none.
+    """
+
+    name = "macos"
+
+    def keychain_ready(self) -> str:
+        """Why the keychain cannot keep a key, or "" when it can."""
+        found = _run("security", "default-keychain")
+        return "" if found.returncode == 0 and found.stdout.strip() else NO_KEYCHAIN
+
+    def get_key(self, address: str) -> str | None:
+        """The company's key, from the login keychain, or None."""
+        found = _run(
+            "security", "find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", address, "-w"
+        )
+        return found.stdout.strip() or None if found.returncode == 0 else None
+
+    def set_key(self, address: str, key: str) -> None:
+        """Keep the company's key in the login keychain, replacing any.
+
+        Raises:
+            OSError: If the keychain refuses it.
+        """
+        command = " ".join(
+            ["add-generic-password", "-U", "-s", _quoted(KEYCHAIN_SERVICE)]
+            + ["-a", _quoted(address), "-l", _quoted(f"{KEYCHAIN_SERVICE} {address}")]
+            + ["-w", _quoted(key)]
+        )
+        done = _run("security", "-i", stdin=command + "\n")
+        if done.returncode != 0 or self.get_key(address) != key:
+            raise OSError(f"the keychain did not keep the key: {done.stderr.strip()}")
+
+    def delete_key(self, address: str) -> bool:
+        """Delete the company's key from the login keychain; whether there was one."""
+        done = _run("security", "delete-generic-password", "-s", KEYCHAIN_SERVICE, "-a", address)
+        return done.returncode == 0
+
+    def machine_name(self) -> str:
+        """The Mac's name, as Sharing shows it."""
+        return _run("scutil", "--get", "ComputerName").stdout.strip()
+
+    def hardware_id(self) -> str:
+        """The sha256 of the Mac's IOPlatformUUID; never the id itself."""
+        found = _run("ioreg", "-rd1", "-c", "IOPlatformExpertDevice").stdout
+        match = re.search(r'"IOPlatformUUID"\s*=\s*"([^"]+)"', found)
+        return hashlib.sha256(match[1].encode()).hexdigest() if match else ""
+
+    def model(self) -> str:
+        """The Mac's model identifier."""
+        return _run("sysctl", "-n", "hw.model").stdout.strip()
+
+    def os(self) -> str:
+        """MacOS and its version."""
+        version = _run("sw_vers", "-productVersion").stdout.strip()
+        return f"macOS {version}".strip()
+
+    def open_browser(self, url: str) -> bool:
+        """Open the page in the default browser."""
+        return _run("open", url).returncode == 0

client/update.py

@@ -0,0 +1,110 @@
+"""The client keeping itself current, at the start of a session and never during one.
+
+The service says the oldest client it still answers and the latest one (`GET /api/client`).
+Below the oldest, the client updates before anything else; below the latest, it updates
+without asking. It updates through uv, which installed it; a client run from a clone of the
+product's repo is that clone's, and is never updated here.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from importlib import metadata
+
+from client.service import PACKAGE, VERSION, ServiceError, fetch
+
+TIMEOUT = 300
+
+
+def numbers(version: str) -> tuple[int, int, int] | None:
+    """A version's three numbers, or None.
+
+    Company: assumes none.
+    """
+    found = re.match(r"^\s*(\d+)\.(\d+)\.(\d+)", version or "")
+    return (int(found[1]), int(found[2]), int(found[3])) if found else None
+
+
+def held_to(door: str) -> dict:
+    """What the service holds the client to: {minimum, latest, plugin}, asked at its door.
+
+    Args:
+        door: The door's origin.
+
+    Returns:
+        The answer.
+
+    Raises:
+        ServiceError: If the service cannot be reached or does not answer.
+
+    Company: assumes none.
+    """
+    status, _, body = fetch("GET", door.rstrip("/") + "/api/client")
+    if status != 200:
+        raise ServiceError(status, f"{door} did not say which versions it needs")
+    return json.loads(body)
+
+
+def installed_by_uv() -> bool:
+    """Whether this client was installed as a uv tool, so it can update itself.
+
+    Company: assumes none.
+    """
+    try:
+        metadata.version(PACKAGE)
+    except metadata.PackageNotFoundError:
+        return False
+    return shutil.which("uv") is not None and "/uv/tools/" in __file__.replace("\\", "/")
+
+
+def needed(versions: dict, current: str = VERSION) -> str:
+    """Whether the client must update: "required", "available", or "".
+
+    Company: assumes none.
+    """
+    here = numbers(current)
+    if here is None or here < (numbers(versions["minimum"]) or (0, 0, 0)):
+        return "required"
+    if here < (numbers(versions["latest"]) or (0, 0, 0)):
+        return "available"
+    return ""
+
+
+def update() -> str:
+    """Update the client to the latest version on the registry.
+
+    Returns:
+        The version it is now.
+
+    Raises:
+        RuntimeError: If it cannot update itself.
+
+    Company: assumes none.
+    """
+    if not installed_by_uv():
+        raise RuntimeError(
+            "this client was not installed by the install line; it cannot update itself"
+        )
+    try:
+        done = subprocess.run(
+            ["uv", "tool", "upgrade", "--quiet", PACKAGE],
+            capture_output=True,
+            text=True,
+            timeout=TIMEOUT,
+            stdin=subprocess.DEVNULL,
+        )
+    except (OSError, subprocess.TimeoutExpired) as e:
+        raise RuntimeError(f"uv could not update the client: {e}") from None
+    if done.returncode != 0:
+        said = (done.stderr or done.stdout).strip().splitlines()
+        raise RuntimeError(
+            f"uv could not update the client: {said[-1] if said else done.returncode}"
+        )
+    found = subprocess.run(
+        ["uv", "tool", "list"], capture_output=True, text=True, timeout=TIMEOUT
+    ).stdout
+    match = re.search(rf"^{re.escape(PACKAGE)} v(\S+)", found, re.MULTILINE)
+    return match[1] if match else "the latest"

ground_control_cli-0.2.0.dist-info/METADATA

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