From acb3cc974b334e1dfde83d4225f2487461117f4a Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Sun, 6 Sep 2026 14:09:32 -0400 Subject: [PATCH] fix(#4197): dedup the update-context fast path against the selected global dir (#4413) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(#4197): dedup the update-context fast path against the selected global candidate The preferredConfigDir fast path derived scope from a cwd-relative match alone, so a global install reported LOCAL whenever the shell sat in $HOME — and run_update then drove the installer through its --local arm (settings.local.json + the #338 relocation) against a global install. Extract resolveGlobalCandidate (env candidates first, then $HOME-relative, first hasInstall hit wins) and use it in BOTH paths: the fast path now answers LOCAL only for a cwd-relative match that is not the selected global dir, which is the same dedup the cascade applies at its isLocal check. A preferred dir that is also the env-directed global now answers GLOBAL on both paths (the cascade's answer), pinned by a parity test. The discriminator is the selected global candidate, not the $HOME pathname: with CLAUDE_CONFIG_DIR directing the global elsewhere, $HOME/.claude probed from cwd === $HOME is a genuine local install, and a pathname check would re-break parity (regression-pinned). * chore(#4197): add changeset * chore(#4197): backfill PR number in changeset --------- Co-authored-by: agent-4197 --- .changeset/bold-jaguars-parade.md | 5 ++ src/update-context.cts | 46 ++++++++++----- tests/update-context.test.cjs | 96 +++++++++++++++++++++++++++++++ 3 files changed, 133 insertions(+), 14 deletions(-) create mode 100644 .changeset/bold-jaguars-parade.md diff --git a/.changeset/bold-jaguars-parade.md b/.changeset/bold-jaguars-parade.md new file mode 100644 index 000000000..ca1bc696f --- /dev/null +++ b/.changeset/bold-jaguars-parade.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 4413 +--- +**`/gsd:update` no longer misreports a global install as LOCAL when the shell sits in $HOME** — running the update from a home-directory shell drove the installer's --local arm (settings.local.json + the #338 relocation) against a global install; the preferred-config-dir fast path now applies the same same-path dedup the rest of the detection cascade always has. (#4197) diff --git a/src/update-context.cts b/src/update-context.cts index 673f4e4ac..a8dcdb6f4 100644 --- a/src/update-context.cts +++ b/src/update-context.cts @@ -130,6 +130,27 @@ function preferFirst(entries: RuntimeDirEntry[], preferred: string): RuntimeDirE return [...pref, ...rest]; } +// GLOBAL probe: absolute env candidates first (in preferFirst order, first +// hasInstall hit wins), then $HOME-relative. Single resolver shared by the +// preferredConfigDir fast path's same-path dedup and the full cascade (#4197), +// so both compare against the global dir the resolution would actually select — +// an env-directed candidate, not necessarily the $HOME-relative pathname. +function resolveGlobalCandidate( + fs: FsAdapter, + env: Record, + home: string, + preferred: string, +): { runtime: string; dir: string } { + for (const [rt, absdir] of preferFirst(envRuntimeDirs({ env, home }), preferred)) { + if (hasInstall(fs, absdir)) return { runtime: rt, dir: path.resolve(absdir) }; + } + for (const [rt, reldir] of preferFirst(RUNTIME_DIRS, preferred)) { + const cand = path.resolve(home, reldir); + if (hasInstall(fs, cand)) return { runtime: rt, dir: cand }; + } + return { runtime: '', dir: '' }; +} + export interface ResolveUpdateContextOpts { home: string; cwd: string; @@ -164,9 +185,15 @@ export function resolveUpdateContext({ // Fast path: a validated preferredConfigDir (custom --config-dir install). if (preferredConfigDir && hasInstall(fs, preferredConfigDir)) { const resolvedPref = path.resolve(preferredConfigDir); + // Same-path dedup the cascade applies (#4197): a preferred dir that IS the + // selected global install (an env candidate or the $HOME-relative dir) is + // GLOBAL even when cwd === $HOME also makes it the cwd-relative match. + const { dir: globalDir } = resolveGlobalCandidate(fs, env, home, preferred); let scope: 'LOCAL' | 'GLOBAL' = 'GLOBAL'; - for (const [, reldir] of RUNTIME_DIRS) { - if (path.resolve(cwd, reldir) === resolvedPref) { scope = 'LOCAL'; break; } + if (resolvedPref !== globalDir) { + for (const [, reldir] of RUNTIME_DIRS) { + if (path.resolve(cwd, reldir) === resolvedPref) { scope = 'LOCAL'; break; } + } } return { installedVersion: trustedVersionAt(fs, preferredConfigDir) ?? '0.0.0', @@ -176,7 +203,6 @@ export function resolveUpdateContext({ }; } - const orderedEnv = preferFirst(envRuntimeDirs({ env, home }), preferred); const orderedRuntime = preferFirst(RUNTIME_DIRS, preferred); // LOCAL probe (relative to cwd). @@ -186,17 +212,9 @@ export function resolveUpdateContext({ if (hasInstall(fs, cand)) { localRuntime = rt; localDir = cand; break; } } - // GLOBAL probe: absolute env candidates first, then $HOME-relative. - let globalRuntime = '', globalDir = ''; - for (const [rt, absdir] of orderedEnv) { - if (hasInstall(fs, absdir)) { globalRuntime = rt; globalDir = path.resolve(absdir); break; } - } - if (!globalRuntime) { - for (const [rt, reldir] of orderedRuntime) { - const cand = path.resolve(home, reldir); - if (hasInstall(fs, cand)) { globalRuntime = rt; globalDir = cand; break; } - } - } + // GLOBAL probe: absolute env candidates first, then $HOME-relative — the + // same resolver the fast path dedups against. + const { runtime: globalRuntime, dir: globalDir } = resolveGlobalCandidate(fs, env, home, preferred); const localValid = trustedVersionAt(fs, localDir); const isLocal = !!localValid && (!globalDir || localDir !== globalDir); diff --git a/tests/update-context.test.cjs b/tests/update-context.test.cjs index 55535c8a4..04368346b 100644 --- a/tests/update-context.test.cjs +++ b/tests/update-context.test.cjs @@ -165,6 +165,102 @@ describe('resolveUpdateContext: runtime probing + env overrides', () => { }); }); +describe('resolveUpdateContext: preferredConfigDir fast-path dedup (#4197)', () => { + test('cwd === home does NOT misdetect as LOCAL on the preferredConfigDir fast path (dedup)', () => { + // #4197: the fast path derived scope from a cwd-relative match alone, so a + // global install probed with cwd === $HOME answered LOCAL. The cascade's + // same-path dedup (update.md: "local-over-global with same-path dedup (so + // CWD=$HOME does not misdetect as LOCAL)") must hold on the fast path too. + const fs = fakeFs({ [ver(`${HOME}/.claude`)]: '1.40.0\n', [marker(`${HOME}/.claude`)]: 'x' }); + const r = resolveUpdateContext({ + home: HOME, cwd: HOME, env: {}, fs, + preferredConfigDir: `${HOME}/.claude`, preferredRuntime: 'claude', + }); + assert.equal(r.scope, 'GLOBAL'); + }); + + test('same global install resolves identically from home and elsewhere on the fast path', () => { + const fs = fakeFs({ [ver(`${HOME}/.claude`)]: '1.40.0\n', [marker(`${HOME}/.claude`)]: 'x' }); + const inputs = { + home: HOME, env: {}, fs, + preferredConfigDir: `${HOME}/.claude`, preferredRuntime: 'claude', + }; + const fromElsewhere = resolveUpdateContext({ ...inputs, cwd: CWD }); + assert.equal(fromElsewhere.scope, 'GLOBAL'); + assert.deepEqual( + resolveUpdateContext({ ...inputs, cwd: HOME }), + fromElsewhere, + 'scope must not depend on which directory the shell is sitting in', + ); + }); + + test('genuine project-local install stays LOCAL on the fast path', () => { + // Control: the dedup must not over-correct into GLOBAL-always. A preferred + // dir that is the cwd-relative install and NOT the selected global is LOCAL. + const fs = fakeFs({ [ver(`${CWD}/.claude`)]: '1.39.0\n', [marker(`${CWD}/.claude`)]: 'x' }); + const r = resolveUpdateContext({ + home: HOME, cwd: CWD, env: {}, fs, + preferredConfigDir: `${CWD}/.claude`, preferredRuntime: 'claude', + }); + assert.equal(r.scope, 'LOCAL'); + assert.equal(r.installedVersion, '1.39.0'); + assert.ok(sameDir(r.gsdDir, `${CWD}/.claude`), `gsdDir was ${r.gsdDir}`); + }); + + test('genuine project-local install stays LOCAL even with a global install also present', () => { + const fs = fakeFs({ + [ver(`${CWD}/.claude`)]: '1.39.0\n', [marker(`${CWD}/.claude`)]: 'x', + [ver(`${HOME}/.claude`)]: '1.40.0\n', [marker(`${HOME}/.claude`)]: 'x', + }); + const r = resolveUpdateContext({ + home: HOME, cwd: CWD, env: {}, fs, + preferredConfigDir: `${CWD}/.claude`, preferredRuntime: 'claude', + }); + assert.equal(r.scope, 'LOCAL'); + assert.equal(r.installedVersion, '1.39.0'); + }); + + test('env-directed global elsewhere: $HOME/.claude is LOCAL and the fast path agrees with the cascade', () => { + // The dedup must compare against the SELECTED global candidate (env-ranked), + // not the $HOME pathname: with CLAUDE_CONFIG_DIR pointing the global at + // /opt/claude-global, $HOME/.claude probed from cwd === $HOME is a genuine + // cwd-local install, and the cascade already answers LOCAL for it. + const custom = '/opt/claude-global'; + const fs = fakeFs({ + [ver(`${HOME}/.claude`)]: '1.39.0\n', [marker(`${HOME}/.claude`)]: 'x', + [ver(custom)]: '1.40.0\n', [marker(custom)]: 'x', + }); + const env = { CLAUDE_CONFIG_DIR: custom }; + const cascade = resolveUpdateContext({ home: HOME, cwd: HOME, env, fs }); + const fast = resolveUpdateContext({ + home: HOME, cwd: HOME, env, fs, + preferredConfigDir: `${HOME}/.claude`, preferredRuntime: 'claude', + }); + assert.equal(cascade.scope, 'LOCAL'); + assert.equal(fast.scope, cascade.scope); + assert.equal(fast.installedVersion, cascade.installedVersion); + assert.equal(fast.runtime, cascade.runtime); + assert.ok(sameDir(fast.gsdDir, cascade.gsdDir), `fast gsdDir ${fast.gsdDir} vs cascade ${cascade.gsdDir}`); + }); + + test('env candidate IS the preferred dir: fast path answers GLOBAL, matching the cascade', () => { + // A preferred dir that is also the env-directed global is the selected + // global — the cascade answers GLOBAL, and the fast path must agree. + const fs = fakeFs({ [ver(`${HOME}/.claude`)]: '1.40.0\n', [marker(`${HOME}/.claude`)]: 'x' }); + const env = { CLAUDE_CONFIG_DIR: `${HOME}/.claude` }; + const cascade = resolveUpdateContext({ home: HOME, cwd: HOME, env, fs }); + const fast = resolveUpdateContext({ + home: HOME, cwd: HOME, env, fs, + preferredConfigDir: `${HOME}/.claude`, preferredRuntime: 'claude', + }); + assert.equal(cascade.scope, 'GLOBAL'); + assert.equal(fast.scope, cascade.scope); + assert.equal(fast.installedVersion, cascade.installedVersion); + assert.equal(fast.runtime, cascade.runtime); + assert.ok(sameDir(fast.gsdDir, cascade.gsdDir), `fast gsdDir ${fast.gsdDir} vs cascade ${cascade.gsdDir}`); + }); +}); + describe('gsd-tools update-context (CLI): emits the JSON contract', () => { test('--config-dir fixture resolves to the documented 4-field JSON', () => { const tmp = nodeFs.mkdtempSync(path.join(os.tmpdir(), 'gsd-uc-'));