rs command collides with the pre-installed BSD rs (reshape) utility on macOS/BSD, causing a silent, CPU-idle hang #518

Environment

• rstack: 0.8.0
• Node.js: v24.21.0
• pnpm: 12.6.0
• OS: macOS 27
• Package manager mode: pnpm strict node_modules

Summary

On macOS and other BSD-derived operating systems (FreeBSD, NetBSD, OpenBSD), /usr/bin/rs is a standard pre-installed utility (BSD rs — "reshape a data array", part of the base system since 4.2BSD). When Rstack CLI's rs binary is not resolved first on $PATH (e.g. when typed directly in an interactive shell rather than invoked through a package.json script), the shell falls back to the OS-native /usr/bin/rs instead of node_modules/.bin/rs.

Steps to reproduce

1. In a project using rstack@0.8.0, open a plain shell (not through pnpm run <script>) and run:

rs check

2. The command hangs indefinitely with no output.
3. Ctrl+C exits with no error message.
4. Running npx rs check (which forces resolution to the local node_modules/.bin/rs) works correctly and completes.

Root cause

BSD's rs utility reads from standard input by default and blocks waiting for piped input when invoked with no valid input stream — this matches the observed symptoms exactly:

• Near-zero CPU usage during the hang (blocked on a read() call, not computing)
• No output before or after interruption
• Resolved entirely by forcing local binary resolution via npx/pnpm exec

Impact

This affects any BSD-derived OS (macOS included) where /usr/bin/rs precedes the project's node_modules/.bin in $PATH — which is the default shell behavior outside of npm/pnpm script execution contexts. Linux (GNU coreutils-based) is unaffected, as it has no native rs command.

Suggested fix

Since renaming the rs binary would be a breaking change, consider:

• Documenting the $PATH collision explicitly in the README, alongside a recommendation to invoke via pnpm exec rs / npx rs rather than a bare rs in interactive shells
• Optionally detecting this collision at runtime (e.g., checking which rs resolves to the expected package path) and warning the user

Related

This was discovered while investigating what first appeared to be an unrelated hang in rs check --type-check; see #519 for the original (now corrected) report.