fix(cli): skip lazyPlugins only while resolving config metadata (#1939)

## Problem

`lazyPlugins` decided whether to run the user's plugin factory from
`VP_COMMAND`. That signal is:

- **overloaded** — `vp run`'s task-discovery config read and a verbatim
build child both see `run`;
- **unnormalized** — the `vp format` alias is `format`, not `fmt`;
- **inherited** by spawned children.

So a Vite build spawned under `vp run` (a verbatim `node build.mjs`
task) or `vp exec` built **without** the user's plugins, while `vp
format` wrongly **loaded** them. (Both were raised in review.)

## Fix

Decide from the resolution intent instead of the command name. The
metadata resolvers (`resolveViteConfig`, migrate's rolldown-compat
check, and the oxlint/oxfmt subprocess) mark that the config is being
loaded only to read a config block, and `lazyPlugins` skips the factory
**only while that marker is set**.

The default is to load, so `dev`/`build`/`test`/`preview` and any
spawned build keep their plugins, regardless of which command launched
them. The marker is scoped to the resolution, so it never leaks to task
children, and it's immune to aliases and not-yet-known commands.

`VP_COMMAND` had no other reader, so it's removed.

Adds snap tests for the two fixed cases (verbatim `vp run` build loads
plugins; `vp format` skips them) plus updated unit tests and docs.

Author: fengmk2

docs/guide/troubleshooting.md

@@ -69,7 +69,7 @@ export default defineConfig({
 
 When `vite.config.ts` imports plugins at the top level, they are evaluated for every command, including `vp lint`, `vp fmt`, editor integrations, and long-lived background processes. This can make config loading slow and may trigger plugin setup side effects, such as reading files, starting watchers, or connecting to services.
 
-Use `lazyPlugins` to load plugins only when the Vite pipeline actually runs (`dev`, `build`, `test`, `preview`):
+Use `lazyPlugins` to skip the plugin factory when vite-plus loads your config only to read a metadata block (`lint`, `fmt`, `check`, `staged`, `pack`, `create`, the `run`/`cache` task lookup, and editor tooling). The plugins still load whenever Vite actually runs, `dev`, `build`, `test`, `preview`, and any build your own scripts spawn (a `vp run` task, `vp exec`):
 
 ```ts [vite.config.ts]
 import { defineConfig, lazyPlugins } from 'vite-plus';

packages/cli/bin/oxfmt

@@ -23,8 +23,11 @@ const oxfmtBin = join(dirname(dirname(oxfmtMainPath)), 'bin', 'oxfmt');
 
 // This allows oxfmt to load vite.config.ts.
 // For `vp check` and `vp fmt`, VP_VERSION is injected by
-// `merge_resolved_envs_with_version()` in `cli.rs`, and VP_COMMAND is injected
-// by `SubcommandResolver::resolve()`.
+// `merge_resolved_envs_with_version()` in `cli.rs`.
 process.env.VP_VERSION = pkg.version;
-process.env.VP_COMMAND ??= 'fmt';
+// oxfmt reads vite.config.ts only for the `fmt` block, so skip the user's
+// Vite plugin factory (lazyPlugins) while the config evaluates.
+// Literal kept in sync with CONFIG_METADATA_ENV in src/utils/constants.ts
+// (this plain-JS bin can't import the bundled constant).
+process.env.VP_RESOLVING_CONFIG_METADATA ??= '1';
 await import(pathToFileURL(oxfmtBin).href);

packages/cli/bin/oxlint

@@ -27,9 +27,12 @@ const tsgolintBin = resolveTsgolintExecutable(
 
 // This allows oxlint to load vite.config.ts.
 // For `vp check` and `vp lint`, VP_VERSION is injected by
-// `merge_resolved_envs_with_version()` in `cli.rs`, and VP_COMMAND is injected
-// by `SubcommandResolver::resolve()`.
+// `merge_resolved_envs_with_version()` in `cli.rs`.
 process.env.VP_VERSION = pkg.version;
-process.env.VP_COMMAND ??= 'lint';
+// oxlint reads vite.config.ts only for the `lint` block, so skip the user's
+// Vite plugin factory (lazyPlugins) while the config evaluates.
+// Literal kept in sync with CONFIG_METADATA_ENV in src/utils/constants.ts
+// (this plain-JS bin can't import the bundled constant).
+process.env.VP_RESOLVING_CONFIG_METADATA ??= '1';
 process.env.OXLINT_TSGOLINT_PATH ??= tsgolintBin;
 await import(pathToFileURL(oxlintBin).href);

packages/cli/binding/src/cli/resolver.rs

@@ -68,13 +68,7 @@ impl SubcommandResolver {
         resolved_vite_config: Option<&ResolvedUniversalViteConfig>,
         envs: &Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
     ) -> anyhow::Result<ResolvedSubcommand> {
-        let command_name = subcommand.command_name();
-        let mut resolved = self.resolve_inner(subcommand, resolved_vite_config, envs).await?;
-        // Inject VP_COMMAND so that defineConfig's plugin factory knows which command is running,
-        // even when the subcommand is synthesized inside `vp run`.
-        let envs = Arc::make_mut(&mut resolved.envs);
-        envs.insert(Arc::from(OsStr::new("VP_COMMAND")), Arc::from(OsStr::new(command_name)));
-        Ok(resolved)
+        self.resolve_inner(subcommand, resolved_vite_config, envs).await
     }
 
     async fn resolve_inner(

packages/cli/binding/src/cli/types.rs

@@ -96,23 +96,6 @@ pub enum SynthesizableSubcommand {
     },
 }
 
-impl SynthesizableSubcommand {
-    /// Return the command name string for use in `VP_COMMAND` env var.
-    pub(super) fn command_name(&self) -> &'static str {
-        match self {
-            Self::Lint { .. } => "lint",
-            Self::Fmt { .. } => "fmt",
-            Self::Build { .. } => "build",
-            Self::Test { .. } => "test",
-            Self::Pack { .. } => "pack",
-            Self::Dev { .. } => "dev",
-            Self::Preview { .. } => "preview",
-            Self::Doc { .. } => "doc",
-            Self::Check { .. } => "check",
-        }
-    }
-}
-
 /// Top-level CLI argument parser for vite-plus.
 #[derive(Debug, Parser)]
 #[command(name = "vp", disable_help_subcommand = true)]

packages/cli/snap-tests/vite-plugins-exec-build/build.mjs

@@ -0,0 +1,8 @@
+// Run a programmatic Vite build, mirroring a downstream framework CLI
+// (e.g. `node framework-cli.js build`) that is spawned underneath `vp exec`.
+// `vp exec` does not load the config for metadata, so the config-metadata
+// marker is unset here; `lazyPlugins` must load the plugins for the build to
+// produce a usable index.html.
+import { build } from 'vite-plus';
+
+await build({ root: import.meta.dirname, logLevel: 'silent' });

packages/cli/snap-tests/vite-plugins-exec-build/index.html

@@ -0,0 +1,8 @@
+<!doctype html>
+<html>
+  <body>
+    <script type="module">
+      console.log('hello');
+    </script>
+  </body>
+</html>

packages/cli/snap-tests/vite-plugins-exec-build/my-plugin.ts

@@ -0,0 +1,8 @@
+export default function myPlugin() {
+  return {
+    name: 'my-exec-build-plugin',
+    transformIndexHtml(html: string) {
+      return html.replace('</body>', '<!-- exec-build-plugin-injected --></body>');
+    },
+  };
+}

packages/cli/snap-tests/vite-plugins-exec-build/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "vite-plugins-exec-build-test",
+  "private": true
+}

packages/cli/snap-tests/vite-plugins-exec-build/snap.txt

@@ -0,0 +1,3 @@
+> vp exec node build.mjs
+> cat dist/index.html | grep 'exec-build-plugin-injected' # vp exec should still load vite plugins from factory
+  <!-- exec-build-plugin-injected --></body>