npm install fails on Windows when Git Bash's GNU tar wins PATH (drive-letter mis-parsed as rsh host)

[ethan-n-m]

Summary

npm install -g @higgsfield/cli fails on Windows whenever Git for Windows is installed (i.e. nearly every developer machine), because the package's postinstall script shells out to tar and gets the wrong tar flavor off PATH.

The README lists npm as the cross-platform install path, so this is the documented Windows install flow.

I couldn't open a PR against this repo because install.js isn't tracked here (the public repo only contains install.sh, README.md, MODELS.md, LICENSE, demo.png). A ready-to-apply patch is included below for whoever maintains the npm publishing source.

Reproduction

On Windows 11 with Git for Windows installed (default PATH includes C:\Program Files\Git\usr\bin\tar.exe):

PS> npm install -g @higgsfield/cli
npm error code 1
npm error path C:\Users\<user>\AppData\Roaming\npm\node_modules\@higgsfield\cli
npm error command failed
npm error command C:\WINDOWS\system32\cmd.exe /d /s /c node install.js
npm error @higgsfield/cli: downloading https://github.com/higgsfield-ai/cli/releases/download/v0.1.28/hf_0.1.28_windows_amd64.tar.gz
npm error tar (child): Cannot connect to higgsfield\cli\vendor\hf_0.1.28_windows_amd64.tar.gz: resolve failed
npm error
npm error gzip: stdin: unexpected end of file
npm error tar: Child returned status 128
npm error tar: Error is not recoverable: exiting now
npm error @higgsfield/cli: install failed — Command failed: tar -xzf C:\Users\<user>\AppData\Roaming\npm\node_modules\@higgsfield\cli\vendor\hf_0.1.28_windows_amd64.tar.gz -C C:\Users\<user>\AppData\Roaming\npm\node_modules\@higgsfield\cli\vendor hf.exe

Versions tested: @higgsfield/cli@0.1.28, Node >=14, Windows 11 26200, Git for Windows 2.x (GNU tar 1.35).

Root cause

The current install.js extraction step:

execFileSync("tar", ["-xzf", tarballPath, "-C", vendorDir, binName]);

On Windows, tarballPath is an absolute path like C:\Users\...\vendor\hf_0.1.28_windows_amd64.tar.gz. Two tar binaries can resolve via PATH:

• GNU tar from Git Bash / MSYS at C:\Program Files\Git\usr\bin\tar.exe. Interprets the leading C: as an rsh-style host:path (a 1990s convention --force-local was added to disable). It tries to "connect" to host C with path \Users\..., which fails — and the diagnostic strips the C: prefix, producing the misleading "Cannot connect to higgsfield\cli\vendor\...: resolve failed" message.
• Windows-bundled bsdtar at C:\Windows\System32\tar.exe. Handles drive-letter paths natively. Bundled with Windows since Windows 10 build 17063 (April 2018).

Most Windows developer setups put Git's usr\bin ahead of System32 on PATH, so GNU tar wins and the install fails. The download itself is fine; only the extraction shell-out breaks. Which is why the error is so confusing — it looks network-shaped but isn't.

The shell installer (install.sh) is unaffected because it runs only on macOS/Linux, where paths are POSIX and there's no C: to mis-parse.

Proposed fix

On Windows, pin extraction to the OS-bundled bsdtar at %SystemRoot%\System32\tar.exe. macOS/Linux behavior is unchanged.

// On Windows, pin to the OS-bundled bsdtar (System32\tar.exe). If GNU tar
// from Git Bash / MSYS wins the PATH lookup it mis-parses `C:\` as an
// rsh-style `host:path` and fails with "Cannot connect to ...: resolve
// failed". bsdtar handles drive-letter paths natively.
function extractBinary(tarballPath, vendorDir, binName) {
  const tarBin =
    process.platform === "win32"
      ? path.join(process.env.SystemRoot || "C:\\Windows", "System32", "tar.exe")
      : "tar";
  execFileSync(tarBin, ["-xzf", tarballPath, "-C", vendorDir, binName]);
}

Then replace the inline execFileSync call in the install IIFE with extractBinary(tarballPath, vendorDir, binName);. Total diff: +12 / −1 lines, zero new dependencies.

Verification

Reproduced on Windows 11 + Git Bash + Node 22:

1. npm install -g @higgsfield/cli --ignore-scripts (installs metadata + bin shims).
2. Replace install.js with the patched version, wipe vendor/, run node install.js.
3. Output: @higgsfield/cli: downloading ... @higgsfield/cli: installed.
4. higgsfield --help prints the full command tree.

Pre-fix install fails with the error above on every Git-for-Windows machine; post-fix it completes cleanly.

Considered alternatives

• --force-local flag (smallest possible diff). Rejected: GNU-tar-specific, breaks on bsdtar (which is what macOS uses by default and what Windows ships in System32). Detecting tar flavor is its own rabbit hole.
• Replace shell-out with the tar npm package. Stronger long-term shape — eliminates platform branching entirely; the tar package is npm-team-maintained and ~50 KB. Trade-off is adding a runtime dependency. Happy to follow up with that approach if preferred over the System32 pin.

Compatibility

• process.env.SystemRoot is set on every supported Windows version; "C:\\Windows" fallback covers the (extremely unlikely) unset case.
• System32\tar.exe ships in Windows 10 build 17063+ (April 2018+).
• macOS / Linux paths through this function are byte-for-byte identical to before.

Happy to iterate on the patch, switch to the tar npm package approach, or open a PR if install.js gets mirrored to a public repo.