golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fix(install): prefer stable Homebrew symlinks over versioned Cellar paths in node runner

Browse Source 
process.execPath on Homebrew resolves symlinks and returns the versioned
Cellar path (e.g. /usr/local/Cellar/node/25.8.1/bin/node). After
brew upgrade node, the old Cellar binary fails with dyld: Library not
loaded because shared libraries have changed SOVERSION.

- Add normalizeNodePath() helper that maps Cellar paths to stable
  Homebrew symlinks (/usr/local/bin/node or /opt/homebrew/bin/node)
- resolveNodeRunner() now calls normalizeNodePath() before quoting
- rewriteLegacyManagedNodeHookCommands() also normalizes baked Cellar
  runner paths in existing hook commands so reinstall doesn't re-bake them
- Export normalizeNodePath for testability
- Add 22 tests covering all cases (Cellar paths, stable symlinks,
  NVM, system node, Windows, null/empty, both function surfaces)

Closes #3181

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-05-06 21:03:33 -04:00
parent ff832089bf
commit 69aa7ec04e
4 changed files with 327 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.changeset/gallant-badgers-bark.md Normal file
View File

@@ -0,0 +1,5 @@
---
type: Fixed
pr: 3181
---
resolveNodeRunner() and rewriteLegacyManagedNodeHookCommands() now prefer stable Homebrew symlinks (/usr/local/bin/node, /opt/homebrew/bin/node) over versioned Cellar paths when a Cellar path is detected, preventing dyld: Library not loaded errors after brew upgrade node

2
CHANGELOG.md
View File

@@ -8,7 +8,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
### Fixed
- **Workstream resolution in `init.milestone-op` and `roadmap.analyze`** — both handlers now respect `--ws`, `GSD_WORKSTREAM`, and the `.planning/active-workstream` file; workstream-scoped repos no longer exit "All phases complete — Nothing left to do" due to `phase_count: 0` from reading the wrong root `.planning/`. (#3196)
- **Stable node path on Homebrew** — `resolveNodeRunner()` now maps versioned Homebrew Cellar paths (e.g. `/usr/local/Cellar/node/25.8.1/bin/node`) to the stable Homebrew symlinks (`/usr/local/bin/node` on Intel, `/opt/homebrew/bin/node` on Apple Silicon). `rewriteLegacyManagedNodeHookCommands()` applies the same normalization to baked Cellar paths in existing hook commands. This prevents `dyld: Library not loaded` errors after `brew upgrade node`. (#3181)
- **Milestone-archive layout support** — `validate consistency`, `validate health`, and `find-phase` now scan `.planning/milestones/v*-phases/` directories in addition to the flat `.planning/phases/` layout. Projects that have graduated to milestone-archive layout no longer receive spurious W006 "Phase N in ROADMAP.md but no directory on disk" warnings for every active phase. (#3164)
### Feature

72
bin/install.js
View File

@@ -525,6 +525,34 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
return `${resolvedTarget}/`;
}
/**
* Normalize a raw `process.execPath` to a stable, upgrade-safe node binary
* path. On Homebrew installs, `process.execPath` resolves symlinks and returns
* the versioned Cellar path (e.g.
* `/usr/local/Cellar/node/25.8.1/bin/node`). Baking that path into hook
* commands causes `dyld: Library not loaded` errors after `brew upgrade node`
* because the shared libraries referenced by the Cellar binary have changed
* SOVERSION. (#3181)
*
* The stable Homebrew symlinks (`/usr/local/bin/node` for Intel,
* `/opt/homebrew/bin/node` for Apple Silicon) survive upgrades — Homebrew
* re-points them atomically. We prefer those when a Cellar path is detected.
*
* Non-Homebrew installs (NVM, system node, Windows, etc.) are returned as-is.
*/
function normalizeNodePath(execPath) {
if (!execPath) return execPath;
// Intel Homebrew: /usr/local/Cellar/node/<version>/bin/node
if (/^\/usr\/local\/Cellar\/node\/[^/]+\/bin\/node(\.exe)?$/.test(execPath)) {
return '/usr/local/bin/node';
}
// Apple Silicon Homebrew: /opt/homebrew/Cellar/node/<version>/bin/node
if (/^\/opt\/homebrew\/Cellar\/node\/[^/]+\/bin\/node(\.exe)?$/.test(execPath)) {
return '/opt/homebrew/bin/node';
}
return execPath;
}
/**
* Resolve the absolute path to the node binary running the installer.
* Used as the runner for .js hooks so they execute in GUI/minimal-PATH
@@ -537,13 +565,17 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
* gives the absolute path of the node binary actively running the
* installer — that is the version the user just installed under, and
* the right default runtime for hooks invoked under the same install.
*
* When `process.execPath` is a versioned Homebrew Cellar path, the stable
* Homebrew symlink is returned instead to survive `brew upgrade node` (#3181).
*/
function resolveNodeRunner() {
const execPath = typeof process.execPath === 'string' ? process.execPath : '';
if (!execPath) return null;
const stablePath = normalizeNodePath(execPath);
// JSON.stringify produces a properly escaped double-quoted shell token,
// safe for paths containing spaces or unusual characters.
return JSON.stringify(execPath.replace(/\\/g, '/'));
return JSON.stringify(stablePath.replace(/\\/g, '/'));
}
/**
@@ -580,20 +612,49 @@ function rewriteLegacyManagedNodeHookCommands(settings, absoluteRunner) {
for (const h of entry.hooks) {
if (!h || typeof h.command !== 'string') continue;
const trimmed = h.command.trim();
// Match the EXACT legacy form: `node <script>` with optional quoting.
// Match two runner forms:
// 1. Legacy bare-node form: `node <script>` (#2979/#3002)
// 2. Cellar-path form: `"/usr/local/Cellar/node/<v>/bin/node" <script>`
// or `"/opt/homebrew/Cellar/node/<v>/bin/node" <script>` (#3181)
//
// Both patterns use the same script-token capture group so the rewrite
// is uniform. We detect the Cellar form by extracting the runner token
// and running it through normalizeNodePath.
//
// The previous shape used `trimmed.includes(<filename>)` which would
// false-positive on user-authored hooks whose path merely contained
// a managed filename as a substring (e.g.
// /home/me/scripts/wraps-gsd-check-update.js-and-more.js). #3002 CR.
const m = trimmed.match(/^node\s+("([^"]+)"|'([^']+)'|(\S+))\s*$/);
const m = trimmed.match(/^node\s+("([^"]+)"|'([^']+)'|(\S+))\s*$/) ||
trimmed.match(/^("([^"]+)"|'([^']+)'|(\S+))\s+("([^"]+)"|'([^']+)'|(\S+))\s*$/);
if (!m) continue;
const scriptToken = m[1];
const scriptPath = m[2] || m[3] || m[4] || '';
let runnerToken, scriptToken, scriptPath;
if (/^node\s+/.test(trimmed)) {
// bare-node form
runnerToken = 'node';
scriptToken = m[1];
scriptPath = m[2] || m[3] || m[4] || '';
} else {
// quoted/unquoted runner form — check whether runner is a Cellar path
runnerToken = m[1];
const runnerPath = (m[2] || m[3] || m[4] || '').replace(/\\/g, '/');
const stableRunner = normalizeNodePath(runnerPath);
// Only process if the runner IS a Cellar path that normalizes to something different
if (stableRunner === runnerPath) continue;
scriptToken = m[5];
scriptPath = m[6] || m[7] || m[8] || '';
}
// Take the basename — match against MANAGED_HOOK_FILES by exact
// equality, not substring containment. Handles both forward and
// backslash separators (Windows).
const scriptBase = scriptPath.split(/[\\/]/).pop() || '';
if (!MANAGED_HOOK_FILES.has(scriptBase)) continue;
// Skip if already using the desired stable runner
if (runnerToken !== 'node' && runnerToken === absoluteRunner) continue;
h.command = `${absoluteRunner} ${scriptToken}`;
changed = true;
}
@@ -9989,6 +10050,7 @@ if (process.env.GSD_TEST_MODE) {
parseUpdateBannerInput,
buildUpdateBannerHookEntry,
buildHookCommand,
normalizeNodePath,
resolveNodeRunner,
rewriteLegacyManagedNodeHookCommands,
buildCodexHookBlock,

254
tests/bug-3181-node-cellar-path.test.cjs Normal file
View File

@@ -0,0 +1,254 @@
'use strict';
process.env.GSD_TEST_MODE = '1';
/**
* Bug #3181: `resolveNodeRunner()` bakes versioned Homebrew Cellar paths
* (e.g. `/usr/local/Cellar/node/25.8.1/bin/node`) into hook commands in
* `~/.claude/settings.json`. After `brew upgrade node` the Cellar binary
* fails with `dyld: Library not loaded` because shared libraries have
* changed SOVERSION.
*
* Fix: prefer the stable Homebrew symlinks (`/usr/local/bin/node` for Intel
* Macs, `/opt/homebrew/bin/node` for Apple Silicon) when a Cellar path is
* detected. Non-Homebrew paths (NVM, system node, Windows, etc.) are
* returned unchanged.
*
* Also: `rewriteLegacyManagedNodeHookCommands()` must normalize Cellar paths
* baked into existing hook commands so reinstall doesn't re-bake them.
*
* All assertions go against exported function return values — no source-grep.
*/
const { test, describe } = require('node:test');
const assert = require('node:assert/strict');
const path = require('node:path');
const INSTALL = require(path.join(__dirname, '..', 'bin', 'install.js'));
const { normalizeNodePath, resolveNodeRunner, rewriteLegacyManagedNodeHookCommands } = INSTALL;
// ─── normalizeNodePath ────────────────────────────────────────────────────────
describe('Bug #3181: normalizeNodePath — exported as a function', () => {
test('normalizeNodePath is exported', () => {
assert.equal(typeof normalizeNodePath, 'function');
});
});
describe('Bug #3181: normalizeNodePath — Intel Homebrew Cellar paths → /usr/local/bin/node', () => {
test('simple versioned Intel Cellar path', () => {
const result = normalizeNodePath('/usr/local/Cellar/node/25.8.1/bin/node');
assert.equal(result, '/usr/local/bin/node');
});
test('Intel Cellar path with long semver', () => {
const result = normalizeNodePath('/usr/local/Cellar/node/20.11.0/bin/node');
assert.equal(result, '/usr/local/bin/node');
});
test('Intel Cellar path with prerelease version segment', () => {
const result = normalizeNodePath('/usr/local/Cellar/node/22.0.0-rc.1/bin/node');
assert.equal(result, '/usr/local/bin/node');
});
});
describe('Bug #3181: normalizeNodePath — Apple Silicon Homebrew Cellar paths → /opt/homebrew/bin/node', () => {
test('simple versioned Apple Silicon Cellar path', () => {
const result = normalizeNodePath('/opt/homebrew/Cellar/node/25.8.1/bin/node');
assert.equal(result, '/opt/homebrew/bin/node');
});
test('Apple Silicon Cellar path with another version', () => {
const result = normalizeNodePath('/opt/homebrew/Cellar/node/18.20.4/bin/node');
assert.equal(result, '/opt/homebrew/bin/node');
});
});
describe('Bug #3181: normalizeNodePath — non-Homebrew paths are returned unchanged', () => {
test('NVM path is unchanged', () => {
const nvm = '/Users/dev/.nvm/versions/node/v20.11.0/bin/node';
assert.equal(normalizeNodePath(nvm), nvm);
});
test('already-stable Intel Homebrew symlink is unchanged', () => {
assert.equal(normalizeNodePath('/usr/local/bin/node'), '/usr/local/bin/node');
});
test('already-stable Apple Silicon Homebrew symlink is unchanged', () => {
assert.equal(normalizeNodePath('/opt/homebrew/bin/node'), '/opt/homebrew/bin/node');
});
test('system node (/usr/bin/node) is unchanged', () => {
assert.equal(normalizeNodePath('/usr/bin/node'), '/usr/bin/node');
});
test('Windows path is unchanged', () => {
const win = 'C:\\Program Files\\nodejs\\node.exe';
assert.equal(normalizeNodePath(win), win);
});
test('empty string is returned as-is', () => {
assert.equal(normalizeNodePath(''), '');
});
test('null is returned as-is', () => {
assert.equal(normalizeNodePath(null), null);
});
});
// ─── resolveNodeRunner ────────────────────────────────────────────────────────
describe('Bug #3181: resolveNodeRunner — maps Cellar execPath to stable symlink', () => {
test('Intel Cellar execPath → stable symlink quoted token', () => {
const orig = process.execPath;
try {
Object.defineProperty(process, 'execPath', {
value: '/usr/local/Cellar/node/25.8.1/bin/node',
configurable: true,
});
const runner = resolveNodeRunner();
assert.equal(runner, '"/usr/local/bin/node"',
`expected stable Intel symlink, got: ${runner}`);
} finally {
Object.defineProperty(process, 'execPath', { value: orig, configurable: true });
}
});
test('Apple Silicon Cellar execPath → stable symlink quoted token', () => {
const orig = process.execPath;
try {
Object.defineProperty(process, 'execPath', {
value: '/opt/homebrew/Cellar/node/25.8.1/bin/node',
configurable: true,
});
const runner = resolveNodeRunner();
assert.equal(runner, '"/opt/homebrew/bin/node"',
`expected stable Apple Silicon symlink, got: ${runner}`);
} finally {
Object.defineProperty(process, 'execPath', { value: orig, configurable: true });
}
});
test('non-Homebrew execPath is returned as a quoted absolute path unchanged', () => {
const orig = process.execPath;
const nvmPath = '/Users/dev/.nvm/versions/node/v20.11.0/bin/node';
try {
Object.defineProperty(process, 'execPath', { value: nvmPath, configurable: true });
const runner = resolveNodeRunner();
assert.equal(runner, JSON.stringify(nvmPath));
} finally {
Object.defineProperty(process, 'execPath', { value: orig, configurable: true });
}
});
test('returns null when execPath is empty (existing null-guard is preserved)', () => {
const orig = process.execPath;
try {
Object.defineProperty(process, 'execPath', { value: '', configurable: true });
assert.equal(resolveNodeRunner(), null);
} finally {
Object.defineProperty(process, 'execPath', { value: orig, configurable: true });
}
});
});
// ─── rewriteLegacyManagedNodeHookCommands — Cellar runner rewrite ─────────────
describe('Bug #3181: rewriteLegacyManagedNodeHookCommands — rewrites baked Cellar runner to stable symlink', () => {
test('Intel Cellar runner in a managed hook is rewritten to the stable symlink', () => {
const settings = {
hooks: {
SessionStart: [{
hooks: [{
type: 'command',
command: '"/usr/local/Cellar/node/25.8.1/bin/node" "/Users/x/.gemini/hooks/gsd-check-update.js"',
}],
}],
},
};
const runner = '"/usr/local/bin/node"';
const changed = rewriteLegacyManagedNodeHookCommands(settings, runner);
assert.equal(changed, true, 'expected rewrite to occur');
assert.equal(
settings.hooks.SessionStart[0].hooks[0].command,
'"/usr/local/bin/node" "/Users/x/.gemini/hooks/gsd-check-update.js"',
);
});
test('Apple Silicon Cellar runner in a managed hook is rewritten to the stable symlink', () => {
const settings = {
hooks: {
SessionStart: [{
hooks: [{
type: 'command',
command: '"/opt/homebrew/Cellar/node/25.8.1/bin/node" "/Users/x/.gemini/hooks/gsd-check-update.js"',
}],
}],
},
};
const runner = '"/opt/homebrew/bin/node"';
const changed = rewriteLegacyManagedNodeHookCommands(settings, runner);
assert.equal(changed, true, 'expected rewrite to occur');
assert.equal(
settings.hooks.SessionStart[0].hooks[0].command,
'"/opt/homebrew/bin/node" "/Users/x/.gemini/hooks/gsd-check-update.js"',
);
});
test('a hook already using the stable runner is NOT rewritten (no churn)', () => {
const settings = {
hooks: {
SessionStart: [{
hooks: [{
type: 'command',
command: '"/usr/local/bin/node" "/Users/x/.gemini/hooks/gsd-check-update.js"',
}],
}],
},
};
const runner = '"/usr/local/bin/node"';
const before = settings.hooks.SessionStart[0].hooks[0].command;
const changed = rewriteLegacyManagedNodeHookCommands(settings, runner);
assert.equal(changed, false, 'already-stable entry must not be touched');
assert.equal(settings.hooks.SessionStart[0].hooks[0].command, before);
});
test('a user hook using a Cellar runner but an unmanaged filename is NOT rewritten', () => {
const settings = {
hooks: {
SessionStart: [{
hooks: [{
type: 'command',
command: '"/usr/local/Cellar/node/25.8.1/bin/node" "/Users/x/my-custom-hook.js"',
}],
}],
},
};
const runner = '"/usr/local/bin/node"';
const before = settings.hooks.SessionStart[0].hooks[0].command;
const changed = rewriteLegacyManagedNodeHookCommands(settings, runner);
assert.equal(changed, false, 'unmanaged hooks with Cellar runner must not be touched');
assert.equal(settings.hooks.SessionStart[0].hooks[0].command, before);
});
// Existing bare-node rewrite still works alongside the new Cellar rewrite
test('bare `node` managed hook is still rewritten (existing #2979 behaviour preserved)', () => {
const settings = {
hooks: {
SessionStart: [{
hooks: [{
type: 'command',
command: 'node "/Users/x/.gemini/hooks/gsd-check-update.js"',
}],
}],
},
};
const runner = '"/usr/local/bin/node"';
const changed = rewriteLegacyManagedNodeHookCommands(settings, runner);
assert.equal(changed, true);
assert.equal(
settings.hooks.SessionStart[0].hooks[0].command,
'"/usr/local/bin/node" "/Users/x/.gemini/hooks/gsd-check-update.js"',
);
});
});