From bb6f081b66b1f6d1f81374c3f32de4bf348aa19e Mon Sep 17 00:00:00 2001 From: didericis Date: Mon, 27 Jul 2026 00:59:09 -0400 Subject: [PATCH] docs: correct two claims the live harness run disproved MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The PATH story was wrong in an instructive way. I said a Homebrew Python is on PATH only because of a shell-profile line; on this host /etc/paths.d/homebrew puts /opt/homebrew/bin on every login shell's PATH, fresh accounts included. The stub still wins, because path_helper appends /etc/paths.d/* *after* /etc/paths and /usr/bin is in the latter. Ordering, not absence, is what makes bare `python3` the 3.9.6 stub — which is also why the versioned `python3.14` candidate is the one that matched during the real run, rather than the /opt/homebrew/bin/python3 fallback I expected. The harness header also credited install.sh with writing a PATH line into the login shell. It does not write one. The reset argument is unaffected (such a line would live in the deleted home either way), but the claim was untrue. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01WEfZZhakx13bxTfXcZCoS5 --- README.md | 2 +- scripts/macos-install-test.sh | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8aeef05a..5063a3cd 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ The installer is a bootstrapper: it finds a suitable Python, installs bot-bottle ### Requirements -**Python ≥ 3.11**, and this is the one that trips people up on macOS: the `python3` Apple ships at `/usr/bin/python3` is **3.9.6**, which is too old. A Homebrew or python.org Python is only on your `PATH` because of a line in your shell profile, so anything running without that profile — a fresh user account, a launchd job, a CI runner — sees the 3.9 stub instead. The installer therefore looks past `PATH` before giving up: it tries `python3`, then `python3.11`–`python3.14`, then `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, and python.org framework builds, and tells you which one it picked when it isn't the obvious one. Point it somewhere specific with `BOT_BOTTLE_PYTHON=/path/to/python3`. +**Python ≥ 3.11**, and this is the one that trips people up on macOS: the `python3` Apple ships at `/usr/bin/python3` is **3.9.6**, which is too old. Bare `python3` resolves to that stub far more often than people expect. `path_helper` builds a login shell's `PATH` from `/etc/paths` and then appends `/etc/paths.d/*`, and `/usr/bin` sits in the former — so even when `/opt/homebrew/bin` *is* on the `PATH` (via `/etc/paths.d/homebrew`), it comes after `/usr/bin` and loses. Prepending a newer Python is something your shell profile does, and a fresh account, a launchd job, or a CI runner has no such profile. So the installer looks past bare `python3` before giving up: it tries `python3`, then the versioned `python3.11`–`python3.14` names, then `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin`, and python.org framework builds — and tells you which one it picked when it isn't the obvious one. Point it somewhere specific with `BOT_BOTTLE_PYTHON=/path/to/python3`. **`pipx`** is strongly preferred over the `pip --user` fallback. Homebrew and Debian/Ubuntu interpreters are externally managed (PEP 668), which blocks `pip install --user` outright; the installer detects this and tells you to install `pipx` rather than failing deep inside pip. diff --git a/scripts/macos-install-test.sh b/scripts/macos-install-test.sh index 0ec94dde..2e69120a 100755 --- a/scripts/macos-install-test.sh +++ b/scripts/macos-install-test.sh @@ -4,8 +4,8 @@ # Exercises install.sh the way a brand-new user would, inside a throwaway # macOS account you create and delete from the CLI. install.sh's entire # footprint is user-home-local — the pipx venv under ~/.local (or the pip -# --user tree under ~/Library/Python), the ~/.bot-bottle config dir, and a -# PATH line in the login shell. It never installs the backend itself (see +# --user tree under ~/Library/Python) and the ~/.bot-bottle config dir. It +# writes no shell-profile PATH line, and never installs the backend (see # the header of install.sh), so deleting the user is a complete, # deterministic reset of everything the installer touched. The Apple # `container` runtime is a HOST prerequisite installed once and kept;