From c5d511d93291782169c0c4e08db5d9dec68518cf Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Thu, 20 Aug 2026 14:55:35 -0700 Subject: [PATCH 1/2] build: keep the checkout build off PATH MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `just build` wrote straight into ~/.local/bin, so compiling put the working tree in front of whatever ob the machine had installed. Typing `ob` then meant the checkout, and `ob doctor` reported it on every run as "PATH selects a different ob executable than the running binary; 1 stale PATH candidate(s) found" — a warning that was correct, permanent, and easy to stop reading. The difference only surfaces when someone is already confused about which binary produced a result, which is the worst moment to discover it. Shipping a binary onto PATH is a decision rather than a side effect of compiling, so the build lands in ./bin — already gitignored, already where the docs generator reads it from — and `just install` is the step that puts it on PATH, saying where it landed and what it answers to. `just clean` removes both. OB_BIN_DIR moves the build, OB_INSTALL_DIR the install. Co-Authored-By: Claude Opus 5 --- CONTRIBUTING.md | 2 +- Justfile | 33 ++++++++++++++++++++++++--------- README.md | 14 ++++++++++---- 3 files changed, 35 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29fe2bd6..e2d2f2c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,7 +39,7 @@ end-to-end suite. ```sh just site-install # once, on a fresh clone: installs site/node_modules -just build # builds ob into $OB_BIN_DIR, or ~/.local/bin +just build # builds ob into ./bin, which is not on PATH ``` ## The verification gate diff --git a/Justfile b/Justfile index a6b90a93..c92f4f42 100644 --- a/Justfile +++ b/Justfile @@ -1,11 +1,17 @@ -# Build the CLI into a user-local directory on PATH. +# Build the CLI into the checkout. default: build -# Build the ob binary. +# Build the ob binary into ./bin, which is not on PATH. +# +# It used to build straight into ~/.local/bin, which put a checkout build in +# front of whatever `ob` the machine had installed — so `ob` meant the working +# tree rather than the release, and `ob doctor` reported the mismatch as a stale +# PATH candidate on every run. Shipping a binary onto PATH is a decision, not a +# side effect of compiling, so it now belongs to `just install`. build: #!/bin/bash set -euo pipefail - ob_build_dir="${OB_BIN_DIR:-${HOME}/.local/bin}" + ob_build_dir="${OB_BIN_DIR:-bin}" ob_build_version="${OB_VERSION:-}" if [ -n "$ob_build_version" ] && [[ ! "$ob_build_version" =~ ^v[1-9][0-9]{3}\.([1-9]|1[0-2])\.(0|[1-9][0-9]{0,18})$ ]]; then echo "OB_VERSION must match vYYYY.M.REVISION" >&2; exit 1 @@ -20,8 +26,17 @@ build: go build -ldflags "-X github.com/labstack/onebox/internal/buildinfo.release=${ob_build_version} -X github.com/labstack/onebox/internal/buildinfo.buildTime=${ob_build_time}" -o "${ob_build_dir}/ob" ./cmd/ob echo "built ${ob_build_dir}/ob" -# Install the ob binary (alias for build). +# Put the built binary on PATH, deliberately. +# +# This is what shadows an installed release, so it says where it landed and +# what it will answer to. install: build + #!/bin/bash + set -euo pipefail + ob_install_dir="${OB_INSTALL_DIR:-${HOME}/.local/bin}" + mkdir -p "$ob_install_dir" + install -m 0755 "${OB_BIN_DIR:-bin}/ob" "${ob_install_dir}/ob" + echo "installed ${ob_install_dir}/ob ($("${ob_install_dir}/ob" --version))" # Run the test suite. test: @@ -151,11 +166,11 @@ e2e: # just built, named explicitly rather than resolved from PATH — otherwise an # older `ob` installed elsewhere documents a tree it did not come from. docs-generate: build - go run ./cmd/ob-docgen --ob "${OB_BIN_DIR:-$HOME/.local/bin}/ob" + go run ./cmd/ob-docgen --ob "${OB_BIN_DIR:-bin}/ob" # Fail when a generated documentation page is behind the binary. docs-generate-check: build - go run ./cmd/ob-docgen --check --ob "${OB_BIN_DIR:-$HOME/.local/bin}/ob" + go run ./cmd/ob-docgen --check --ob "${OB_BIN_DIR:-bin}/ob" # Install the documentation site's dependencies. site-install: @@ -180,9 +195,9 @@ docs-check: docs-generate-check release: bash scripts/release.sh -# Remove the installed binary. +# Remove the built binary and any copy `just install` placed on PATH. clean: #!/bin/bash set -euo pipefail - ob_build_dir="${OB_BIN_DIR:-${HOME}/.local/bin}" - rm -f "${ob_build_dir}/ob" + rm -f "${OB_BIN_DIR:-bin}/ob" + rm -f "${OB_INSTALL_DIR:-${HOME}/.local/bin}/ob" diff --git a/README.md b/README.md index 74a01d6a..b225d08c 100644 --- a/README.md +++ b/README.md @@ -88,15 +88,21 @@ Released archives and Linux packages are installed from GitHub Releases, macOS users can install through Homebrew, and Windows users can install through Scoop. Follow the verified steps in the [installation guide](https://onebox.run/start/install). -To build the binary from a checkout into `~/.local/bin`: +To build the binary from a checkout: ```sh just build ``` -`just install` is an alias for the same target. Ensure `~/.local/bin` is on -`PATH`; set `OB_BIN_DIR` to use another destination. Run `just --list` to see -the available build, test, formatting, and check targets. +It lands in `./bin/ob`, which is deliberately not on `PATH`: a checkout build +that shadows an installed release makes `ob` mean the working tree, and the +difference only surfaces when someone is already confused about which binary +produced a result. + +`just install` is the deliberate step that copies it to `~/.local/bin` and +prints what it will answer to; `just clean` removes both. `OB_BIN_DIR` changes +where the build lands and `OB_INSTALL_DIR` where the install goes. Run `just +--list` to see the available build, test, formatting, and check targets. Onebox releases use `vYYYY.M.REVISION`, for example `v2026.8.0` for the first release in August 2026. The year is four digits, months are unpadded, and each From 6471d05dfd40f444d59d047403c94901458dce73 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Thu, 20 Aug 2026 15:13:08 -0700 Subject: [PATCH 2/2] build: clean the checkout, not the binary on PATH MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first version of this change left `clean` removing ~/.local/bin/ob as well as the build. That was right while `build` wrote there — it removed what the recipe had put there — and wrong the moment the build moved to ./bin: `just clean` in a checkout would delete a binary this checkout may never have created, including a release installed by hand through the steps the installation guide gives. `clean` now removes the build. `uninstall` removes the copy on PATH, and says which path it removed. Verified: with a binary installed, `just clean` removes ./bin/ob and leaves ~/.local/bin/ob standing; `just uninstall` then removes it and `ob` falls back to the Homebrew release. Co-Authored-By: Claude Opus 5 --- Justfile | 18 ++++++++++++++++-- README.md | 3 ++- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/Justfile b/Justfile index c92f4f42..da1b8663 100644 --- a/Justfile +++ b/Justfile @@ -195,9 +195,23 @@ docs-check: docs-generate-check release: bash scripts/release.sh -# Remove the built binary and any copy `just install` placed on PATH. +# Remove the built binary. +# +# The checkout only, never the copy on PATH. While `build` wrote straight to +# ~/.local/bin, removing it there was removing what this recipe had put there; +# now that the build lands in ./bin, doing the same would delete a binary this +# checkout may never have created — including a release installed by hand +# through the steps the installation guide gives. `just uninstall` is how you +# ask for that, and it says so. clean: #!/bin/bash set -euo pipefail rm -f "${OB_BIN_DIR:-bin}/ob" - rm -f "${OB_INSTALL_DIR:-${HOME}/.local/bin}/ob" + +# Remove the copy `just install` placed on PATH. +uninstall: + #!/bin/bash + set -euo pipefail + ob_install_dir="${OB_INSTALL_DIR:-${HOME}/.local/bin}" + rm -f "${ob_install_dir}/ob" + echo "removed ${ob_install_dir}/ob" diff --git a/README.md b/README.md index b225d08c..850f2c0b 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,8 @@ difference only surfaces when someone is already confused about which binary produced a result. `just install` is the deliberate step that copies it to `~/.local/bin` and -prints what it will answer to; `just clean` removes both. `OB_BIN_DIR` changes +prints what it will answer to; `just clean` removes the build and `just +uninstall` the copy on PATH. `OB_BIN_DIR` changes where the build lands and `OB_INSTALL_DIR` where the install goes. Run `just --list` to see the available build, test, formatting, and check targets.