feat(env): add vp env use command for per-shell session Node.js version override

- Add `vp env use [VERSION]` command that outputs shell-appropriate
  export/unset commands to stdout (eval'd by shell function wrapper)
- Add VITE_PLUS_NODE_VERSION env var as priority 0 in version resolution
- Add fast-path in shim cache to skip disk I/O when env var is set
- Extend env files (POSIX, fish, PowerShell) with shell function wrappers
  that intercept `vp env use` and eval its stdout
- Add -h/--help bypass in shell function wrappers to avoid eval'ing help text
- Patch env files for vp-dev binary name in install-global-cli.ts
- Add friendly error message for invalid version inputs (e.g., `vp env use d`)
- Update doctor diagnostics to report active session override
- Add snap tests for command output and shell wrapper behavior

Author: fengmk2

.github/workflows/ci.yml

@@ -242,7 +242,7 @@ jobs:
           Get-ChildItem "$env:USERPROFILE\.vite-plus-dev\bin\"
 
           # Test 3: Uninstall
-          npm uninstall -g typescript
+          vp uninstall -g typescript
 
           # Test 4: Verify uninstall removed shim
           Write-Host "Checking bin dir after uninstall:"
@@ -274,7 +274,7 @@ jobs:
           dir "%USERPROFILE%\.vite-plus-dev\bin\"
 
           :: Test 3: Uninstall
-          npm uninstall -g typescript
+          vp uninstall -g typescript
 
           :: Test 4: Verify uninstall removed shim (.cmd wrapper)
           echo Checking bin dir after uninstall:
@@ -312,7 +312,7 @@ jobs:
           ls -la ~/.vite-plus-dev/bin/
 
           # Test 3: Uninstall
-          npm uninstall -g typescript
+          vp uninstall -g typescript
 
           # Test 4: Verify uninstall removed shim
           echo "Checking bin dir after uninstall:"

crates/vite_global_cli/src/cli.rs

@@ -727,6 +727,25 @@ pub enum EnvSubcommands {
         /// If not provided, installs the version from .node-version or package.json
         version: Option<String>,
     },
+
+    /// Use a specific Node.js version for this shell session
+    Use {
+        /// Version to use (e.g., "20", "20.18.0", "lts", "latest")
+        /// If not provided, reads from .node-version or package.json
+        version: Option<String>,
+
+        /// Remove session override (revert to file-based resolution)
+        #[arg(long)]
+        unset: bool,
+
+        /// Skip auto-installation if version not present
+        #[arg(long)]
+        no_install: bool,
+
+        /// Suppress output if version is already active
+        #[arg(long)]
+        silent_if_unchanged: bool,
+    },
 }
 
 /// Package manager subcommands

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

@@ -145,15 +145,34 @@ pub async fn save_config(config: &Config) -> Result<(), Error> {
     Ok(())
 }
 
+/// Environment variable for per-shell session Node.js version override.
+/// Set by `vp env use` command.
+pub const VERSION_ENV_VAR: &str = "VITE_PLUS_NODE_VERSION";
+
 /// Resolve Node.js version for a directory.
 ///
 /// Resolution order:
+/// 0. `VITE_PLUS_NODE_VERSION` env var (session override from `vp env use`)
 /// 1. `.node-version` file in current or parent directories
 /// 2. `package.json#engines.node` in current or parent directories
 /// 3. `package.json#devEngines.runtime` in current or parent directories
 /// 4. User default from config.json
 /// 5. Latest LTS version
 pub async fn resolve_version(cwd: &AbsolutePath) -> Result<VersionResolution, Error> {
+    // Session override via environment variable (set by `vp env use`)
+    if let Ok(env_version) = std::env::var(VERSION_ENV_VAR) {
+        let env_version = env_version.trim();
+        if !env_version.is_empty() {
+            return Ok(VersionResolution {
+                version: env_version.to_string(),
+                source: VERSION_ENV_VAR.into(),
+                source_path: None,
+                project_root: None,
+                is_range: false,
+            });
+        }
+    }
+
     let provider = NodeProvider::new();
 
     // Use shared version resolution with directory walking
@@ -291,11 +310,13 @@ async fn resolve_version_string(version: &str, provider: &NodeProvider) -> Resul
 }
 
 /// Resolve version alias (lts, latest) to an exact version.
+///
+/// Wraps resolution errors with a user-friendly message showing valid examples.
 pub async fn resolve_version_alias(
     version: &str,
     provider: &NodeProvider,
 ) -> Result<String, Error> {
-    match version.to_lowercase().as_str() {
+    let result = match version.to_lowercase().as_str() {
         "lts" => {
             let resolved = provider.resolve_latest_version().await?;
             Ok(resolved.to_string())
@@ -306,7 +327,24 @@ pub async fn resolve_version_alias(
             Ok(resolved.to_string())
         }
         _ => resolve_version_string(version, provider).await,
-    }
+    };
+    result.map_err(|e| match e {
+        Error::RuntimeDownload(
+            vite_js_runtime::Error::SemverRange(_)
+            | vite_js_runtime::Error::NoMatchingVersion { .. },
+        ) => Error::Other(
+            format!(
+                "Invalid Node.js version: \"{version}\"\n\n\
+                 Valid examples:\n  \
+                 vp env use 20          # Latest Node.js 20.x\n  \
+                 vp env use 20.18.0     # Exact version\n  \
+                 vp env use lts         # Latest LTS version\n  \
+                 vp env use latest      # Latest version"
+            )
+            .into(),
+        ),
+        other => other,
+    })
 }
 
 #[cfg(test)]
@@ -723,4 +761,83 @@ mod tests {
             resolution.version
         );
     }
+
+    #[tokio::test]
+    #[serial]
+    async fn test_resolve_version_env_var_takes_priority() {
+        let temp_dir = TempDir::new().unwrap();
+        let temp_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+
+        // Create .node-version file
+        tokio::fs::write(temp_path.join(".node-version"), "20.18.0\n").await.unwrap();
+
+        // SAFETY: This test runs in isolation with serial_test
+        unsafe {
+            std::env::set_var(VERSION_ENV_VAR, "22.0.0");
+        }
+
+        let resolution = resolve_version(&temp_path).await.unwrap();
+
+        // VITE_PLUS_NODE_VERSION should take priority over .node-version
+        assert_eq!(resolution.version, "22.0.0");
+        assert_eq!(resolution.source, VERSION_ENV_VAR);
+        assert!(resolution.source_path.is_none());
+        assert!(!resolution.is_range);
+
+        unsafe {
+            std::env::remove_var(VERSION_ENV_VAR);
+        }
+    }
+
+    #[tokio::test]
+    #[serial]
+    async fn test_resolve_version_empty_env_var_is_ignored() {
+        let temp_dir = TempDir::new().unwrap();
+        let temp_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+
+        // Create .node-version file
+        tokio::fs::write(temp_path.join(".node-version"), "20.18.0\n").await.unwrap();
+
+        // Set empty env var - should be ignored
+        // SAFETY: This test runs in isolation with serial_test
+        unsafe {
+            std::env::set_var(VERSION_ENV_VAR, "");
+        }
+
+        let resolution = resolve_version(&temp_path).await.unwrap();
+
+        // Empty env var should be ignored, should fall through to .node-version
+        assert_eq!(resolution.version, "20.18.0");
+        assert_eq!(resolution.source, ".node-version");
+
+        unsafe {
+            std::env::remove_var(VERSION_ENV_VAR);
+        }
+    }
+
+    #[tokio::test]
+    #[serial]
+    async fn test_resolve_version_whitespace_env_var_is_ignored() {
+        let temp_dir = TempDir::new().unwrap();
+        let temp_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+
+        // Create .node-version file
+        tokio::fs::write(temp_path.join(".node-version"), "20.18.0\n").await.unwrap();
+
+        // Set whitespace-only env var - should be ignored
+        // SAFETY: This test runs in isolation with serial_test
+        unsafe {
+            std::env::set_var(VERSION_ENV_VAR, "   ");
+        }
+
+        let resolution = resolve_version(&temp_path).await.unwrap();
+
+        // Whitespace env var should be ignored, should fall through to .node-version
+        assert_eq!(resolution.version, "20.18.0");
+        assert_eq!(resolution.source, ".node-version");
+
+        unsafe {
+            std::env::remove_var(VERSION_ENV_VAR);
+        }
+    }
 }

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

@@ -34,6 +34,9 @@ pub async fn execute(cwd: AbsolutePathBuf) -> Result<ExitStatus, Error> {
     // Check shim mode
     check_shim_mode().await;
 
+    // Check session override
+    check_session_override();
+
     // Check PATH
     has_errors |= !check_path().await;
 
@@ -199,6 +202,24 @@ fn find_system_node() -> Option<std::path::PathBuf> {
     which::which_in("node", Some(filtered_path), cwd).ok()
 }
 
+/// Check for active session override via VITE_PLUS_NODE_VERSION.
+fn check_session_override() {
+    if let Ok(version) = std::env::var(super::config::VERSION_ENV_VAR) {
+        let version = version.trim();
+        if !version.is_empty() {
+            println!();
+            println!("Session Override:");
+            println!(
+                "  {}",
+                format!("\u{2139} VITE_PLUS_NODE_VERSION={} (set by `vp env use`)", version)
+                    .yellow()
+            );
+            println!("  This overrides all file-based version resolution.");
+            println!("  Run 'vp env use --unset' to remove.");
+        }
+    }
+}
+
 /// Check PATH configuration.
 async fn check_path() -> bool {
     println!();

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

@@ -18,6 +18,7 @@ mod pin;
 mod run;
 mod setup;
 mod unpin;
+mod r#use;
 mod which;
 
 use std::process::ExitStatus;
@@ -72,6 +73,9 @@ pub async fn execute(cwd: AbsolutePathBuf, args: EnvArgs) -> Result<ExitStatus,
                 println!("Uninstalled Node.js v{}", resolved);
                 Ok(ExitStatus::default())
             }
+            crate::cli::EnvSubcommands::Use { version, unset, no_install, silent_if_unchanged } => {
+                r#use::execute(cwd, version, unset, no_install, silent_if_unchanged).await
+            }
             crate::cli::EnvSubcommands::Install { version } => {
                 let resolved = if let Some(version) = version {
                     let provider = vite_js_runtime::NodeProvider::new();
@@ -126,6 +130,7 @@ fn print_help() {
     println!("  pin [VERSION]      Pin a Node.js version in current directory");
     println!("  unpin              Remove the .node-version file from current directory");
     println!("  list [PATTERN]     List available Node.js versions");
+    println!("  use [VERSION]      Use a Node.js version for this shell session");
     println!("  run [--node <VER>] Run a command (--node optional for shim tools)");
     println!("  packages           List installed global packages");
     println!("  install [VERSION]  Install a Node.js version (reads project config if omitted)");
@@ -154,6 +159,10 @@ fn print_help() {
     println!("  vp env install                # Install version from .node-version / package.json");
     println!("  vp env install lts            # Install latest LTS version");
     println!("  vp env uninstall 20.18.0      # Uninstall Node.js 20.18.0");
+    println!("  vp env use 20                 # Use Node.js 20 for this shell session");
+    println!("  vp env use lts                # Use latest LTS for this shell session");
+    println!("  vp env use                    # Use project version for this shell session");
+    println!("  vp env use --unset            # Remove session override");
     println!("  vp env run --node 20 node -v  # Run 'node -v' with Node.js 20");
     println!("  vp env run --node lts npm i   # Run 'npm i' with latest LTS");
     println!("  vp env run node -v            # Shim mode (version auto-resolved)");