graphban-cli 0.1.1__tar.gz → 0.3.0__tar.gz

{graphban_cli-0.1.1 → graphban_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.1.1
+Version: 0.3.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
@@ -108,6 +108,64 @@ role the key does not permit is the server's refusal, printed in the server's ow
 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.
 
+## Enabling delegation on a project
+
+```bash
+gban login          # once, at a terminal
+gban setup          # everything mechanical between that and a delegating agent
+gban setup --auto   # …or every project whose repository sits here or beside here
+```
+
+An agent with the delegation skill runs all of this for you except `gban login`, which it
+hands back as a `! gban login` line to type — it needs a terminal, and no agent has one — and
+then carries on from where you left it.
+
+**The directory names the project.** Run `setup` from inside the repository the work belongs
+to and it matches that directory against the projects you can read. An explicit `--project`
+wins; nothing else does. In particular the default `gban login` stores is *not* used here and
+is named in the refusal when it exists — logging in once inside one project must not quietly
+mint a credential for it while you are standing in another repository, and a key in the wrong
+project is not a mistake anybody notices quickly.
+
+`setup` mints a project-scoped credential, writes the `graphban` and `gbfleet` MCP entries,
+installs the supervisor if it is missing, drops the delegation skill into `.claude/skills/`,
+and then **verifies** rather than asserting: it asks the new credential what it can actually
+see. Restart the harness afterwards — MCP servers are read at startup.
+
+Three properties worth knowing, each of which is a bug this command exists to not have:
+
+- **The credential does not expire.** `gban keys mint` produces a *wave* key, which lasts a
+  day (`FLEET_KEY_DAYS`); that is right for a wave and wrong for a project. Only seats expire.
+- **It writes where the harness will actually read.** `~/.claude.json`'s per-project
+  `mcpServers` outranks a repository `.mcp.json`, so writing the repository file under a
+  stale entry leaves the agent on the old key — which surfaces as a JSON parse error, because
+  the harness is parsing a 401 body. `--scope user` is the default for that reason, and
+  because a credential outside the repository cannot be committed.
+- **`--auto` matches, and says so.** A project carries no repository link — no remote, no
+  path — so `--auto` compares your project ids and names against this directory, what is in
+  it, and its siblings. One level, never a recursive walk. Two directories answering to one
+  project, or one directory answering to two, are **refused rather than guessed**: a
+  credential minted into the wrong repository is not a mistake anybody notices quickly.
+- **It refuses to write a key into a file git tracks.** `--scope project` on a tracked
+  `.mcp.json` is refused rather than warned about, because a warning attached to committing a
+  credential still commits it.
+
+## Wiring a checkout to Swamp
+
+```bash
+gban swamp setup
+```
+
+Steps 3 and 5 of [the Swamp runbook](https://github.com/asc-me/graphban/blob/main/docs/swamp.md):
+`repo init`, `extension source add`, `vault create`, and the **gate** credential — minted,
+piped to `swamp vault put` on stdin, then checked for the scopes it actually came back with.
+Every step is skipped when already done.
+
+Two things it will not do. It does not install Swamp, because that install pipes a remote
+script into a shell. And it never writes the gate key into an MCP config: `gban setup`'s agent
+key must not carry `gate`, or the agent doing the work attests its own completion — which
+fails silently, since a gate that always says yes looks exactly like a gate that held.
+
 ## `gban login` wants a real terminal
 
 It refuses without one, rather than prompting. `getpass` falls back to a plain **echoing**

{graphban_cli-0.1.1 → graphban_cli-0.3.0}/README.md

@@ -93,6 +93,64 @@ role the key does not permit is the server's refusal, printed in the server's ow
 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.
 
+## Enabling delegation on a project
+
+```bash
+gban login          # once, at a terminal
+gban setup          # everything mechanical between that and a delegating agent
+gban setup --auto   # …or every project whose repository sits here or beside here
+```
+
+An agent with the delegation skill runs all of this for you except `gban login`, which it
+hands back as a `! gban login` line to type — it needs a terminal, and no agent has one — and
+then carries on from where you left it.
+
+**The directory names the project.** Run `setup` from inside the repository the work belongs
+to and it matches that directory against the projects you can read. An explicit `--project`
+wins; nothing else does. In particular the default `gban login` stores is *not* used here and
+is named in the refusal when it exists — logging in once inside one project must not quietly
+mint a credential for it while you are standing in another repository, and a key in the wrong
+project is not a mistake anybody notices quickly.
+
+`setup` mints a project-scoped credential, writes the `graphban` and `gbfleet` MCP entries,
+installs the supervisor if it is missing, drops the delegation skill into `.claude/skills/`,
+and then **verifies** rather than asserting: it asks the new credential what it can actually
+see. Restart the harness afterwards — MCP servers are read at startup.
+
+Three properties worth knowing, each of which is a bug this command exists to not have:
+
+- **The credential does not expire.** `gban keys mint` produces a *wave* key, which lasts a
+  day (`FLEET_KEY_DAYS`); that is right for a wave and wrong for a project. Only seats expire.
+- **It writes where the harness will actually read.** `~/.claude.json`'s per-project
+  `mcpServers` outranks a repository `.mcp.json`, so writing the repository file under a
+  stale entry leaves the agent on the old key — which surfaces as a JSON parse error, because
+  the harness is parsing a 401 body. `--scope user` is the default for that reason, and
+  because a credential outside the repository cannot be committed.
+- **`--auto` matches, and says so.** A project carries no repository link — no remote, no
+  path — so `--auto` compares your project ids and names against this directory, what is in
+  it, and its siblings. One level, never a recursive walk. Two directories answering to one
+  project, or one directory answering to two, are **refused rather than guessed**: a
+  credential minted into the wrong repository is not a mistake anybody notices quickly.
+- **It refuses to write a key into a file git tracks.** `--scope project` on a tracked
+  `.mcp.json` is refused rather than warned about, because a warning attached to committing a
+  credential still commits it.
+
+## Wiring a checkout to Swamp
+
+```bash
+gban swamp setup
+```
+
+Steps 3 and 5 of [the Swamp runbook](https://github.com/asc-me/graphban/blob/main/docs/swamp.md):
+`repo init`, `extension source add`, `vault create`, and the **gate** credential — minted,
+piped to `swamp vault put` on stdin, then checked for the scopes it actually came back with.
+Every step is skipped when already done.
+
+Two things it will not do. It does not install Swamp, because that install pipes a remote
+script into a shell. And it never writes the gate key into an MCP config: `gban setup`'s agent
+key must not carry `gate`, or the agent doing the work attests its own completion — which
+fails silently, since a gate that always says yes looks exactly like a gate that held.
+
 ## `gban login` wants a real terminal
 
 It refuses without one, rather than prompting. `getpass` falls back to a plain **echoing**

{graphban_cli-0.1.1 → graphban_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphban-cli"
-version = "0.1.1"
+version = "0.3.0"
 description = "gban — a Graphban client for the human at a terminal"
 readme = "README.md"
 requires-python = ">=3.12"

{graphban_cli-0.1.1 → graphban_cli-0.3.0}/src/gban/cli.py

@@ -13,8 +13,9 @@ import os
 import shutil
 import subprocess
 import sys
+from pathlib import Path
 
-from gban import config, doctor as doctor_mod
+from gban import config, doctor as doctor_mod, setup as setup_mod, swamp as swamp_mod
 from gban.client import (EXIT_NO_SESSION, EXIT_NO_SUPERVISOR, EXIT_REFUSED, EXIT_UNREACHABLE,
                        Client, NoSession,
                        Refused, Unreachable, authenticated, login)
@@ -52,6 +53,41 @@ def _parser() -> argparse.ArgumentParser:
                      "Neither half silences the other: what could not be checked prints "
                      "UNKNOWN with its reason, never a pass."))
 
+    setup_cmd = sub.add_parser(
+        "setup", help="enable delegation on a project",
+        description=("Mints a project-scoped credential that does NOT expire, writes the "
+                     "graphban and gbfleet MCP entries where the harness will actually read "
+                     "them, and installs the supervisor. Only seats expire; a credential that "
+                     "died overnight would make 'delegation is set up' quietly stop being "
+                     "true. Re-running is safe: a working configuration is left alone."))
+    setup_cmd.add_argument(
+        "--scope", choices=["user", "project"], default="user",
+        help="user (default) writes ~/.claude.json, which OUTRANKS a repo .mcp.json and "
+             "cannot be committed; project writes .mcp.json beside the repo")
+    setup_cmd.add_argument(
+        "--auto", action="store_true",
+        help="every project with a repository here: matches this directory, what is in it and "
+             "its siblings against your projects BY NAME, and refuses any ambiguity rather "
+             "than guessing. A project carries no repository link, so this is a match, not a "
+             "lookup")
+    setup_cmd.add_argument("--no-install", action="store_true",
+                           help="do not install the supervisor")
+
+    swamp_cmd = sub.add_parser(
+        "swamp", help="wire this checkout to Swamp's Graphban adapter",
+        description=("Mints the GATE credential — the one that attests completion — and puts "
+                     "it in the Swamp vault and nowhere else. It is deliberately not the "
+                     "agent key `gban setup` writes into your MCP config: an agent that can "
+                     "attest its own work turns the completion gate into theatre, and nothing "
+                     "errors when it does. Does not install Swamp; a remote install script is "
+                     "for a person to read and run."))
+    swamp_do = swamp_cmd.add_subparsers(dest="act")
+    swamp_setup = swamp_do.add_parser("setup", help="init, source, vault, and the gate key")
+    swamp_setup.add_argument("--adapter", default=swamp_mod.DEFAULT_ADAPTER,
+                             help=f"the graphban-swamp checkout (default: {swamp_mod.DEFAULT_ADAPTER})")
+    swamp_setup.add_argument("--no-init", action="store_true",
+                             help="refuse rather than run `swamp repo init` here")
+
     fleet = sub.add_parser(
         "fleet", help="hand off to gbfleet (the supervisor)",
         description=("Passes everything through to `gbfleet` and returns its exit code "
@@ -150,15 +186,52 @@ def cmd_login(args) -> int:
     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)
+    asked = config.resolve(args.project, config.PROJECT_ENV, "project")
+    chosen, projects, why = _default_project(url, asked)
+    config.save_settings(url=url, project=chosen)
+    human = [f"{PROG}: signed in to {url} as {email}",
+             f"     session stored at {path} (mode 600)"]
+    if chosen:
+        human.append(f"     project {chosen}" + (" (the only one you can read)"
+                                                 if not asked and len(projects) == 1 else ""))
+        human.append(f"     next: `{PROG} setup` enables delegation on it")
+    elif len(projects) > 1:
+        human.append(f"     {len(projects)} projects — none set as default:")
+        human += [f"       {p.get('id', ''):<20} {p.get('name', '')}" for p in projects]
+        human.append(f"     pick one: `{PROG} setup --project <id>`")
+    elif why:
+        # Discovery failed, the login did not. Reporting this as a failed login would send
+        # somebody to re-enter a password that was already accepted.
+        human.append(f"     WARNING: could not list your projects ({why}).")
+        human.append(f"     Name one when you need it: `{PROG} setup --project <id>`")
+    else:
+        human.append("     you can read no projects yet — create one in the web app first")
+    _out({"server": url, "session": str(path), "user": email, "project": chosen,
+          "projects": [p.get("id") for p in projects]}, "\n".join(human), args.as_json)
     return 0
 
 
+def _default_project(url: str, asked: str) -> tuple[str, list[dict], str]:
+    """What `login` should store as the default, the projects it saw, and why it saw none.
+
+    ONE project is chosen for you; several are listed and none is chosen. Picking the first of
+    several would be a coin toss whose result is invisible until a key lands in the wrong
+    project, and the list is short enough to read.
+
+    An explicit `--project` is never overridden — the person naming one has said the thing
+    this function exists to guess.
+    """
+    if asked:
+        return asked, [], ""
+    try:
+        rows = authenticated(url, act="login").call("GET", "/api/projects")
+    except (Unreachable, Refused, NoSession) as exc:
+        return "", [], str(exc)
+    projects = [p for p in (rows if isinstance(rows, list) else []) if isinstance(p, dict)]
+    return (projects[0].get("id", "") if len(projects) == 1 else ""), projects, ""
+
+
 def cmd_logout(args) -> int:
     url = _server(args)
     told_server, why = False, ""
@@ -208,6 +281,101 @@ def cmd_doctor(args) -> int:
     return code
 
 
+def cmd_setup(args) -> int:
+    """Everything between a session and a delegating agent, in one act (GRPH-792)."""
+    url = _server(args)
+    # THE SESSION FIRST, and the order is the point. Resolving the project first told somebody
+    # who had never logged in that they had "no project" — true about the wrong thing, with
+    # the wrong exit code (1 rather than 3), and it sends a reader hunting for a project id
+    # when the remedy is a person at a terminal. Found by running the built wheel rather than
+    # by a test, because every test here starts from a stored session.
+    client = authenticated(url, act="setup")
+    if args.auto:
+        return _setup_auto(args, url, client)
+    # EXPLICIT ONLY. `config.resolve` would fold in the default `gban login` stored, and this
+    # is the one verb where that default is dangerous rather than convenient — see
+    # `setup.resolve_project`.
+    asked = (args.project or os.environ.get(config.PROJECT_ENV) or "").strip()
+    try:
+        project, how = setup_mod.resolve_project(
+            client, Path.cwd(), asked, config.settings().get("project", ""))
+    except setup_mod.Unresolved as exc:
+        print(f"{PROG}: {exc}", file=sys.stderr)
+        return EXIT_REFUSED
+    lines, code, made = setup_mod.run(client, url, project, Path.cwd(), scope=args.scope,
+                                      install=not args.no_install)
+    human = [doctor_mod.render(lines)]
+    if how != "named":
+        human.insert(0, f"{PROG}: {project} — {how}")
+    if code == 0:
+        human.append(f"\n     delegation is enabled on {project}. An agent can now "
+                     f"`delegate(id=…, lane=…, tier=…, seat=true)` then `spawn`.")
+        human.append(f"     restart the harness so it reads the new config.")
+    _out({"lines": lines, "ok": code == 0, "project": project, **made},
+         "\n".join(human), args.as_json)
+    return code
+
+
+def _setup_auto(args, url: str, client) -> int:
+    """Every project that has a repository here, each in its own.
+
+    Reports what it did NOT match as loudly as what it did. A sweep that silently skipped a
+    project would leave somebody believing delegation is enabled everywhere.
+    """
+    projects = client.call("GET", "/api/projects")
+    projects = [p for p in (projects if isinstance(projects, list) else []) if isinstance(p, dict)]
+    found, notes = setup_mod.match(projects, Path.cwd())
+    if not found:
+        print(doctor_mod.render(notes) if notes else
+              f"{PROG}: no projects to match", file=sys.stderr)
+        print(f"{PROG}: matched no repository here. `{PROG} setup --project <id>` from inside "
+              f"one names it directly.", file=sys.stderr)
+        return EXIT_REFUSED
+    lines, worst, done = list(notes), 0, {}
+    for pid, repo in sorted(found.items()):
+        lines.append(doctor_mod._line("match", doctor_mod.PASS, pid, str(repo)))
+        got, code, made = setup_mod.run(client, url, pid, repo, scope=args.scope,
+                                        install=not args.no_install)
+        lines += [{**l, "name": f"{pid}: {l['name']}"} for l in got]
+        done[pid], worst = {"repo": str(repo), "ok": code == 0, **made}, max(worst, code)
+    human = [doctor_mod.render(lines),
+             f"\n     {sum(1 for d in done.values() if d['ok'])} of {len(done)} enabled. "
+             f"Restart the harness so it reads the new config."]
+    _out({"lines": lines, "ok": worst == 0, "projects": done}, "\n".join(human), args.as_json)
+    return worst
+
+
+def cmd_swamp(args) -> int:
+    """Wire this checkout to Swamp's Graphban adapter (GRPH-796).
+
+    Mints a SECOND credential — the gate key — and puts it in the vault and nowhere else. The
+    agent key `gban setup` writes into the MCP config must never carry `gate`: an agent that
+    can attest its own completion turns the gate into theatre, and nothing errors when it does.
+    """
+    if args.act != "setup":
+        print(f"{PROG}: usage: {PROG} swamp setup", file=sys.stderr)
+        return EXIT_REFUSED
+    url = _server(args)
+    client = authenticated(url, act="swamp setup")
+    repo = Path.cwd()
+    asked = (args.project or os.environ.get(config.PROJECT_ENV) or "").strip()
+    try:
+        project, how = setup_mod.resolve_project(
+            client, repo, asked, config.settings().get("project", ""))
+    except setup_mod.Unresolved as exc:
+        print(f"{PROG}: {exc}", file=sys.stderr)
+        return EXIT_REFUSED
+    lines, code = swamp_mod.setup(client, url, project, repo,
+                                  Path(args.adapter).expanduser(), init=not args.no_init)
+    human = [f"{PROG}: {project} — {how}" if how != "named" else f"{PROG}: {project}",
+             doctor_mod.render(lines)]
+    if code == 0:
+        human.append(f"\n     The gate key is in the vault and in no MCP config. Keep it that "
+                     f"way: an agent that can attest its own work is not gated.")
+    _out({"lines": lines, "ok": code == 0, "project": project}, "\n".join(human), args.as_json)
+    return code
+
+
 def cmd_fleet(args) -> int:
     """A subprocess, never an import (D5).
 
@@ -358,8 +526,8 @@ def cmd_keys(args) -> int:
 
 
 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}
+            "doctor": cmd_doctor, "setup": cmd_setup, "fleet": cmd_fleet, "seats": cmd_seats,
+            "agents": cmd_agents, "keys": cmd_keys, "swamp": cmd_swamp}
 
 
 def main(argv: list[str] | None = None) -> int:

{graphban_cli-0.1.1 → graphban_cli-0.3.0}/src/gban/doctor.py

@@ -166,6 +166,40 @@ def offer_to_install(stream=None) -> bool:
     return bool(find_supervisor())
 
 
+def install_supervisor(timeout: float = 600.0) -> tuple[bool, str]:
+    """Install it, without asking. `(installed, why_not)`.
+
+    `offer_to_install` prompts because it is reached from `gban fleet`, where a person typed a
+    read-only command and did not consent to software being installed. `gban setup` is the
+    other case entirely: it mints a credential and rewrites the harness config, and installing
+    the supervisor is squarely inside what "enable delegation on this project" asks for. So
+    the consent argument is satisfied by the verb rather than by a second prompt — which an
+    agent driving this could not answer anyway.
+
+    Still nothing into `gban`'s own environment: `uv tool install` gives the supervisor its
+    own, which is the only correct answer when `gban` may live in a Homebrew Cellar that brew
+    will replace.
+    """
+    if not shutil.which("uv"):
+        return False, ("uv is not on PATH, so there is nothing to install with — "
+                       "`brew install uv`, or see https://docs.astral.sh/uv/")
+    try:
+        done = subprocess.run(INSTALL_SUPERVISOR.split(), capture_output=True, text=True,
+                              timeout=timeout)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return False, f"`{INSTALL_SUPERVISOR}` could not run: {exc}"
+    if done.returncode != 0:
+        tail = (done.stderr or done.stdout or "").strip().splitlines()
+        return False, (f"`{INSTALL_SUPERVISOR}` failed ({done.returncode})"
+                       + (f": {tail[-1][:160]}" if tail else ""))
+    if not find_supervisor():
+        # It reported success and the binary is not resolvable. Almost always uv's tool bin
+        # directory missing from PATH, which is a real state and not a failed install.
+        return False, ("installed, but `gbfleet` is not on PATH — run `uv tool update-shell` "
+                       "and open a new shell")
+    return True, ""
+
+
 def find_supervisor() -> str:
     """`gbfleet`, from beside this interpreter first and only then from PATH.