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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -26,32 +26,63 @@ Specified by [PRD-40](https://github.com/asc-me/graphban/blob/main/docs/prd-40-g
 
 ## 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 graphban-cli
+```
+
+or, on macOS:
 
 ```bash
-uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+brew install asc-me/tap/gban
 ```
 
-Add `gbfleet` too if you run waves — it is a separate package, and `gban fleet` hands off to it:
+The formula carries no `resource` stanzas — `graphban-cli` has no runtime dependencies, so
+there is nothing to vendor and nothing to regenerate when a transitive moves. The supervisor
+is deliberately not in the tap; see below.
+
+Add the supervisor too if you run waves — a separate package, and `gban fleet` hands off to
+it. At a terminal, `gban fleet` will offer to run this for you when it finds no supervisor;
+it asks first and never installs on a bare return, because a person who typed a read-only
+command did not consent to software being installed:
 
 ```bash
-uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=fleet"
+uv tool install graphban-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.
+That also gives you `gbagent`, the first-party coding agent: it is an entry point of
+`graphban-fleet`, not a package of its own, because the supervisor resolves it on PATH like
+any other vendor binary.
+
+`uv tool update-shell` once, if uv says the bin directory is not on your PATH.
+`uv tool upgrade --all` to move both forward.
+
+Two commands rather than one, and an extra (`graphban-cli[fleet]`) is deliberately not
+offered: `uv tool install` exposes only the REQUESTED package's executables, so an extra
+installs `gbfleet` into `gban`'s environment and puts it on no path at all. Measured — with
+the extra, `gban fleet` reported "gbfleet is not installed here" while `gbfleet` sat in the
+very environment it was running from.
+
+`gban` pulls **nothing**: `client.py` is `urllib.request` throughout, and the install lands
+exactly one distribution. `gbfleet` brings httpx and its transitives, which is why they are
+separate packages and not one.
 
 With pip instead, into an environment you already have:
 
 ```bash
-pip install "graphban-cli @ git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+pip install graphban-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.
+`gban` looks for `gbfleet` beside its own interpreter before falling back to PATH, so that
+shape works with neither on PATH.
+
+To run an unreleased change, install from the repository instead — the same spec the release
+builds from:
+
+```bash
+uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+```
+
+Releasing is [docs/releasing.md](https://github.com/asc-me/graphban/blob/main/docs/releasing.md).
 
 ```bash
 gban login --server https://cloud.agentldgr.dev

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

@@ -11,32 +11,63 @@ Specified by [PRD-40](https://github.com/asc-me/graphban/blob/main/docs/prd-40-g
 
 ## 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 graphban-cli
+```
+
+or, on macOS:
 
 ```bash
-uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+brew install asc-me/tap/gban
 ```
 
-Add `gbfleet` too if you run waves — it is a separate package, and `gban fleet` hands off to it:
+The formula carries no `resource` stanzas — `graphban-cli` has no runtime dependencies, so
+there is nothing to vendor and nothing to regenerate when a transitive moves. The supervisor
+is deliberately not in the tap; see below.
+
+Add the supervisor too if you run waves — a separate package, and `gban fleet` hands off to
+it. At a terminal, `gban fleet` will offer to run this for you when it finds no supervisor;
+it asks first and never installs on a bare return, because a person who typed a read-only
+command did not consent to software being installed:
 
 ```bash
-uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=fleet"
+uv tool install graphban-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.
+That also gives you `gbagent`, the first-party coding agent: it is an entry point of
+`graphban-fleet`, not a package of its own, because the supervisor resolves it on PATH like
+any other vendor binary.
+
+`uv tool update-shell` once, if uv says the bin directory is not on your PATH.
+`uv tool upgrade --all` to move both forward.
+
+Two commands rather than one, and an extra (`graphban-cli[fleet]`) is deliberately not
+offered: `uv tool install` exposes only the REQUESTED package's executables, so an extra
+installs `gbfleet` into `gban`'s environment and puts it on no path at all. Measured — with
+the extra, `gban fleet` reported "gbfleet is not installed here" while `gbfleet` sat in the
+very environment it was running from.
+
+`gban` pulls **nothing**: `client.py` is `urllib.request` throughout, and the install lands
+exactly one distribution. `gbfleet` brings httpx and its transitives, which is why they are
+separate packages and not one.
 
 With pip instead, into an environment you already have:
 
 ```bash
-pip install "graphban-cli @ git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+pip install graphban-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.
+`gban` looks for `gbfleet` beside its own interpreter before falling back to PATH, so that
+shape works with neither on PATH.
+
+To run an unreleased change, install from the repository instead — the same spec the release
+builds from:
+
+```bash
+uv tool install "git+https://github.com/asc-me/graphban.git#subdirectory=cli"
+```
+
+Releasing is [docs/releasing.md](https://github.com/asc-me/graphban/blob/main/docs/releasing.md).
 
 ```bash
 gban login --server https://cloud.agentldgr.dev

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

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

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

@@ -215,10 +215,17 @@ def cmd_fleet(args) -> int:
     and leaves `gbfleet --help` authoritative about its own commands.
     """
     binary = doctor_mod.find_supervisor()
+    if not binary:
+        # At a terminal, offer to fix it here rather than making the person read a command,
+        # copy it, run it and type this one again. Declined or unavailable, the message is
+        # what it always was.
+        if doctor_mod.offer_to_install():
+            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)
+              f"     …or `brew install asc-me/tap/gban` installs this client only — the "
+              f"supervisor is a separate package.", 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")

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

@@ -118,12 +118,52 @@ def local(url: str, project: str, api_key: str) -> list[dict]:
                   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"')
+#: The command that actually installs the supervisor. It has been wrong twice: first naming a
+#: PyPI package that did not exist, then a git spec that worked but stopped being the right
+#: advice the moment `graphban-fleet` was published. A remedy a tool prints is a promise, and
+#: `cli/tests/test_packaging.py` now checks this one against the same source the README uses.
+INSTALL_SUPERVISOR = "uv tool install graphban-fleet"
+
+
+def offer_to_install(stream=None) -> bool:
+    """Ask, then install `graphban-fleet` with uv. Returns whether it is there afterwards.
+
+    **Asked, never assumed.** Installing software is not a side effect anybody should get
+    from `gban fleet ps`: it writes outside this program, it takes a minute, and a person
+    who typed a read-only command did not consent to it. So it happens only at an
+    interactive prompt, only on an explicit `y`, and only when the wall has actually been
+    hit — a missing supervisor, on the command that needs one.
+
+    Nothing is installed into `gban`'s OWN environment. `uv tool install` gives the
+    supervisor its own, which is the only correct answer when `gban` may itself live in a
+    Homebrew Cellar that brew will replace: a `pip install` next to it would be silently
+    undone by the next upgrade.
+
+    Declines, non-interactive shells and a machine without uv all return False and leave the
+    caller to print the command — a prompt nobody can answer is a hang, and a hang in a
+    script is worse than the error it replaced.
+    """
+    import sys
+
+    out = stream or sys.stderr
+    if not sys.stdin.isatty():
+        return False
+    if not shutil.which("uv"):
+        return False
+    print(f"gban: gbfleet is not installed here.", file=out)
+    try:
+        answer = input(f"       run `{INSTALL_SUPERVISOR}` now? [y/N] ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print("", file=out)
+        return False
+    if answer not in ("y", "yes"):
+        return False
+    done = subprocess.run(INSTALL_SUPERVISOR.split())
+    if done.returncode != 0:
+        print(f"gban: that install failed ({done.returncode}); nothing changed here.",
+              file=out)
+        return False
+    return bool(find_supervisor())
 
 
 def find_supervisor() -> str:

{graphban_cli-0.1.0 → graphban_cli-0.1.1}/tests/test_doctor.py

@@ -171,7 +171,7 @@ def test_a_missing_supervisor_says_how_to_install_it(home, monkeypatch, capsys):
     a real gbfleet on the machine running it."""
     monkeypatch.setattr("gban.cli.doctor_mod.find_supervisor", lambda: "")
     assert main(["fleet", "ps"]) == EXIT_NO_SUPERVISOR
-    assert "graphban.git" in capsys.readouterr().err
+    assert doctor.INSTALL_SUPERVISOR in capsys.readouterr().err
 
 
 def test_the_credential_reaches_gbfleet_in_the_environment_never_argv(home, monkeypatch):
@@ -356,8 +356,8 @@ def test_the_install_it_names_is_one_that_exists(home, monkeypatch, capsys):
     monkeypatch.setattr("gban.cli.doctor_mod.find_supervisor", lambda: "")
     assert main(["fleet", "ps"]) == EXIT_NO_SUPERVISOR
     err = capsys.readouterr().err
-    assert "git+https://github.com/asc-me/graphban.git#subdirectory=fleet" in err
-    assert "uv pip install graphban-fleet" not in err
+    assert doctor.INSTALL_SUPERVISOR in err
+    assert "uv pip install graphban-fleet" not in err, "that package name has never existed"
 
 
 def test_the_doctor_names_the_same_install(home, monkeypatch):
@@ -365,7 +365,7 @@ def test_the_doctor_names_the_same_install(home, monkeypatch):
     monkeypatch.setattr("gban.doctor.authenticated", lambda url: _Server())
     lines, _ = doctor.run("http://gb.invalid", "core", "")
     local = [l for l in lines if l["side"] == "local"][0]
-    assert "subdirectory=fleet" in local["detail"]
+    assert doctor.INSTALL_SUPERVISOR in local["detail"]
     assert "uv pip install graphban-fleet" not in local["detail"]
 
 
@@ -404,3 +404,107 @@ def test_both_commands_find_the_supervisor_the_same_way(home):
     for fn in (cli_mod.cmd_fleet, doctor.local):
         assert "find_supervisor" in inspect.getsource(fn), (
             f"{fn.__qualname__} looks for gbfleet some other way")
+
+
+# ---- offering to install the supervisor, never doing it uninvited -----------------------------
+
+class _Tty:
+    """Stdin that claims to be a terminal, so the guard below is not what is under test."""
+
+    def isatty(self) -> bool:
+        return True
+
+
+def test_it_never_installs_without_being_asked(home, monkeypatch, capsys):
+    """THE INVARIANT. Installing software is not a side effect anybody should get from
+    `gban fleet ps` — it writes outside this program and a person who typed a read-only
+    command did not consent to it.
+
+    Sabotage: install on a bare return and this fails."""
+    ran = []
+    monkeypatch.setattr("sys.stdin", _Tty())
+    monkeypatch.setattr("gban.doctor.shutil.which", lambda name: "/usr/bin/uv")
+    monkeypatch.setattr("gban.doctor.subprocess.run", lambda *a, **kw: ran.append(a))
+    monkeypatch.setattr("builtins.input", lambda *_: "")   # a bare return is not a yes
+
+    assert doctor.offer_to_install() is False
+    assert ran == [], "it installed without an explicit yes"
+
+
+def test_a_yes_runs_the_install_and_reports_what_it_found(home, monkeypatch):
+    ran = []
+
+    class Done:
+        returncode = 0
+
+    monkeypatch.setattr("sys.stdin", _Tty())
+    monkeypatch.setattr("gban.doctor.shutil.which",
+                        lambda name: "/usr/bin/uv" if name == "uv" else None)
+    monkeypatch.setattr("gban.doctor.subprocess.run",
+                        lambda argv, **kw: (ran.append(argv), Done())[1])
+    monkeypatch.setattr("builtins.input", lambda *_: "y")
+    monkeypatch.setattr("gban.doctor.find_supervisor", lambda: "/usr/bin/gbfleet")
+
+    assert doctor.offer_to_install() is True
+    assert ran == [["uv", "tool", "install", "graphban-fleet"]]
+
+
+def test_a_failed_install_is_reported_and_not_papered_over(home, monkeypatch, capsys):
+    """Returning True after a failed install would send the caller to look for a binary that
+    is not there, and the second error would describe the wrong thing."""
+    class Died:
+        returncode = 2
+
+    monkeypatch.setattr("sys.stdin", _Tty())
+    monkeypatch.setattr("gban.doctor.shutil.which", lambda name: "/usr/bin/uv")
+    monkeypatch.setattr("gban.doctor.subprocess.run", lambda *a, **kw: Died())
+    monkeypatch.setattr("builtins.input", lambda *_: "y")
+
+    assert doctor.offer_to_install() is False
+    assert "install failed" in capsys.readouterr().err
+
+
+def test_it_does_not_prompt_where_nobody_can_answer(home, monkeypatch):
+    """A prompt in a script is a hang, and a hang is worse than the error it replaced."""
+    import io
+
+    monkeypatch.setattr("sys.stdin", io.StringIO(""))
+    monkeypatch.setattr("gban.doctor.shutil.which", lambda name: "/usr/bin/uv")
+    monkeypatch.setattr("builtins.input",
+                        lambda *_: pytest.fail("it prompted with no terminal"))
+    assert doctor.offer_to_install() is False
+
+
+def test_no_uv_means_no_offer(home, monkeypatch):
+    """The offer names one installer. Without it there is nothing to offer, and the caller's
+    message is the whole answer."""
+    monkeypatch.setattr("sys.stdin", _Tty())
+    monkeypatch.setattr("gban.doctor.shutil.which", lambda name: None)
+    monkeypatch.setattr("builtins.input",
+                        lambda *_: pytest.fail("it offered an installer it does not have"))
+    assert doctor.offer_to_install() is False
+
+
+def test_gban_fleet_runs_the_command_after_a_successful_install(home, monkeypatch):
+    """The point of asking at all: the person typed `gban fleet ps`, and after saying yes
+    they should get `ps` — not a second error telling them to type it again."""
+    seen = {}
+
+    class Done:
+        returncode = 0
+
+    calls = iter(["", "/usr/bin/gbfleet"])   # missing, then present after the install
+    monkeypatch.setattr("gban.cli.doctor_mod.find_supervisor", lambda: next(calls))
+    monkeypatch.setattr("gban.cli.doctor_mod.offer_to_install", lambda: True)
+    monkeypatch.setattr("gban.cli.subprocess.run",
+                        lambda argv, **kw: (seen.update(argv=argv), Done())[1])
+
+    assert main(["fleet", "ps"]) == 0
+    assert seen["argv"][0] == "/usr/bin/gbfleet"
+
+
+def test_a_declined_offer_still_prints_the_command(home, monkeypatch, capsys):
+    monkeypatch.setattr("gban.cli.doctor_mod.find_supervisor", lambda: "")
+    monkeypatch.setattr("gban.cli.doctor_mod.offer_to_install", lambda: False)
+    assert main(["fleet", "ps"]) == EXIT_NO_SUPERVISOR
+    assert doctor.INSTALL_SUPERVISOR in capsys.readouterr().err

{graphban_cli-0.1.0 → graphban_cli-0.1.1}/tests/test_packaging.py

@@ -183,3 +183,31 @@ def test_the_readme_ships_and_none_of_its_links_are_repo_relative():
                 if not t.startswith(("http://", "https://", "mailto:", "#"))]
     assert not relative, (
         f"cli/README.md ships to PyPI, where these resolve to nothing: {relative}")
+
+
+def test_the_install_the_tool_prints_is_the_one_the_readme_gives():
+    """It has been wrong twice: first naming a PyPI package that did not exist, then a git
+    spec that worked and stopped being the right advice the moment `graphban-fleet` was
+    published. A remedy a tool prints is a promise, and the README is where the promise is
+    maintained — so they are checked against each other rather than both against memory.
+
+    Sabotage: change either and this fails."""
+    from gban.doctor import INSTALL_SUPERVISOR
+
+    readmes = ((CLI / "README.md").read_text(encoding="utf-8")
+               + (REPO / "fleet" / "README.md").read_text(encoding="utf-8"))
+    assert INSTALL_SUPERVISOR in readmes, (
+        f"gban prints {INSTALL_SUPERVISOR!r}, which neither README tells anyone to run")
+
+
+def test_the_printed_install_names_a_package_that_is_actually_published():
+    """The distribution name in the command must be one this repository builds. Checked
+    against the pyprojects rather than against PyPI, because a test that reaches the network
+    fails for reasons that have nothing to do with the code."""
+    from gban.doctor import INSTALL_SUPERVISOR
+
+    built = {tomllib.loads((REPO / d / "pyproject.toml").read_text())["project"]["name"]
+             for d in ("cli", "fleet")}
+    named = [w for w in INSTALL_SUPERVISOR.split() if w.startswith("graphban")]
+    assert named, f"{INSTALL_SUPERVISOR!r} names no package at all"
+    assert set(named) <= built, f"{named} is not built here; built are {sorted(built)}"