feat(env): make vp env off disable Node.js management for all vp commands

Previously, `vp env off` only affected shim dispatch (node/npm/npx
invoked directly). All vp commands (create, build, install, etc.)
still downloaded managed Node.js via JsExecutor, ignoring the
system-first mode setting.

Now when `vp env off` is active, JsExecutor checks ShimMode before
downloading and uses the system-installed Node.js found in PATH.
This fixes NixOS/Guix (where downloaded binaries fail), air-gapped
environments, and users managing Node.js via other tools (mise, nvm).

- Add JsRuntime::from_system() constructor for system binary paths
- Add system-first checks to ensure_cli_runtime/ensure_project_runtime
- Expose find_system_tool as pub(crate) and deduplicate doctor.rs copy
- Update vp env off/on messaging to reflect broader scope
- Add CI E2E tests for system-first mode on all platforms

Closes #977

Author: fengmk2

.github/workflows/ci.yml

@@ -235,6 +235,11 @@ jobs:
         if: ${{ matrix.target == 'x86_64-unknown-linux-gnu' }}
         run: pnpm tsgo
 
+      - name: Save system Node.js info
+        run: |
+          echo "SYSTEM_NODE_PATH=$(which node)" >> "$GITHUB_ENV"
+          echo "SYSTEM_NODE_VERSION=$(node --version)" >> "$GITHUB_ENV"
+
       - name: Install Global CLI vp
         run: |
           pnpm bootstrap-cli:ci
@@ -258,6 +263,28 @@ jobs:
         env:
           RUST_MIN_STACK: 8388608
 
+      - name: Test vp env off (system-first mode)
+        run: |
+          echo "System Node.js: $SYSTEM_NODE_PATH ($SYSTEM_NODE_VERSION)"
+
+          vp env off
+          vp env doctor
+
+          # Verify vp --version still works using system Node.js
+          vp --version
+
+          # In system-first mode, the node shim should resolve to system node
+          SHIM_NODE_VERSION=$(node --version)
+          echo "Shim Node.js version: $SHIM_NODE_VERSION"
+          if [ "$SHIM_NODE_VERSION" != "$SYSTEM_NODE_VERSION" ]; then
+            echo "Error: expected shim to use system Node.js $SYSTEM_NODE_VERSION, got $SHIM_NODE_VERSION"
+            exit 1
+          fi
+
+          vp env on
+          vp env doctor
+          echo "vp env off/on test passed"
+
       - name: Test global package install (powershell)
         if: ${{ matrix.os == 'windows-latest' }}
         shell: pwsh
@@ -298,6 +325,27 @@ jobs:
           vp env use --unset
           node --version
 
+      - name: Test vp env off (powershell)
+        if: ${{ matrix.os == 'windows-latest' }}
+        shell: pwsh
+        run: |
+          Write-Host "System Node.js: $env:SYSTEM_NODE_PATH ($env:SYSTEM_NODE_VERSION)"
+
+          vp env off
+          vp env doctor
+          vp --version
+
+          $ShimNodeVersion = node --version
+          Write-Host "Shim Node.js version: $ShimNodeVersion"
+          if ($ShimNodeVersion -ne $env:SYSTEM_NODE_VERSION) {
+            Write-Error "Expected shim to use system Node.js $env:SYSTEM_NODE_VERSION, got $ShimNodeVersion"
+            exit 1
+          }
+
+          vp env on
+          vp env doctor
+          Write-Host "vp env off/on test passed"
+
       - name: Test global package install (cmd)
         if: ${{ matrix.os == 'windows-latest' }}
         shell: cmd

crates/vite_global_cli/src/commands/env/doctor.rs

@@ -7,7 +7,7 @@ use vite_path::{AbsolutePathBuf, current_dir};
 use vite_shared::{env_vars, output};
 
 use super::config::{self, ShimMode, get_bin_dir, get_vp_home, load_config, resolve_version};
-use crate::error::Error;
+use crate::{error::Error, shim};
 
 /// IDE-relevant profile files that GUI-launched applications can see.
 /// GUI apps don't run through an interactive shell, so only login/environment
@@ -263,23 +263,23 @@ async fn check_shim_mode() {
 
     match config.shim_mode {
         ShimMode::Managed => {
-            print_check(&output::CHECK.green().to_string(), "Shim mode", "managed");
+            print_check(&output::CHECK.green().to_string(), "Node.js mode", "managed");
         }
         ShimMode::SystemFirst => {
             print_check(
                 &output::CHECK.green().to_string(),
-                "Shim mode",
+                "Node.js mode",
                 &"system-first".bright_blue().to_string(),
             );
 
             // Check if system Node.js is available
-            if let Some(system_node) = find_system_node() {
-                print_check(" ", "System Node.js", &system_node.display().to_string());
+            if let Some(system_node) = shim::find_system_tool("node") {
+                print_check(" ", "System Node.js", &system_node.as_path().display().to_string());
             } else {
                 print_check(
                     &output::WARN_SIGN.yellow().to_string(),
                     "System Node.js",
-                    &"not found (will use managed)".yellow().to_string(),
+                    &"not found (will fall back to managed)".yellow().to_string(),
                 );
             }
         }
@@ -338,36 +338,6 @@ fn check_env_sourcing() -> EnvSourcingStatus {
     EnvSourcingStatus::NotFound
 }
 
-/// Find system Node.js, skipping vite-plus bin directory and any
-/// directories listed in `VP_BYPASS`.
-fn find_system_node() -> Option<std::path::PathBuf> {
-    let bin_dir = get_bin_dir().ok();
-    let path_var = std::env::var_os("PATH")?;
-
-    // Parse VP_BYPASS as a PATH-style list of additional directories to skip
-    let bypass_paths: Vec<std::path::PathBuf> = std::env::var_os(env_vars::VP_BYPASS)
-        .map(|v| std::env::split_paths(&v).collect())
-        .unwrap_or_default();
-
-    // Filter PATH to exclude our bin directory and any bypass directories
-    let filtered_paths: Vec<_> = std::env::split_paths(&path_var)
-        .filter(|p| {
-            if let Some(ref bin) = bin_dir {
-                if p == bin.as_path() {
-                    return false;
-                }
-            }
-            !bypass_paths.iter().any(|bp| p == bp)
-        })
-        .collect();
-
-    let filtered_path = std::env::join_paths(filtered_paths).ok()?;
-
-    // Use vite_command::resolve_bin with filtered PATH - stops at first match
-    let cwd = current_dir().ok()?;
-    vite_command::resolve_bin("node", Some(&filtered_path), &cwd).ok().map(|p| p.into_path_buf())
-}
-
 /// Check for active session override via VP_NODE_VERSION or session file.
 fn check_session_override() {
     if let Ok(version) = std::env::var(config::VERSION_ENV_VAR) {
@@ -806,9 +776,12 @@ mod tests {
             std::env::set_var(env_vars::VP_BYPASS, dir_a.as_os_str());
         }
 
-        let result = find_system_node();
+        let result = shim::find_system_tool("node");
         assert!(result.is_some(), "Should find node in non-bypassed directory");
-        assert!(result.unwrap().starts_with(&dir_b), "Should find node in dir_b, not dir_a");
+        assert!(
+            result.unwrap().as_path().starts_with(&dir_b),
+            "Should find node in dir_b, not dir_a"
+        );
     }
 
     #[test]
@@ -826,7 +799,7 @@ mod tests {
             std::env::set_var(env_vars::VP_BYPASS, dir_a.as_os_str());
         }
 
-        let result = find_system_node();
+        let result = shim::find_system_tool("node");
         assert!(result.is_none(), "Should return None when all paths are bypassed");
     }
 

crates/vite_global_cli/src/commands/env/off.rs

@@ -23,23 +23,23 @@ pub async fn execute() -> Result<ExitStatus, Error> {
     let mut config = load_config().await?;
 
     if config.shim_mode == ShimMode::SystemFirst {
-        println!("Shim mode is already set to system-first.");
+        println!("Node.js management is already set to system-first.");
         println!(
-            "Shims will prefer system Node.js, falling back to Vite+ managed Node.js if not found."
+            "All vp commands and shims will prefer system Node.js, falling back to managed if not found."
         );
         return Ok(ExitStatus::default());
     }
 
     config.shim_mode = ShimMode::SystemFirst;
     save_config(&config).await?;
 
-    println!("\u{2713} Shim mode set to system-first.");
+    println!("\u{2713} Node.js management set to system-first.");
     println!();
     println!(
-        "Shims will now prefer system Node.js, falling back to Vite+ managed Node.js if not found."
+        "All vp commands and shims will now prefer system Node.js, falling back to managed if not found."
     );
     println!();
-    println!("Run {} to always use the Vite+ managed Node.js.", accent_command("vp env on"));
+    println!("Run {} to always use Vite+ managed Node.js.", accent_command("vp env on"));
 
     Ok(ExitStatus::default())
 }

crates/vite_global_cli/src/commands/env/on.rs

@@ -22,17 +22,17 @@ pub async fn execute() -> Result<ExitStatus, Error> {
     let mut config = load_config().await?;
 
     if config.shim_mode == ShimMode::Managed {
-        println!("Shim mode is already set to managed.");
-        println!("Shims will always use the Vite+ managed Node.js.");
+        println!("Node.js management is already set to managed.");
+        println!("All vp commands and shims will always use Vite+ managed Node.js.");
         return Ok(ExitStatus::default());
     }
 
     config.shim_mode = ShimMode::Managed;
     save_config(&config).await?;
 
-    println!("\u{2713} Shim mode set to managed.");
+    println!("\u{2713} Node.js management set to managed.");
     println!();
-    println!("Shims will now always use the Vite+ managed Node.js.");
+    println!("All vp commands and shims will now always use Vite+ managed Node.js.");
     println!();
     println!("Run {} to prefer system Node.js instead.", accent_command("vp env off"));
 

crates/vite_global_cli/src/js_executor.rs

@@ -13,7 +13,11 @@ use vite_js_runtime::{
 use vite_path::{AbsolutePath, AbsolutePathBuf};
 use vite_shared::{PrependOptions, PrependResult, env_vars, format_path_with_prepend};
 
-use crate::{commands::env::config, error::Error};
+use crate::{
+    commands::env::config::{self, ShimMode},
+    error::Error,
+    shim,
+};
 
 /// JavaScript executor using managed Node.js runtime.
 ///
@@ -125,8 +129,15 @@ impl JsExecutor {
     ///
     /// Uses the CLI's package.json `devEngines.runtime` configuration
     /// to determine which Node.js version to use.
+    ///
+    /// When system-first mode is active (`vp env off`), prefers the
+    /// system-installed Node.js found in PATH.
     pub async fn ensure_cli_runtime(&mut self) -> Result<&JsRuntime, Error> {
         if self.cli_runtime.is_none() {
+            if let Some(system_runtime) = find_system_node_runtime().await {
+                return Ok(self.cli_runtime.insert(system_runtime));
+            }
+
             let cli_dir = self.get_cli_package_dir()?;
             tracing::debug!("Resolving CLI runtime from {:?}", cli_dir);
             let runtime = download_runtime_for_project(&cli_dir).await?;
@@ -151,6 +162,10 @@ impl JsExecutor {
         if self.project_runtime.is_none() {
             tracing::debug!("Resolving project runtime from {:?}", project_path);
 
+            if let Some(system_runtime) = find_system_node_runtime().await {
+                return Ok(self.project_runtime.insert(system_runtime));
+            }
+
             // 1–2. Session overrides: env var (from `vp env use`), then file
             let session_version = vite_shared::EnvConfig::get()
                 .node_version
@@ -391,6 +406,24 @@ async fn has_valid_version_source(
     Ok(engines_valid || dev_engines_valid)
 }
 
+/// Try to find system Node.js when in system-first mode (`vp env off`).
+///
+/// Returns `Some(JsRuntime)` when both conditions are met:
+/// 1. Config has `shim_mode == SystemFirst`
+/// 2. A system `node` binary is found in PATH (excluding the vite-plus bin directory)
+///
+/// Returns `None` if mode is `Managed` or no system Node.js is found,
+/// allowing the caller to fall through to managed runtime resolution.
+async fn find_system_node_runtime() -> Option<JsRuntime> {
+    let config = config::load_config().await.ok()?;
+    if config.shim_mode != ShimMode::SystemFirst {
+        return None;
+    }
+    let system_node = shim::find_system_tool("node")?;
+    tracing::info!("System-first mode: using system Node.js at {:?}", system_node);
+    Some(JsRuntime::from_system(JsRuntimeType::Node, system_node))
+}
+
 #[cfg(test)]
 mod tests {
     use serial_test::serial;

crates/vite_global_cli/src/shim/dispatch.rs

@@ -1159,7 +1159,7 @@ async fn load_shim_mode() -> ShimMode {
 /// directories listed in `VP_BYPASS`.
 ///
 /// Returns the absolute path to the tool if found, None otherwise.
-fn find_system_tool(tool: &str) -> Option<AbsolutePathBuf> {
+pub(crate) fn find_system_tool(tool: &str) -> Option<AbsolutePathBuf> {
     let bin_dir = config::get_bin_dir().ok();
     let path_var = std::env::var_os("PATH")?;
     tracing::debug!("path_var: {:?}", path_var);

crates/vite_global_cli/src/shim/mod.rs

@@ -14,6 +14,7 @@ pub(crate) mod exec;
 
 pub(crate) use cache::invalidate_cache;
 pub use dispatch::dispatch;
+pub(crate) use dispatch::find_system_tool;
 use vite_shared::env_vars;
 
 /// Core shim tools (node, npm, npx)

crates/vite_js_runtime/src/runtime.rs

@@ -66,6 +66,27 @@ impl JsRuntime {
     pub fn version(&self) -> &str {
         &self.version
     }
+
+    /// Create a `JsRuntime` from a system-installed binary path.
+    ///
+    /// `get_bin_prefix()` returns the parent directory of `binary_path`.
+    #[must_use]
+    pub fn from_system(runtime_type: JsRuntimeType, binary_path: AbsolutePathBuf) -> Self {
+        let install_dir = binary_path
+            .parent()
+            .map(vite_path::AbsolutePath::to_absolute_path_buf)
+            .unwrap_or_else(|| binary_path.clone());
+        let binary_filename: Str = Str::from(
+            binary_path.as_path().file_name().unwrap_or_default().to_string_lossy().as_ref(),
+        );
+        Self {
+            runtime_type,
+            version: "system".into(),
+            install_dir,
+            binary_relative_path: binary_filename,
+            bin_dir_relative_path: Str::default(),
+        }
+    }
 }
 
 /// Download and cache a JavaScript runtime
@@ -557,6 +578,26 @@ mod tests {
         assert_eq!(JsRuntimeType::Node.to_string(), "node");
     }
 
+    #[test]
+    fn test_js_runtime_from_system() {
+        let binary_path = AbsolutePathBuf::new(std::path::PathBuf::from(if cfg!(windows) {
+            "C:\\Program Files\\nodejs\\node.exe"
+        } else {
+            "/usr/local/bin/node"
+        }))
+        .unwrap();
+
+        let runtime = JsRuntime::from_system(JsRuntimeType::Node, binary_path.clone());
+
+        assert_eq!(runtime.runtime_type(), JsRuntimeType::Node);
+        assert_eq!(runtime.version(), "system");
+        assert_eq!(runtime.get_binary_path(), binary_path);
+
+        // bin prefix should be the directory containing the binary
+        let expected_bin_prefix = binary_path.parent().unwrap().to_absolute_path_buf();
+        assert_eq!(runtime.get_bin_prefix(), expected_bin_prefix);
+    }
+
     /// Test that install_dir path is constructed correctly without embedded forward slashes.
     /// This ensures Windows compatibility by using separate join() calls.
     #[test]