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

[shauryagangrade]

Fixesnpm/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.

[shauryagangrade]

Fixesnpm/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.

[shauryagangrade]

Fixesnpm/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.

[shauryagangrade]

Fixesnpm/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.

[shauryagangrade]

Fixesnpm/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.

[shauryagangrade]

Fixesnpm/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.

[shauryagangrade]

Fixesnpm/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.

[shauryagangrade]

Fixesnpm/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.