From 367f25e250257d2207cad052eea9558aef90986e Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Fri, 6 Feb 2026 17:52:24 +0800
Subject: [PATCH] feat(cli): fall back to package manager for `vp run` without
 vite-plus dependency

When `vp run <script>` is executed in a project without `vite-plus` in
dependencies or devDependencies, fall back to `<pm> run <script>` directly
from the Rust layer instead of entering the JS delegation flow. This avoids
unnecessary overhead of downloading Node.js runtime and prompting users to
install vite-plus.

- Add `has_vite_plus_dependency()` utility that walks up from cwd to find
  the nearest package.json and checks for vite-plus
- Add `run_script_command()` / `resolve_run_script_command()` on
  PackageManager for executing `<pm> run <args>`
- Add `run_or_delegate` module that checks dependency before routing
- Add unit tests for dependency detection and command resolution
- Add snap test verifying fallback behavior with pnpm
---
 crates/vite_global_cli/src/cli.rs             |   2 +-
 crates/vite_global_cli/src/commands/mod.rs    | 135 +++++
 .../src/commands/run_or_delegate.rs           |  23 +
 crates/vite_install/src/commands/mod.rs       |   1 +
 crates/vite_install/src/commands/run.rs       | 116 +++++
 .../package.json                              |   9 +
 .../command-run-without-vite-plus/snap.txt    |  18 +
 .../command-run-without-vite-plus/steps.json  |  10 +
 rfcs/run-without-vite-plus-dependency.md      | 469 ++++++++++++++++++
 9 files changed, 782 insertions(+), 1 deletion(-)
 create mode 100644 crates/vite_global_cli/src/commands/run_or_delegate.rs
 create mode 100644 crates/vite_install/src/commands/run.rs
 create mode 100644 packages/global/snap-tests/command-run-without-vite-plus/package.json
 create mode 100644 packages/global/snap-tests/command-run-without-vite-plus/snap.txt
 create mode 100644 packages/global/snap-tests/command-run-without-vite-plus/steps.json
 create mode 100644 rfcs/run-without-vite-plus-dependency.md

diff --git a/crates/vite_global_cli/src/cli.rs b/crates/vite_global_cli/src/cli.rs
index 9e1eea0d22..a365261e32 100644
--- a/crates/vite_global_cli/src/cli.rs
+++ b/crates/vite_global_cli/src/cli.rs
@@ -1538,7 +1538,7 @@ pub async fn run_command(cwd: AbsolutePathBuf, args: Args) -> Result<ExitStatus,
 
         Commands::Fmt { args } => commands::delegate::execute(cwd, "fmt", &args).await,
 
-        Commands::Run { args } => commands::delegate::execute(cwd, "run", &args).await,
+        Commands::Run { args } => commands::run_or_delegate::execute(cwd, &args).await,
 
         Commands::Preview { args } => commands::delegate::execute(cwd, "preview", &args).await,
 
diff --git a/crates/vite_global_cli/src/commands/mod.rs b/crates/vite_global_cli/src/commands/mod.rs
index 6d6bf0ad46..66755176c7 100644
--- a/crates/vite_global_cli/src/commands/mod.rs
+++ b/crates/vite_global_cli/src/commands/mod.rs
@@ -23,12 +23,50 @@
 //! Category C - Local CLI Delegation:
 //! - `delegate`: Local CLI delegation
 
+use std::{collections::HashMap, io::BufReader};
+
 use vite_install::package_manager::PackageManager;
 use vite_path::AbsolutePath;
 use vite_shared::{PrependOptions, prepend_to_path_env};
 
 use crate::{error::Error, js_executor::JsExecutor};
 
+#[derive(serde::Deserialize, Default)]
+#[serde(rename_all = "camelCase")]
+struct DepCheckPackageJson {
+    #[serde(default)]
+    dependencies: HashMap<String, serde_json::Value>,
+    #[serde(default)]
+    dev_dependencies: HashMap<String, serde_json::Value>,
+}
+
+/// Check if vite-plus is listed in the nearest package.json's
+/// dependencies or devDependencies.
+///
+/// Returns `true` if vite-plus is found, `false` if not found
+/// or if no package.json exists.
+pub fn has_vite_plus_dependency(cwd: &AbsolutePath) -> bool {
+    let mut current = cwd;
+    loop {
+        let package_json_path = current.join("package.json");
+        if package_json_path.as_path().exists() {
+            if let Ok(file) = std::fs::File::open(&package_json_path) {
+                if let Ok(pkg) =
+                    serde_json::from_reader::<_, DepCheckPackageJson>(BufReader::new(file))
+                {
+                    return pkg.dependencies.contains_key("vite-plus")
+                        || pkg.dev_dependencies.contains_key("vite-plus");
+                }
+            }
+            return false; // Found package.json but couldn't parse deps → treat as no dependency
+        }
+        match current.parent() {
+            Some(parent) if parent != current => current = parent,
+            _ => return false, // Reached filesystem root
+        }
+    }
+}
+
 /// Ensure a package.json exists in the given directory.
 /// If it doesn't exist, create a minimal one with `{ "type": "module" }`.
 pub async fn ensure_package_json(project_path: &AbsolutePath) -> Result<(), Error> {
@@ -106,6 +144,7 @@ pub mod self_update;
 
 // Category C: Local CLI Delegation
 pub mod delegate;
+pub mod run_or_delegate;
 
 // Re-export command structs for convenient access
 pub use add::AddCommand;
@@ -118,3 +157,99 @@ pub use remove::RemoveCommand;
 pub use unlink::UnlinkCommand;
 pub use update::UpdateCommand;
 pub use why::WhyCommand;
+
+#[cfg(test)]
+mod tests {
+    use vite_path::AbsolutePathBuf;
+
+    use super::*;
+
+    #[test]
+    fn test_has_vite_plus_in_dev_dependencies() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        let temp_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+        std::fs::write(
+            temp_path.join("package.json"),
+            r#"{ "devDependencies": { "vite-plus": "^1.0.0" } }"#,
+        )
+        .unwrap();
+        assert!(has_vite_plus_dependency(&temp_path));
+    }
+
+    #[test]
+    fn test_has_vite_plus_in_dependencies() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        let temp_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+        std::fs::write(
+            temp_path.join("package.json"),
+            r#"{ "dependencies": { "vite-plus": "^1.0.0" } }"#,
+        )
+        .unwrap();
+        assert!(has_vite_plus_dependency(&temp_path));
+    }
+
+    #[test]
+    fn test_no_vite_plus_dependency() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        let temp_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+        std::fs::write(
+            temp_path.join("package.json"),
+            r#"{ "devDependencies": { "vite": "^6.0.0" } }"#,
+        )
+        .unwrap();
+        assert!(!has_vite_plus_dependency(&temp_path));
+    }
+
+    #[test]
+    fn test_no_package_json() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        let temp_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+        assert!(!has_vite_plus_dependency(&temp_path));
+    }
+
+    #[test]
+    fn test_nested_directory_walks_up() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        let temp_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+        std::fs::write(
+            temp_path.join("package.json"),
+            r#"{ "devDependencies": { "vite-plus": "^1.0.0" } }"#,
+        )
+        .unwrap();
+        let child_dir = temp_path.join("child");
+        std::fs::create_dir(&child_dir).unwrap();
+        let child_path = AbsolutePathBuf::new(child_dir.as_path().to_path_buf()).unwrap();
+        assert!(has_vite_plus_dependency(&child_path));
+    }
+
+    #[test]
+    fn test_empty_package_json() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        let temp_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+        std::fs::write(temp_path.join("package.json"), r#"{}"#).unwrap();
+        assert!(!has_vite_plus_dependency(&temp_path));
+    }
+
+    #[test]
+    fn test_nested_dir_stops_at_nearest_package_json() {
+        let temp_dir = tempfile::tempdir().unwrap();
+        let temp_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+        // Parent has vite-plus
+        std::fs::write(
+            temp_path.join("package.json"),
+            r#"{ "devDependencies": { "vite-plus": "^1.0.0" } }"#,
+        )
+        .unwrap();
+        // Child has its own package.json without vite-plus
+        let child_dir = temp_path.join("child");
+        std::fs::create_dir(&child_dir).unwrap();
+        std::fs::write(
+            child_dir.join("package.json"),
+            r#"{ "devDependencies": { "vite": "^6.0.0" } }"#,
+        )
+        .unwrap();
+        let child_path = AbsolutePathBuf::new(child_dir.as_path().to_path_buf()).unwrap();
+        // Should find the child's package.json first and return false
+        assert!(!has_vite_plus_dependency(&child_path));
+    }
+}
diff --git a/crates/vite_global_cli/src/commands/run_or_delegate.rs b/crates/vite_global_cli/src/commands/run_or_delegate.rs
new file mode 100644
index 0000000000..334dd9e497
--- /dev/null
+++ b/crates/vite_global_cli/src/commands/run_or_delegate.rs
@@ -0,0 +1,23 @@
+//! Run command with fallback to package manager when vite-plus is not a dependency.
+
+use std::process::ExitStatus;
+
+use vite_path::AbsolutePathBuf;
+
+use crate::error::Error;
+
+/// Execute `vp run <args>`.
+///
+/// If vite-plus is a dependency, delegate to the local CLI.
+/// If not, fall back to `<pm> run <args>`.
+pub async fn execute(cwd: AbsolutePathBuf, args: &[String]) -> Result<ExitStatus, Error> {
+    if super::has_vite_plus_dependency(&cwd) {
+        tracing::debug!("vite-plus is a dependency, delegating to local CLI");
+        super::delegate::execute(cwd, "run", args).await
+    } else {
+        tracing::debug!("vite-plus is not a dependency, falling back to package manager run");
+        super::prepend_js_runtime_to_path_env(&cwd).await?;
+        let package_manager = super::build_package_manager(&cwd).await?;
+        Ok(package_manager.run_script_command(args, &cwd).await?)
+    }
+}
diff --git a/crates/vite_install/src/commands/mod.rs b/crates/vite_install/src/commands/mod.rs
index a144870cb5..7b16139d87 100644
--- a/crates/vite_install/src/commands/mod.rs
+++ b/crates/vite_install/src/commands/mod.rs
@@ -12,6 +12,7 @@ pub mod pack;
 pub mod prune;
 pub mod publish;
 pub mod remove;
+pub mod run;
 pub mod unlink;
 pub mod update;
 pub mod view;
diff --git a/crates/vite_install/src/commands/run.rs b/crates/vite_install/src/commands/run.rs
new file mode 100644
index 0000000000..6ebfdd430c
--- /dev/null
+++ b/crates/vite_install/src/commands/run.rs
@@ -0,0 +1,116 @@
+use std::{collections::HashMap, process::ExitStatus};
+
+use vite_command::run_command;
+use vite_error::Error;
+use vite_path::AbsolutePath;
+
+use crate::package_manager::{
+    PackageManager, PackageManagerType, ResolveCommandResult, format_path_env,
+};
+
+impl PackageManager {
+    /// Run `<pm> run <args>` to execute a package.json script.
+    pub async fn run_script_command(
+        &self,
+        args: &[String],
+        cwd: impl AsRef<AbsolutePath>,
+    ) -> Result<ExitStatus, Error> {
+        let resolve_command = self.resolve_run_script_command(args);
+        run_command(&resolve_command.bin_path, &resolve_command.args, &resolve_command.envs, cwd)
+            .await
+    }
+
+    /// Resolve the `<pm> run <args>` command.
+    #[must_use]
+    pub fn resolve_run_script_command(&self, args: &[String]) -> ResolveCommandResult {
+        let envs = HashMap::from([("PATH".to_string(), format_path_env(self.get_bin_prefix()))]);
+        let mut cmd_args: Vec<String> = vec!["run".to_string()];
+        cmd_args.extend(args.iter().cloned());
+
+        let bin_path = match self.client {
+            PackageManagerType::Pnpm => "pnpm",
+            PackageManagerType::Npm => "npm",
+            PackageManagerType::Yarn => "yarn",
+        };
+
+        ResolveCommandResult { bin_path: bin_path.to_string(), args: cmd_args, envs }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use tempfile::{TempDir, tempdir};
+    use vite_path::AbsolutePathBuf;
+    use vite_str::Str;
+
+    use super::*;
+
+    fn create_temp_dir() -> TempDir {
+        tempdir().expect("Failed to create temp directory")
+    }
+
+    fn create_mock_package_manager(pm_type: PackageManagerType, version: &str) -> PackageManager {
+        let temp_dir = create_temp_dir();
+        let temp_dir_path = AbsolutePathBuf::new(temp_dir.path().to_path_buf()).unwrap();
+        let install_dir = temp_dir_path.join("install");
+
+        PackageManager {
+            client: pm_type,
+            package_name: pm_type.to_string().into(),
+            version: Str::from(version),
+            hash: None,
+            bin_name: pm_type.to_string().into(),
+            workspace_root: temp_dir_path.clone(),
+            is_monorepo: false,
+            install_dir,
+        }
+    }
+
+    #[test]
+    fn test_pnpm_run_script() {
+        let pm = create_mock_package_manager(PackageManagerType::Pnpm, "10.0.0");
+        let result = pm.resolve_run_script_command(&["dev".into()]);
+        assert_eq!(result.bin_path, "pnpm");
+        assert_eq!(result.args, vec!["run", "dev"]);
+    }
+
+    #[test]
+    fn test_pnpm_run_script_with_args() {
+        let pm = create_mock_package_manager(PackageManagerType::Pnpm, "10.0.0");
+        let result = pm.resolve_run_script_command(&["dev".into(), "--port".into(), "3000".into()]);
+        assert_eq!(result.bin_path, "pnpm");
+        assert_eq!(result.args, vec!["run", "dev", "--port", "3000"]);
+    }
+
+    #[test]
+    fn test_npm_run_script() {
+        let pm = create_mock_package_manager(PackageManagerType::Npm, "11.0.0");
+        let result = pm.resolve_run_script_command(&["dev".into()]);
+        assert_eq!(result.bin_path, "npm");
+        assert_eq!(result.args, vec!["run", "dev"]);
+    }
+
+    #[test]
+    fn test_npm_run_script_with_args() {
+        let pm = create_mock_package_manager(PackageManagerType::Npm, "11.0.0");
+        let result = pm.resolve_run_script_command(&["dev".into(), "--port".into(), "3000".into()]);
+        assert_eq!(result.bin_path, "npm");
+        assert_eq!(result.args, vec!["run", "dev", "--port", "3000"]);
+    }
+
+    #[test]
+    fn test_yarn_run_script() {
+        let pm = create_mock_package_manager(PackageManagerType::Yarn, "4.0.0");
+        let result = pm.resolve_run_script_command(&["build".into()]);
+        assert_eq!(result.bin_path, "yarn");
+        assert_eq!(result.args, vec!["run", "build"]);
+    }
+
+    #[test]
+    fn test_run_script_no_args() {
+        let pm = create_mock_package_manager(PackageManagerType::Pnpm, "10.0.0");
+        let result = pm.resolve_run_script_command(&[]);
+        assert_eq!(result.bin_path, "pnpm");
+        assert_eq!(result.args, vec!["run"]);
+    }
+}
diff --git a/packages/global/snap-tests/command-run-without-vite-plus/package.json b/packages/global/snap-tests/command-run-without-vite-plus/package.json
new file mode 100644
index 0000000000..164242e8db
--- /dev/null
+++ b/packages/global/snap-tests/command-run-without-vite-plus/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "command-run-without-vite-plus",
+  "version": "1.0.0",
+  "scripts": {
+    "hello": "echo hello from script",
+    "greet": "echo greet"
+  },
+  "packageManager": "pnpm@10.19.0"
+}
diff --git a/packages/global/snap-tests/command-run-without-vite-plus/snap.txt b/packages/global/snap-tests/command-run-without-vite-plus/snap.txt
new file mode 100644
index 0000000000..8fdfed245a
--- /dev/null
+++ b/packages/global/snap-tests/command-run-without-vite-plus/snap.txt
@@ -0,0 +1,18 @@
+> vp run hello # should fall back to pnpm run when no vite-plus dependency
+
+> command-run-without-vite-plus@<semver> hello <cwd>
+> echo hello from script
+
+hello from script
+
+> vp run greet --arg1 value1 # should pass through args to pnpm run
+
+> command-run-without-vite-plus@<semver> greet <cwd>
+> echo greet --arg1 value1
+
+greet --arg1 value1
+
+[1]> vp run nonexistent # should show pnpm missing script error
+ ERR_PNPM_NO_SCRIPT  Missing script: nonexistent
+
+Command "nonexistent" not found.
diff --git a/packages/global/snap-tests/command-run-without-vite-plus/steps.json b/packages/global/snap-tests/command-run-without-vite-plus/steps.json
new file mode 100644
index 0000000000..577c449d9c
--- /dev/null
+++ b/packages/global/snap-tests/command-run-without-vite-plus/steps.json
@@ -0,0 +1,10 @@
+{
+  "env": {
+    "VITE_DISABLE_AUTO_INSTALL": "1"
+  },
+  "commands": [
+    "vp run hello # should fall back to pnpm run when no vite-plus dependency",
+    "vp run greet --arg1 value1 # should pass through args to pnpm run",
+    "vp run nonexistent # should show pnpm missing script error"
+  ]
+}
diff --git a/rfcs/run-without-vite-plus-dependency.md b/rfcs/run-without-vite-plus-dependency.md
new file mode 100644
index 0000000000..d7157fdb57
--- /dev/null
+++ b/rfcs/run-without-vite-plus-dependency.md
@@ -0,0 +1,469 @@
+# RFC: `vp run` Without vite-plus Dependency
+
+## Summary
+
+Allow `vp run <script>` to work in projects that do not have `vite-plus` as a dependency. When vite-plus is not found in the nearest `package.json`'s `dependencies` or `devDependencies`, fall back to executing `<package-manager> run <script> [args...]` directly from the Rust layer, bypassing the JS delegation entirely.
+
+## Motivation
+
+Currently, all Category C commands (`vp run`, `vp build`, `vp test`, `vp lint`, `vp dev`, `vp fmt`, `vp preview`, `vp cache`) delegate to the local vite-plus CLI via the JS layer. When vite-plus is not installed as a dependency, `packages/global/src/local/bin.ts` prompts the user to add it to devDependencies:
+
+```
+Local "vite-plus" package was not found
+? Do you want to add vite-plus to devDependencies? (Y/n)
+```
+
+If the user declines, it exits with:
+
+```
+Please add vite-plus to devDependencies first
+```
+
+This creates several issues:
+
+1. **Barrier to adoption**: Users who install `vp` globally cannot use `vp run dev` as a drop-in replacement for `pnpm run dev` without first adding vite-plus to their project
+2. **Unnecessary overhead**: The current flow downloads a Node.js runtime and enters the JS layer just to discover that vite-plus is missing
+3. **Friction in existing projects**: Projects that want to use `vp` for its managed Node.js runtime and package manager features (install, add, remove) but not the task runner are blocked from using `vp run`
+
+### Current Pain Points
+
+```bash
+# User installs vp globally and tries to use it
+$ vp run dev
+Local "vite-plus" package was not found
+? Do you want to add vite-plus to devDependencies? (Y/n) n
+Please add vite-plus to devDependencies first
+
+# User just wants the equivalent of:
+$ pnpm run dev
+```
+
+### Proposed Solution
+
+```bash
+# Without vite-plus as a dependency, falls back to PM run
+$ vp run dev
+# Executes: pnpm run dev (or npm/yarn depending on project)
+
+# With vite-plus as a dependency, uses full task runner
+$ vp run build -r
+# Executes via vite-plus task runner with recursive + topological ordering
+```
+
+## Proposed Solution
+
+### Detection Logic
+
+Check the nearest `package.json` from the current working directory for `vite-plus` in `dependencies` or `devDependencies`. This matches the existing JS-side behavior in `hasVitePlusDependency(readNearestPackageJson(cwd))`.
+
+**Decision: Check `package.json` only, NOT `node_modules`**
+
+- If vite-plus is listed in `package.json` but not installed, the existing JS layer handles auto-installation
+- If vite-plus is NOT listed in `package.json`, we fall back to PM run
+- Checking `node_modules` would be fragile (hoisted deps, workspaces) and inconsistent with the intent
+
+### Scope
+
+This RFC applies **only to `vp run`**. Other Category C commands (`build`, `test`, `lint`, `dev`, `fmt`, `preview`, `cache`) are vite-plus specific features and do not have natural PM fallbacks:
+
+- `vp build` = Vite build (not `pnpm build`)
+- `vp test` = Vitest (not `pnpm test`)
+- `vp lint` = OxLint (not `pnpm lint`)
+
+These should continue to delegate to the local CLI and prompt for vite-plus installation.
+
+### Command Mapping
+
+When falling back to PM run, all arguments are passed through as-is:
+
+| `vp run` invocation      | Fallback command           | Notes                    |
+| ------------------------ | -------------------------- | ------------------------ |
+| `vp run dev`             | `pnpm run dev`             | Basic script execution   |
+| `vp run dev --port 3000` | `pnpm run dev --port 3000` | Args passed through      |
+| `vp run build -r`        | `pnpm run build -r`        | PM ignores unknown flags |
+| `vp run app#build`       | `pnpm run app#build`       | PM treats as script name |
+
+vite-plus specific flags (`-r`, `--recursive`, `--topological`, `package#task` syntax) are only meaningful when vite-plus is installed. When falling back, these are passed verbatim to the PM which will naturally error with "Missing script" -- this is correct behavior since these features require vite-plus.
+
+### Architecture: Rust-Side Fallback
+
+The fallback is implemented in the Rust layer, **before** entering the JS delegation flow. This avoids the unnecessary overhead of downloading Node.js runtime and entering the JS layer.
+
+```
+                  vp run <args>
+                       |
+               has_vite_plus_dependency(cwd)?
+                   /        \
+                 yes         no
+                  |           |
+          delegate to JS     build PM
+          (existing flow)      |
+                          <pm> run <args>
+```
+
+## Implementation Architecture
+
+### 1. Dependency Check Utility
+
+**File**: `crates/vite_global_cli/src/commands/mod.rs`
+
+A utility function that walks up from `cwd` to find the nearest `package.json` and checks for vite-plus:
+
+```rust
+use std::collections::HashMap;
+use std::io::BufReader;
+
+#[derive(serde::Deserialize, Default)]
+#[serde(rename_all = "camelCase")]
+struct DepCheckPackageJson {
+    #[serde(default)]
+    dependencies: HashMap<String, serde_json::Value>,
+    #[serde(default)]
+    dev_dependencies: HashMap<String, serde_json::Value>,
+}
+
+/// Check if vite-plus is listed in the nearest package.json's
+/// dependencies or devDependencies.
+///
+/// Returns `true` if vite-plus is found, `false` if not found
+/// or if no package.json exists.
+pub fn has_vite_plus_dependency(cwd: &AbsolutePath) -> bool {
+    let mut current = cwd;
+    loop {
+        let package_json_path = current.join("package.json");
+        if package_json_path.exists() {
+            if let Ok(file) = std::fs::File::open(&package_json_path) {
+                if let Ok(pkg) = serde_json::from_reader::<_, DepCheckPackageJson>(
+                    BufReader::new(file)
+                ) {
+                    return pkg.dependencies.contains_key("vite-plus")
+                        || pkg.dev_dependencies.contains_key("vite-plus");
+                }
+            }
+            return false; // Found package.json but couldn't parse deps → treat as no dependency
+        }
+        match current.parent() {
+            Some(parent) if parent != current => current = parent,
+            _ => return false, // Reached filesystem root
+        }
+    }
+}
+```
+
+### 2. PM Run Command
+
+**File**: `crates/vite_install/src/commands/run.rs` (new file)
+
+Following the established pattern from `dlx.rs`:
+
+```rust
+use std::{collections::HashMap, process::ExitStatus};
+use vite_command::run_command;
+use vite_error::Error;
+use vite_path::AbsolutePath;
+use crate::package_manager::{PackageManager, PackageManagerType, ResolveCommandResult, format_path_env};
+
+impl PackageManager {
+    /// Run `<pm> run <args>` to execute a package.json script.
+    pub async fn run_script_command(
+        &self,
+        args: &[String],
+        cwd: impl AsRef<AbsolutePath>,
+    ) -> Result<ExitStatus, Error> {
+        let resolve_command = self.resolve_run_script_command(args);
+        run_command(&resolve_command.bin_path, &resolve_command.args, &resolve_command.envs, cwd)
+            .await
+    }
+
+    /// Resolve the `<pm> run <args>` command.
+    #[must_use]
+    pub fn resolve_run_script_command(&self, args: &[String]) -> ResolveCommandResult {
+        let envs = HashMap::from([("PATH".to_string(), format_path_env(self.get_bin_prefix()))]);
+        let mut cmd_args: Vec<String> = vec!["run".to_string()];
+        cmd_args.extend(args.iter().cloned());
+
+        let bin_path = match self.client {
+            PackageManagerType::Pnpm => "pnpm",
+            PackageManagerType::Npm => "npm",
+            PackageManagerType::Yarn => "yarn",
+        };
+
+        ResolveCommandResult {
+            bin_path: bin_path.to_string(),
+            args: cmd_args,
+            envs,
+        }
+    }
+}
+```
+
+**Register**: Add `pub mod run;` to `crates/vite_install/src/commands/mod.rs`
+
+### 3. Run-or-Delegate Orchestration
+
+**File**: `crates/vite_global_cli/src/commands/run_or_delegate.rs` (new file)
+
+```rust
+//! Run command with fallback to package manager when vite-plus is not a dependency.
+
+use std::process::ExitStatus;
+use vite_path::AbsolutePathBuf;
+use crate::error::Error;
+
+/// Execute `vp run <args>`.
+///
+/// If vite-plus is a dependency, delegate to the local CLI.
+/// If not, fall back to `<pm> run <args>`.
+pub async fn execute(
+    cwd: AbsolutePathBuf,
+    args: &[String],
+) -> Result<ExitStatus, Error> {
+    if super::has_vite_plus_dependency(&cwd) {
+        tracing::debug!("vite-plus is a dependency, delegating to local CLI");
+        super::delegate::execute(cwd, "run", args).await
+    } else {
+        tracing::debug!("vite-plus is not a dependency, falling back to package manager run");
+        super::prepend_js_runtime_to_path_env(&cwd).await?;
+        let package_manager = super::build_package_manager(&cwd).await?;
+        Ok(package_manager.run_script_command(args, &cwd).await?)
+    }
+}
+```
+
+### 4. CLI Dispatch Update
+
+**File**: `crates/vite_global_cli/src/cli.rs`, line 1541
+
+```rust
+// Before:
+Commands::Run { args } => commands::delegate::execute(cwd, "run", &args).await,
+
+// After:
+Commands::Run { args } => commands::run_or_delegate::execute(cwd, &args).await,
+```
+
+## Design Decisions
+
+### 1. Rust-Side vs JS-Side Fallback
+
+**Decision**: Implement the fallback in the Rust layer.
+
+**Rationale**:
+
+- **Performance**: Avoids downloading Node.js runtime and entering JS layer when unnecessary
+- **Consistency**: Follows the same pattern as other PM commands (install, add, remove) which are Rust-native
+- **Reuse**: Leverages existing `build_package_manager()` and `prepend_js_runtime_to_path_env()` utilities
+
+**Alternative rejected**: Modifying `packages/global/src/local/bin.ts` to add a PM fallback would work but still require downloading Node.js first.
+
+### 2. Check Nearest package.json Only
+
+**Decision**: Walk up from `cwd` to find the nearest `package.json`, check only that file.
+
+**Rationale**:
+
+- Matches the existing JS-side behavior (`readNearestPackageJson(cwd)`)
+- In a monorepo, a sub-package without vite-plus in its own package.json should still fall back even if the root has it -- the user is running from that package's context
+- Simple, predictable behavior
+
+**Alternative rejected**: Checking all ancestor package.json files up to workspace root would be more permissive but inconsistent with JS-side behavior.
+
+### 3. Return `false` When No package.json Found
+
+**Decision**: When no `package.json` exists at all, treat as "no vite-plus dependency" and fall back to PM run.
+
+**Rationale**:
+
+- `build_package_manager()` will fail with "No package.json found" which is already a clear error
+- No special error handling needed
+- Consistent with PM commands that also require package.json
+
+### 4. Scope Limited to `vp run`
+
+**Decision**: Only `vp run` gets the PM fallback. Other commands (`build`, `test`, `lint`, etc.) continue requiring vite-plus.
+
+**Rationale**:
+
+- `vp run <script>` maps naturally to `<pm> run <script>`
+- `vp build` means "Vite build", not `<pm> run build` -- there's no meaningful fallback
+- This keeps the behavior clear and predictable
+
+### 5. Pass-Through All Arguments
+
+**Decision**: All arguments after `run` are passed verbatim to the PM.
+
+**Rationale**:
+
+- Simple implementation with no argument rewriting
+- vite-plus specific flags (`-r`, `package#task`) are meaningless without vite-plus
+- PM will naturally error on unknown flags/scripts
+
+## Error Handling
+
+### No package.json Found
+
+```bash
+$ cd /tmp && vp run dev
+No package.json found.
+```
+
+This comes from `build_package_manager()` which is the standard error for all PM commands.
+
+### Script Not Found
+
+```bash
+$ vp run nonexistent
+# Falls back to: pnpm run nonexistent
+ ERR_PNPM_NO_SCRIPT  Missing script: nonexistent
+```
+
+Standard PM error, no special handling needed.
+
+### No Package Manager Detected
+
+When `package.json` exists but has no `packageManager` field and no lockfiles:
+
+```bash
+$ vp run dev
+# build_package_manager prompts for PM selection (existing behavior)
+```
+
+## User Experience
+
+### Without vite-plus Dependency
+
+```bash
+# package.json has scripts.dev but no vite-plus dependency
+$ vp run dev
+# Detects pnpm (from pnpm-lock.yaml)
+# Executes: pnpm run dev
+> my-app@1.0.0 dev
+> vite
+  VITE v6.0.0  ready in 200ms
+```
+
+### With vite-plus Dependency
+
+```bash
+# package.json has vite-plus in devDependencies
+$ vp run build -r
+# Delegates to local vite-plus CLI
+# Uses task runner with recursive + topological ordering
+  my-lib  build  done in 1.2s
+  my-app  build  done in 2.3s
+```
+
+### Mixed Monorepo
+
+```bash
+# Root package.json has vite-plus, sub-package does not
+/workspace$ vp run dev          # → delegates to vite-plus (found in root deps)
+/workspace/legacy-pkg$ vp run dev  # → falls back to PM run (not in legacy-pkg's deps)
+```
+
+## Testing Strategy
+
+### Unit Tests
+
+**`has_vite_plus_dependency` tests:**
+
+```rust
+#[test]
+fn test_has_vite_plus_in_dev_dependencies() {
+    // package.json: { "devDependencies": { "vite-plus": "^1.0.0" } }
+    // → returns true
+}
+
+#[test]
+fn test_has_vite_plus_in_dependencies() {
+    // package.json: { "dependencies": { "vite-plus": "^1.0.0" } }
+    // → returns true
+}
+
+#[test]
+fn test_no_vite_plus_dependency() {
+    // package.json: { "devDependencies": { "vite": "^6.0.0" } }
+    // → returns false
+}
+
+#[test]
+fn test_no_package_json() {
+    // Empty temp directory
+    // → returns false
+}
+
+#[test]
+fn test_nested_directory_walks_up() {
+    // parent/package.json has vite-plus, cwd is parent/child/
+    // → returns true
+}
+```
+
+**`resolve_run_script_command` tests:**
+
+```rust
+#[test]
+fn test_pnpm_run_script() {
+    let pm = create_mock_package_manager(PackageManagerType::Pnpm, "10.0.0");
+    let result = pm.resolve_run_script_command(&["dev".into()]);
+    assert_eq!(result.bin_path, "pnpm");
+    assert_eq!(result.args, vec!["run", "dev"]);
+}
+
+#[test]
+fn test_npm_run_script_with_args() {
+    let pm = create_mock_package_manager(PackageManagerType::Npm, "11.0.0");
+    let result = pm.resolve_run_script_command(&["dev".into(), "--port".into(), "3000".into()]);
+    assert_eq!(result.bin_path, "npm");
+    assert_eq!(result.args, vec!["run", "dev", "--port", "3000"]);
+}
+
+#[test]
+fn test_yarn_run_script() {
+    let pm = create_mock_package_manager(PackageManagerType::Yarn, "4.0.0");
+    let result = pm.resolve_run_script_command(&["build".into()]);
+    assert_eq!(result.bin_path, "yarn");
+    assert_eq!(result.args, vec!["run", "build"]);
+}
+```
+
+## Backward Compatibility
+
+- **Projects with vite-plus**: No change in behavior. The `has_vite_plus_dependency` check passes, and delegation proceeds as before.
+- **Projects without vite-plus**: Previously errored or prompted for installation. Now works by falling back to PM run.
+- **No breaking changes**: This is strictly additive behavior.
+
+## Future Enhancements
+
+### 1. Extend to Other Commands
+
+If demand exists, other commands could gain PM fallbacks:
+
+```bash
+vp dev   → <pm> run dev   (when no vite-plus)
+vp build → <pm> run build (when no vite-plus)
+```
+
+This would require a separate RFC and careful consideration of when `vp build` should mean "Vite build" vs "run the build script".
+
+### 2. Informational Message
+
+Optionally show a message when falling back:
+
+```bash
+$ vp run dev
+(vite-plus not found, using pnpm run)
+> my-app@1.0.0 dev
+```
+
+This could be controlled by a `--verbose` flag or shown only once.
+
+## Files Changed
+
+| File                                                     | Action | Description                                                          |
+| -------------------------------------------------------- | ------ | -------------------------------------------------------------------- |
+| `crates/vite_global_cli/src/commands/mod.rs`             | Modify | Add `has_vite_plus_dependency()` + register `run_or_delegate` module |
+| `crates/vite_global_cli/src/commands/run_or_delegate.rs` | Create | Orchestration: check deps, delegate or fallback                      |
+| `crates/vite_install/src/commands/mod.rs`                | Modify | Register `pub mod run;`                                              |
+| `crates/vite_install/src/commands/run.rs`                | Create | PM `run` command resolution                                          |
+| `crates/vite_global_cli/src/cli.rs`                      | Modify | Update dispatch at line 1541                                         |