fix(drivers): report a missing npm on Windows as missing, not as a failed install

RA
2h ago
+179-0

Issue for this PR

Closes #1789.

Type of change

  • Bug fix

What does this PR do?

On Windows, a missing npm gets the "npm is not available on PATH … Install Node.js, then run: …" message instead of cmd.exe's raw "'npm' is not recognized" text.

The driver install runs npm through the shell and picks the npm-missing message when the shell exits 127. cmd.exe exits 1 for a missing command, the same as a failed install, and prints its "is not recognized" line in the system's language. So on Windows a missing npm fell through to npm install failed (exit 1) for @databricks/sql: 'npm' is not recognized as an internal or external command, ….

Now, after a failed run on Windows, runNpm looks npm up the way cmd.exe does: the current directory (unless NoDefaultCurrentDirectoryInExePath is set), then each PATH entry (quotes removed, Path in any case) with each PATHEXT extension. If npm isn't there, the run counts as exit 127, and performInstall answers with the existing message and the Windows-quoted npm install --prefix "…" <packages>.

Claims:

  • C1: On Windows, when npm exits non-zero and npm is in neither the current directory (searched unless NoDefaultCurrentDirectoryInExePath is set, as cmd.exe does) nor any PATH entry under any PATHEXT extension, the install answers "npm is not available on PATH, so cannot be installed automatically. Install Node.js, then run: npm install --prefix ".
  • C2: On Windows, when npm is found there, a failed run keeps npm's exit code and output, as on main.
  • C3: Successful runs, timeouts (124), spawn errors (127) and every platform other than Windows behave as on main, and the lookup doesn't run for them.
  • C4: The lookup never throws. A PATH entry that is a file, or that can't be read, counts as not holding npm.

Residuals:

  • R1: The lookup follows cmd.exe's PATH and PATHEXT search. A PATH entry with an unexpanded %VAR% isn't expanded; if npm only resolves through such an entry, a failed install is reported as a missing npm.

How did you verify your code works?

  • Fail on main: the two runNpm tests that reach the 127 mapping (the cmd.exe exit, and the install message through the runNpm injection).
  • Real Windows: Windows 11 (10.0.26200) with Bun 1.3.14's Windows runtime, through cmd.exe, calling installOptionalDriver from main's and this branch's resolve.ts:
    • npm off PATH, main: npm install failed (exit 1) for @databricks/sql: 'npm' is not recognized as an internal or external command, ….
    • npm off PATH, this PR: npm is not available on PATH, so Databricks cannot be installed automatically. Install Node.js, then run: npm install --prefix "C:\Users\…\My Drivers ts-fix" @databricks/sql. The same answer when PATH also holds a file and a quoted directory.
    • That command, pasted into cmd.exe with npm on PATH, installs @databricks/sql.
    • With NoDefaultCurrentDirectoryInExePath set, cmd.exe stops running a .cmd from the current directory, which the lookup now mirrors.
    • npm on PATH: postgres installs. With an unreachable registry it answers npm's own ECONNREFUSED failure, also when npm's directory is a quoted PATH entry.
  • Local: packages/drivers tests 83 pass; typecheck clean for drivers and opencode.

Cost side effects

None.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR
  • I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"

🤖 Generated with Claude Code

https://claude.ai/code/session_01VEmKQu1Qn99YbrBzhKdtAr

Summary by CodeRabbit

  • Bug Fixes
    • Improved npm detection on Windows, including case-insensitive environment settings and standard command-search behavior.
    • When npm is unavailable on Windows, failures now report the appropriate “command not found” exit code instead of a generic failure code.
    • Missing-npm installation errors now include a shell-quoted command that can be copied for manual use.