node-version-use 2.4.0 → 2.4.1

package/README.md

@@ -1,140 +1,117 @@
 ## node-version-use
 
-Cross-platform solution for using multiple versions of Node.js. Useful for compatibility testing and transparent version switching.
+Cross-platform solution for using multiple versions of Node.js. Transparent version switching via command interception.
 
 ### Installation
 
 ```bash
 npm install -g node-version-use
+export PATH="$HOME/.nvu/bin:$PATH"  # Add to shell profile
 ```
 
-On install, nvu automatically downloads platform-specific binaries to `~/.nvu/bin/`. To enable transparent Node version switching, add to your shell profile:
+### Quick Start
 
 ```bash
-# For bash (~/.bashrc) or zsh (~/.zshrc):
-export PATH="$HOME/.nvu/bin:$PATH"
-
-# For fish (~/.config/fish/config.fish):
-set -gx PATH $HOME/.nvu/bin $PATH
+nvu default 20           # Set global default
+nvu local 18             # Set project version (.nvmrc)
+node --version           # Uses v20 (or v18 in project)
 ```
 
-### Quick Start
+### Commands
 
-```bash
-# Set a global default Node version
-nvu default 20
+```
+nvu default 20           # Global default
+nvu default system       # Use system Node
+nvu local 18             # Project version (.nvmrc)
+nvu install 22           # Install Node
+nvu uninstall 22         # Uninstall Node
+nvu list                 # List installed
+nvu 22 npm run test      # Run with specific version
+```
 
-# Or set a project-specific version (creates .nvmrc)
-nvu local 18
+### How It Works
 
-# Now 'node' and 'npm' use the configured version automatically
-node --version  # v20.x.x (or v18.x.x in project directory)
+```
+~/.nvu/bin/              # Go binary shims (node, npm, npx, nvu, ...)
+  ↓
+~/.nvu/default          # Contains "22", "20", or "system"
+  ↓
+~/.nvu/installed/v22/   # Real Node.js installation
+  └── bin/node          # Actual Node binary
 ```
 
-### Commands
-
-#### Version Management
+**Key design decisions:**
 
-```bash
-# Set global default version
-nvu default 20
+1. **Strict routing** - Each command routes to exactly one version (the default)
+2. **npm compatibility** - Uses `npm_config_prefix` so npm behaves normally
+3. **System escape hatch** - `nvu system npm ...` bypasses version routing
+4. **Version-specific packages** - Global npm packages live in the version's directory
 
-# Set local version for current directory (creates .nvmrc)
-nvu local 18
+### Frequently Asked Questions
 
-# Install a Node version
-nvu install 22
+#### How do I reinstall nvu if it's missing?
 
-# Uninstall a Node version
-nvu uninstall 22
+```bash
+nvu system npm install -g node-version-use
+```
 
-# List installed versions
-nvu list
+This bypasses version routing entirely.
 
-# Show which version would be used
-nvu which
-```
+#### Are global npm packages shared across versions?
 
-#### Binary Management
+No. Each Node version has its own `lib/node_modules/`. Install separately:
 
 ```bash
-# Install/reinstall binaries
-nvu setup
-
-# Remove binaries
-nvu teardown
+nvu 22 npm install -g some-package
+nvu 20 npm install -g some-package
 ```
 
-#### Run Commands with Specific Versions
+#### Can I use system Node?
 
 ```bash
-# Run with a specific version
-nvu 14.4.0 npm run test
-
-# Run with highest matching major version
-nvu 12 npm run test
+nvu default system
+```
 
-# Run with LTS version
-nvu lts npm run test
+Routes all commands to system binaries via PATH.
 
-# Run with multiple versions (comma-delimited)
-nvu 0.8,4,8,14 npm run test
+#### Why not search all installed versions for binaries?
 
-# Run with version expression
-nvu >=0.8 node --version
+Explicit is better than implicit. You know exactly which version runs. Use `nvu <version> <command>` for specific versions.
 
-# Use engines.node from package.json
-nvu engines node --version
-```
+### How nvu Differs from Other Version Managers
 
-### How It Works
+| Feature | nvu | nvm | Volta |
+|---------|-----|-----|-------|
+| Command routing | Go binary shim | Shell function | npm shim |
+| Default version | Global or per-project | Global | Per-project (package.json) |
+| Global packages | Version-specific | Shared (via symlinks) | Pin to version |
+| System Node | `nvu default system` | `nvm use system` | `volta off` |
+| Recovery when broken | `nvu system npm ...` | Reinstall nvm | Reinstall volta |
 
-nvu uses lightweight binaries that intercept `node`, `npm`, and `npx` commands. When you run `node`, the binary:
+**nvu** uses a single Go binary that intercepts commands. Simple, predictable routing.
 
-1. Checks for `.nvurc` in current/parent directories
-2. Checks for `.nvmrc` in current/parent directories
-3. Falls back to `~/.nvu/default`
-4. Executes the matching installed Node version
+**nvm** is a shell function that changes `$NODE_HOME` environment variable.
 
-This works in all contexts: terminals, IDEs, CI, scripts - without shell integration.
-
-### Version Resolution
-
-The binary resolves partial versions to installed versions:
-- `20` matches `v20.19.6`
-- `18.19` matches `v18.19.0`
-- `v22` matches `v22.0.0`
+**Volta** pins packages to specific Node versions in package.json and uses npm shims.
 
 ### JavaScript API
 
 ```javascript
 const nvu = require('node-version-use');
-
-// Run with callback
-nvu('>=0.8', 'node', ['--version'], { versions: '12', stdio: 'inherit' }, (err, results) => {
-  // results is an array per-version of form {version, error, result}
-});
-
-// Run with async/await
-const results = await nvu('engines', 'node', ['--version'], { stdio: 'inherit' });
+const results = await nvu('>=0.8', 'node', ['--version'], { stdio: 'inherit' });
 ```
 
-### Uninstalling
+### Uninstall
 
 ```bash
-# Remove binaries
-nvu teardown
-
-# Optionally remove all nvu data
-rm -rf ~/.nvu
+nvu teardown           # Remove ~/.nvu/bin
+rm -rf ~/.nvu          # Remove all data
 ```
 
-Then remove the PATH line from your shell profile.
-
 ### Compatibility
 
 - macOS (arm64, x64)
 - Linux (arm64, x64)
 - Windows (arm64, x64)
 
-Compatible with `.nvmrc` files from nvm, fnm, and other version managers.
+Compatible with `.nvmrc` files from nvm, fnm, and other tools.

package/assets/installBinaries.cjs

@@ -37,21 +37,24 @@ function removeIfExistsSync(filePath) {
     }
 }
 /**
- * On Windows, rename a file out of the way instead of deleting.
- * This works even if the file is currently running.
+ * Move a file out of the way (works even if running on Windows)
+ * First tries to unlink; if that fails (Windows locked), rename to .old-timestamp
  */ function moveOutOfWay(filePath) {
     if (!fs.existsSync(filePath)) return;
+    // First try to unlink (works on Unix, fails on Windows if running)
+    try {
+        fs.unlinkSync(filePath);
+        return;
+    } catch (_e) {
+    // Unlink failed (likely Windows locked file), try rename
+    }
+    // Rename to .old-timestamp as fallback
     var timestamp = Date.now();
     var oldPath = "".concat(filePath, ".old-").concat(timestamp);
     try {
         fs.renameSync(filePath, oldPath);
-    } catch (_e) {
-        // If rename fails, try delete as fallback (works on Unix)
-        try {
-            fs.unlinkSync(filePath);
-        } catch (_e2) {
-        // ignore - will fail on atomic rename instead
-        }
+    } catch (_e2) {
+    // Both unlink and rename failed - will fail on atomic rename instead
     }
 }
 /**
@@ -114,6 +117,55 @@ function removeIfExistsSync(filePath) {
     var content = fs.readFileSync(src);
     fs.writeFileSync(dest, content);
 }
+/**
+ * Sync all shims by copying the nvu binary to all other files in the bin directory
+ * All shims (node, npm, npx, corepack, eslint, etc.) are copies of the same binary
+ */ module.exports.syncAllShims = function syncAllShims(binDir) {
+    var isWindows = process.platform === 'win32' || /^(msys|cygwin)$/.test(process.env.OSTYPE);
+    var ext = isWindows ? '.exe' : '';
+    // Source: nvu binary
+    var nvuSource = path.join(binDir, "nvu".concat(ext));
+    if (!fs.existsSync(nvuSource)) return;
+    try {
+        var entries = fs.readdirSync(binDir);
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = entries[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var name = _step.value;
+                // Skip nvu itself and nvu.json
+                if (name === "nvu".concat(ext) || name === 'nvu.json') continue;
+                // On Windows, only process .exe files
+                if (isWindows && !name.endsWith('.exe')) continue;
+                var shimPath = path.join(binDir, name);
+                var stat = fs.statSync(shimPath);
+                if (!stat.isFile()) continue;
+                // Move existing file out of the way (Windows compatibility)
+                moveOutOfWay(shimPath);
+                // Copy nvu binary to shim
+                copyFileSync(nvuSource, shimPath);
+                // Make executable on Unix
+                if (!isWindows) {
+                    fs.chmodSync(shimPath, 493);
+                }
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+    } catch (_e) {
+    // Ignore errors - shim sync is best effort
+    }
+};
 /**
  * Atomic rename with fallback to copy+delete for cross-device moves
  */ function atomicRename(src, dest, callback) {
@@ -296,38 +348,63 @@ function removeIfExistsSync(filePath) {
     }
     var extractedBinaryName = "".concat(archiveBaseName).concat(isWindows ? '.exe' : '');
     var binDir = path.join(storagePath, 'bin');
+    var nvuJsonPath = path.join(binDir, 'nvu.json');
     // check if we need to upgrade
     if (!options.force) {
         try {
-            // already installed
-            if (fs.statSync(binDir)) {
-                if (fs.readFileSync(path.join(binDir, 'version.txt'), 'utf8') === BINARY_VERSION) {
-                    callback(null, false);
-                    return;
-                }
+            // already installed - read nvu.json
+            var nvuJson = JSON.parse(fs.readFileSync(nvuJsonPath, 'utf8'));
+            if (nvuJson.binaryVersion === BINARY_VERSION) {
+                callback(null, false);
+                return;
             }
         } catch (_err) {}
     }
     // Create directories
     mkdirp.sync(storagePath);
     mkdirp.sync(binDir);
+    mkdirp.sync(path.join(storagePath, 'cache'));
     // Clean up old .old-* files from previous installs
     cleanupOldFiles(binDir);
     var downloadUrl = "https://github.com/".concat(GITHUB_REPO, "/releases/download/binary-v").concat(BINARY_VERSION, "/").concat(archiveBaseName).concat(isWindows ? '.zip' : '.tar.gz');
-    var tempPath = path.join(tmpdir(), "nvu-binary-".concat(Date.now()).concat(isWindows ? '.zip' : '.tar.gz'));
+    var cachePath = path.join(storagePath, 'cache', "".concat(archiveBaseName).concat(isWindows ? '.zip' : '.tar.gz'));
+    // Check cache first
+    if (fs.existsSync(cachePath)) {
+        console.log('Using cached binary...');
+        // Use cached file
+        extractAndInstall(cachePath, binDir, extractedBinaryName, function(err) {
+            if (err) return callback(err);
+            // save binary version for upgrade checks
+            fs.writeFileSync(nvuJsonPath, JSON.stringify({
+                binaryVersion: BINARY_VERSION
+            }, null, 2), 'utf8');
+            console.log('Binary installed successfully!');
+            callback(null, true);
+        });
+        return;
+    }
+    // Download to temp file
     console.log("Downloading binary for ".concat(process.platform, "-").concat(process.arch, "..."));
+    var tempPath = path.join(tmpdir(), "nvu-binary-".concat(Date.now()).concat(isWindows ? '.zip' : '.tar.gz'));
     getFile(downloadUrl, tempPath, function(err) {
         if (err) {
             removeIfExistsSync(tempPath);
             callback(new Error("No prebuilt binary available for ".concat(process.platform, "-").concat(process.arch, ". Download: ").concat(downloadUrl, ". Error: ").concat(err.message)));
             return;
         }
-        console.log('Extracting binary...');
+        // Copy to cache for future use
+        try {
+            copyFileSync(tempPath, cachePath);
+        } catch (_e) {
+        // Cache write failed, continue anyway
+        }
         extractAndInstall(tempPath, binDir, extractedBinaryName, function(err) {
             removeIfExistsSync(tempPath);
             if (err) return callback(err);
             // save binary version for upgrade checks
-            fs.writeFileSync(path.join(binDir, 'version.txt'), BINARY_VERSION, 'utf8');
+            fs.writeFileSync(nvuJsonPath, JSON.stringify({
+                binaryVersion: BINARY_VERSION
+            }, null, 2), 'utf8');
             console.log('Binary installed successfully!');
             callback(null, true);
         });

package/assets/postinstall.cjs

@@ -10,7 +10,17 @@
  * 2. Extract to temp directory
  * 3. Atomic rename to final location
  */ var exit = require('exit-compat');
-var _require = require('./installBinaries.cjs'), installBinaries = _require.installBinaries, printInstructions = _require.printInstructions;
+var path = require('path');
+var os = require('os');
+var _require = require('./installBinaries.cjs'), installBinaries = _require.installBinaries, printInstructions = _require.printInstructions, syncAllShims = _require.syncAllShims;
+var hasHomedir = typeof os.homedir === 'function';
+function homedir() {
+    if (hasHomedir) return os.homedir();
+    var home = require('homedir-polyfill');
+    return home();
+}
+// Allow NVU_HOME override for testing
+var storagePath = process.env.NVU_HOME || path.join(homedir(), '.nvu');
 /**
  * Main installation function
  */ function main() {
@@ -22,8 +32,13 @@ var _require = require('./installBinaries.cjs'), installBinaries = _require.inst
             return;
         }
         if (installed) {
+            // Sync all shims to the new binary version
+            var binDir = path.join(storagePath, 'bin');
+            syncAllShims(binDir);
             printInstructions();
             console.log('postinstall: Binary installed successfully!');
+        } else {
+            console.log('postinstall: Binaries already up to date.');
         }
         exit(0);
     });

package/dist/cjs/assets/installBinaries.cjs

@@ -37,21 +37,24 @@ function removeIfExistsSync(filePath) {
     }
 }
 /**
- * On Windows, rename a file out of the way instead of deleting.
- * This works even if the file is currently running.
+ * Move a file out of the way (works even if running on Windows)
+ * First tries to unlink; if that fails (Windows locked), rename to .old-timestamp
  */ function moveOutOfWay(filePath) {
     if (!fs.existsSync(filePath)) return;
+    // First try to unlink (works on Unix, fails on Windows if running)
+    try {
+        fs.unlinkSync(filePath);
+        return;
+    } catch (_e) {
+    // Unlink failed (likely Windows locked file), try rename
+    }
+    // Rename to .old-timestamp as fallback
     var timestamp = Date.now();
     var oldPath = "".concat(filePath, ".old-").concat(timestamp);
     try {
         fs.renameSync(filePath, oldPath);
-    } catch (_e) {
-        // If rename fails, try delete as fallback (works on Unix)
-        try {
-            fs.unlinkSync(filePath);
-        } catch (_e2) {
-        // ignore - will fail on atomic rename instead
-        }
+    } catch (_e2) {
+    // Both unlink and rename failed - will fail on atomic rename instead
     }
 }
 /**
@@ -114,6 +117,55 @@ function removeIfExistsSync(filePath) {
     var content = fs.readFileSync(src);
     fs.writeFileSync(dest, content);
 }
+/**
+ * Sync all shims by copying the nvu binary to all other files in the bin directory
+ * All shims (node, npm, npx, corepack, eslint, etc.) are copies of the same binary
+ */ module.exports.syncAllShims = function syncAllShims(binDir) {
+    var isWindows = process.platform === 'win32' || /^(msys|cygwin)$/.test(process.env.OSTYPE);
+    var ext = isWindows ? '.exe' : '';
+    // Source: nvu binary
+    var nvuSource = path.join(binDir, "nvu".concat(ext));
+    if (!fs.existsSync(nvuSource)) return;
+    try {
+        var entries = fs.readdirSync(binDir);
+        var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+        try {
+            for(var _iterator = entries[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                var name = _step.value;
+                // Skip nvu itself and nvu.json
+                if (name === "nvu".concat(ext) || name === 'nvu.json') continue;
+                // On Windows, only process .exe files
+                if (isWindows && !name.endsWith('.exe')) continue;
+                var shimPath = path.join(binDir, name);
+                var stat = fs.statSync(shimPath);
+                if (!stat.isFile()) continue;
+                // Move existing file out of the way (Windows compatibility)
+                moveOutOfWay(shimPath);
+                // Copy nvu binary to shim
+                copyFileSync(nvuSource, shimPath);
+                // Make executable on Unix
+                if (!isWindows) {
+                    fs.chmodSync(shimPath, 493);
+                }
+            }
+        } catch (err) {
+            _didIteratorError = true;
+            _iteratorError = err;
+        } finally{
+            try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                    _iterator.return();
+                }
+            } finally{
+                if (_didIteratorError) {
+                    throw _iteratorError;
+                }
+            }
+        }
+    } catch (_e) {
+    // Ignore errors - shim sync is best effort
+    }
+};
 /**
  * Atomic rename with fallback to copy+delete for cross-device moves
  */ function atomicRename(src, dest, callback) {
@@ -296,38 +348,63 @@ function removeIfExistsSync(filePath) {
     }
     var extractedBinaryName = "".concat(archiveBaseName).concat(isWindows ? '.exe' : '');
     var binDir = path.join(storagePath, 'bin');
+    var nvuJsonPath = path.join(binDir, 'nvu.json');
     // check if we need to upgrade
     if (!options.force) {
         try {
-            // already installed
-            if (fs.statSync(binDir)) {
-                if (fs.readFileSync(path.join(binDir, 'version.txt'), 'utf8') === BINARY_VERSION) {
-                    callback(null, false);
-                    return;
-                }
+            // already installed - read nvu.json
+            var nvuJson = JSON.parse(fs.readFileSync(nvuJsonPath, 'utf8'));
+            if (nvuJson.binaryVersion === BINARY_VERSION) {
+                callback(null, false);
+                return;
             }
         } catch (_err) {}
     }
     // Create directories
     mkdirp.sync(storagePath);
     mkdirp.sync(binDir);
+    mkdirp.sync(path.join(storagePath, 'cache'));
     // Clean up old .old-* files from previous installs
     cleanupOldFiles(binDir);
     var downloadUrl = "https://github.com/".concat(GITHUB_REPO, "/releases/download/binary-v").concat(BINARY_VERSION, "/").concat(archiveBaseName).concat(isWindows ? '.zip' : '.tar.gz');
-    var tempPath = path.join(tmpdir(), "nvu-binary-".concat(Date.now()).concat(isWindows ? '.zip' : '.tar.gz'));
+    var cachePath = path.join(storagePath, 'cache', "".concat(archiveBaseName).concat(isWindows ? '.zip' : '.tar.gz'));
+    // Check cache first
+    if (fs.existsSync(cachePath)) {
+        console.log('Using cached binary...');
+        // Use cached file
+        extractAndInstall(cachePath, binDir, extractedBinaryName, function(err) {
+            if (err) return callback(err);
+            // save binary version for upgrade checks
+            fs.writeFileSync(nvuJsonPath, JSON.stringify({
+                binaryVersion: BINARY_VERSION
+            }, null, 2), 'utf8');
+            console.log('Binary installed successfully!');
+            callback(null, true);
+        });
+        return;
+    }
+    // Download to temp file
     console.log("Downloading binary for ".concat(process.platform, "-").concat(process.arch, "..."));
+    var tempPath = path.join(tmpdir(), "nvu-binary-".concat(Date.now()).concat(isWindows ? '.zip' : '.tar.gz'));
     getFile(downloadUrl, tempPath, function(err) {
         if (err) {
             removeIfExistsSync(tempPath);
             callback(new Error("No prebuilt binary available for ".concat(process.platform, "-").concat(process.arch, ". Download: ").concat(downloadUrl, ". Error: ").concat(err.message)));
             return;
         }
-        console.log('Extracting binary...');
+        // Copy to cache for future use
+        try {
+            copyFileSync(tempPath, cachePath);
+        } catch (_e) {
+        // Cache write failed, continue anyway
+        }
         extractAndInstall(tempPath, binDir, extractedBinaryName, function(err) {
             removeIfExistsSync(tempPath);
             if (err) return callback(err);
             // save binary version for upgrade checks
-            fs.writeFileSync(path.join(binDir, 'version.txt'), BINARY_VERSION, 'utf8');
+            fs.writeFileSync(nvuJsonPath, JSON.stringify({
+                binaryVersion: BINARY_VERSION
+            }, null, 2), 'utf8');
             console.log('Binary installed successfully!');
             callback(null, true);
         });