chore: CLI improvements. (#668)

Author: cpojer

crates/vite_global_cli/src/cli.rs

@@ -17,6 +17,7 @@ use crate::{
         RemoveCommand, UnlinkCommand, UpdateCommand, WhyCommand,
     },
     error::Error,
+    help,
 };
 
 /// Vite+ Global CLI
@@ -1793,25 +1794,65 @@ pub async fn run_command(cwd: AbsolutePathBuf, args: Args) -> Result<ExitStatus,
         Commands::Migrate { args } => commands::migrate::execute(cwd, &args).await,
 
         // Category C: Local CLI Delegation (stubs)
-        Commands::Dev { args } => commands::delegate::execute(cwd, "dev", &args).await,
+        Commands::Dev { args } => {
+            if help::maybe_print_unified_delegate_help("dev", &args) {
+                return Ok(ExitStatus::default());
+            }
+            commands::delegate::execute(cwd, "dev", &args).await
+        }
 
-        Commands::Build { args } => commands::delegate::execute(cwd, "build", &args).await,
+        Commands::Build { args } => {
+            if help::maybe_print_unified_delegate_help("build", &args) {
+                return Ok(ExitStatus::default());
+            }
+            commands::delegate::execute(cwd, "build", &args).await
+        }
 
-        Commands::Test { args } => commands::delegate::execute(cwd, "test", &args).await,
+        Commands::Test { args } => {
+            if help::maybe_print_unified_delegate_help("test", &args) {
+                return Ok(ExitStatus::default());
+            }
+            commands::delegate::execute(cwd, "test", &args).await
+        }
 
-        Commands::Lint { args } => commands::delegate::execute(cwd, "lint", &args).await,
+        Commands::Lint { args } => {
+            if help::maybe_print_unified_delegate_help("lint", &args) {
+                return Ok(ExitStatus::default());
+            }
+            commands::delegate::execute(cwd, "lint", &args).await
+        }
 
-        Commands::Fmt { args } => commands::delegate::execute(cwd, "fmt", &args).await,
+        Commands::Fmt { args } => {
+            if help::maybe_print_unified_delegate_help("fmt", &args) {
+                return Ok(ExitStatus::default());
+            }
+            commands::delegate::execute(cwd, "fmt", &args).await
+        }
 
-        Commands::Check { args } => commands::delegate::execute(cwd, "check", &args).await,
+        Commands::Check { args } => {
+            if help::maybe_print_unified_delegate_help("check", &args) {
+                return Ok(ExitStatus::default());
+            }
+            commands::delegate::execute(cwd, "check", &args).await
+        }
 
-        Commands::Pack { args } => commands::delegate::execute(cwd, "pack", &args).await,
+        Commands::Pack { args } => {
+            if help::maybe_print_unified_delegate_help("pack", &args) {
+                return Ok(ExitStatus::default());
+            }
+            commands::delegate::execute(cwd, "pack", &args).await
+        }
 
         Commands::Run { args } => commands::run_or_delegate::execute(cwd, &args).await,
 
         Commands::Exec { args } => commands::delegate::execute(cwd, "exec", &args).await,
 
-        Commands::Preview { args } => commands::delegate::execute(cwd, "preview", &args).await,
+        Commands::Preview { args } => {
+            if help::maybe_print_unified_delegate_help("preview", &args) {
+                return Ok(ExitStatus::default());
+            }
+            commands::delegate::execute(cwd, "preview", &args).await
+        }
 
         Commands::Cache { args } => commands::delegate::execute(cwd, "cache", &args).await,
 
@@ -1854,52 +1895,12 @@ pub fn command_with_help() -> clap::Command {
 
 /// Apply custom help formatting to a clap Command to match the JS CLI output.
 fn apply_custom_help(cmd: clap::Command) -> clap::Command {
-    let bold = "\x1b[1m";
-    let bold_underline = "\x1b[1;4m";
-    let reset = "\x1b[0m";
     let version = env!("CARGO_PKG_VERSION");
-
-    let after_help = format!(
-        "{bold_underline}Core Commands:{reset}
-  {bold}create{reset}                         Create a new project from a template
-  {bold}dev{reset}                            Run the development server
-  {bold}build{reset}                          Build for production
-  {bold}test{reset}                           Run tests
-  {bold}lint{reset}                           Lint code
-  {bold}fmt{reset}                            Format code
-  {bold}check{reset}                          Run format, lint, and type checks
-  {bold}pack{reset}                           Build library
-  {bold}run{reset}                            Run tasks
-  {bold}exec{reset}                           Execute a command from local node_modules/.bin
-  {bold}preview{reset}                        Preview production build
-  {bold}env{reset}                            Manage Node.js versions
-  {bold}migrate{reset}                        Migrate an existing project to Vite+
-  {bold}cache{reset}                          Manage the task cache
-
-{bold_underline}Package Manager Commands:{reset}
-  {bold}install, i{reset}                     Install all dependencies, or add packages if package names are provided
-  {bold}add{reset}                            Add packages to dependencies
-  {bold}remove, rm, un, uninstall{reset}      Remove packages from dependencies
-  {bold}dedupe{reset}                         Deduplicate dependencies by removing older versions
-  {bold}dlx{reset}                            Execute a package binary without installing it as a dependency
-  {bold}info, view, show{reset}               View package information from the registry
-  {bold}link, ln{reset}                       Link packages for local development
-  {bold}list, ls{reset}                       List installed packages
-  {bold}outdated{reset}                       Check for outdated packages
-  {bold}pm{reset}                             Forward a command to the package manager
-  {bold}unlink{reset}                         Unlink packages
-  {bold}update, up{reset}                     Update packages to their latest versions
-  {bold}why, explain{reset}                   Show why a package is installed
-
-{bold_underline}Maintenance Commands:{reset}
-  {bold}upgrade{reset}                        Update vp itself to the latest version
-"
-    );
+    let after_help = help::render_help_doc(&help::top_level_help_doc());
     let help_template = format!(
-        "Vite+/{version}
-
-{{usage-heading}} {{usage}}{{after-help}}
-{bold_underline}Options:{reset}
+        "Vite+/{version}\
+{{after-help}}
+Options:
 {{options}}
 "
     );

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

@@ -27,6 +27,8 @@ pub async fn execute(
     npm_version: Option<&str>,
     command: &[String],
 ) -> Result<ExitStatus, Error> {
+    let command = normalize_wrapper_command(command);
+
     if command.is_empty() {
         eprintln!("vp env exec: missing command to execute");
         eprintln!("Usage: vp env exec [--node <version>] <command> [args...]");
@@ -35,7 +37,7 @@ pub async fn execute(
 
     // If --node is provided, use explicit version mode (existing behavior)
     if let Some(version) = node_version {
-        return execute_with_version(version, npm_version, command).await;
+        return execute_with_version(version, npm_version, &command).await;
     }
 
     // No --node provided - check if first command is a shim tool
@@ -77,6 +79,34 @@ pub async fn execute(
     Ok(exit_status(1))
 }
 
+/// Normalize arguments when invoked via Windows shim wrappers.
+///
+/// Wrappers insert `--` after the tool name so flags like `--help` aren't
+/// consumed by clap while parsing `vp env exec`. Remove only that inserted
+/// separator before forwarding args to the target tool.
+fn normalize_wrapper_command(command: &[String]) -> Vec<String> {
+    let from_wrapper = std::env::var_os(env_vars::VITE_PLUS_SHIM_WRAPPER).is_some();
+    let normalized = normalize_wrapper_command_inner(command, from_wrapper);
+
+    if from_wrapper {
+        // SAFETY: We're in a short-lived CLI process and clearing a wrapper-only
+        // marker before tool execution avoids leaking it to child processes.
+        unsafe {
+            std::env::remove_var(env_vars::VITE_PLUS_SHIM_WRAPPER);
+        }
+    }
+
+    normalized
+}
+
+fn normalize_wrapper_command_inner(command: &[String], from_wrapper: bool) -> Vec<String> {
+    let mut normalized = command.to_vec();
+    if from_wrapper && normalized.len() >= 2 && normalized[1] == "--" {
+        normalized.remove(1);
+    }
+    normalized
+}
+
 /// Execute a command with an explicitly specified Node.js version.
 async fn execute_with_version(
     node_version: &str,
@@ -238,4 +268,18 @@ mod tests {
         // Should fail because python is not a shim tool and --node was not provided
         assert!(!status.success(), "Non-shim command without --node should fail");
     }
+
+    #[test]
+    fn test_normalize_wrapper_command_strips_only_wrapper_separator() {
+        let command = vec!["node".to_string(), "--".to_string(), "--version".to_string()];
+        let normalized = normalize_wrapper_command_inner(&command, true);
+        assert_eq!(normalized, vec!["node", "--version"]);
+    }
+
+    #[test]
+    fn test_normalize_wrapper_command_no_wrapper_keeps_separator() {
+        let command = vec!["node".to_string(), "--".to_string(), "--version".to_string()];
+        let normalized = normalize_wrapper_command_inner(&command, false);
+        assert_eq!(normalized, command);
+    }
 }

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

@@ -405,11 +405,13 @@ async fn create_package_shim(
             return Ok(());
         }
 
-        // Create .cmd wrapper that calls vp env exec <bin_name>
+        // Create .cmd wrapper that calls vp env exec <bin_name>.
+        // Use `--` so args like `--help` are forwarded to the package binary,
+        // not consumed by clap while parsing `vp env exec`.
         // Set VITE_PLUS_HOME using %~dp0.. which resolves to the parent of bin/
         // This ensures the vp binary knows its home directory
         let wrapper_content = format!(
-            "@echo off\r\nset VITE_PLUS_HOME=%~dp0..\r\n\"%VITE_PLUS_HOME%\\current\\bin\\vp.exe\" env exec {} %*\r\nexit /b %ERRORLEVEL%\r\n",
+            "@echo off\r\nset VITE_PLUS_HOME=%~dp0..\r\nset VITE_PLUS_SHIM_WRAPPER=1\r\n\"%VITE_PLUS_HOME%\\current\\bin\\vp.exe\" env exec {} -- %*\r\nexit /b %ERRORLEVEL%\r\n",
             bin_name
         );
         tokio::fs::write(&cmd_path, wrapper_content).await?;
@@ -422,7 +424,8 @@ async fn create_package_shim(
             r#"#!/bin/sh
 VITE_PLUS_HOME="$(dirname "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")")"
 export VITE_PLUS_HOME
-exec "$VITE_PLUS_HOME/current/bin/vp.exe" env exec {} "$@"
+export VITE_PLUS_SHIM_WRAPPER=1
+exec "$VITE_PLUS_HOME/current/bin/vp.exe" env exec {} -- "$@"
 "#,
             bin_name
         );

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

@@ -233,12 +233,14 @@ async fn create_windows_shim(
 ) -> Result<(), Error> {
     let cmd_path = bin_dir.join(format!("{tool}.cmd"));
 
-    // Create .cmd wrapper that calls vp env exec <tool>
+    // Create .cmd wrapper that calls vp env exec <tool>.
+    // Use `--` so tool args like `--help` are forwarded to the tool,
+    // not consumed by clap while parsing `vp env exec`.
     // Use a for loop to canonicalize VITE_PLUS_HOME path.
     // %~dp0.. would produce paths like C:\Users\x\.vite-plus\bin\..
     // The for loop resolves this to a clean C:\Users\x\.vite-plus
     let cmd_content = format!(
-        "@echo off\r\nfor %%I in (\"%~dp0..\") do set VITE_PLUS_HOME=%%~fI\r\n\"%VITE_PLUS_HOME%\\current\\bin\\vp.exe\" env exec {} %*\r\nexit /b %ERRORLEVEL%\r\n",
+        "@echo off\r\nfor %%I in (\"%~dp0..\") do set VITE_PLUS_HOME=%%~fI\r\nset VITE_PLUS_SHIM_WRAPPER=1\r\n\"%VITE_PLUS_HOME%\\current\\bin\\vp.exe\" env exec {} -- %*\r\nexit /b %ERRORLEVEL%\r\n",
         tool
     );
 
@@ -252,7 +254,8 @@ async fn create_windows_shim(
         r#"#!/bin/sh
 VITE_PLUS_HOME="$(dirname "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")")"
 export VITE_PLUS_HOME
-exec "$VITE_PLUS_HOME/current/bin/vp.exe" env exec {} "$@"
+export VITE_PLUS_SHIM_WRAPPER=1
+exec "$VITE_PLUS_HOME/current/bin/vp.exe" env exec {} -- "$@"
 "#,
         tool
     );