feat(env): implement symlinks (Unix) and vp env run wrappers (Windows)

- Unix: Replace hardlinks with symlinks to ../current/bin/vp
  - Symlinks preserve argv[0] for tool detection
  - Same pattern as Volta

- Windows: Replace node.exe copy + VITE_PLUS_SHIM_TOOL with .cmd wrappers
  - All shims (node, npm, npx) use .cmd files calling `vp env run <tool>`
  - No binary copies needed

- Package shims: Same changes for global package binaries (e.g., tsc)
  - Unix: Symlink to ../current/bin/vp
  - Windows: .cmd wrapper calling `vp env run <bin_name>`

- Update tests to handle symlink detection (use symlink_metadata)
- Keep VITE_PLUS_SHIM_TOOL detection for backward compatibility

Author: fengmk2

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

@@ -289,6 +289,9 @@ fn is_javascript_binary(path: &AbsolutePath) -> bool {
 const CORE_SHIMS: &[&str] = &["node", "npm", "npx", "vp"];
 
 /// Create a shim for a package binary.
+///
+/// On Unix: Creates a symlink to ../current/bin/vp
+/// On Windows: Creates a .cmd wrapper that calls `vp env run <bin_name>`
 async fn create_package_shim(
     bin_dir: &vite_path::AbsolutePath,
     bin_name: &str,
@@ -308,22 +311,16 @@ async fn create_package_shim(
 
     #[cfg(unix)]
     {
-        let current_exe = std::env::current_exe().map_err(|e| {
-            Error::ConfigError(format!("Cannot find current executable: {e}").into())
-        })?;
-
         let shim_path = bin_dir.join(bin_name);
 
         // Skip if already exists (e.g., re-installing the same package)
         if tokio::fs::try_exists(&shim_path).await.unwrap_or(false) {
             return Ok(());
         }
 
-        // Create hardlink
-        if tokio::fs::hard_link(&current_exe, &shim_path).await.is_err() {
-            // Fallback to copy
-            tokio::fs::copy(&current_exe, &shim_path).await?;
-        }
+        // Create symlink to ../current/bin/vp
+        tokio::fs::symlink("../current/bin/vp", &shim_path).await?;
+        tracing::debug!("Created package shim symlink {:?} -> ../current/bin/vp", shim_path);
     }
 
     #[cfg(windows)]
@@ -335,12 +332,13 @@ async fn create_package_shim(
             return Ok(());
         }
 
-        // Create .cmd wrapper
+        // Create .cmd wrapper that calls vp env run <bin_name>
         let wrapper_content = format!(
-            "@echo off\r\nsetlocal\r\nset \"VITE_PLUS_SHIM_TOOL={}\"\r\n\"%~dp0node.exe\" %*\r\nexit /b %ERRORLEVEL%\r\n",
+            "@echo off\r\n\"%~dp0..\\current\\bin\\vp.exe\" env run {} %*\r\nexit /b %ERRORLEVEL%\r\n",
             bin_name
         );
         tokio::fs::write(&shim_path, wrapper_content).await?;
+        tracing::debug!("Created package shim wrapper {:?} -> vp env run {}", shim_path, bin_name);
     }
 
     Ok(())
@@ -359,7 +357,8 @@ async fn remove_package_shim(
     #[cfg(unix)]
     {
         let shim_path = bin_dir.join(bin_name);
-        if tokio::fs::try_exists(&shim_path).await.unwrap_or(false) {
+        // Use symlink_metadata to detect symlinks (even broken ones)
+        if tokio::fs::symlink_metadata(&shim_path).await.is_ok() {
             tokio::fs::remove_file(&shim_path).await?;
         }
     }
@@ -399,11 +398,20 @@ mod tests {
         assert!(bin_dir.as_path().exists());
 
         // Verify shim file was created (on Windows, shims have .cmd extension)
+        // On Unix, symlinks may be broken (target doesn't exist), so use symlink_metadata
         #[cfg(unix)]
-        let shim_path = bin_dir.join("test-shim");
+        {
+            let shim_path = bin_dir.join("test-shim");
+            assert!(
+                std::fs::symlink_metadata(shim_path.as_path()).is_ok(),
+                "Symlink shim should exist"
+            );
+        }
         #[cfg(windows)]
-        let shim_path = bin_dir.join("test-shim.cmd");
-        assert!(shim_path.as_path().exists());
+        {
+            let shim_path = bin_dir.join("test-shim.cmd");
+            assert!(shim_path.as_path().exists());
+        }
     }
 
     #[tokio::test]
@@ -437,17 +445,35 @@ mod tests {
         create_package_shim(&bin_dir, "tsc", "typescript").await.unwrap();
 
         // Verify the shim was created
+        // On Unix, symlinks may be broken (target doesn't exist), so use symlink_metadata
         #[cfg(unix)]
-        let shim_path = bin_dir.join("tsc");
+        {
+            let shim_path = bin_dir.join("tsc");
+            assert!(
+                std::fs::symlink_metadata(shim_path.as_path()).is_ok(),
+                "Shim should exist after creation"
+            );
+
+            // Remove the shim
+            remove_package_shim(&bin_dir, "tsc").await.unwrap();
+
+            // Verify the shim was removed
+            assert!(
+                std::fs::symlink_metadata(shim_path.as_path()).is_err(),
+                "Shim should be removed"
+            );
+        }
         #[cfg(windows)]
-        let shim_path = bin_dir.join("tsc.cmd");
-        assert!(shim_path.as_path().exists(), "Shim should exist after creation");
+        {
+            let shim_path = bin_dir.join("tsc.cmd");
+            assert!(shim_path.as_path().exists(), "Shim should exist after creation");
 
-        // Remove the shim
-        remove_package_shim(&bin_dir, "tsc").await.unwrap();
+            // Remove the shim
+            remove_package_shim(&bin_dir, "tsc").await.unwrap();
 
-        // Verify the shim was removed
-        assert!(!shim_path.as_path().exists(), "Shim should be removed");
+            // Verify the shim was removed
+            assert!(!shim_path.as_path().exists(), "Shim should be removed");
+        }
     }
 
     #[tokio::test]
@@ -486,10 +512,17 @@ mod tests {
         create_package_shim(&bin_dir, "tsserver", "typescript").await.unwrap();
 
         // Verify shims exist
+        // On Unix, symlinks may be broken (target doesn't exist), so use symlink_metadata
         #[cfg(unix)]
         {
-            assert!(bin_dir.join("tsc").as_path().exists(), "tsc shim should exist");
-            assert!(bin_dir.join("tsserver").as_path().exists(), "tsserver shim should exist");
+            assert!(
+                std::fs::symlink_metadata(bin_dir.join("tsc").as_path()).is_ok(),
+                "tsc shim should exist"
+            );
+            assert!(
+                std::fs::symlink_metadata(bin_dir.join("tsserver").as_path()).is_ok(),
+                "tsserver shim should exist"
+            );
         }
         #[cfg(windows)]
         {

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

@@ -2,10 +2,16 @@
 //!
 //! Creates the following structure:
 //! - ~/.vite-plus/bin/     - Contains vp symlink and node/npm/npx shims
-//! - ~/.vite-plus/current/ - Symlink to the installed version directory
+//! - ~/.vite-plus/current/ - Contains the actual vp CLI binary
 //!
-//! On Unix: bin/vp is a symlink to ../current/bin/vp
-//! On Windows: bin/vp.cmd is a wrapper script that calls ..\current\bin\vp.exe
+//! On Unix:
+//! - bin/vp is a symlink to ../current/bin/vp
+//! - bin/node, bin/npm, bin/npx are symlinks to ../current/bin/vp
+//! - Symlinks preserve argv[0], allowing tool detection via the symlink name
+//!
+//! On Windows:
+//! - bin/vp.cmd is a wrapper script that calls ..\current\bin\vp.exe
+//! - bin/node.cmd, bin/npm.cmd, bin/npx.cmd are wrappers calling `vp env run <tool>`
 
 use std::process::ExitStatus;
 
@@ -160,7 +166,8 @@ async fn create_shim(
 fn shim_filename(tool: &str) -> String {
     #[cfg(windows)]
     {
-        if tool == "node" { format!("{tool}.exe") } else { format!("{tool}.cmd") }
+        // All tools use .cmd wrappers on Windows (including node)
+        format!("{tool}.cmd")
     }
 
     #[cfg(not(windows))]
@@ -169,57 +176,45 @@ fn shim_filename(tool: &str) -> String {
     }
 }
 
-/// Create a Unix shim using hardlink, falling back to copy.
+/// Create a Unix shim using symlink to ../current/bin/vp.
+///
+/// Symlinks preserve argv[0], allowing the vp binary to detect which tool
+/// was invoked. This is the same pattern used by Volta.
 #[cfg(unix)]
 async fn create_unix_shim(
-    source: &std::path::Path,
+    _source: &std::path::Path,
     shim_path: &vite_path::AbsolutePath,
     _tool: &str,
 ) -> Result<(), Error> {
-    // Try hardlink first
-    match tokio::fs::hard_link(source, shim_path).await {
-        Ok(()) => {
-            tracing::debug!("Created hardlink shim at {:?}", shim_path);
-        }
-        Err(e) => {
-            tracing::debug!("Hardlink failed ({e}), falling back to copy");
-            tokio::fs::copy(source, shim_path).await?;
-        }
-    }
+    // Create symlink to ../current/bin/vp (relative path)
+    tokio::fs::symlink("../current/bin/vp", shim_path).await?;
+    tracing::debug!("Created symlink shim at {:?} -> ../current/bin/vp", shim_path);
 
     Ok(())
 }
 
-/// Create Windows shims.
-/// - node.exe: Copy of vp.exe
-/// - npm.cmd, npx.cmd: Wrapper scripts that set VITE_PLUS_SHIM_TOOL
+/// Create Windows shims using .cmd wrappers that call `vp env run <tool>`.
+///
+/// All tools (node, npm, npx) get .cmd wrappers that invoke `vp env run`.
+/// This is consistent with Volta's Windows approach.
 #[cfg(windows)]
 async fn create_windows_shim(
-    source: &std::path::Path,
+    _source: &std::path::Path,
     bin_dir: &vite_path::AbsolutePath,
     tool: &str,
 ) -> Result<(), Error> {
-    if tool == "node" {
-        // Copy vp.exe as node.exe
-        let node_exe = bin_dir.join("node.exe");
-        tokio::fs::copy(source, &node_exe).await?;
-    } else {
-        // Create .cmd wrapper script
-        let cmd_path = bin_dir.join(format!("{tool}.cmd"));
-        let node_exe_path = bin_dir.join("node.exe");
-
-        let cmd_content = format!(
-            r#"@echo off
-setlocal
-set "VITE_PLUS_SHIM_TOOL={tool}"
-"{}" %*
+    let cmd_path = bin_dir.join(format!("{tool}.cmd"));
+
+    // Create .cmd wrapper that calls vp env run <tool>
+    let cmd_content = format!(
+        r#"@echo off
+"%~dp0..\current\bin\vp.exe" env run {tool} %*
 exit /b %ERRORLEVEL%
-"#,
-            node_exe_path.as_path().display()
-        );
+"#
+    );
 
-        tokio::fs::write(&cmd_path, cmd_content).await?;
-    }
+    tokio::fs::write(&cmd_path, cmd_content).await?;
+    tracing::debug!("Created Windows wrapper {:?} -> vp env run {}", cmd_path, tool);
 
     Ok(())
 }

crates/vite_global_cli/src/shim/mod.rs

@@ -2,7 +2,11 @@
 //!
 //! This module provides the functionality for the vp binary to act as a shim
 //! when invoked as `node`, `npm`, `npx`, or any globally installed package binary.
-//! It detects the invocation mode via argv[0] or the VITE_PLUS_SHIM_TOOL environment variable.
+//!
+//! Detection methods:
+//! - Unix: Symlinks to vp binary preserve argv[0], allowing tool detection
+//! - Windows: .cmd wrappers call `vp env run <tool>` directly
+//! - Legacy: VITE_PLUS_SHIM_TOOL env var (kept for backward compatibility)
 
 mod cache;
 mod dispatch;
@@ -99,10 +103,12 @@ fn is_potential_package_binary(tool: &str) -> bool {
 
 /// Detect the shim tool from environment and argv.
 ///
-/// Checks `VITE_PLUS_SHIM_TOOL` first (set by Windows .cmd wrappers),
-/// then falls back to argv[0] detection.
+/// Checks `VITE_PLUS_SHIM_TOOL` first (legacy, for backward compatibility),
+/// then falls back to argv[0] detection (primary method on Unix).
+///
+/// Note: Modern Windows wrappers use `vp env run <tool>` instead of env vars.
 pub fn detect_shim_tool(argv0: &str) -> Option<String> {
-    // Check VITE_PLUS_SHIM_TOOL env var first (set by Windows .cmd wrappers)
+    // Check VITE_PLUS_SHIM_TOOL env var first (legacy backward compatibility)
     if let Ok(tool) = std::env::var("VITE_PLUS_SHIM_TOOL") {
         if !tool.is_empty() {
             let tool_lower = tool.to_lowercase();

rfcs/env-command.md

@@ -1522,6 +1522,7 @@ VITE_PLUS_HOME/
 ### How argv[0] Detection Works
 
 When a user runs `node`:
+
 1. Shell finds `~/.vite-plus/bin/node` in PATH
 2. This is a symlink to `../current/bin/vp`
 3. Kernel resolves symlink and executes `vp` binary
@@ -1580,6 +1581,7 @@ exit /b %ERRORLEVEL%
 ```
 
 For npm:
+
 ```batch
 @echo off
 "%~dp0..\current\bin\vp.exe" env run npm %*