Skip to content

fix: bridge colon-tainted bin paths so hoisted bins resolve in lifecycle scripts - #281

Open
shauryagangrade wants to merge 1 commit into
npm:mainfrom
shauryagangrade:fix/colon-bin-path-bridge
Open

fix: bridge colon-tainted bin paths so hoisted bins resolve in lifecycle scripts#281
shauryagangrade wants to merge 1 commit into
npm:mainfrom
shauryagangrade:fix/colon-bin-path-bridge

Conversation

@shauryagangrade

Copy link
Copy Markdown

Fixes npm/cli#9910

Problem

When any ancestor directory of a project contains the POSIX PATH delimiter
(: on unix), @npmcli/run-script builds a lifecycle-script PATH whose
node_modules/.bin entry contains an embedded :. The shell splits that
entry at the : into two bogus entries, so hoisted binaries like tsc
cannot be found (tsc: command not found, exit 127).

Repro (faithful to the issue):

parent:directory/
  mono-repo/
    node_modules/.bin/tsc -> ../typescript/bin/tsc

Running a workspace lifecycle script that calls tsc fails with exit 127.
Renaming the parent to parent-directory fixes it, confirming the PATH
delimiter collision as the root cause.

Why not a trivial fix

A : cannot be escaped inside a PATH entry on POSIX — there is no escaping
in PATH. The current code already knows about this (it emits Path contains delimiter ... may not behave as expected), but provides no workaround.

Approach: symlink bridge

Since a colon-containing dir cannot be put on PATH, present a colon-free
symlink mirror instead:

  1. For each colon-tainted node_modules dir, create
    <tmp>/npm-run-script-bridge-<uid>-<hash>/<nmhash>/node_modules as a
    symlink to the real node_modules.
  2. Put the mirrored .bin path on PATH instead of the real one.

We symlink node_modules itself (not .bin) because hoisted bin entries
resolve their real target relative to the .bin dir
($basedir/../<pkg>/...). Symlinking node_modules keeps that relative
resolution landing in the real project tree, so existing bins keep working.

Guards

  • POSIX only. Windows PATH delimiter is ; and drive letters (C:)
    contain : — the bridge would false-positive. Guarded on
    sep === '/' && delimiter === ':'.
  • Degrades to the existing warning when the tmpdir itself contains :.
  • No behavior change for colon-free projects (identity mapping).

Implementation

  • lib/bin-bridge.js (new): createBinBridge(projectPath, opts) returns a
    path-mapping function with lazy tmp-root creation, deterministic
    per-user/per-project hashing, 0700 perms, and a parallel-race guard.
  • lib/set-path.js: route both the binPaths entries and the walk-up
    node_modules/.bin entries through the bridge; only warn when a path is
    unbridgeable.

Tests

test/bin-bridge.js (new): unit tests for guards/identity/determinism plus
integration tests that execute a shim resolving relative to its new location
through the bridge, and setPATH-level assertions that the emitted PATH is
colon-free.

npm test passes (100% coverage, lint clean).

Changelog / semver

fix: → patch release, per CONTRIBUTING.md.

…cle scripts

When any ancestor directory of a project contains the POSIX PATH delimiter
(':' on unix), set-path would emit a node_modules/.bin entry with an
embedded ':' that the shell splits into two entries, so hoisted binaries
like tsc could not be found (exit 127).

Since a ':' cannot be escaped in a PATH entry, present a colon-free symlink
mirror instead: for each colon-containing node_modules dir, create a
node_modules symlink under a tmp root and put the mirrored .bin path on
PATH. Symlinking node_modules (not .bin) preserves the relative
/../<pkg> resolution used by bin shims.

POSIX-only (Windows PATH delimiter is ';' and drive letters contain ':').
Degrades to the existing warning when the tmpdir itself contains the
delimiter. No behavior change for colon-free projects.

Fixes npm/cli#9910
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] npm fails to find hoisted bin files in monorepo when parent directory path contains a ':' character

1 participant