graphban-cli 0.1.0__py3-none-any.whl

gban/cli.py

@@ -0,0 +1,379 @@
+"""`gban` — the client for a human at a terminal (PRD-40).
+
+The v1 verb list is short on purpose (D11). Every verb here is one HTTP call to one route
+that already exists, named one-to-one, because a client that composes several calls into a
+new act becomes a second place the rules live.
+"""
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+from gban import config, doctor as doctor_mod
+from gban.client import (EXIT_NO_SESSION, EXIT_NO_SUPERVISOR, EXIT_REFUSED, EXIT_UNREACHABLE,
+                       Client, NoSession,
+                       Refused, Unreachable, authenticated, login)
+
+PROG = "gban"
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=PROG,
+        description=("A Graphban client for a human at a terminal. The web app, `gbfleet` and "
+                     "`graphban` all still exist; this is for the acts that otherwise need a "
+                     "browser, and for finding out why something is stuck."),
+    )
+    parser.add_argument("--json", action="store_true", dest="as_json",
+                        help="machine-readable output; the human format is never parsed")
+    parser.add_argument("--server", default=None,
+                        help=f"Graphban base URL (or ${config.URL_ENV}, or {config.SETTINGS_FILE})")
+    parser.add_argument("--project", default=None,
+                        help=f"project id (or ${config.PROJECT_ENV}, or {config.SETTINGS_FILE})")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    login_cmd = sub.add_parser(
+        "login", help="start a session on this machine",
+        description=("Exchanges an email and password for a session. The refresh token is "
+                     "written to session.json at mode 600; the access token is never stored, "
+                     "because it is renewed on every invocation anyway."))
+    login_cmd.add_argument("--email", default=None)
+
+    sub.add_parser("logout", help="end the session, here and on the server")
+    sub.add_parser(
+        "doctor", help="check both halves: the ledger, and the local fleet",
+        description=("Everything that can be checked before anything is spawned. The ledger "
+                     "half runs here; the local half is `gbfleet doctor`, run as a subprocess. "
+                     "Neither half silences the other: what could not be checked prints "
+                     "UNKNOWN with its reason, never a pass."))
+
+    fleet = sub.add_parser(
+        "fleet", help="hand off to gbfleet (the supervisor)",
+        description=("Passes everything through to `gbfleet` and returns its exit code "
+                     "unchanged — 75 is stuck, 69 an unreachable model endpoint, 55 a spent "
+                     "budget, and folding those into one code would destroy a taxonomy the "
+                     "supervisor's own tests pin."),
+        add_help=False)
+    fleet.add_argument("rest", nargs=argparse.REMAINDER,
+                       help="arguments for gbfleet; try `gban fleet --help`")
+    sub.add_parser("whoami", help="who this session belongs to, and where it points")
+
+    seats = sub.add_parser(
+        "seats", help="the seats a wave was issued, and issuing more",
+        description=("A SEAT is an enrolment code: one agent's right to register once, for "
+                     "half an hour. It is not a credential — the credential is the API key "
+                     "the child authenticates with, and `gban keys` is where those live."))
+    seats_do = seats.add_subparsers(dest="act")
+    issue = seats_do.add_parser("issue", help="issue seats, one role per agent")
+    issue.add_argument("roles", nargs="+", metavar="ROLE",
+                       help="one entry per agent, repeats included: worker worker planner")
+    issue.add_argument("--wave", default="",
+                       help="blank means the next one, computed server-side")
+    revoke = seats_do.add_parser("revoke-unused", help="throw away seats nobody redeemed")
+    revoke.add_argument("--wave", default="")
+
+    agents = sub.add_parser(
+        "agents", help="the roster, and re-tasking one",
+        description=("Who is live, what each is doing, and — the reason this verb exists — "
+                     "what any of them was last refused and why."))
+    agents_do = agents.add_subparsers(dest="act")
+    role = agents_do.add_parser(
+        "role", help="re-task a live agent, as the human who owns its credential",
+        description=("The credential ceiling still decides. A role the agent's key does not "
+                     "permit is refused by the server, and widening a ceiling means minting "
+                     "a different credential — keeping those two acts apart is the point of "
+                     "having a ceiling. Lands on the agent's next poll."))
+    role.add_argument("agent_id")
+    role.add_argument("role", metavar="ROLE")
+    role.add_argument("--reason", default="", help="recorded on the event, and told to the agent")
+
+    keys = sub.add_parser("keys", help="the credentials this project's agents authenticate with")
+    keys_do = keys.add_subparsers(dest="act")
+    mint = keys_do.add_parser(
+        "mint", help="mint a credential narrowed to a role, or to several",
+        description=("Repeat --role to mint a credential an agent can be RE-TASKED within. "
+                     "One role is the default and is a real bound: it is what stops a client "
+                     "config from registering a worker as a planner. But a role change cannot "
+                     "climb past the credential the agent already holds, so an agent minted "
+                     "for one role can never be promoted without being restarted."))
+    mint.add_argument("--role", required=True, action="append", metavar="ROLE",
+                      help="repeatable; the first is the role the agent registers into")
+    mint.add_argument("--wave", default="wave-1")
+    mint.add_argument("--label", default="")
+    return parser
+
+
+def _out(payload: dict, human: str, as_json: bool) -> None:
+    print(json.dumps(payload, indent=1, sort_keys=True) if as_json else human)
+
+
+def _server(args) -> str:
+    url = config.resolve(args.server, config.URL_ENV, "url")
+    if not url:
+        print(f"{PROG}: no server. Pass --server, set ${config.URL_ENV}, or run `gban login "
+              f"--server …` once.", file=sys.stderr)
+        raise SystemExit(EXIT_REFUSED)
+    return url
+
+
+def cmd_login(args) -> int:
+    url = _server(args)
+    # A TERMINAL, OR NOTHING. `getpass` falls back to a plain echoing read when it cannot
+    # turn echo off, and warns about it — which is the wrong trade for a password: the
+    # warning arrives after the person has already decided to type. Without a tty the
+    # password would land in the scrollback, in a transcript, or in whatever captured the
+    # session. Refusing is the only safe branch, and it is not a limitation somebody can
+    # work around by trying harder.
+    if not sys.stdin.isatty():
+        print(f"{PROG}: `{PROG} login` needs a terminal. Without one, the prompt cannot turn "
+              f"off echo and your password would be written to the scrollback.\n"
+              f"     Run it in a shell, not through a pipe, a heredoc or an editor's "
+              f"command runner.", file=sys.stderr)
+        return EXIT_REFUSED
+    try:
+        email = args.email or input("email: ").strip()
+        # Prompted, never an argument: argv is world-readable in `ps`, and a password in
+        # shell history is a credential nobody remembers leaving there.
+        password = getpass.getpass("password: ")
+    except (EOFError, KeyboardInterrupt):
+        # Somebody pressed ctrl-C or the input ended. One line, not a traceback — the
+        # same rule criterion 4 applies to an expired session applies to a cancelled login.
+        print(f"\n{PROG}: cancelled", file=sys.stderr)
+        return EXIT_REFUSED
+    pair = login(url, email, password)
+    refresh = pair.get("refresh_token") or ""
+    if not refresh:
+        print(f"{PROG}: the server returned no refresh token", file=sys.stderr)
+        return EXIT_REFUSED
+    config.save_settings(url=url, project=config.resolve(args.project, config.PROJECT_ENV,
+                                                         "project"))
+    path = config.save_session(refresh, user=email)
+    _out({"server": url, "session": str(path), "user": email},
+         f"{PROG}: signed in to {url} as {email}\n     session stored at {path} (mode 600)",
+         args.as_json)
+    return 0
+
+
+def cmd_logout(args) -> int:
+    url = _server(args)
+    told_server, why = False, ""
+    try:
+        authenticated(url).call("POST", "/api/auth/logout")
+        told_server = True
+    except NoSession:
+        # Already dead server-side. Not an error: the person asked to be logged out and they
+        # are, which is the outcome they wanted.
+        told_server, why = True, "the session was already ended"
+    except (Unreachable, Refused) as exc:
+        why = str(exc)
+    removed = config.clear_session()
+    # The file goes EITHER WAY. Leaving it because the server could not be told would leave a
+    # live token on disk belonging to somebody who believes they logged out, which is the one
+    # outcome worth avoiding here.
+    human = f"{PROG}: signed out" + ("" if told_server else
+                                     f"\n     WARNING: the server was not told ({why}).\n"
+                                     "     The local session is gone; the server-side one "
+                                     "stays valid until it expires.\n     Revoke it from the "
+                                     "web app, or run `gban logout` again when the network is "
+                                     "back.")
+    if not removed and told_server:
+        human = f"{PROG}: no local session to remove"
+    _out({"signed_out": True, "server_told": told_server, "local_removed": removed,
+          "reason": why}, human, args.as_json)
+    return 0
+
+
+def cmd_whoami(args) -> int:
+    url = _server(args)
+    me = authenticated(url).call("GET", "/api/auth/me")
+    project = config.resolve(args.project, config.PROJECT_ENV, "project")
+    _out({"server": url, "project": project, **me},
+         f"{PROG}: {me.get('email') or me.get('id')} at {url}"
+         + (f"\n     project {project}" if project else "\n     no default project set"),
+         args.as_json)
+    return 0
+
+
+def cmd_doctor(args) -> int:
+    url = config.resolve(args.server, config.URL_ENV, "url")
+    project = config.resolve(args.project, config.PROJECT_ENV, "project")
+    api_key = os.environ.get(config.API_KEY_ENV, "")
+    lines, code = doctor_mod.run(url, project, api_key)
+    _out({"lines": lines, "ok": code == 0}, doctor_mod.render(lines), args.as_json)
+    return code
+
+
+def cmd_fleet(args) -> int:
+    """A subprocess, never an import (D5).
+
+    Keeps `gban` free of the supervisor's dependencies, keeps the Apache-2.0 boundary intact,
+    and leaves `gbfleet --help` authoritative about its own commands.
+    """
+    binary = doctor_mod.find_supervisor()
+    if not binary:
+        print(f"{PROG}: gbfleet is not installed here. Install it with:\n"
+              f"     {doctor_mod.INSTALL_SUPERVISOR}\n"
+              f"     …or run it from the repository's fleet/ directory.", file=sys.stderr)
+        return EXIT_NO_SUPERVISOR
+    argv = [binary, *[a for a in args.rest if a != "--"]]
+    url = config.resolve(args.server, config.URL_ENV, "url")
+    if url and "--server" not in argv:
+        argv += ["--server", url]
+    project = config.resolve(args.project, config.PROJECT_ENV, "project")
+    if project and "--project" not in argv:
+        argv += ["--project", project]
+    # Its exit code, unchanged. `gban` adds nothing and explains nothing: the supervisor's
+    # message is the one its own tests pin.
+    #
+    # The ENVIRONMENT goes through the same function `doctor` uses (GRPH-782). It used not
+    # to, so the doctor certified a local half this command could not reproduce.
+    return subprocess.run(argv, env=doctor_mod.child_environment(
+        os.environ.get(config.API_KEY_ENV, ""))).returncode
+
+
+def _project(args, act: str) -> str:
+    project = config.resolve(args.project, config.PROJECT_ENV, "project")
+    if not project:
+        print(f"{PROG}: `{PROG} {act}` needs a project. Pass --project, set "
+              f"${config.PROJECT_ENV}, or run `gban login --project …` once.", file=sys.stderr)
+        raise SystemExit(EXIT_REFUSED)
+    return project
+
+
+def _fleet_read(args, act: str) -> tuple[dict, str]:
+    """The one read behind `seats`, `agents` and `keys` (D11).
+
+    `GET /api/fleet` already returns the roster, the seats and the credentials together,
+    because they are read together. Three verbs over one route is not three routes.
+    """
+    url, project = _server(args), _project(args, act)
+    client = authenticated(url, act=act)
+    return client.call("GET", f"/api/fleet?project_id={project}"), project
+
+
+def cmd_seats(args) -> int:
+    if args.act == "issue":
+        url, project = _server(args), _project(args, "seats issue")
+        out = authenticated(url, act="seats issue").call(
+            "POST", "/api/fleet/seats",
+            {"project_id": project, "roles": args.roles, "wave": args.wave})
+        # The codes are returned ONCE, by the server, and nothing here stores them. A CLI
+        # that helpfully wrote them to a file would be inventing a second credential at rest
+        # that no route and no test knows about.
+        lines = [f"{PROG}: {len(out.get('seats', []))} seats on {out.get('wave')}",
+                 "     each code is shown once and is not stored anywhere:"]
+        lines += [f"     {s['code']}  {s['role']}" for s in out.get("seats", [])]
+        lines.append("     feed them to `gban fleet up --seats-file`, one per line.")
+        _out(out, "\n".join(lines), args.as_json)
+        return 0
+    if args.act == "revoke-unused":
+        url, project = _server(args), _project(args, "seats revoke-unused")
+        out = authenticated(url, act="seats revoke-unused").call(
+            "POST", "/api/fleet/seats/revoke-unused",
+            {"project_id": project, "wave": args.wave or None})
+        _out(out, f"{PROG}: {out.get('revoked', 0)} unused seats revoked"
+                  f"\n     consumed seats are untouched: they record which agent took what.",
+             args.as_json)
+        return 0
+    fleet, _ = _fleet_read(args, "seats")
+    seats = fleet.get("seats", [])
+    human = [f"{PROG}: {len(seats)} seats"] + [
+        f"     {s.get('wave', ''):<10} {s.get('role', ''):<8} {s.get('state', '')}"
+        + (f"  taken by {s['consumed_by']}" if s.get("consumed_by") else "")
+        for s in seats] or [f"{PROG}: no seats"]
+    _out({"seats": seats}, "\n".join(human), args.as_json)
+    return 0
+
+
+def cmd_agents(args) -> int:
+    if args.act == "role":
+        url = _server(args)
+        # No project in the path: the agent id already names one, and the server resolves it.
+        # Asking for a project here would let a person name one the agent is not on.
+        out = authenticated(url, act="agents role").call(
+            "PUT", f"/api/fleet/agents/{args.agent_id}/role",
+            {"role": args.role, "reason": args.reason})
+        _out(out, f"{PROG}: {out.get('agent_id')} is now {out.get('active_role')}"
+                  f"\n     {out.get("takes_effect") or "on the agent's next poll"}", args.as_json)
+        return 0
+    fleet, _ = _fleet_read(args, "agents")
+    agents = fleet.get("agents", [])
+    human = [f"{PROG}: {len(agents)} agents"]
+    for a in agents:
+        # WHAT IT COULD BE MOVED TO, next to what it is. Without the ceiling on the row,
+        # `agents role` is a coin flip against a bound nothing shows (GRPH-780).
+        ceiling = a.get("credential_roles") or []
+        human.append(f"     {a.get('key') or a.get('id'):<12} {a.get('active_role', ''):<8} "
+                     f"{a.get('state', ''):<10} {a.get('credential') or ''}"
+                     + (f"  [{'|'.join(ceiling)}]" if len(ceiling) > 1 else ""))
+        # THE LINE THIS VERB EXISTS FOR (criterion 8). A roster that says "idle worker" for an
+        # agent being refused every call it makes is the thing that cost an afternoon and a
+        # database query on Super-Arc.
+        refusal = a.get("last_refusal") or {}
+        if refusal.get("tool"):
+            human.append(f"       last refused {refusal['tool']} x{refusal.get('count', 1)}: "
+                         f"{refusal.get('reason', '')}")
+    _out({"agents": agents}, "\n".join(human) if agents else f"{PROG}: no agents", args.as_json)
+    return 0
+
+
+def cmd_keys(args) -> int:
+    if args.act == "mint":
+        url, project = _server(args), _project(args, "keys mint")
+        first, *also = args.role
+        out = authenticated(url, act="keys mint").call(
+            "POST", "/api/fleet/keys",
+            {"project_id": project, "role": first, "also": also, "wave": args.wave,
+             "label": args.label})
+        ceiling = out.get("roles") or [out.get("role")]
+        _out(out, f"{PROG}: {out.get('plaintext')}"
+                  f"\n     {out.get('role')} on {out.get('wave')}, shown once, expires "
+                  f"{out.get('expires_at')}"
+                  + (f"\n     re-taskable within {', '.join(ceiling)}" if len(ceiling) > 1
+                     else "\n     one role only: an agent on this key cannot be re-tasked"),
+             args.as_json)
+        return 0
+    fleet, _ = _fleet_read(args, "keys")
+    creds = fleet.get("credentials", [])
+    human = [f"{PROG}: {len(creds)} credentials"] + [
+        f"     {c.get('prefix', ''):<14} {c.get('name', ''):<20} {c.get('wave') or '-':<10}"
+        + ("  REVOKED" if c.get("revoked") else "")
+        + ("  all-in-one" if c.get("posture") == "single" else "")
+        for c in creds]
+    _out({"credentials": creds}, "\n".join(human) if creds else f"{PROG}: no credentials",
+         args.as_json)
+    return 0
+
+
+COMMANDS = {"login": cmd_login, "logout": cmd_logout, "whoami": cmd_whoami,
+            "doctor": cmd_doctor, "fleet": cmd_fleet, "seats": cmd_seats,
+            "agents": cmd_agents, "keys": cmd_keys}
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        return COMMANDS[args.command](args)
+    except NoSession as exc:
+        # Never a 401 traceback: the person needs one instruction, and this is it.
+        print(f"{PROG}: {exc.advice(PROG)}", file=sys.stderr)
+        return EXIT_NO_SESSION
+    except Unreachable as exc:
+        print(f"{PROG}: {exc}", file=sys.stderr)
+        return EXIT_UNREACHABLE
+    except Refused as exc:
+        # The server's own words, unedited (D8). Its `hint` is already the machine-readable
+        # next step, and re-wording it here would be a second definition of the rule.
+        print(f"{PROG}: {exc.detail}", file=sys.stderr)
+        if exc.hint:
+            print(f"     {exc.hint}", file=sys.stderr)
+        return EXIT_REFUSED
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

gban/client.py

@@ -0,0 +1,154 @@
+"""The one place `gban` talks to a Graphban server (PRD-40 D3, D11).
+
+Every verb is one endpoint, called once. The only call that is not a verb is the token
+exchange, and it is transport rather than policy: it carries no rule, decides nothing, and
+happens before any verb runs.
+
+**The session model, and why it needs no machinery.** `POST /api/auth/refresh` issues a new
+pair but does not consume the token presented — validity is keyed on `user.token_version`,
+which moves only on logout or a password change (AL-59). So an invocation exchanges once, holds
+the access token in memory, makes its call, and exits; two `gban` processes at once cannot
+disturb each other; and `session.json` is written only by `gban login`, never per call. Writing
+it every time would manufacture the race that does not otherwise exist.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+from gban import config
+
+#: Exit codes. Chosen so they cannot collide with a passed-through `gbfleet` code, which
+#: carries meaning of its own (75 stuck, 69 unreachable endpoint, 55 budget) and is returned
+#: unchanged by `gban fleet` (D5).
+EXIT_REFUSED = 1
+EXIT_UNREACHABLE = 2
+EXIT_NO_SESSION = 3
+EXIT_NO_SUPERVISOR = 4
+
+TIMEOUT = 30.0
+
+
+class Unreachable(Exception):
+    """No HTTP response at all: the server, the network, or the URL."""
+
+
+class NoSession(Exception):
+    """No stored session, or one the server will not renew.
+
+    Expired and revoked are deliberately the SAME state here. Both come back 401, and the
+    person does the same thing either way — a distinction would be precision nobody can act on.
+
+    "You have a credential, but not one that can do this" IS a different state, and the only
+    one where the next step is not simply `gban login` (criterion 5). Somebody who exported
+    `GRAPHBAN_API_KEY` and watched `gban fleet` work has every reason to read "session expired"
+    as a bug in the tool rather than as a statement about what a key is for.
+    """
+
+    def __init__(self, why: str, *, act: str = "", have_key: bool = False) -> None:
+        super().__init__(why)
+        self.why = why
+        self.act = act
+        self.have_key = have_key
+
+    def advice(self, prog: str) -> str:
+        if self.have_key and self.act:
+            return (f"`{prog} {self.act}` needs a session, not an API key. It acts as YOU — "
+                    f"the ledger records which human did it — and ${config.API_KEY_ENV} names "
+                    f"an agent.\n     Run `{prog} login`.")
+        return f"session expired, run `{prog} login`"
+
+
+class Refused(Exception):
+    """The server said no, in its own words (D8).
+
+    Carries the server's `detail` and `hint` unedited. Re-wording either would put a second
+    copy of a rule in the client, and the server's phrasing is the one under test.
+    """
+
+    def __init__(self, status: int, detail: str, hint: str = "") -> None:
+        super().__init__(detail)
+        self.status = status
+        self.detail = detail
+        self.hint = hint
+
+
+class Client:
+    """A server, and the credential this invocation is using."""
+
+    def __init__(self, url: str, *, token: str = "", api_key: str = "") -> None:
+        self.url = url.rstrip("/")
+        self.token = token
+        self.api_key = api_key
+
+    # ---- transport ---------------------------------------------------------------------
+    def _open(self, method: str, path: str, body: dict | None, headers: dict) -> tuple[int, dict]:
+        data = json.dumps(body).encode() if body is not None else None
+        request = urllib.request.Request(self.url + path, data=data, method=method,
+                                         headers={"Content-Type": "application/json", **headers})
+        try:
+            with urllib.request.urlopen(request, timeout=TIMEOUT) as response:
+                raw = response.read().decode() or "{}"
+                return response.status, (json.loads(raw) if raw.strip() else {})
+        except urllib.error.HTTPError as exc:
+            raw = exc.read().decode() or "{}"
+            try:
+                payload = json.loads(raw)
+            except ValueError:
+                payload = {"detail": raw[:400]}
+            return exc.code, payload if isinstance(payload, dict) else {"detail": str(payload)}
+        except (urllib.error.URLError, OSError, TimeoutError) as exc:
+            # No HTTP response at all. Structurally different from a refusal, and reported as
+            # such — the client never reads a message to decide which failure it is in (D8).
+            raise Unreachable(f"could not reach {self.url}: {exc}") from exc
+
+    def call(self, method: str, path: str, body: dict | None = None) -> dict:
+        headers = {}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        elif self.api_key:
+            headers["X-API-Key"] = self.api_key
+        status, payload = self._open(method, path, body, headers)
+        if status >= 400:
+            detail = payload.get("detail") or payload.get("message") or f"HTTP {status}"
+            if isinstance(detail, dict):
+                detail, hint = (detail.get("message") or str(detail)), detail.get("hint", "")
+            else:
+                hint = payload.get("hint", "")
+            raise Refused(status, str(detail), str(hint))
+        return payload
+
+
+def login(url: str, email: str, password: str) -> dict:
+    """Exchange credentials for a token pair. The only call that sends a password."""
+    return Client(url).call("POST", "/api/auth/login",
+                            {"email": email, "password": password})
+
+
+def authenticated(url: str, *, act: str = "") -> Client:
+    """A client for this invocation: one refresh exchange, access token held in memory.
+
+    Raises `NoSession` when there is nothing stored or the server will not renew it. The
+    caller turns that into one instruction and exit 3 — never a traceback, and never a bare
+    401 (criterion 4). `act` is the verb the person typed; it appears only in the message for
+    somebody holding an API key and nothing else.
+    """
+    stored = config.session().get("refresh_token")
+    if not stored:
+        # `act` is what the person typed, so the message can name it rather than describe a
+        # category they would then have to work out they are in.
+        raise NoSession("no stored session", act=act,
+                        have_key=bool(os.environ.get(config.API_KEY_ENV)))
+    try:
+        pair = Client(url).call("POST", "/api/auth/refresh", {"refresh_token": stored})
+    except Refused as exc:
+        raise NoSession(str(exc)) from exc
+    token = pair.get("access_token") or ""
+    if not token:
+        raise NoSession("the server returned no access token")
+    # The new refresh token is NOT written back. The presented one stays valid (the server
+    # keys on `token_version`), so rewriting the file on every call would buy nothing and
+    # create a race between concurrent invocations.
+    return Client(url, token=token)

gban/config.py

@@ -0,0 +1,102 @@
+"""Where `gban` keeps its two facts, and why they are two files (PRD-40 D3, D10).
+
+`~/.graphban/` is shared with `graphban`, the operator's database-side tool, and the sharing
+stops at the directory. `gban` reads `gban.json` (`url`, `project`) and `session.json` (a refresh
+token) and **never opens `config.json`**, which is `graphban`'s and may hold a database link.
+
+The grill made that stricter than the draft. Reading `config.json` and ignoring the keys it did
+not recognise would have been true and insufficient: the risk is not misreading a database
+password, it is that password living in a file which now has a second consumer and a second
+reason to be copied onto another machine. `graphban` runs in a container against a database;
+`gban` runs on a laptop against HTTP; the credential that must not cross that line lives in its
+own file, so copying a config never carries it.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+#: The directory both tools use. Shared deliberately — a person has one Graphban.
+HOME_ENV = "GRAPHBAN_HOME"
+
+#: `gban`'s own settings. NOT `config.json`, which belongs to `graphban` (D10).
+SETTINGS_FILE = "gban.json"
+
+#: The refresh token, alone in its own file so that copying settings never carries it.
+SESSION_FILE = "session.json"
+
+#: `graphban`'s file. Named here only so the test that asserts `gban` never opens it has
+#: something to name, and so a reader knows the omission is deliberate.
+NOT_OURS = "config.json"
+
+URL_ENV = "GRAPHBAN_URL"
+PROJECT_ENV = "GRAPHBAN_PROJECT"
+API_KEY_ENV = "GRAPHBAN_API_KEY"
+
+#: Owner read/write and nothing else. A credential at rest gets the same mode the seat files
+#: in `gbfleet` get, for the same reason.
+PRIVATE = stat.S_IRUSR | stat.S_IWUSR
+
+
+def home() -> Path:
+    return Path(os.environ.get(HOME_ENV) or (Path.home() / ".graphban"))
+
+
+def _read(path: Path) -> dict:
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        # A missing file and an unreadable one are the same to a caller that has a default,
+        # and neither is worth a traceback in front of somebody trying to log in.
+        return {}
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def _write(path: Path, payload: dict) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Created private BEFORE anything is written to it. Writing first and chmod-ing after
+    # leaves a window where the token is world-readable, which is the whole failure.
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, PRIVATE)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        json.dump(payload, fh, indent=1, sort_keys=True)
+        fh.write("\n")
+    os.chmod(path, PRIVATE)
+    return path
+
+
+def settings() -> dict:
+    return _read(home() / SETTINGS_FILE)
+
+
+def save_settings(**values: str) -> Path:
+    merged = {k: v for k, v in {**settings(), **values}.items() if v}
+    return _write(home() / SETTINGS_FILE, merged)
+
+
+def session() -> dict:
+    return _read(home() / SESSION_FILE)
+
+
+def save_session(refresh_token: str, *, user: str = "") -> Path:
+    return _write(home() / SESSION_FILE,
+                  {"refresh_token": refresh_token, "user": user})
+
+
+def clear_session() -> bool:
+    path = home() / SESSION_FILE
+    try:
+        path.unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def resolve(flag: str | None, env: str, key: str) -> str:
+    """D10's precedence, in one place: flag, then environment, then the settings file.
+
+    One function rather than three lookups at each call site, because a precedence that is
+    re-implemented per option is one that will eventually differ per option.
+    """
+    return (flag or os.environ.get(env) or settings().get(key) or "").strip()

gban/doctor.py

@@ -0,0 +1,196 @@
+"""`gban doctor` — one answer to "is this set up correctly", across both halves (PRD-40 D7).
+
+Two halves fail in each other's terms. `gbfleet doctor` already checks the local one — repo,
+workspace, adapter binary, seats file — and nothing checked the other: whether the credential
+is valid, whether the project exists, whether an agent is quarantined or being refused every
+call it makes. Diagnosing a stuck worker on the deployed instance needed a database query.
+
+**Neither half may silence the other.** A half that could not be checked prints UNKNOWN with
+its reason, never a pass and never a fail — the same three states `gbfleet doctor` uses, for
+the same reason: "we could not tell" must never render as "nothing is wrong".
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from gban import config
+from gban.client import Client, NoSession, Refused, Unreachable, authenticated
+
+PASS, FAIL, UNKNOWN = "PASS", "FAIL", "UNKNOWN"
+
+#: Worst first. The exit code is the worst finding across BOTH halves, never whichever ran
+#: last — a local pass after a ledger failure must not report success.
+SEVERITY = {PASS: 0, UNKNOWN: 1, FAIL: 2}
+
+
+def _line(side: str, status: str, name: str, detail: str = "", report: str = "") -> dict:
+    """One finding. `detail` is this line's own reason; `report` is another tool's output,
+    kept in its own field so it can never be mistaken for one."""
+    return {"side": side, "status": status, "name": name, "detail": detail, "report": report}
+
+
+def ledger(url: str, project: str) -> list[dict]:
+    """The half nothing checked. Every line says `ledger`, because a line that does not say
+    where it came from sends a reader to the wrong machine."""
+    if not url:
+        return [_line("ledger", UNKNOWN, "server",
+                      f"no server configured; pass --server or run `gban login`")]
+    try:
+        client = authenticated(url)
+    except NoSession as exc:
+        return [_line("ledger", FAIL, "session", f"{exc} — run `gban login`")]
+    except Unreachable as exc:
+        # Three distinct lines for three distinct failures, because they send a reader to
+        # three different places: the network, the credential, or the project.
+        return [_line("ledger", UNKNOWN, "server", str(exc))]
+
+    out = [_line("ledger", PASS, "server", url)]
+    try:
+        me = client.call("GET", "/api/auth/me")
+        out.append(_line("ledger", PASS, "session", me.get("email") or me.get("id", "")))
+    except Refused as exc:
+        return out + [_line("ledger", FAIL, "session", exc.detail)]
+    except Unreachable as exc:
+        return out + [_line("ledger", UNKNOWN, "session", str(exc))]
+
+    if not project:
+        out.append(_line("ledger", UNKNOWN, "project",
+                         "no project configured; pass --project or set one with `gban login`"))
+        return out
+    try:
+        fleet = client.call("GET", f"/api/fleet?project_id={project}")
+    except Refused as exc:
+        out.append(_line("ledger", FAIL, "project",
+                         f"{project}: {exc.detail}" + (f" — {exc.hint}" if exc.hint else "")))
+        return out
+    except Unreachable as exc:
+        out.append(_line("ledger", UNKNOWN, "project", str(exc)))
+        return out
+
+    agents = fleet.get("agents") or []
+    live = [a for a in agents if a.get("state") != "offline"]
+    out.append(_line("ledger", PASS, "project",
+                     f"{project}: {len(live)} agent(s) online of {len(agents)}"))
+
+    # The two states that are the whole reason a person runs this. Reported per agent, because
+    # "one agent is quarantined" and "which one" are different amounts of help.
+    for agent in agents:
+        if agent.get("state") == "quarantined":
+            out.append(_line("ledger", FAIL, f"agent {agent.get('id')}",
+                             "quarantined — it kept calling tools it is not permitted"))
+        refusal = agent.get("last_refusal") or {}
+        if refusal.get("tool"):
+            times = f" x{refusal['count']}" if refusal.get("count", 1) > 1 else ""
+            out.append(_line("ledger", FAIL, f"agent {agent.get('id')}",
+                             f"refused {refusal['tool']}{times} — {refusal.get('reason', '')}"))
+    return out
+
+
+def local(url: str, project: str, api_key: str) -> list[dict]:
+    """`gbfleet doctor`, run as a subprocess (D5). Its output is passed through, not parsed:
+    the supervisor's own report is the one under test."""
+    binary = find_supervisor()
+    if not binary:
+        return [_line("local", UNKNOWN, "gbfleet",
+                      f"not installed here — {INSTALL_SUPERVISOR} to check the local half")]
+    argv = [binary, "doctor"]
+    if url:
+        argv += ["--server", url]
+    if project:
+        argv += ["--project", project]
+    try:
+        done = subprocess.run(argv, capture_output=True, text=True, timeout=120,
+                              env=child_environment(api_key))
+    except (OSError, subprocess.SubprocessError) as exc:
+        return [_line("local", UNKNOWN, "gbfleet", f"could not run: {exc}")]
+    status = PASS if done.returncode == 0 else FAIL
+    body = (done.stdout or done.stderr or "").strip()
+    # The summary line says what HAPPENED; the child's report goes underneath, verbatim, in
+    # its own field. Putting the body in `detail` put the child's banner where the reason
+    # belongs — the walk read `FAIL local gbfleet  gbfleet 0.1.0 doctor`, which names a
+    # version and explains nothing. Choosing some line of the body to promote instead would
+    # be parsing the supervisor's output, which is the thing D5 is careful not to do.
+    verdict = "every check passed" if status is PASS else f"exited {done.returncode}"
+    return [_line("local", status, "gbfleet",
+                  f"`gbfleet doctor` {verdict}; its own report follows", report=body)]
+
+
+#: The command that actually installs the supervisor. NOT `uv pip install graphban-fleet`,
+#: which is what this said until somebody ran it: neither package is on PyPI, so that line
+#: 404s. A tool whose remedy does not work is worse than one that offers none — it spends the
+#: reader's trust before spending their time.
+INSTALL_SUPERVISOR = (
+    'uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=fleet"')
+
+
+def find_supervisor() -> str:
+    """`gbfleet`, from beside this interpreter first and only then from PATH.
+
+    **A sibling install is invisible to `PATH` alone**, and that is not a corner case: a
+    `graphban-cli[fleet]` extra, or a plain `pip install` of both into one virtualenv, puts
+    `gbfleet` in the same `bin/` as `gban` — and `uv tool install` deliberately exposes only
+    the requested package's executables, so the supervisor lands there and on no path at all.
+    Measured: with the extra installed, `gban fleet` said "gbfleet is not installed here"
+    while `gbfleet` sat in the very environment it was running from.
+
+    PATH still wins for a supervisor the operator installed separately and put there on
+    purpose — a sibling is a fallback for the case PATH cannot see, not an override of it.
+    """
+    import sys
+
+    found = shutil.which("gbfleet")
+    if found:
+        return found
+    beside = Path(sys.executable).parent / "gbfleet"
+    return str(beside) if beside.exists() and os.access(beside, os.X_OK) else ""
+
+
+#: What `gbfleet` reads. `gban` names it once, here, and both paths that launch a supervisor
+#: go through this function (GRPH-782).
+SUPERVISOR_KEY_ENV = "GBFLEET_API_KEY"
+
+
+def child_environment(api_key: str) -> dict:
+    """The environment a `gbfleet` child is launched with, for `doctor` AND for `fleet`.
+
+    **The two used to disagree, and that made the doctor a liar.** `doctor` translated
+    `$GRAPHBAN_API_KEY` into `$GBFLEET_API_KEY` for the child; `gban fleet` was a bare
+    `subprocess.run` and did not. So on a machine set up the way this tool's own premise
+    assumes — one key exported, under `gban`'s name — `gban doctor` reported the local half
+    green using a credential it manufactured, and `gban fleet up`, which `gban seats issue`
+    sends people to by name, started the supervisor with nothing. D7's promise is
+    "everything that can be checked before anything is spawned"; a local verdict that does
+    not predict what the next command does is the failure that promise exists to prevent.
+
+    In the ENVIRONMENT, never argv: `ps` shows argv to every process on the machine. And
+    never over a value the caller set themselves — somebody who exported `$GBFLEET_API_KEY`
+    deliberately, to run the supervisor on a different credential, means it.
+    """
+    import os
+
+    env = dict(os.environ)
+    if api_key and not env.get(SUPERVISOR_KEY_ENV):
+        env[SUPERVISOR_KEY_ENV] = api_key
+    return env
+
+
+def run(url: str, project: str, api_key: str = "") -> tuple[list[dict], int]:
+    lines = ledger(url, project) + local(url, project, api_key)
+    worst = max((SEVERITY[l["status"]] for l in lines), default=0)
+    # FAIL exits 1, UNKNOWN exits 0: "could not check" is not "broken", and a doctor that
+    # failed a script because a laptop lacked `gbfleet` would stop being run.
+    return lines, (1 if worst == SEVERITY[FAIL] else 0)
+
+
+def render(lines: list[dict]) -> str:
+    width = max((len(l["name"]) for l in lines), default=0)
+    out = []
+    for l in lines:
+        out.append(f"{l['status']:<7} {l['side']:<6} {l['name']:<{width}}  {l['detail']}".rstrip())
+        # Indented, so a reader scanning the summary column can skip a page of somebody
+        # else's report without losing the two lines they came for.
+        out += [f"    {row}".rstrip() for row in (l.get("report") or "").splitlines()]
+    return "\n".join(out)

graphban_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: graphban-cli
+Version: 0.1.0
+Summary: gban — a Graphban client for the human at a terminal
+Project-URL: Homepage, https://github.com/asc-me/graphban
+Project-URL: Repository, https://github.com/asc-me/graphban
+Project-URL: Documentation, https://github.com/asc-me/graphban/blob/main/cli/README.md
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# graphban-cli
+
+**`gban`** — the client for a human at a terminal.
+
+Five surfaces existed before this and none of them was for a person at a shell prompt:
+`graphban` talks to the database from inside the container, `gbfleet` supervises processes,
+`gbagent` is a spawned child, the web app is a browser, and `/api/mcp` is for agents. Issuing
+a seat, seeing why an agent is stuck, or re-tasking one meant opening a browser.
+
+Specified by [PRD-40](https://github.com/asc-me/graphban/blob/main/docs/prd-40-gb-cli.md).
+
+## Install
+
+Not on PyPI yet, so it installs from the repository. `uv tool install` puts it on your PATH
+in its own environment, which is what you want for a CLI:
+
+```bash
+uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+```
+
+Add `gbfleet` too if you run waves — it is a separate package, and `gban fleet` hands off to it:
+
+```bash
+uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=fleet"
+```
+
+`uv tool update-shell` once, if uv says the bin directory is not on your PATH. Upgrade either
+with `uv tool upgrade graphban-cli` (or `--all`); reinstalling from the same URL also works,
+since the spec is a branch rather than a pin.
+
+With pip instead, into an environment you already have:
+
+```bash
+pip install "graphban-cli @ git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+```
+
+`gban` pulls **nothing**: `client.py` is `urllib.request` throughout, and the install lands
+exactly one distribution. `gbfleet` brings httpx and its four transitive dependencies, which
+is why they are separate packages and not one.
+
+```bash
+gban login --server https://cloud.agentldgr.dev
+gban doctor                       # both halves: the ledger, and the local fleet
+gban agents                       # the roster, and why an agent is stuck
+gban agents role SA-A4 planner    # what used to need a browser
+gban seats issue worker worker planner                  # one entry per agent
+gban keys                                               # which key is that agent on
+gban fleet up --seats-file seats.txt --adapter claude   # hands off to gbfleet
+```
+
+`seats issue` takes **one role per agent, repeats included**, because that is the server's
+own shape: two agents on one seat share a session and cannot review each other. Each code is
+printed once and written nowhere — a CLI that helpfully saved them would invent a second
+credential at rest that no route and no test knows about.
+
+`agents` prints what an agent was **last refused, and why**. That line is the reason the verb
+exists: a roster saying "idle worker" for an agent being told no on every call it makes is
+what made the Super-Arc diagnosis take a database query.
+
+`agents role` re-tasks a live agent **within its credential's ceiling** and never past it. A
+role the key does not permit is the server's refusal, printed in the server's own words;
+widening a ceiling means minting a different credential, and keeping those two acts apart is
+the point of having a ceiling. It lands on the agent's next poll.
+
+## `gban login` wants a real terminal
+
+It refuses without one, rather than prompting. `getpass` falls back to a plain **echoing**
+read when it cannot turn echo off — it warns, but the warning arrives after the person has
+decided to type — so a login through a pipe, a heredoc or an editor's command runner would
+put the password in the scrollback. There is no non-interactive login yet (PRD-40 open
+question 2: an API key cannot reach the JWT routes, so CI would need a service session).
+
+## Why not `gb`
+
+Because `gb` is already `git branch` on a large share of developer machines, and **an alias
+beats a binary on `PATH`**. The deployed walk hit it on the very first command and got git's
+usage text; nothing inside the process can detect that, because by the time `gb` would have
+run, the alias did not.
+
+It is not one alias but a whole namespace. oh-my-zsh's git plugin — which is where most of
+these come from — defines sixteen `gb*` aliases and ten `grb*`, so `gb`, `gba`, `grb` and
+`gbl` are all spoken for. `gban` is outside it, still short, and still says which product it
+belongs to.
+
+## Licence — Apache-2.0, deliberately not the repository's FSL-1.1
+
+The repository is [FSL-1.1-Apache-2.0](https://github.com/asc-me/graphban/blob/main/LICENSE.md). This directory is
+[Apache-2.0](https://github.com/asc-me/graphban/blob/main/cli/LICENSE), for the reasons PRD-22 §8 gives for `fleet/` — every one of which
+applies here identically. `gban` is inert without a Graphban server and holds no authority of
+its own, so FSL's Competing Use clause protects the server and protects nothing here. It is a
+laptop-installed developer CLI, which is exactly the kind of dependency that has to clear a
+corporate licence policy scanner.
+
+## Why it is in this repository
+
+**Not a second repository**, for the reason [`fleet/README.md`](https://github.com/asc-me/graphban/blob/main/fleet/README.md) gives for
+the supervisor, with more force: the client↔server contract has no schema anywhere, and a
+cross-repo break would present as absence reading clean — `gban` still runs, nothing errors, the
+verb quietly stops meaning what it said. The evidence is recent and specific: `ROLES` lost
+`reviewer` in one PR while another added a test naming it, and CI caught the pair inside
+seventeen minutes because both lived in one repository. Split across two, that lands as a bug
+report from somebody whose `gban agents role ... reviewer` started refusing.
+
+**Not inside `backend/`**, because `graphban-api` pulls fastapi, sqlalchemy, pgvector, psycopg,
+alembic, redis and cryptography, and this installs on a laptop. `tests/test_packaging.py`
+derives its forbidden set from the backend's own dependency list rather than a denylist
+somebody maintains.
+
+## What it is not
+
+It is **not a second web app**: no board, no PRD editor, no search. Every verb is either
+something a human currently opens a browser for, or a diagnosis nothing else gives.
+
+It is **not `graphban`**, which talks to the local database from inside the container and
+stays exactly as it is. Mixing "against the DB in the container" and "over HTTP from a laptop"
+into one command is an ambiguity that ends with somebody purging the wrong instance.
+
+It **holds no state the server does not** and computes nothing the server computes. Every verb
+is one endpoint, called once (PRD-40 D11); an ordering between two calls would be a rule, and
+a rule in the client is a second definition of something the server already enforces.

graphban_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+gban/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gban/cli.py,sha256=MNzyjywOXNSdzixpio0tp_M_J6Z-gKlXSJGVxuMtQEI,19163
+gban/client.py,sha256=IZc7C7V9EYY0Iq51X6j9acZa7f_nUKpChgHZLTiR_Sc,7026
+gban/config.py,sha256=-BI1KUeSvU11aJ79faOMoTuuv2YHc0ShQ-J6zjxzjRE,3816
+gban/doctor.py,sha256=7xiCAWlGpi3aCeHN2d_G8WDqKZsNpKytjQia6U_jMn4,9766
+graphban_cli-0.1.0.dist-info/METADATA,sha256=bsMjyMZdpzdih6OpbAPo1O8WVwcy4oL9BJtYPJwRrto,7074
+graphban_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+graphban_cli-0.1.0.dist-info/entry_points.txt,sha256=nc7a--ylRW5tl7Y3zGYYj8iCfvEU4bHFXuLC5XrzR2Y,39
+graphban_cli-0.1.0.dist-info/licenses/LICENSE,sha256=bTJXVKNN5dcSiUDYFuITA3s6oqa7HFoEOyxmodoZ8Ak,10833
+graphban_cli-0.1.0.dist-info/RECORD,,

graphban_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

graphban_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gban = gban.cli:main

graphban_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright 2026 Ascme Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.