feat(doctor,update): global doctor checks and isobox update --check (#50, #58, #59) - #64
Merged
Merged
Conversation
This comment has been minimized.
This comment has been minimized.
added 2 commits
June 28, 2026 16:27
, #58, #59) Adds the global isobox doctor checks (issue #50): - git on PATH (error when missing) - bwrap on PATH (warning with Tool-Call Sandbox consequence when missing) - isobox on PATH (warning when missing) - multiple isobox binaries on PATH (warning listing the active and duplicates) - version metadata as ok (dev is never treated as a warning) The checks use an injectable PathLookup so they are unit-tested without depending on the host's actual dependency state, and they never call the network or evaluate self-update eligibility. Adds isobox update --check (issue #58) and Update Target resolution with duplicate and managed-path guardrails (issue #59): - isobox update --check is the observability-only update check using the GitHub Releases API - drafts and prereleases are ignored - already-latest exits 0 - the Update Target is resolved from the first isobox on PATH - duplicate isobox binaries are reported as warnings - dev builds are refused with an actionable message - clearly package-manager-managed targets are refused with guidance to use the package manager or move to a writable manual-style dir - the release metadata source is injectable so tests do not depend on live GitHub
The previous integration tests relied on the host having git, bubblewrap (bwrap), and isobox on PATH. CI runners do not have bwrap installed, so several tests failed: - TestDoctorReportsBwrapOnPathAsOK - TestDoctorReportsBwrapMissingAsWarningNamingToolCallSandbox - TestDoctorReportsIsoboxMissingAsWarning - TestDoctorReportsDuplicateIsoboxAsWarning - TestDoctorReportsVersionMetadataAsOKForDevBuild - TestUpdateCheckRefusesPackageManagedUpdateTarget The fix introduces: 1. A writeFakeExecutable helper that creates an empty file with the execute bit set in a temp dir. The doctor global checks call exec.LookPath only to test for presence, so a fake bwrap is sufficient and the test no longer depends on bubblewrap being installed on the host. 2. Fully controlled PATHs that exclude the host PATH for tests that exercise the bwrap-missing and the version-metadata branches, so a real bwrap installed on the host cannot accidentally satisfy the check. 3. ISOBOX_UPDATE_MANAGED_PATH_PREFIXES, an environment variable that adds extra managed path prefixes to the updater's refusal list. The default list still covers the common package-manager-managed locations; the env var exists for power users with unusual system-managed install locations and for the integration test suite, which can now teach the updater about a temp directory without requiring write access to /opt or /usr/bin. The PR-ready state covers issues #50, #58, #59 with all hermetic tests passing on environments with and without bubblewrap.
This was referenced Jun 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the three 0.1.1 first-run usability issues from PRD #56.
Summary
This PR implements the global isobox doctor checks (issue #50), the
isobox update --check observability command (issue #58), and the
Update Target resolution with duplicate and managed-path guardrails
(issue #59).
Issue #50: Global isobox doctor checks
The doctor command now reports the following global checks on every
invocation:
ok(adevversion is never treated as awarning or update-eligibility error)
gitonPATH(error when missing, with consequence and fix)bubblewrap (bwrap)onPATH(warning with Tool-Call Sandboxconsequence when missing, plus a fix to install bubblewrap)
isoboxonPATH(warning when missing)isoboxbinaries onPATH(warning listing theactive binary plus duplicates)
The checks use an injectable
PathLookup(internal/doctorenv)so the unit tests run without depending on the host's actual
dependency state, and they never call the network, evaluate
self-update eligibility, or run a bubblewrap self-test.
Issue #58: isobox update --check
Adds the
isobox update --checkobservability-only update check.The command:
release (drafts and prereleases are ignored)
(up-to-date / behind / ahead), and selected Update Target
devbuilds with an actionable messageReleaseClient(internal/update) so the integration testsdo not depend on live GitHub
The release metadata wire format uses GitHub's
tag_name,prerelease,draft, andpublished_atJSON keys.Issue #59: Update Target resolution with duplicate and managed-path guardrails
isoboxexecutable onthe host
PATH.isobox update --checkreports the selected Update Target.isoboxexecutables onPATHare reported aswarnings without changing the selected target.
/usr/bin,/opt/homebrew,/snap,/var/lib/dpkg,/var/lib/rpm,/var/lib/pacman,/nix/store) are refusedwith guidance to use the package manager or move the binary to a
writable manual-style directory (
${HOME}/.local/binor/usr/local/bin).teach the updater about additional managed prefixes by exporting
ISOBOX_UPDATE_MANAGED_PATH_PREFIXES(one path per line) beforerunning the check. The default behavior is unchanged.
Target resolution and eligibility behavior are covered by unit
tests in
internal/update/target_test.gousing a fakePathLookup, plus an end-to-end integration test thatmanipulates the test process
PATHand usesISOBOX_UPDATE_MANAGED_PATH_PREFIXESto simulate a managedtarget without requiring write access to
/optor/usr/bin.Documentation
CHANGELOG.mdrecords the newdoctorglobal checks andisobox update --checkunder Unreleased.README.mddocuments theisobox update --checkflow andthe global doctor checks.
isobox <command> --helpand the top-levelisobox --helpnow include
updatealongside the existing commands.docs_test.goaddsTestReadmeDocumentsUpdateCheckCommandand
TestReadmeDocumentsGlobalDoctorChecksto guard thedocumentation.
Pre-PR checks
All pre-PR checks pass:
The global doctor and update-check integration tests are
hermetic: they build a fake
bwrapin a temp directory so thetests do not depend on bubblewrap being installed on the host,
and they use a fully controlled
PATHfor tests that exercisethe missing-bwrap branch.
Out of scope (deferred to follow-up slices)
isobox update(the full update flow with download, checksumverification, replace, backup, and rollback) is intentionally
not implemented in this PR. The
--checkslice is theobservability-only vertical slice from PRD PRD: isobox 0.1.1 CLI help and self-update #56.
--force,--target,--install-dir, or--yesupdate flags.
install.shremains the first-install path only; update doesnot download or execute installer scripts.