feat(doctor): add INSTALLATION section for Homebrew distribution health#485
Merged
Conversation
added 2 commits
July 2, 2026 02:02
Catches the class of bug fixed in homebrew-tap PR #135: a Homebrew formula install that "succeeds" (brew reports installed, brew upgrade says "already installed") but silently fails to link — man-page name collisions on case-insensitive filesystems, and shell/Cellar version drift after an upgrade the user forgot to restart their shell for. New `_doctor_check_installation` checks, scoped to flow-cli's own Homebrew install (skips silently for git-clone/plugin-manager installs): - opt/Cellar symlink integrity (installed-but-unlinked detection) - shell-loaded FLOW_VERSION vs. installed Cellar keg version drift - flow-cli's own man pages actually resolving into the shared man1 dir (vs. losing a case-insensitive name collision to another formula, scoped to formulae that actually link — Homebrew's own keg-only convention, e.g. lua vs lua@5.4, produces same-name kegs constantly and is not a bug) New tests/e2e-doctor-install.zsh (7 scenarios, all via mocked `brew`).
Adds the new section to REFCARD-DOCTOR.md's check-category list (renumbering the categories after it) and to both CHANGELOGs.
Data-Wise
pushed a commit
that referenced
this pull request
Jul 2, 2026
231 test files (was 230), 76 registered suites (was 75), 75/75 passing (was 74/74) — reflects tests/e2e-doctor-install.zsh added in PR #485. Also fixed a pre-existing 32→33 command-file drift.
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
1 participant
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.
Summary
doctorINSTALLATION section catches the class of bug fixed in homebrew-tap PR fix(ci): add mkdocs-exclude plugin to docs workflow #135: a Homebrew install that "succeeds" but silently fails to link (man-page name collision, stale Cellar keg after an upgrade the shell wasn't restarted for).luavslua@5.4).tests/e2e-doctor-install.zsh(7 scenarios, mockedbrew), docs updated (REFCARD-DOCTOR.md, both CHANGELOGs).Test plan
zsh tests/e2e-doctor-install.zsh— 7/7 passed./tests/run-all.sh— 74 passed / 0 failed / 1 timeout (pre-existing interactive/tmux baseline) / 1 skipped (himalaya absent)mkdocs build --strict— 0 warningslua/lua@5.4,node/node@20sharing man-page basenames) during development, which drove the design to scope the check to flow-cli's own man pages resolving correctly rather than a whole-Cellar collision scan — re-verified clean after the fix.🤖 Generated with Claude Code