Follow-up to #1660: PostToolUse hook still hardcodes `npx gitnexus` in 1.6.5 — proposed fix never shipped

[ProductOfAmerica]

Summary

#1660 (closed 2026-05-17) proposed using which gitnexus to detect a PATH-installed binary and prefer gitnexus over npx gitnexus in the PostToolUse stale-index hint. That fix never landed in the published package. gitnexus 1.6.5 ships with the same bare hardcode #1660 originally reported.

I can't reopen #1660 (no permissions), so filing this as a follow-up so the maintainer has a fresh thread.

Verbatim repro from a clean install

gitnexus@1.6.5 installed via Volta on Windows 11. The hook source at node_modules/gitnexus/hooks/claude/gitnexus-hook.cjs lines 339-344:

const analyzeCmd = `npx gitnexus analyze${hadEmbeddings ? ' --embeddings' : ''}`;
sendHookResponse(
  'PostToolUse',
  `GitNexus index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
    `Run \`${analyzeCmd}\` to update the knowledge graph.`,
);

No spawnSync('which', ...), no command -v, no PATH probe of any kind. Grep across the entire file:

$ grep -nE "which|command -v|onPath|analyzeBin" gitnexus-hook.cjs
$ # zero matches

Confirmed: the #1660 "fix" was either reverted, never merged, or merged into a different code path that doesn't ship to the installed hook.

Impact on Windows

Even if the proposed spawnSync('which', ['gitnexus']) had landed, which is a Unix command. On Windows it isn't installed by default — only available inside Git Bash / MSYS shims. The Node-side spawnSync('which', ...) call would return a non-zero status on stock Windows because which itself isn't found, falling through to the npx gitnexus branch every time even when the bare gitnexus IS on PATH.

So whenever this gets re-attempted, the fix needs to be cross-platform.

Proposed fix (cross-platform)

Option A — pure-Node existence check, no subprocess:

const which = (cmd) => {
  const exts = process.platform === 'win32'
    ? ['', '.cmd', '.bat', '.exe', '.ps1']
    : [''];
  const dirs = (process.env.PATH || '').split(path.delimiter);
  for (const dir of dirs) {
    for (const ext of exts) {
      try {
        if (fs.statSync(path.join(dir, cmd + ext)).isFile()) return true;
      } catch { /* not here, try next */ }
    }
  }
  return false;
};
const analyzeBin = which('gitnexus') ? 'gitnexus' : 'npx gitnexus';
const analyzeCmd = `${analyzeBin} analyze${hadEmbeddings ? ' --embeddings' : ''}`;

Option B — shell out, but with a platform-appropriate probe:

const probe = process.platform === 'win32' ? 'where' : 'command';
const args  = process.platform === 'win32' ? ['gitnexus'] : ['-v', 'gitnexus'];
const onPath = spawnSync(probe, args, { stdio: 'pipe' }).status === 0;
const analyzeBin = onPath ? 'gitnexus' : 'npx gitnexus';

Either resolves the gap on every supported OS. Option A is preferable — no subprocess overhead, no shell-environment dependency.

Why this is more than cosmetic

Same blast radius as #1660 — agents that follow the hint literally invoke npx gitnexus, bypassing user wrappers. And on this machine npx gitnexus hits the npm 11.x arborist null-target crash (see my companion follow-up to #819), so the hint sends users into a known-broken code path with no fallback.

Environment

• gitnexus: 1.6.5 (installed via volta install gitnexus@1.6.5)
• Hook file inspected: <volta>/tools/image/packages/gitnexus/node_modules/gitnexus/hooks/claude/gitnexus-hook.cjs
• Node: 24.13.0
• npm: 11.x
• OS: Windows 11
• Shell context: Claude Code

Cross-references

• PostToolUse hook hint hardcodes npx gitnexus, bypassing PATH-installed wrappers #1660 — original report + proposed fix (closed without shipping)
• companion follow-up to npx gitnexus analyze crashes with 'Cannot destructure property package of node.target as it is null' #819 — the npx-route crash that makes this hint actively harmful, not just suboptimal
• analyze re-emits npx gitnexus in SKILL templates + AGENTS.md/CLAUDE.md every run; clobbers projects that standardized on bare gitnexus #1663 — open umbrella for the related npx gitnexus hardcode in CLAUDE.md / SKILL.md generation

[magyargergo]

Fixed. The stale-index hint no longer hardcodes npx gitnexus:

• fix(cli): steer docs, skills, and hooks through a CLI-neutral project-local runner (#1939) #1945 (Follow-up to #819: npx gitnexus still crashes with "node.target is null" on npm 11.x — clean cache doesn't help #1939) routes all three hooks through formatAnalyzeCommand(), which prefers a PATH-installed gitnexus (step 1 of resolveInvocationMode), is cross-platform (where on Windows, not the Unix-only which), and — critically — avoids the npm-11 npx arborist crash by routing npm-11 boxes to pnpm dlx. Verified at runtime: global gitnexus on PATH → gitnexus analyze; npm 11 + pnpm, no global gitnexus → pnpm …dlx gitnexus@latest analyze (never bare npx).
• fix(hooks): resolve gitnexus on PATH with a pure-Node scan, all-OS (#1938) #1980 adds the last piece of your "Option A": a spawn-free PATH-scan fallback for when where/which itself is unreachable (sanitized PATH without System32 / a minimal container) but a global gitnexus is installed — so even then the hint prefers gitnexus analyze.

(#1958 proposed a hand-rolled fix but predated #1945 and would have regressed the npm-11 mitigation; closed as superseded.)

Resolved by #1945 (with #1980 hardening the edge case). Thanks for the precise, well-researched report.