You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
macos/bootstrap.sh: harden against pre-existing brew Node + apply lessons from 2026-05-13 incidents #5
macos/bootstrap.sh already installs Node via fnm install --lts, which is the right design. But two real Macs (mbp13 and the primary dev Mac) were both running odd-line Node (v25.7.0 and v26.0.0 respectively) on 2026-05-13, both via ad-hoc brew install node that predated this script, and both crashed Claude Code and qmd (via better-sqlite3 ABI mismatch). The fix took ~45 min across the two boxes.
Harden the macOS bootstrap so it's safe to run on a Mac that's already been touched ad-hoc, and so it produces a system where Node version cannot silently drift to a non-LTS Current-line release on the next brew upgrade. This is a defensive/idempotency pass, not a redesign.
Acceptance criteria
Script detects an existing brew installation of the node formula (any Current-line version) and either brew unlink nodes it OR warns and prompts before continuing — pre-existing brew Node must not shadow fnm
Script offers a Plan B: when the user wants a stable, brew-only setup (no fnm shell hook needed), install node@22 and brew link --force --overwrite node@22 directly — single-flag toggle, documented in README
Script pre-flights and fixes ownership of /usr/local/share/zsh, /usr/local/share/zsh/site-functions, /usr/local/var/homebrew, /usr/local/Cellar, /opt/homebrew/share/zsh, /opt/homebrew/var/homebrew (Intel + Apple Silicon paths) so compinit doesn't prompt and brew install doesn't fail with Permission denied @ rb_sysopen — both happened on mbp13 on 2026-05-13
zshrc.snippet.sh appends a guard that warns on shell startup if node -v is on an odd-line release (v23/v25/v27/v29), and prints the recovery command inline
Script supports a --restore-globals <file> flag that reads a list of npm package names (one per line, as produced by npm ls -g --depth=0 --json | jq -r '.dependencies | keys[]') and reinstalls them on the now-pinned Node, so machine-to-machine moves and Node-version flips don't lose globals silently
README has a "Migrating a Mac that was already set up ad-hoc" section showing the exact commands run on 2026-05-13: save globals list → brew install node@22 → brew unlink node && brew link --force --overwrite node@22 → reinstall globals → uninstall old keg
Script is idempotent: rerunning on an already-bootstrapped Mac produces zero changes and exit 0
None — can start immediately. Touches existing issue #3 (npm not found during Claude Code / Codex install — fnm not activated in piped execution scope); fold its fix in if the activation order is part of this hardening pass.
Category: enhancement Summary: Harden macos/bootstrap.sh so a Mac that was previously touched ad-hoc (especially pre-existing brew install node) reaches a green state on first run, and so Node version cannot silently drift to a non-LTS Current-line release later. Bundled with the Windows fix in #3 into a single PR — proposed PR title: bootstrap: harden fnm/Node activation across macOS + Windows.
Current behavior: macos/bootstrap.sh installs Node via fnm install --lts, which is the correct default. In practice, on Macs that already had brew install node from prior ad-hoc setup, the brew-installed Current-line Node (v25 / v26 on 2026-05-13) shadows the fnm-managed LTS on PATH. This breaks Claude Code and qmd via better-sqlite3 ABI mismatch and required ~45 min of manual recovery per machine across mbp13 and the primary dev Mac. The script also does not pre-flight common Homebrew permission issues on /usr/local/share/zsh*, /usr/local/var/homebrew, /usr/local/Cellar, and the /opt/homebrew/* equivalents, which cause compinit prompts and brew install failures with Permission denied @ rb_sysopen. There is no machinery for restoring global npm packages when migrating between Macs or flipping Node versions.
Desired behavior:
The script becomes idempotent and self-healing on a Mac that's already been touched ad-hoc. Pre-existing brew Node is detected and resolved before the fnm path runs. A "Plan B" --brew-only flag is offered for users who want a stable, brew-only node@22 setup without any fnm shell hook. Homebrew-owned paths that commonly break compinit and brew install are pre-flighted and repaired with the user's explicit sudo grant, gathered in one prompt up front. A guard in the appended zsh snippet warns on shell startup when node -v is on an odd-line release. A --restore-globals <file> flag re-installs a saved list of npm globals on the now-pinned Node. The README gains a "Migrating a Mac that was already set up ad-hoc" section with the exact recovery sequence used on 2026-05-13.
Key interfaces:
The macOS bootstrapper (macos/bootstrap.sh) — new CLI flags: --brew-only, --force-relink, --restore-globals <file>. Default mode (no flags) preserves today's fnm-based behavior plus the new safety probes.
--brew-only and the default fnm path are mutually exclusive: invoking both errors early with a message telling the user to pick one (exit 1).
--force-relink makes the pre-existing-brew-Node remediation non-interactive (auto brew unlink node) for CI / scripted reruns. Without it, the script warns and prompts.
Ownership repair: chown $(whoami):staff runs only on paths that fail test -w. Sudo is requested once up front in a single prompt rather than per-path. Paths that don't exist on the current arch (Intel vs Apple Silicon) are skipped silently.
Shell snippet appended to ~/.zshrc — adds a guard that runs once per interactive shell startup, calls node -v only if node is on PATH, and prints a warning plus inline recovery command when the major version is odd (v23 / v25 / v27 / v29 …).
--restore-globals <file> — file format is one npm package name per line, exactly as produced by npm ls -g --depth=0 --json | jq -r '.dependencies | keys[]'. The script installs each at @latest (no version pinning). Failures are skipped and reported at the end; the script does not abort on a single failed install.
README — a new "Migrating a Mac that was already set up ad-hoc" section walking through: save globals list → brew install node@22 → brew unlink node && brew link --force --overwrite node@22 → reinstall globals → uninstall the old keg.
Acceptance criteria:
On a Mac with the Current-line node formula installed (brew list --formula includes node), the script detects it before invoking fnm and either warns + prompts (default) or brew unlink nodes automatically with --force-relink. It does not silently proceed into a broken state where brew Node shadows fnm Node.
--brew-only installs node@22, runs brew link --force --overwrite node@22, and skips the fnm path entirely. Passing both --brew-only and any fnm-implying option errors with a clear message and exits 1.
Before any brew install, the script tests writability of /usr/local/share/zsh, /usr/local/share/zsh/site-functions, /usr/local/var/homebrew, /usr/local/Cellar, /opt/homebrew/share/zsh, and /opt/homebrew/var/homebrew. Paths that fail test -w are repaired with sudo chown $(whoami):staff after a single up-front sudo prompt. Paths that don't exist on the current arch are skipped silently.
The shell snippet appended to ~/.zshrc includes a guard that runs once per shell startup, checks node -v only when node is on PATH, and prints a warning + recovery command when the major version is odd (v23 / v25 / v27 / v29 …).
--restore-globals <file> reads the file, runs npm install -g <pkg>@latest for each package, skips failures, and prints a summary of installed / skipped / failed packages at the end. The script exits 0 when at least one install succeeds and there are no other script errors.
README's "Migrating a Mac that was already set up ad-hoc" section walks through the recovery sequence with copy-pasteable commands.
Re-running the script on an already-bootstrapped Mac produces zero state mutations: no brew install, no chown, no file writes. Read-only probes (brew list, test -w, node -v) are allowed. Exit 0.
End-to-end run on mbp13 and the primary dev Mac reaches a green state. This is a maintainer-verified merge gate: the agent may complete all other criteria, but the PR holds until the maintainer signs off on the two real-Mac runs.
Out of scope:
Linux (linux/bootstrap.sh) and WSL bootstrappers — separate platforms, separate hardening passes.
While implementing in #6, AC #4 ("warns on shell startup if node -v is on an odd-line release (v23/v25/v27/v29)") was broadened to a non-LTS check: warn when node -v's major ≠ the pinned LTS major (default 22).
Why: the 2026-05-13 incident on the primary dev Mac was v26.0.0 — even-major-but-Current. An odd-only guard would have slipped past that one. The broader rule catches both odd-line drift (v23/v25/v27/v29) and even-but-Current drift (v26).
How to override: export DEV_BOOTSTRAP_PINNED_NODE_MAJOR before the snippet runs to change the pin (e.g. when v24 becomes Active LTS).
Code lives in macos/zshrc.snippet.sh and macos/lib/node-utils.sh::is_non_lts_node_version. All other ACs in this issue are implemented to spec.
Activity
linear commentedon May 13, 2026
HOM-57
AojdevStudio commentedon May 13, 2026
Agent Brief
Category: enhancement
Summary: Harden
macos/bootstrap.shso a Mac that was previously touched ad-hoc (especially pre-existingbrew install node) reaches a green state on first run, and so Node version cannot silently drift to a non-LTS Current-line release later. Bundled with the Windows fix in #3 into a single PR — proposed PR title: bootstrap: harden fnm/Node activation across macOS + Windows.Current behavior:
macos/bootstrap.shinstalls Node viafnm install --lts, which is the correct default. In practice, on Macs that already hadbrew install nodefrom prior ad-hoc setup, the brew-installed Current-line Node (v25 / v26 on 2026-05-13) shadows the fnm-managed LTS on PATH. This breaks Claude Code andqmdviabetter-sqlite3ABI mismatch and required ~45 min of manual recovery per machine acrossmbp13and the primary dev Mac. The script also does not pre-flight common Homebrew permission issues on/usr/local/share/zsh*,/usr/local/var/homebrew,/usr/local/Cellar, and the/opt/homebrew/*equivalents, which causecompinitprompts andbrew installfailures withPermission denied @ rb_sysopen. There is no machinery for restoring global npm packages when migrating between Macs or flipping Node versions.Desired behavior:
The script becomes idempotent and self-healing on a Mac that's already been touched ad-hoc. Pre-existing brew Node is detected and resolved before the fnm path runs. A "Plan B"
--brew-onlyflag is offered for users who want a stable, brew-onlynode@22setup without any fnm shell hook. Homebrew-owned paths that commonly breakcompinitandbrew installare pre-flighted and repaired with the user's explicit sudo grant, gathered in one prompt up front. A guard in the appended zsh snippet warns on shell startup whennode -vis on an odd-line release. A--restore-globals <file>flag re-installs a saved list of npm globals on the now-pinned Node. The README gains a "Migrating a Mac that was already set up ad-hoc" section with the exact recovery sequence used on 2026-05-13.Key interfaces:
macos/bootstrap.sh) — new CLI flags:--brew-only,--force-relink,--restore-globals <file>. Default mode (no flags) preserves today's fnm-based behavior plus the new safety probes.--brew-onlyand the default fnm path are mutually exclusive: invoking both errors early with a message telling the user to pick one (exit 1).--force-relinkmakes the pre-existing-brew-Node remediation non-interactive (autobrew unlink node) for CI / scripted reruns. Without it, the script warns and prompts.chown $(whoami):staffruns only on paths that failtest -w. Sudo is requested once up front in a single prompt rather than per-path. Paths that don't exist on the current arch (Intel vs Apple Silicon) are skipped silently.~/.zshrc— adds a guard that runs once per interactive shell startup, callsnode -vonly ifnodeis on PATH, and prints a warning plus inline recovery command when the major version is odd (v23 / v25 / v27 / v29 …).--restore-globals <file>— file format is one npm package name per line, exactly as produced bynpm ls -g --depth=0 --json | jq -r '.dependencies | keys[]'. The script installs each at@latest(no version pinning). Failures are skipped and reported at the end; the script does not abort on a single failed install.brew install node@22→brew unlink node && brew link --force --overwrite node@22→ reinstall globals → uninstall the old keg.Acceptance criteria:
nodeformula installed (brew list --formulaincludesnode), the script detects it before invokingfnmand either warns + prompts (default) orbrew unlink nodes automatically with--force-relink. It does not silently proceed into a broken state where brew Node shadows fnm Node.--brew-onlyinstallsnode@22, runsbrew link --force --overwrite node@22, and skips the fnm path entirely. Passing both--brew-onlyand any fnm-implying option errors with a clear message and exits 1.brew install, the script tests writability of/usr/local/share/zsh,/usr/local/share/zsh/site-functions,/usr/local/var/homebrew,/usr/local/Cellar,/opt/homebrew/share/zsh, and/opt/homebrew/var/homebrew. Paths that failtest -ware repaired withsudo chown $(whoami):staffafter a single up-front sudo prompt. Paths that don't exist on the current arch are skipped silently.~/.zshrcincludes a guard that runs once per shell startup, checksnode -vonly whennodeis on PATH, and prints a warning + recovery command when the major version is odd (v23 / v25 / v27 / v29 …).--restore-globals <file>reads the file, runsnpm install -g <pkg>@latestfor each package, skips failures, and prints a summary of installed / skipped / failed packages at the end. The script exits 0 when at least one install succeeds and there are no other script errors.brew install, nochown, no file writes. Read-only probes (brew list,test -w,node -v) are allowed. Exit 0.mbp13and the primary dev Mac reaches a green state. This is a maintainer-verified merge gate: the agent may complete all other criteria, but the PR holds until the maintainer signs off on the two real-Mac runs.Out of scope:
linux/bootstrap.sh) and WSL bootstrappers — separate platforms, separate hardening passes.bootstrap.ps1) — covered bynpmnot found during Claude Code / Codex install — fnm not activated in piped execution scope #3 in the same PR.node@22as the LTS pin.--restore-globalsfrom a cached globals list — restoring is opt-in via the explicit flag.AojdevStudio commentedon May 13, 2026
Implementation note — AC #4 broadened
While implementing in #6, AC #4 ("warns on shell startup if
node -vis on an odd-line release (v23/v25/v27/v29)") was broadened to a non-LTS check: warn whennode -v's major ≠ the pinned LTS major (default 22).Why: the 2026-05-13 incident on the primary dev Mac was v26.0.0 — even-major-but-Current. An odd-only guard would have slipped past that one. The broader rule catches both odd-line drift (v23/v25/v27/v29) and even-but-Current drift (v26).
How to override: export
DEV_BOOTSTRAP_PINNED_NODE_MAJORbefore the snippet runs to change the pin (e.g. when v24 becomes Active LTS).Code lives in
macos/zshrc.snippet.shandmacos/lib/node-utils.sh::is_non_lts_node_version. All other ACs in this issue are implemented to spec.