Say which git-fi runs, and how to replace a token

[chris-peterson]

Context

git-fi shipped as a Ruby gem until 0.9.x and now ships on npm. A user migrating across deleted the gem's files by hand, which left RubyGems' launcher in Ruby's bin — earlier on PATH than npm's prefix. git fi kept reaching that dead launcher while the npm install sat behind it, complete and unreachable, and nothing could say so: the copy that would notice is the copy not being run. Separately, an expired GITLAB_ACCESS_TOKEN returned a 401 whose only offered remedy was turning CI status off.

A requirement for each (INSTALL-01, AUTH-13), plus the Windows CI that made the first designable.

Review guide

Tier 1 — the new behavior

• src/which.ts — shadowingLauncher is the idea: resolve git-fi on PATH, compare it to the copy running, return the winner only when they differ. isSameInstall is worth a second look.
• warnIfShadowed — the npx branch, which is what makes the feature reachable when git fi is shadowed. See Approach.
• src/index.ts — the only call site. --version, nothing else, on stderr so stdout stays a bare version string.
• src/gitlab.ts — rejectedTokenMessage. AUTH-10 already built the prefilled token form for --auth=login; this puts it on the 401, sharing REQUIRED_SCOPE so the prose and the URL can't disagree.
• src/style.ts — hintsOptedOut. This notice wants the explicit switch without the ambient suppressions, since it answers a question just asked.

Tier 2 — the CI that proves it

• .github/workflows/ci.yml — two Windows jobs. One plants a leftover launcher; windows-leftover-gem installs a gem shaped like git-fi's predecessor with --no-wrappers, then deletes its files by hand. Both check git fi has actually stopped working before asserting what the notice says.

Tier 3 — a correctness fix the cleanup pass introduced

• src/git.ts — git symbolic-ref exits 0 on a pruned target, and basename truncates a default branch containing /. Either way %(ahead-behind:) is fatal, so a repo whose default branch was renamed couldn't list branches at all. Now resolved before use, with tests for both states.

Tier 4 — consolidation, spec, docs

• src/branches.ts — localBranchName / resolveBranchName in a module importing nothing, so the rendering and --json layers can strip an origin/ prefix without pulling in the one that spawns subprocesses. Every call site uses it now.
• src/gitlab.ts and src/json.ts — both branch tables built the Branch column the same four ways, and both --json writers built their own envelope while only one waited for the bytes to reach the OS. One branchLabel, one writeJson.
• package.json — the git floor was spelled out in two files; it's engines.git now, read by preflightChecks and the postinstall, since npm records the field but enforces only node. A test pins the range's shape: anything but >=x.y.z makes ordinal return NaN and silently stops the floor applying.
• SPEC.md INSTALL-01 and AUTH-13; STORAGE regains the heading the prefix rename dropped, which had left two links pointing at anchors that no longer existed.
• docs/quickstart.md — migration callout, instructions only. STATUS.md — ledger 132 → 134, all Covered.

Approach & trade-offs

Which launcher is in the way was measured, because both tools you'd check with disagree with git. git fi resolves to git-fi.exe, else the extensionless git-fi, and nothing else — a stale .cmd, .bat or .ps1 ahead of npm's prefix leaves it working. But PowerShell runs the .ps1 and where.exe lists the .cmd, so launcherNames searching PATHEXT named files in nobody's way. That is also why the reporter got nowhere: PowerShell can't execute an extensionless file, so Get-Command skipped the leftover Ruby launcher entirely and named npm's .ps1, while git fi was running the Ruby one.

Whether a launcher is reachable is a different question per platform. gem install --no-wrappers links its executables into Ruby's bin, so removing the gem's files leaves dangling links. Windows git stops at one and dies; POSIX git skips it for the next PATH entry. So the test is the directory entry on Windows and X_OK on POSIX, which also covers a missing execute bit. Asking whether the path exists follows the link, and so was blind to exactly the reported state.

Under npx the notice states a fact rather than a verdict. npx is the route out of a shadowed install, and it didn't work: npx prepends its own cache to PATH, so the walk matched git-fi's own launcher and reported nothing. The walk now skips node_modules/.bin directories, which a shell never has. That alone was worse than silence — the copy answering is a throwaway, so the user's real install reads as a different copy and gets named as the culprit. So npx names the launcher PATH resolves and stops.

Install identity is the launcher's target resolving to the copy answering, not a package-name match. Two npm prefixes (an nvm/fnm switch) each hold a launcher naming this package, so a name match would suppress the notice in the case it exists for.

The check is not in the installer, where it was first proposed. On npm 11 install scripts are blocked by default, so a global install skips postinstall entirely unless the package is in allowScripts — observed on a user's machine this week. That also stops PRE-06's install-time floor and COMPLETE-07's completion files running at all; PRE-02 still enforces the floor at first use. Both need their own fix, outside this branch.

Testing

226 green on both platforms — 29 tests for INSTALL-01, 8 for AUTH-13, 2 for the default-branch resolution, 2 for the git floor.

Naming order is asserted from any host by passing the platform in, since which names to look for is a pure string decision. Reachability is not: the platform argument picks the rule, but X_OK is answered by the host's filesystem, so those cases are gated to where the rule is real.

Validation

What	Evidence
The diagnosis	Get-Command git-fi returned C:\tools\ruby33\bin\git-fi; deleting it made git fi resolve to npm's copy.
The token path	A new PAT from the linked form restored CI status. That link is what AUTH-13 now puts in the error.
Launcher resolution	A throwaway Windows job planted each shim shape ahead of npm's prefix and asked git fi which it ran: .exe and bare only, .cmd / .bat / .ps1 never.
The leftover gem	windows-leftover-gem confirms --no-wrappers symlinks three executables into Ruby's bin, and that deleting the gem's files leaves git fi dying on a dangling link.
npx	Against a packed tarball with a stale launcher ahead: silent before, names the leftover now, and names the real install when nothing is wrong.
The default-branch crash	Reproduced in a throwaway repo; both new tests fail against the unfixed code and pass against the fix.