From 66eb0ea56210b1f2c4b8e2fe91fb23f465b8c663 Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Sun, 6 Sep 2026 22:41:50 +0800
Subject: [PATCH 1/9] docs: propose shared Vite core module identity

---
 rfcs/vite-core-module-identity.md | 299 ++++++++++++++++++++++++++++++
 1 file changed, 299 insertions(+)
 create mode 100644 rfcs/vite-core-module-identity.md

diff --git a/rfcs/vite-core-module-identity.md b/rfcs/vite-core-module-identity.md
new file mode 100644
index 0000000000..5e2e294d8d
--- /dev/null
+++ b/rfcs/vite-core-module-identity.md
@@ -0,0 +1,299 @@
+# RFC: Share the Vite Core Runtime Through One Dependency Name
+
+- Status: Proposed
+- Issue: [#1391](https://github.com/voidzero-dev/vite-plus/issues/1391)
+- Related: [Core package bundling](../packages/core/BUNDLING.md),
+  [CLI package bundling](../packages/cli/BUNDLING.md),
+  [Core binding resolution](./core-binding-resolution.md)
+
+## Proposal
+
+Use `vite` as the dependency name for the core runtime throughout `vite-plus`.
+The CLI will depend on an exact alias to `@voidzero-dev/vite-plus-core`. Its
+runtime imports, public re-exports, and generated shims will use that alias.
+
+This applies the dependency change suggested in #1391 to the CLI's API surface
+as well as its command resolver. User plugins and the CLI can then resolve the
+same dependency under the same name.
+
+## Problem
+
+A migrated project can have this manifest:
+
+```json
+{
+  "devDependencies": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
+    "vite-plus": "0.3.0"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0"
+  }
+}
+```
+
+The `vite-plus` package also depends on `@voidzero-dev/vite-plus-core` under its
+published name. Bun installs two copies:
+
+```text
+node_modules/vite/                          # project's alias
+node_modules/@voidzero-dev/vite-plus-core/  # CLI's dependency
+```
+
+Node loads these paths as separate modules even though the package versions
+match. `vp dev` creates the server through the second copy. TanStack Start
+imports `isRunnableDevEnvironment` from the first copy through `vite`.
+
+Vite implements the guard with `environment instanceof RunnableDevEnvironment`.
+The constructor belongs to a different module instance, so the guard returns
+`false`. TanStack skips its SSR middleware, and requests to `/` return HTTP 404
+with `Cannot GET /`.
+
+The public `vite-plus` entry point also re-exports the second copy. Changing
+the command resolver to start the first copy reverses the mismatch: TanStack's
+guard passes, but the guard exported by `vite-plus` fails.
+
+## Goals and scope
+
+For a project with matching Vite+ versions and compatible peer dependencies,
+`vp dev`, imports from `vite`, and Vite APIs exported by `vite-plus` must share
+one core runtime. The same rule applies to ESM, CommonJS, and the module-runner
+exports.
+
+The CLI must use its declared core dependency without depending on a hoisted
+copy under the canonical package name. A project that uses `vite-plus` alone
+must retain access to the bundled commands and public APIs.
+
+This proposal addresses duplication caused by the alias and canonical
+dependency names. Package managers can still install separate versions or
+peer variants under one name. The validation plan covers those layouts; this
+RFC does not propose a process-wide module loader hook or constructor registry.
+
+## Design
+
+### Dependency declaration
+
+Replace the CLI's core dependency in `packages/cli/package.json` with a
+workspace alias:
+
+```json
+{
+  "dependencies": {
+    "vite": "workspace:@voidzero-dev/vite-plus-core@*"
+  }
+}
+```
+
+The release packer must emit an exact npm alias. For the version used in the
+prototype, the packed dependency is:
+
+```json
+{
+  "dependencies": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0"
+  }
+}
+```
+
+Preview and local-registry builds must preserve their corresponding exact
+core version or artifact reference. Add packing assertions for these flows;
+the committed manifest must not contain a release-specific version pin.
+
+The proposed dependency graph is:
+
+```mermaid
+flowchart TD
+  app["project"] --> cli["vite-plus"]
+  app -->|"vite alias"| core["@voidzero-dev/vite-plus-core"]
+  cli -->|"vite alias, exact pin"| core
+  plugins["Vite plugins"] -.->|"import from vite"| core
+```
+
+The diagram describes the target for matching versions and peer contexts. The
+package-manager integration tests must establish runtime identity in the
+supported layouts.
+
+### Imports and generated exports
+
+Change import specifiers that refer to the CLI's core dependency from
+`@voidzero-dev/vite-plus-core` to `vite`, including subpaths:
+
+| Source                                    | Required change                                                         |
+| ----------------------------------------- | ----------------------------------------------------------------------- |
+| `packages/cli/src/index.ts`, `index.cts`  | Re-export Vite APIs through `vite` in both module formats               |
+| `packages/cli/src/pack.ts`, `pack-bin.ts` | Import the bundled tsdown API through `vite/pack`                       |
+| `packages/cli/build.ts`                   | Generate module-runner, internal, client, and type shims through `vite` |
+| `packages/cli/src/define-config.ts`       | Update type imports and review the module augmentation                  |
+| Migration and build metadata readers      | Resolve the declared alias when reading the CLI's core dependency       |
+
+Separate the dependency specifier from the published package identity in build
+helpers. Keep `@voidzero-dev/vite-plus-core` as the package name in npm alias
+targets, version checks, registry records, and toolchain metadata. Do not apply
+a repository-wide string replacement.
+
+Review the `UserConfig` augmentation in `define-config.ts` with declaration
+generation enabled. Vitest augments `vite` too, so the implementation must
+check both augmentations together and retain the public Vite+ configuration
+types.
+
+### Command resolution and version checks
+
+Resolve `vite` relative to the selected `vite-plus` package before starting a
+Vite-backed command. That anchor must match the CLI's static re-exports.
+Choosing a project copy first could start one runtime while the API exports
+another.
+
+The existing `resolveBundled()` helper prefers the CLI's location but permits
+a project fallback. Use a resolver without that fallback for the required
+core dependency. If the selected package cannot resolve its declared alias,
+report the incomplete installation.
+
+Before invoking a core-specific command entry, read the resolved
+`vite/package.json` and check:
+
+1. Its `name` is `@voidzero-dev/vite-plus-core`.
+2. Its version matches the selected CLI's expected core release.
+3. The command entry exists in that package.
+
+The check must distinguish the core package version from its bundled Vite
+version. For example, core `0.3.0` bundles Vite `8.2.2`.
+
+If the active project's `vite` resolves to upstream Vite or a different core
+version, report the expected and actual packages and their locations. Ask the
+user to align the aliases and reinstall. A project without a resolvable
+top-level `vite` may use the CLI's declared dependency. A matching version in
+a different peer context needs the layout validation described below; version
+equality alone does not establish module identity.
+
+Apply these checks before the CLI starts Vite or loads its packaging entry.
+Retain the distinction between pure `vite.defineConfig()` and the Vite+
+configuration helper, which injects Vite+ plugins.
+
+### Compatibility and installation
+
+Projects retain `vite` aliases that target `@voidzero-dev/vite-plus-core`.
+Upgrading the CLI and aligning the existing aliases to the same release gives
+the package manager the proposed dependency graph. No new alias target is
+required by this design.
+
+The CLI's dependency remains required and exact-pinned. Replacing it with a
+peer dependency would make bundled commands depend on the user's installation.
+
+Audit the release and preview packers, local npm registry, toolchain manifest,
+and migration metadata readers for canonical-name resolution assumptions.
+Keep standalone core installations and their native binding resolution intact.
+Consumers that import core by its published name must declare that dependency;
+they cannot rely on the CLI exposing it through hoisting.
+
+## Prototype results
+
+The investigation used repository commit
+`b87593c580ed5d7c6932f60468df474909990f96` and the
+[issue reproduction](https://github.com/keyding/vite-plus-tanstack-start-ssr-broken/tree/2fc3db690c09fa877439b6d653641362e35f965e).
+The experiments used published Vite+ and core `0.3.0` artifacts, bundled Vite
+`8.2.2`, TanStack Start `1.168.49`, Node `24.14.1`, and macOS arm64.
+
+The dependency prototype repacked the CLI with the alias dependency and
+rewrote core references in its built files. Fresh installs produced these
+results:
+
+| Package manager | `GET /`  | Same environment guard from `vite` and `vite-plus` |
+| --------------- | -------- | -------------------------------------------------- |
+| Bun `1.4.2`     | HTTP 200 | Yes                                                |
+| npm `11.11.0`   | HTTP 200 | Yes                                                |
+| pnpm `10.30.1`  | HTTP 200 | Yes                                                |
+
+API probes confirmed identity for `createServer`, `mergeConfig`,
+`DevEnvironment`, the runnable factory, and both environment guards across
+ESM and CommonJS. The module-runner exports shared `ModuleRunner` too. The
+pure Vite `defineConfig()` retained its identity-function behavior.
+
+A focused `vp test` case passed. Importing the packaging API and running
+`vp pack --help` also succeeded. These experiments establish feasibility;
+they did not build the proposed source changes or run full build, migration,
+type, and ecosystem suites.
+
+## Alternatives
+
+### Change only the CLI resolver
+
+Starting the project's alias returned HTTP 200 in the reproduction. The core
+guard then returned `false`, so the CLI's public re-exports still disagreed with
+the active server. The dependency and export changes are part of this RFC for
+that reason.
+
+### Shared markers in upstream Vite
+
+Vite could mark `RunnableDevEnvironment` and `FetchableDevEnvironment` with
+`Symbol.for(...)` keys and let their guards accept those markers across module
+copies. A prototype retained both physical copies, passed 42 checks, and
+restored HTTP 200. The checks covered both import directions, subclasses,
+wrong-kind environments, and guarding without initializing the lazy runner.
+
+This is a useful upstream improvement. It fixes those guards while leaving
+other constructor identities and module state separate. Old unpatched guards
+also cannot recognize a marker from another copy. Pursue it as a separate
+change with an upstream compatibility policy for the symbol keys.
+
+### Thin Vite compatibility package
+
+A new alias target could re-export core through a declared canonical
+dependency. The CLI would retain its current dependency. A forwarding-package
+prototype returned HTTP 200 and shared runtime identity with Bun `1.4.2`, npm
+`11.11.0`, and pnpm `11.24.0`.
+
+That design needs a new published package, complete Vite exports and types,
+client asset handling, and changes to migration and release tooling. It remains
+an alternative if changing the CLI's dependency specifier causes compatibility
+problems that the implementation cannot resolve.
+
+### Alias `vite` to `vite-plus`
+
+The alias `npm:vite-plus@0.3.0` restored SSR, but changed
+`vite.defineConfig({})` into a call that returns a new object with injected
+plugins. It also adds a `vite-plus` -> `vitest/config` -> `vite` import cycle.
+The proposed design retains the pure Vite API at `vite`.
+
+### Postinstall symlink repair
+
+Pointing the canonical core directory at the alias fixes the reproduction.
+Supporting that repair would require handling reinstalls, nested dependency
+layouts, and package managers that do not use `node_modules`. Declare the
+intended dependency graph instead of repairing it after installation.
+
+## Implementation and validation
+
+Implement the dependency, imports, generated shims, and resolver as one
+behavior change. Splitting their rollout would expose mixed runtime identities
+or imports of an undeclared dependency.
+
+Use packed source builds through the
+[local npm registry](../CONTRIBUTING.md#test-vp-migrate--vp-create-through-a-local-npm-registry).
+Workspace links can conceal the alias duplication. Add CLI regressions to the
+[PTY snapshot suite](../crates/vp_cli_snapshots/tests/cli_snapshots/README.md)
+and API/type coverage in the corresponding package tests.
+
+| Area                        | Required coverage                                                                                                        |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| SSR regression              | Original TanStack reproduction and latest supported TanStack; HTTP 200 and both guards pass                              |
+| Module identity             | ESM, CommonJS, module-runner, and CLI-created environments share the expected APIs                                       |
+| Package layouts             | Bun, npm, pnpm, Yarn with `node_modules`, Yarn PnP, pnpm global virtual store, and monorepos with separate peer contexts |
+| CLI without a project alias | Install `vite-plus` alone; resolve bundled commands and public APIs from its required dependency                         |
+| Invalid installations       | Missing dependency, upstream Vite override, stale core alias, and version mismatch produce actionable CLI errors         |
+| Types and commands          | Generated declarations, Vite/Vitest config augmentation, `vp dev`, `vp build`, `vp preview`, `vp test`, and `vp pack`    |
+| Distribution                | Release, preview, and local-registry tarballs declare the intended alias and retain standalone core binding support      |
+| Upgrade                     | Reinstall an existing project with the new CLI and matching aliases; exercise migration and version synchronization      |
+
+The release gate is a source-built install that shares runtime identity in the
+supported layouts. If a package manager creates separate peer variants that
+break the regression, resolve that case before shipping or revise this design.
+
+## Open questions
+
+1. Can the CLI's alias dependency and each plugin's Vite peer resolve to the
+   same runtime across the supported monorepo and PnP layouts? The prototype
+   covered single-project installs.
+2. Which existing configuration types require changes when the CLI augments
+   `vite` alongside Vitest? Declaration tests must settle this before release.
+3. Should a separate upstream Vite change add shared environment markers even
+   after this dependency change removes the duplication in #1391?

From db496d392aa14f7c5fd175fe616f74bb016c0427 Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Sun, 6 Sep 2026 23:11:58 +0800
Subject: [PATCH 2/9] fix(cli): share Vite runtime through the core alias

---
 .github/workflows/publish-preview.yml         |  9 ++
 .../core_module_identity/check-api.mjs        | 29 ++++++
 .../core_module_identity/check-bundled.mjs    | 12 +++
 .../fixtures/core_module_identity/entry.js    |  1 +
 .../core_module_identity/identity.test.js     | 11 +++
 .../fixtures/core_module_identity/index.html  |  3 +
 .../core_module_identity/package.json         | 13 +++
 .../core_module_identity/snapshots.toml       | 93 +++++++++++++++++++
 .../snapshots/core_module_identity_bun.md     | 21 +++++
 .../snapshots/core_module_identity_npm.md     | 24 +++++
 .../snapshots/core_module_identity_pnpm.md    | 30 ++++++
 .../core_module_identity_pnpm_global_store.md | 31 +++++++
 ...core_module_identity_pnpm_peer_contexts.md | 70 ++++++++++++++
 ...e_module_identity_without_project_alias.md | 77 +++++++++++++++
 .../snapshots/core_module_identity_yarn.md    | 32 +++++++
 .../core_module_identity/vite.config.ts       | 46 +++++++++
 .../core_resolution_errors/package.json       |  5 +
 .../core_resolution_errors/snapshots.toml     | 17 ++++
 .../snapshots/core_resolution_stale_core.md   | 21 +++++
 .../core_resolution_upstream_vite.md          | 21 +++++
 packages/cli/BUNDLING.md                      | 27 ++++--
 packages/cli/build.ts                         | 25 +++--
 packages/cli/package.json                     |  3 +-
 .../__tests__/define-config-plugins.spec.ts   |  2 +-
 .../define-config-vitest-resolver.spec.ts     |  2 +-
 .../cli/src/__tests__/resolve-core.spec.ts    | 88 ++++++++++++++++++
 packages/cli/src/define-config.ts             | 20 +---
 packages/cli/src/index.cts                    |  2 +-
 packages/cli/src/index.ts                     |  2 +-
 .../cli/src/migration/__tests__/tsup.spec.ts  |  2 +-
 packages/cli/src/migration/migrator/tsup.ts   |  2 +-
 packages/cli/src/pack-bin.ts                  |  4 +-
 packages/cli/src/pack.ts                      |  4 +-
 packages/cli/src/resolve-core.ts              | 53 +++++++++++
 packages/cli/src/resolve-pack.ts              |  2 +
 packages/cli/src/resolve-vite.ts              | 14 +--
 .../src/__tests__/install-global-cli.spec.ts  | 42 +++++++++
 packages/tools/src/install-global-cli.ts      | 41 +++++---
 pnpm-lock.yaml                                |  9 +-
 rfcs/vite-core-module-identity.md             | 27 +++---
 40 files changed, 856 insertions(+), 81 deletions(-)
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-api.mjs
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-bundled.mjs
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/entry.js
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/identity.test.js
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/index.html
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/package.json
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_bun.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_global_store.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_peer_contexts.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_without_project_alias.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_yarn.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/vite.config.ts
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/package.json
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots.toml
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots/core_resolution_stale_core.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots/core_resolution_upstream_vite.md
 create mode 100644 packages/cli/src/__tests__/resolve-core.spec.ts
 create mode 100644 packages/cli/src/resolve-core.ts
 create mode 100644 packages/tools/src/__tests__/install-global-cli.spec.ts

diff --git a/.github/workflows/publish-preview.yml b/.github/workflows/publish-preview.yml
index 3c3896ece1..13c82745bc 100644
--- a/.github/workflows/publish-preview.yml
+++ b/.github/workflows/publish-preview.yml
@@ -98,6 +98,15 @@ jobs:
       - name: Install dependencies
         run: pnpm install
 
+      # The registry bridge rewrites dependencies by package name. Stamp core
+      # before pnpm pack so the dependency named `vite` already aliases the
+      # preview version. Keep the CLI manifest aligned with its built dist too.
+      - name: Set preview package versions
+        run: |
+          for package in cli core; do
+            pnpm exec json-edit "packages/$package/package.json" '_.version = process.env.VERSION'
+          done
+
       - name: Download cli dist
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-api.mjs b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-api.mjs
new file mode 100644
index 0000000000..573b1212d6
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-api.mjs
@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+import * as vite from 'vite';
+import { ModuleRunner } from 'vite/module-runner';
+import * as vp from 'vite-plus';
+import { ModuleRunner as VpModuleRunner } from 'vite-plus/module-runner';
+import pkg from 'vite-plus/package.json' with { type: 'json' };
+
+const require = createRequire(import.meta.url);
+const cjsVite = require('vite');
+const cjsVp = require('vite-plus');
+for (const name of [
+  'createServer',
+  'DevEnvironment',
+  'mergeConfig',
+  'isRunnableDevEnvironment',
+  'isFetchableDevEnvironment',
+]) {
+  assert.equal(vite[name], vp[name], name);
+  assert.equal(cjsVite[name], cjsVp[name], name);
+  assert.equal(vite[name], cjsVite[name], name);
+}
+assert.equal(ModuleRunner, VpModuleRunner);
+const config = {};
+assert.equal(vite.defineConfig(config), config);
+assert.equal(pkg.dependencies.vite, `npm:@voidzero-dev/vite-plus-core@${pkg.version}`);
+assert.equal(pkg.dependencies['@voidzero-dev/vite-plus-core'], undefined);
+console.log('Packed alias, ESM, CommonJS, and module-runner identity passed');
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-bundled.mjs b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-bundled.mjs
new file mode 100644
index 0000000000..119a23c051
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-bundled.mjs
@@ -0,0 +1,12 @@
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+import { createServer } from 'vite-plus';
+import { build } from 'vite-plus/pack';
+
+const require = createRequire(import.meta.url);
+const cliRequire = createRequire(require.resolve('vite-plus/package.json'));
+assert.equal(createServer, cliRequire('vite').createServer);
+assert.equal(build, cliRequire('vite/pack').build);
+assert.equal(require('./package.json').devDependencies.vite, undefined);
+console.log('Bundled APIs resolve without a project Vite dependency');
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/entry.js b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/entry.js
new file mode 100644
index 0000000000..1bbe700ce9
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/entry.js
@@ -0,0 +1 @@
+export const message = 'Core identity regression';
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/identity.test.js b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/identity.test.js
new file mode 100644
index 0000000000..86f3a9ca4f
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/identity.test.js
@@ -0,0 +1,11 @@
+import { expect, test } from 'vite-plus/test';
+import { createServer, isRunnableDevEnvironment } from 'vite-plus';
+
+test('the public guard accepts an environment created by the bundled server', async () => {
+  const server = await createServer({ configFile: false, server: { middlewareMode: true } });
+  try {
+    expect(isRunnableDevEnvironment(server.environments.ssr)).toBe(true);
+  } finally {
+    await server.close();
+  }
+});
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/index.html b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/index.html
new file mode 100644
index 0000000000..bd571f1923
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/index.html
@@ -0,0 +1,3 @@
+<!doctype html>
+<title>Core identity regression</title>
+<script type="module" src="/entry.js"></script>
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/package.json b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/package.json
new file mode 100644
index 0000000000..bb31f79399
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "core-module-identity",
+  "private": true,
+  "type": "module",
+  "packageManager": "bun@1.4.2",
+  "devDependencies": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+    "vite-plus": "latest"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest"
+  }
+}
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml
new file mode 100644
index 0000000000..526917d5ac
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml
@@ -0,0 +1,93 @@
+[[case]]
+name = "core_module_identity_bun"
+vp = "global"
+local-registry = true
+steps = [
+  { argv = ["vp", "install", "--ignore-scripts"], snapshot = false },
+  ["node", "check-api.mjs"],
+  ["vp", "dev"],
+]
+
+[[case]]
+name = "core_module_identity_yarn"
+vp = "global"
+local-registry = true
+steps = [
+  { argv = ["vpt", "json-edit", "package.json", "packageManager", "yarn@4.10.3"], snapshot = false },
+  { argv = ["vpt", "json-edit", "package.json", "resolutions.vite", "npm:@voidzero-dev/vite-plus-core@latest"], snapshot = false },
+  { argv = ["vpt", "write-file", ".yarnrc.yml", "nodeLinker: node-modules\nenableScripts: false\n"], snapshot = false },
+  { argv = ["vp", "install"], timeout = 120000, snapshot = false },
+  ["node", "check-api.mjs"],
+  ["vp", "dev"],
+]
+
+[[case]]
+name = "core_module_identity_npm"
+vp = "global"
+local-registry = true
+steps = [
+  { argv = ["vpt", "json-edit", "package.json", "packageManager", "npm@11.11.0"], snapshot = false },
+  { argv = ["vp", "install", "--ignore-scripts"], snapshot = false },
+  ["node", "check-api.mjs"],
+  ["vp", "dev"],
+]
+
+[[case]]
+name = "core_module_identity_pnpm"
+vp = "global"
+local-registry = true
+steps = [
+  { argv = ["vpt", "json-edit", "package.json", "packageManager", "pnpm@11.24.0"], snapshot = false },
+  { argv = ["vpt", "write-file", "pnpm-workspace.yaml", "overrides:\n  vite: npm:@voidzero-dev/vite-plus-core@latest\nminimumReleaseAge: 0\n"], snapshot = false },
+  { argv = ["vp", "install", "--ignore-scripts"], snapshot = false },
+  ["node", "check-api.mjs"],
+  ["vp", "dev"],
+]
+
+[[case]]
+name = "core_module_identity_without_project_alias"
+vp = "global"
+local-registry = true
+steps = [
+  { argv = ["vpt", "write-file", "package.json", "{\"name\":\"core-module-identity\",\"private\":true,\"type\":\"module\",\"devDependencies\":{\"vite-plus\":\"latest\"},\"packageManager\":\"pnpm@11.24.0\"}\n"], snapshot = false },
+  { argv = ["vpt", "write-file", "pnpm-workspace.yaml", "hoist: false\nminimumReleaseAge: 0\noverrides:\n  vite: npm:@voidzero-dev/vite-plus-core@latest\n"], snapshot = false },
+  { argv = ["vpt", "replace-file-content", "vite.config.ts", "from 'vite';", "from 'vite-plus';"], snapshot = false },
+  { argv = ["vp", "install", "--ignore-scripts"], snapshot = false },
+  ["node", "check-bundled.mjs"],
+  ["vp", "dev"],
+  ["vp", "build"],
+  ["vp", "test", "run"],
+  ["vp", "pack", "entry.js"],
+]
+
+[[case]]
+name = "core_module_identity_pnpm_global_store"
+vp = "global"
+local-registry = true
+steps = [
+  { argv = ["vpt", "json-edit", "package.json", "packageManager", "pnpm@11.24.0"], snapshot = false },
+  { argv = ["vpt", "write-file", "pnpm-workspace.yaml", "enableGlobalVirtualStore: true\noverrides:\n  vite: npm:@voidzero-dev/vite-plus-core@latest\nminimumReleaseAge: 0\n"], snapshot = false },
+  { argv = ["vp", "install", "--ignore-scripts"], snapshot = false },
+  ["node", "check-api.mjs"],
+  ["vp", "dev"],
+]
+
+[[case]]
+name = "core_module_identity_pnpm_peer_contexts"
+vp = "global"
+local-registry = true
+steps = [
+  { argv = ["vpt", "json-edit", "package.json", "packageManager", "pnpm@11.24.0"], snapshot = false },
+  { argv = ["vpt", "write-file", "pnpm-workspace.yaml", "packages:\n  - packages/*\nresolvePeersFromWorkspaceRoot: false\noverrides:\n  vite: npm:@voidzero-dev/vite-plus-core@latest\nminimumReleaseAge: 0\n"], snapshot = false },
+  { argv = ["vpt", "write-file", "packages/a/package.json", "{\"name\":\"app-a\",\"private\":true,\"type\":\"module\",\"devDependencies\":{\"vite\":\"npm:@voidzero-dev/vite-plus-core@latest\",\"vite-plus\":\"latest\",\"@types/node\":\"22.20.1\"}}\n"], snapshot = false },
+  { argv = ["vpt", "write-file", "packages/b/package.json", "{\"name\":\"app-b\",\"private\":true,\"type\":\"module\",\"devDependencies\":{\"vite\":\"npm:@voidzero-dev/vite-plus-core@latest\",\"vite-plus\":\"latest\",\"@types/node\":\"24.10.3\"}}\n"], snapshot = false },
+  { argv = ["vpt", "cp", "check-api.mjs", "packages/a/check-api.mjs"], snapshot = false },
+  { argv = ["vpt", "cp", "check-api.mjs", "packages/b/check-api.mjs"], snapshot = false },
+  { argv = ["vpt", "cp", "vite.config.ts", "packages/a/vite.config.ts"], snapshot = false },
+  { argv = ["vpt", "cp", "vite.config.ts", "packages/b/vite.config.ts"], snapshot = false },
+  { argv = ["vp", "install", "--ignore-scripts"], timeout = 120000, snapshot = false },
+  { argv = ["node", "check-api.mjs"], cwd = "packages/a" },
+  { argv = ["vp", "dev"], cwd = "packages/a" },
+  { argv = ["node", "check-api.mjs"], cwd = "packages/b" },
+  { argv = ["vp", "dev"], cwd = "packages/b" },
+]
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_bun.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_bun.md
new file mode 100644
index 0000000000..ea2f29e682
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_bun.md
@@ -0,0 +1,21 @@
+# core_module_identity_bun
+
+## `vp install --ignore-scripts`
+
+
+## `node check-api.mjs`
+
+```
+Packed alias, ESM, CommonJS, and module-runner identity passed
+```
+
+## `vp dev`
+
+```
+
+  VITE <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm.md
new file mode 100644
index 0000000000..c0f8da3c40
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm.md
@@ -0,0 +1,24 @@
+# core_module_identity_npm
+
+## `vpt json-edit package.json packageManager npm@11.11.0`
+
+
+## `vp install --ignore-scripts`
+
+
+## `node check-api.mjs`
+
+```
+Packed alias, ESM, CommonJS, and module-runner identity passed
+```
+
+## `vp dev`
+
+```
+
+  VITE <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm.md
new file mode 100644
index 0000000000..fb84f9bc81
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm.md
@@ -0,0 +1,30 @@
+# core_module_identity_pnpm
+
+## `vpt json-edit package.json packageManager pnpm@11.24.0`
+
+
+## `vpt write-file pnpm-workspace.yaml 'overrides:
+  vite: npm:@voidzero-dev/vite-plus-core@latest
+minimumReleaseAge: 0
+'`
+
+
+## `vp install --ignore-scripts`
+
+
+## `node check-api.mjs`
+
+```
+Packed alias, ESM, CommonJS, and module-runner identity passed
+```
+
+## `vp dev`
+
+```
+
+  VITE <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_global_store.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_global_store.md
new file mode 100644
index 0000000000..efff058413
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_global_store.md
@@ -0,0 +1,31 @@
+# core_module_identity_pnpm_global_store
+
+## `vpt json-edit package.json packageManager pnpm@11.24.0`
+
+
+## `vpt write-file pnpm-workspace.yaml 'enableGlobalVirtualStore: true
+overrides:
+  vite: npm:@voidzero-dev/vite-plus-core@latest
+minimumReleaseAge: 0
+'`
+
+
+## `vp install --ignore-scripts`
+
+
+## `node check-api.mjs`
+
+```
+Packed alias, ESM, CommonJS, and module-runner identity passed
+```
+
+## `vp dev`
+
+```
+
+  VITE <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_peer_contexts.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_peer_contexts.md
new file mode 100644
index 0000000000..80f7592f84
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_peer_contexts.md
@@ -0,0 +1,70 @@
+# core_module_identity_pnpm_peer_contexts
+
+## `vpt json-edit package.json packageManager pnpm@11.24.0`
+
+
+## `vpt write-file pnpm-workspace.yaml 'packages:
+  - packages/*
+resolvePeersFromWorkspaceRoot: false
+overrides:
+  vite: npm:@voidzero-dev/vite-plus-core@latest
+minimumReleaseAge: 0
+'`
+
+
+## `vpt write-file packages/a/package.json '{"name":"app-a","private":true,"type":"module","devDependencies":{"vite":"npm:@voidzero-dev/vite-plus-core@latest","vite-plus":"latest","@types/node":"22.20.1"}}
+'`
+
+
+## `vpt write-file packages/b/package.json '{"name":"app-b","private":true,"type":"module","devDependencies":{"vite":"npm:@voidzero-dev/vite-plus-core@latest","vite-plus":"latest","@types/node":"24.10.3"}}
+'`
+
+
+## `vpt cp check-api.mjs packages/a/check-api.mjs`
+
+
+## `vpt cp check-api.mjs packages/b/check-api.mjs`
+
+
+## `vpt cp vite.config.ts packages/a/vite.config.ts`
+
+
+## `vpt cp vite.config.ts packages/b/vite.config.ts`
+
+
+## `vp install --ignore-scripts`
+
+
+## `cd packages/a && node check-api.mjs`
+
+```
+Packed alias, ESM, CommonJS, and module-runner identity passed
+```
+
+## `cd packages/a && vp dev`
+
+```
+
+  VITE <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
+
+## `cd packages/b && node check-api.mjs`
+
+```
+Packed alias, ESM, CommonJS, and module-runner identity passed
+```
+
+## `cd packages/b && vp dev`
+
+```
+
+  VITE <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_without_project_alias.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_without_project_alias.md
new file mode 100644
index 0000000000..a88407b2d0
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_without_project_alias.md
@@ -0,0 +1,77 @@
+# core_module_identity_without_project_alias
+
+## `vpt write-file package.json '{"name":"core-module-identity","private":true,"type":"module","devDependencies":{"vite-plus":"latest"},"packageManager":"pnpm@11.24.0"}
+'`
+
+
+## `vpt write-file pnpm-workspace.yaml 'hoist: false
+minimumReleaseAge: 0
+overrides:
+  vite: npm:@voidzero-dev/vite-plus-core@latest
+'`
+
+
+## `vpt replace-file-content vite.config.ts 'from '\''vite'\'';' 'from '\''vite-plus'\'';'`
+
+
+## `vp install --ignore-scripts`
+
+
+## `node check-bundled.mjs`
+
+```
+Bundled APIs resolve without a project Vite dependency
+```
+
+## `vp dev`
+
+```
+
+  VITE <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
+
+## `vp build`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ 4 modules transformed.
+computing gzip size...
+dist/index.html                <size> kB │ gzip: <size> kB
+dist/assets/index-<hash>.js  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp test run`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+ RUN  <version> <workspace>
+
+ ✓ identity.test.js (1 test) <duration>
+   ✓ the public guard accepts an environment created by the bundled server <duration>
+
+ Test Files  1 passed (1)
+      Tests  1 passed (1)
+   Start at  <time>
+   Duration  <duration> (transform <duration>, setup <duration>, import <duration>, tests <duration>, environment <duration>)
+```
+
+## `vp pack entry.js`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+ℹ entry: entry.js
+ℹ Build start
+ℹ Cleaning <n> files
+ℹ dist/entry.mjs  <size> kB │ gzip: <size> kB
+ℹ 1 files, total: <size> kB
+✔ Build complete in <duration>
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_yarn.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_yarn.md
new file mode 100644
index 0000000000..1292650b63
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_yarn.md
@@ -0,0 +1,32 @@
+# core_module_identity_yarn
+
+## `vpt json-edit package.json packageManager yarn@4.10.3`
+
+
+## `vpt json-edit package.json resolutions.vite npm:@voidzero-dev/vite-plus-core@latest`
+
+
+## `vpt write-file .yarnrc.yml 'nodeLinker: node-modules
+enableScripts: false
+'`
+
+
+## `vp install`
+
+
+## `node check-api.mjs`
+
+```
+Packed alias, ESM, CommonJS, and module-runner identity passed
+```
+
+## `vp dev`
+
+```
+
+  VITE <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/vite.config.ts b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/vite.config.ts
new file mode 100644
index 0000000000..ac0bb7cb68
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/vite.config.ts
@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+
+import { isRunnableDevEnvironment } from 'vite';
+import { defineConfig, isRunnableDevEnvironment as fromVitePlus } from 'vite-plus';
+
+export default defineConfig({
+  server: { host: '127.0.0.1', port: 0 },
+  plugins: [
+    {
+      name: 'check-ssr-environment',
+      configureServer(server) {
+        // Vitest also loads this config, with an in-memory server.
+        const httpServer = server.httpServer;
+        if (!httpServer) {
+          return;
+        }
+        assert.equal(isRunnableDevEnvironment, fromVitePlus);
+        assert.ok(isRunnableDevEnvironment(server.environments.ssr));
+        httpServer.once('listening', async () => {
+          try {
+            const address = httpServer.address();
+            assert.ok(address && typeof address === 'object');
+            const response = await fetch(`http://127.0.0.1:${address.port}/`, {
+              signal: AbortSignal.timeout(10_000),
+            });
+            assert.equal(response.status, 200);
+            assert.equal(await response.text(), 'SSR middleware installed');
+            console.log('SSR environment identity and HTTP response passed');
+          } catch (error) {
+            console.error(error);
+            process.exitCode = 1;
+          } finally {
+            await server.close();
+          }
+        });
+        // TanStack installs its middleware after this guard. A duplicate core
+        // makes the guard fail, leaving the root route unhandled.
+        return () => {
+          if (isRunnableDevEnvironment(server.environments.ssr)) {
+            server.middlewares.use((_req, res) => res.end('SSR middleware installed'));
+          }
+        };
+      },
+    },
+  ],
+});
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/package.json b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/package.json
new file mode 100644
index 0000000000..baf92f8932
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "core-resolution-errors",
+  "private": true,
+  "type": "module"
+}
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots.toml b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots.toml
new file mode 100644
index 0000000000..09f24b2b7e
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots.toml
@@ -0,0 +1,17 @@
+[[case]]
+name = "core_resolution_upstream_vite"
+vp = "local"
+steps = [
+  { argv = ["vpt", "write-file", "node_modules/vite/package.json", "{\"name\":\"vite\",\"version\":\"8.2.2\"}\n"], snapshot = false },
+  { argv = ["vp", "dev"], continue-on-failure = true },
+  ["vp", "pack", "index.ts"],
+]
+
+[[case]]
+name = "core_resolution_stale_core"
+vp = "local"
+steps = [
+  { argv = ["vpt", "write-file", "node_modules/vite/package.json", "{\"name\":\"@voidzero-dev/vite-plus-core\",\"version\":\"0.0.0-stale\"}\n"], snapshot = false },
+  { argv = ["vp", "dev"], continue-on-failure = true },
+  ["vp", "pack", "index.ts"],
+]
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots/core_resolution_stale_core.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots/core_resolution_stale_core.md
new file mode 100644
index 0000000000..80cf509b19
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots/core_resolution_stale_core.md
@@ -0,0 +1,21 @@
+# core_resolution_stale_core
+
+## `vpt write-file node_modules/vite/package.json '{"name":"@voidzero-dev/vite-plus-core","version":"0.0.0-stale"}
+'`
+
+
+## `vp dev`
+
+**Exit code:** 1
+
+```
+error: Failed to resolve vite command: GenericFailure, Expected @voidzero-dev/vite-plus-core@<version>, but found @voidzero-dev/vite-plus-core@<version> at <workspace>/node_modules/vite/package.json. Run `vp migrate` to align the Vite alias, then run `vp install`.
+```
+
+## `vp pack index.ts`
+
+**Exit code:** 1
+
+```
+error: Failed to resolve pack command: GenericFailure, Expected @voidzero-dev/vite-plus-core@<version>, but found @voidzero-dev/vite-plus-core@<version> at <workspace>/node_modules/vite/package.json. Run `vp migrate` to align the Vite alias, then run `vp install`.
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots/core_resolution_upstream_vite.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots/core_resolution_upstream_vite.md
new file mode 100644
index 0000000000..57f4377cc1
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/snapshots/core_resolution_upstream_vite.md
@@ -0,0 +1,21 @@
+# core_resolution_upstream_vite
+
+## `vpt write-file node_modules/vite/package.json '{"name":"vite","version":"8.2.2"}
+'`
+
+
+## `vp dev`
+
+**Exit code:** 1
+
+```
+error: Failed to resolve vite command: GenericFailure, Expected @voidzero-dev/vite-plus-core@<version>, but found vite@8.2.2 at <workspace>/node_modules/vite/package.json. Run `vp migrate` to align the Vite alias, then run `vp install`.
+```
+
+## `vp pack index.ts`
+
+**Exit code:** 1
+
+```
+error: Failed to resolve pack command: GenericFailure, Expected @voidzero-dev/vite-plus-core@<version>, but found vite@8.2.2 at <workspace>/node_modules/vite/package.json. Run `vp migrate` to align the Vite alias, then run `vp install`.
+```
diff --git a/packages/cli/BUNDLING.md b/packages/cli/BUNDLING.md
index bd3eeb3231..dd1aea1995 100644
--- a/packages/cli/BUNDLING.md
+++ b/packages/cli/BUNDLING.md
@@ -13,6 +13,20 @@ The CLI package uses a **4-step build process**:
 
 This architecture allows users to import everything from a single package (`vite-plus`) as a drop-in replacement for `vite`, without needing to know about the separate `@voidzero-dev/vite-plus-core` bundle or `vitest`.
 
+## Core Dependency Identity
+
+The CLI declares its core dependency as `vite`, using
+`workspace:@voidzero-dev/vite-plus-core@*` in the workspace and an exact npm
+alias in packed releases. Runtime imports and generated shims use `vite` and
+its subpaths. This gives the CLI and plugins the same dependency name and
+avoids separate core instances under the alias and canonical package name.
+
+`resolve-core.ts` resolves the alias from the selected CLI package. It checks
+that the dependency and any project-level Vite alias identify the expected
+core release before starting Vite or packaging commands. Keep the canonical
+name in release metadata and alias targets; it identifies the published
+package, not the runtime import specifier.
+
 ## Build Steps
 
 ### Step 1: tsdown Build (`buildWithTsdown`)
@@ -24,7 +38,7 @@ Bundles all CLI entry points using tsdown (configured in `tsdown.config.ts`). Th
 - Public API entries: `bin`, `index`, `define-config`, `fmt`, `lint`, `pack`, `pack-bin`
 - Global command entries: `create`, `migrate`, `version`, `config`, `hooks`, `mcp`, `staged`
 - All third-party dependencies are inlined at build time
-- Only packages that must be resolved at runtime stay external (NAPI binding, `@voidzero-dev/vite-plus-core`, `vitest`, `oxfmt`, `oxlint`)
+- Only packages that must be resolved at runtime stay external (NAPI binding, `vite`, `vitest`, `oxfmt`, `oxlint`)
 - Code splitting creates shared chunks for code used by multiple entries
 - DTS (`.d.ts`) files are generated for all entries
 
@@ -77,13 +91,13 @@ Creates shim files that re-export from `@voidzero-dev/vite-plus-core`, enabling
 
 ```typescript
 // dist/client.d.ts (triple-slash reference for ambient types)
-/// <reference types="@voidzero-dev/vite-plus-core/client" />
+/// <reference types="vite/client" />
 
 // dist/module-runner.js
-export * from '@voidzero-dev/vite-plus-core/module-runner';
+export * from 'vite/module-runner';
 
 // dist/types/importMeta.d.ts (type-only export)
-export type * from '@voidzero-dev/vite-plus-core/types/importMeta.d.ts';
+export type * from 'vite/types/importMeta.d.ts';
 ```
 
 **Note on export ordering**: In `package.json`, the `./types/internal/*` export (set to `null`) must appear before `./types/*` for correct precedence. More specific patterns must precede wildcards.
@@ -309,7 +323,7 @@ For `./types/*` exports, shim files use `export type *` syntax (TypeScript 5.0+)
 
 ```typescript
 // dist/types/importMeta.d.ts
-export type * from '@voidzero-dev/vite-plus-core/types/importMeta.d.ts';
+export type * from 'vite/types/importMeta.d.ts';
 ```
 
 This is important because `./types/*` only exposes `.d.ts` files and should never include runtime code.
@@ -331,7 +345,7 @@ The `./client` export uses a triple-slash reference instead of a regular export
 
 ```typescript
 // dist/client.d.ts
-/// <reference types="@voidzero-dev/vite-plus-core/client" />
+/// <reference types="vite/client" />
 ```
 
 This allows TypeScript to pick up types like `import.meta.hot`, CSS module types, and asset imports without explicit imports.
@@ -525,6 +539,7 @@ See `package.json` for the complete list of exports.
 ```typescript
 // Core package name for Vite compatibility exports
 const CORE_PACKAGE_NAME = '@voidzero-dev/vite-plus-core';
+const CORE_IMPORT_SPECIFIER = 'vite';
 
 // Test package name for re-exports (vitest itself, not a bundled wrapper)
 const TEST_PACKAGE_NAME = 'vitest';
diff --git a/packages/cli/build.ts b/packages/cli/build.ts
index 7f2f80002f..5f696c406e 100644
--- a/packages/cli/build.ts
+++ b/packages/cli/build.ts
@@ -35,6 +35,7 @@ import corePkg from '../core/package.json' with { type: 'json' };
 const projectDir = dirname(fileURLToPath(import.meta.url));
 const TEST_PACKAGE_NAME = 'vitest';
 const CORE_PACKAGE_NAME = '@voidzero-dev/vite-plus-core';
+const CORE_IMPORT_SPECIFIER = 'vite';
 const NATIVE_BUILD_TIME_PATH = join(projectDir, 'binding', 'vite-plus.build-time');
 const UTC_BUILD_TIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
 
@@ -237,33 +238,36 @@ async function syncCorePackageExports() {
   console.log('  Creating ./client');
   await writeFile(
     join(distDir, 'client.d.ts'),
-    `/// <reference types="${CORE_PACKAGE_NAME}/client" />\n`,
+    `/// <reference types="${CORE_IMPORT_SPECIFIER}/client" />\n`,
   );
 
   // Create ./pack/client shim (types only) - ambient type declarations for tsdown bundler features
   console.log('  Creating ./pack/client');
   await writeFile(
     join(distDir, 'pack-client.d.ts'),
-    `/// <reference types="${CORE_PACKAGE_NAME}/pack/client" />\n`,
+    `/// <reference types="${CORE_IMPORT_SPECIFIER}/pack/client" />\n`,
   );
 
   // Create ./module-runner shim
   console.log('  Creating ./module-runner');
   await writeFile(
     join(distDir, 'module-runner.js'),
-    `export * from '${CORE_PACKAGE_NAME}/module-runner';\n`,
+    `export * from '${CORE_IMPORT_SPECIFIER}/module-runner';\n`,
   );
   await writeFile(
     join(distDir, 'module-runner.d.ts'),
-    `export * from '${CORE_PACKAGE_NAME}/module-runner';\n`,
+    `export * from '${CORE_IMPORT_SPECIFIER}/module-runner';\n`,
   );
 
   // Create ./internal shim
   console.log('  Creating ./internal');
-  await writeFile(join(distDir, 'internal.js'), `export * from '${CORE_PACKAGE_NAME}/internal';\n`);
+  await writeFile(
+    join(distDir, 'internal.js'),
+    `export * from '${CORE_IMPORT_SPECIFIER}/internal';\n`,
+  );
   await writeFile(
     join(distDir, 'internal.d.ts'),
-    `export * from '${CORE_PACKAGE_NAME}/internal';\n`,
+    `export * from '${CORE_IMPORT_SPECIFIER}/internal';\n`,
   );
 
   // Create ./dist/client/* shims by reading core's dist/vite/client files
@@ -283,10 +287,13 @@ async function syncCorePackageExports() {
       continue;
     }
     if (file.endsWith('.js') || file.endsWith('.mjs') || file.endsWith('.cjs')) {
-      await writeFile(shimPath, `export * from '${CORE_PACKAGE_NAME}/dist/client/${file}';\n`);
+      await writeFile(shimPath, `export * from '${CORE_IMPORT_SPECIFIER}/dist/client/${file}';\n`);
     } else if (file.endsWith('.d.ts') || file.endsWith('.d.mts') || file.endsWith('.d.cts')) {
       const baseFile = file.replace(/\.d\.[mc]?ts$/, '');
-      await writeFile(shimPath, `export * from '${CORE_PACKAGE_NAME}/dist/client/${baseFile}';\n`);
+      await writeFile(
+        shimPath,
+        `export * from '${CORE_IMPORT_SPECIFIER}/dist/client/${baseFile}';\n`,
+      );
     } else {
       // Copy non-JS/TS files directly (e.g., CSS, source maps)
       await copyFile(srcPath, shimPath);
@@ -343,7 +350,7 @@ async function syncTypesDir(srcDir: string, destDir: string, relativePath: strin
       // Use 'export type *' since we're re-exporting from a .d.ts file
       await writeFile(
         destPath,
-        `export type * from '${CORE_PACKAGE_NAME}/types/${entryRelPath}';\n`,
+        `export type * from '${CORE_IMPORT_SPECIFIER}/types/${entryRelPath}';\n`,
       );
     }
   }
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 95ecea43c6..0be80d5ab2 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -368,10 +368,10 @@
     "@vitest/snapshot": "catalog:",
     "@vitest/spy": "catalog:",
     "@vitest/utils": "catalog:",
-    "@voidzero-dev/vite-plus-core": "workspace:*",
     "oxfmt": "catalog:",
     "oxlint": "catalog:",
     "oxlint-tsgolint": "catalog:",
+    "vite": "workspace:@voidzero-dev/vite-plus-core@*",
     "vitest": "catalog:"
   },
   "devDependencies": {
@@ -399,7 +399,6 @@
     "semver": "catalog:",
     "tsdown": "catalog:",
     "validate-npm-package-name": "catalog:",
-    "vite": "workspace:*",
     "yaml": "catalog:",
     "zod": "catalog:"
   },
diff --git a/packages/cli/src/__tests__/define-config-plugins.spec.ts b/packages/cli/src/__tests__/define-config-plugins.spec.ts
index cd22d7898e..b9b10b70b3 100644
--- a/packages/cli/src/__tests__/define-config-plugins.spec.ts
+++ b/packages/cli/src/__tests__/define-config-plugins.spec.ts
@@ -1,4 +1,4 @@
-import type { Plugin } from '@voidzero-dev/vite-plus-core';
+import type { Plugin } from 'vite';
 import { describe, expect, it } from 'vitest';
 
 import {
diff --git a/packages/cli/src/__tests__/define-config-vitest-resolver.spec.ts b/packages/cli/src/__tests__/define-config-vitest-resolver.spec.ts
index 1fcc23f9a8..148f8e5604 100644
--- a/packages/cli/src/__tests__/define-config-vitest-resolver.spec.ts
+++ b/packages/cli/src/__tests__/define-config-vitest-resolver.spec.ts
@@ -1,6 +1,6 @@
 import { fileURLToPath } from 'node:url';
 
-import type { Plugin } from '@voidzero-dev/vite-plus-core';
+import type { Plugin } from 'vite';
 import { describe, expect, it } from 'vitest';
 
 import { defineConfig, defineProject, isVitestFamilySpecifier } from '../define-config.ts';
diff --git a/packages/cli/src/__tests__/resolve-core.spec.ts b/packages/cli/src/__tests__/resolve-core.spec.ts
new file mode 100644
index 0000000000..168117ebbb
--- /dev/null
+++ b/packages/cli/src/__tests__/resolve-core.spec.ts
@@ -0,0 +1,88 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import cliPkg from '../../package.json' with { type: 'json' };
+import { resolveCore } from '../resolve-core.ts';
+
+function writeCore(
+  directory: string,
+  name = '@voidzero-dev/vite-plus-core',
+  version = cliPkg.version,
+) {
+  mkdirSync(directory, { recursive: true });
+  writeFileSync(
+    join(directory, 'package.json'),
+    JSON.stringify({
+      name,
+      version,
+      exports: { '.': './index.js', './pack': './pack.js', './package.json': './package.json' },
+    }),
+  );
+  writeFileSync(join(directory, 'index.js'), '');
+  writeFileSync(join(directory, 'pack.js'), '');
+}
+
+describe('resolveCore', () => {
+  let root: string;
+  let project: string;
+  let cliModule: string;
+  let bundled: string;
+
+  beforeEach(() => {
+    root = realpathSync(mkdtempSync(join(tmpdir(), 'vp-core-resolver-')));
+    project = join(root, 'project');
+    mkdirSync(project);
+    cliModule = join(root, 'cli', 'dist', 'bin.js');
+    bundled = join(root, 'cli', 'node_modules', 'vite');
+    writeCore(bundled);
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('supports a CLI installation without a project-level vite alias', () => {
+    expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
+    expect(resolveCore('/pack', project, cliModule)).toBe(join(bundled, 'pack.js'));
+  });
+
+  it('keeps the same anchor as static exports when the project has a matching copy', () => {
+    writeCore(join(project, 'node_modules', 'vite'));
+    expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
+  });
+
+  it('does not fall back to the project when the CLI dependency is missing', () => {
+    writeCore(join(project, 'node_modules', 'vite'));
+    rmSync(bundled, { recursive: true });
+    expect(() => resolveCore('', project, cliModule)).toThrow('Could not resolve the bundled Vite');
+  });
+
+  it.each(['project', 'bundled'])('rejects upstream Vite in the %s dependency', (location) => {
+    writeCore(
+      location === 'project' ? join(project, 'node_modules', 'vite') : bundled,
+      'vite',
+      '8.2.2',
+    );
+    expect(() => resolveCore('', project, cliModule)).toThrow('found vite@8.2.2');
+  });
+
+  it.each(['project', 'bundled'])('rejects a stale core in the %s dependency', (location) => {
+    writeCore(
+      location === 'project' ? join(project, 'node_modules', 'vite') : bundled,
+      '@voidzero-dev/vite-plus-core',
+      '0.0.0-stale',
+    );
+    expect(() => resolveCore('', project, cliModule)).toThrow(
+      'found @voidzero-dev/vite-plus-core@0.0.0-stale',
+    );
+  });
+
+  it('reports a missing core subpath instead of selecting a project copy', () => {
+    writeCore(join(project, 'node_modules', 'vite'));
+    rmSync(join(bundled, 'pack.js'));
+    expect(() => resolveCore('/pack', project, cliModule)).toThrow();
+  });
+});
diff --git a/packages/cli/src/define-config.ts b/packages/cli/src/define-config.ts
index 0426dc277f..058b57afe6 100644
--- a/packages/cli/src/define-config.ts
+++ b/packages/cli/src/define-config.ts
@@ -2,9 +2,9 @@ import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
-import type { PluginOption, UserConfig } from '@voidzero-dev/vite-plus-core';
 import type { OxfmtConfig } from 'oxfmt';
 import type { OxlintConfig } from 'oxlint';
+import type { PluginOption, UserConfig } from 'vite';
 import {
   defineConfig as viteDefineConfig,
   defineProject as viteDefineProject,
@@ -14,7 +14,6 @@ import {
   type UserProjectConfigFn,
   type UserWorkspaceConfig,
 } from 'vitest/config';
-import type { InlineConfig as VitestInlineConfig } from 'vitest/node';
 
 import type { CreateTemplateEntry } from './create/org-manifest.ts';
 import type { PackUserConfig } from './pack.ts';
@@ -22,7 +21,7 @@ import type { RunConfig } from './run-config.ts';
 import type { StagedConfig } from './staged-config.ts';
 import { CONFIG_METADATA_ENV, VITEST_VERSION } from './utils/constants.ts';
 
-declare module '@voidzero-dev/vite-plus-core' {
+declare module 'vite' {
   interface UserConfig {
     /**
      * Options for oxlint
@@ -92,16 +91,6 @@ declare module '@voidzero-dev/vite-plus-core' {
        */
       templates?: CreateTemplateEntry[];
     };
-
-    /**
-     * Vitest test configuration.
-     *
-     * Vitest augments vite's `UserConfig` with a `test` field via
-     * `declare module 'vite'`, but vite-plus-core is a fork of vite so that
-     * augmentation does not apply here. Re-declare it locally so user
-     * configs like `defineConfig({ test: { globals: true } })` typecheck.
-     */
-    test?: VitestInlineConfig;
   }
 }
 
@@ -565,10 +554,7 @@ const coverageGuardedVitestInstances = new WeakSet<object>();
 function vitePlusCoverageVersionGuardPlugin(): PluginOption {
   return {
     name: 'vite-plus:coverage-version-guard',
-    // `configureVitest` is a Vitest-specific plugin hook absent from Vite's
-    // `Plugin` type (vite-plus-core is a vite fork, so Vitest's `declare module
-    // 'vite'` augmentation does not reach it). Cast the object so the extra hook
-    // type-checks; Vitest invokes it via `getSortedPluginHooks('configureVitest')`.
+    // Vitest invokes this hook via `getSortedPluginHooks('configureVitest')`.
     configureVitest(context: VitestConfigureContext) {
       const { vitest } = context;
       // Coverage is global and the provider is imported once from the runner, so
diff --git a/packages/cli/src/index.cts b/packages/cli/src/index.cts
index 09b5b2bf2f..49a1821ca8 100644
--- a/packages/cli/src/index.cts
+++ b/packages/cli/src/index.cts
@@ -1,4 +1,4 @@
-const vite = require('@voidzero-dev/vite-plus-core');
+const vite = require('vite');
 
 const {
   configDefaults,
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index f438526097..2c4b0237f7 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -1,6 +1,6 @@
 import { defineConfig, defineProject, lazyPlugins } from './define-config.ts';
 
-export * from '@voidzero-dev/vite-plus-core';
+export * from 'vite';
 
 export {
   configDefaults,
diff --git a/packages/cli/src/migration/__tests__/tsup.spec.ts b/packages/cli/src/migration/__tests__/tsup.spec.ts
index 02ba84ece6..7935beb699 100644
--- a/packages/cli/src/migration/__tests__/tsup.spec.ts
+++ b/packages/cli/src/migration/__tests__/tsup.spec.ts
@@ -4,7 +4,7 @@ import path from 'node:path';
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-vi.mock('@voidzero-dev/vite-plus-core/package.json', () => ({
+vi.mock('vite/package.json', () => ({
   default: { bundledVersions: { tsdown: '0.99.0' } },
 }));
 
diff --git a/packages/cli/src/migration/migrator/tsup.ts b/packages/cli/src/migration/migrator/tsup.ts
index f652f338f3..d72a61c984 100644
--- a/packages/cli/src/migration/migrator/tsup.ts
+++ b/packages/cli/src/migration/migrator/tsup.ts
@@ -2,8 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { styleText } from 'node:util';
 
-import corePkg from '@voidzero-dev/vite-plus-core/package.json' with { type: 'json' };
 import * as prompts from '@voidzero-dev/vite-plus-prompts';
+import corePkg from 'vite/package.json' with { type: 'json' };
 
 import { PackageManager, type WorkspacePackage } from '../../types/index.ts';
 import { runCommandSilently } from '../../utils/command.ts';
diff --git a/packages/cli/src/pack-bin.ts b/packages/cli/src/pack-bin.ts
index c2444303b7..e7ff631a2e 100644
--- a/packages/cli/src/pack-bin.ts
+++ b/packages/cli/src/pack-bin.ts
@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import module from 'node:module';
 
+import { cac } from 'cac';
 import {
   buildWithConfigs,
   resolveUserConfig,
@@ -9,8 +10,7 @@ import {
   type InlineConfig,
   type ResolvedConfig,
   type TsdownHandle,
-} from '@voidzero-dev/vite-plus-core/pack';
-import { cac } from 'cac';
+} from 'vite/pack';
 
 import { resolveViteConfig } from './resolve-vite-config.ts';
 
diff --git a/packages/cli/src/pack.ts b/packages/cli/src/pack.ts
index 94a2304ee7..4b7f96e0ca 100644
--- a/packages/cli/src/pack.ts
+++ b/packages/cli/src/pack.ts
@@ -1,6 +1,6 @@
-import type { UserConfig as TsdownUserConfig } from '@voidzero-dev/vite-plus-core/pack';
+import type { UserConfig as TsdownUserConfig } from 'vite/pack';
 
-export * from '@voidzero-dev/vite-plus-core/pack';
+export * from 'vite/pack';
 
 export interface PackUserConfig extends TsdownUserConfig {
   /**
diff --git a/packages/cli/src/resolve-core.ts b/packages/cli/src/resolve-core.ts
new file mode 100644
index 0000000000..aaf2aab3a4
--- /dev/null
+++ b/packages/cli/src/resolve-core.ts
@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+import cliPkg from '../package.json' with { type: 'json' };
+
+const CORE_PACKAGE_NAME = '@voidzero-dev/vite-plus-core';
+
+function checkCoreVersion(packageJsonPath: string): void {
+  const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
+    name?: string;
+    version?: string;
+  };
+  if (pkg.name !== CORE_PACKAGE_NAME || pkg.version !== cliPkg.version) {
+    throw new Error(
+      `Expected ${CORE_PACKAGE_NAME}@${cliPkg.version}, but found ${pkg.name}@${pkg.version} at ${packageJsonPath}. ` +
+        'Run `vp migrate` to align the Vite alias, then run `vp install`.',
+    );
+  }
+}
+
+/** Resolve the same core dependency as the CLI's static `vite` re-exports. */
+export function resolveCore(
+  subpath = '',
+  cwd = process.cwd(),
+  modulePath = import.meta.url,
+): string {
+  const require = createRequire(modulePath);
+  let packageJsonPath: string;
+  try {
+    packageJsonPath = require.resolve('vite/package.json');
+  } catch (cause) {
+    throw new Error('Could not resolve the bundled Vite dependency. Run `vp install`.', { cause });
+  }
+  checkCoreVersion(packageJsonPath);
+
+  // A migrated project's alias must match the CLI release. Without a project
+  // alias, the required dependency above still supplies the bundled commands.
+  const projectRequire = createRequire(join(cwd, 'package.json'));
+  let projectPackageJsonPath: string | undefined;
+  try {
+    projectPackageJsonPath = projectRequire.resolve('vite/package.json');
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException).code !== 'MODULE_NOT_FOUND') {
+      throw cause;
+    }
+  }
+  if (projectPackageJsonPath && projectPackageJsonPath !== packageJsonPath) {
+    checkCoreVersion(projectPackageJsonPath);
+  }
+
+  return require.resolve(`vite${subpath}`);
+}
diff --git a/packages/cli/src/resolve-pack.ts b/packages/cli/src/resolve-pack.ts
index 2e5a361a03..8bd5a7fc0f 100644
--- a/packages/cli/src/resolve-pack.ts
+++ b/packages/cli/src/resolve-pack.ts
@@ -10,6 +10,7 @@
 
 import { join } from 'node:path';
 
+import { resolveCore } from './resolve-core.ts';
 import { DEFAULT_ENVS } from './utils/constants.ts';
 
 /**
@@ -25,6 +26,7 @@ export async function pack(): Promise<{
   binPath: string;
   envs: Record<string, string>;
 }> {
+  resolveCore('/pack');
   // Resolve the bundled Tsdown CLI
   const binPath = join(import.meta.dirname, 'pack-bin.js');
 
diff --git a/packages/cli/src/resolve-vite.ts b/packages/cli/src/resolve-vite.ts
index 506cbe8588..49e8bf03e9 100644
--- a/packages/cli/src/resolve-vite.ts
+++ b/packages/cli/src/resolve-vite.ts
@@ -9,9 +9,11 @@
  * Used for: `vite-plus build` and potentially `vite-plus dev` commands
  */
 
+import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
-import { DEFAULT_ENVS, resolve } from './utils/constants.ts';
+import { resolveCore } from './resolve-core.ts';
+import { DEFAULT_ENVS } from './utils/constants.ts';
 
 /**
  * Resolves the Vite binary path and environment variables.
@@ -20,17 +22,17 @@ import { DEFAULT_ENVS, resolve } from './utils/constants.ts';
  *   - binPath: Absolute path to the Vite CLI entry point (vite.js)
  *   - envs: Environment variables to set when executing Vite
  *
- * The function first tries to resolve vite package, then falls back
- * to vite package (for direct vite installations).
- * It constructs the path to the CLI binary within the resolved package.
+ * The CLI and its public re-exports use the same declared `vite` alias.
  */
 export async function vite(): Promise<{
   binPath: string;
   envs: Record<string, string>;
 }> {
-  // Vite's CLI binary is located at bin/vite.js relative to the package root
-  const vitePackagePath = dirname(resolve('@voidzero-dev/vite-plus-core'));
+  const vitePackagePath = dirname(resolveCore());
   const binPath = join(vitePackagePath, 'cli.js');
+  if (!existsSync(binPath)) {
+    throw new Error(`Could not find the bundled Vite CLI at ${binPath}. Run \`vp install\`.`);
+  }
 
   return {
     binPath,
diff --git a/packages/tools/src/__tests__/install-global-cli.spec.ts b/packages/tools/src/__tests__/install-global-cli.spec.ts
new file mode 100644
index 0000000000..9d8988f5dc
--- /dev/null
+++ b/packages/tools/src/__tests__/install-global-cli.spec.ts
@@ -0,0 +1,42 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { createCiInstallPackage } from '../install-global-cli.ts';
+
+describe('createCiInstallPackage', () => {
+  let directory: string;
+
+  beforeEach(() => {
+    directory = mkdtempSync(join(tmpdir(), 'vp-ci-deps-'));
+  });
+
+  afterEach(() => rmSync(directory, { recursive: true, force: true }));
+
+  it.each(['0.3.0', '0.0.0-commit.1234567'])('installs the packed core alias for %s', (version) => {
+    const core = join(directory, `voidzero-dev-vite-plus-core-${version}.tgz`);
+    const cli = join(directory, `vite-plus-${version}.tgz`);
+    writeFileSync(core, '');
+    const result = createCiInstallPackage(
+      { vite: `npm:@voidzero-dev/vite-plus-core@${version}`, vitest: '4.1.11' },
+      cli,
+    );
+    expect(result.dependencies).toEqual({ 'vite-plus': `file:${cli}`, vite: `file:${core}` });
+    expect(result.overrides).toEqual({ vite: '$vite' });
+  });
+
+  it('keeps canonical dependencies compatible with older packed CLIs', () => {
+    const core = join(directory, 'voidzero-dev-vite-plus-core-0.3.0.tgz');
+    writeFileSync(core, '');
+    const result = createCiInstallPackage(
+      { '@voidzero-dev/vite-plus-core': '0.3.0' },
+      join(directory, 'vite-plus-0.3.0.tgz'),
+    );
+    expect(result.dependencies['@voidzero-dev/vite-plus-core']).toBe(`file:${core}`);
+    expect(result.overrides).toEqual({
+      '@voidzero-dev/vite-plus-core': '$@voidzero-dev/vite-plus-core',
+    });
+  });
+});
diff --git a/packages/tools/src/install-global-cli.ts b/packages/tools/src/install-global-cli.ts
index 23450c39d9..e04b3389d7 100644
--- a/packages/tools/src/install-global-cli.ts
+++ b/packages/tools/src/install-global-cli.ts
@@ -333,8 +333,6 @@ function getWindowsPowerShellCommand(): string {
  * references to the main tgz and sibling @voidzero-dev/* tgz files, then running npm install.
  */
 function installCiDeps(versionDir: string, mainTgzPath: string) {
-  const tgzDir = path.dirname(mainTgzPath);
-
   // Extract vite-plus's package.json from the tgz to find @voidzero-dev/* deps
   // On Windows, use the system tar (bsdtar) which handles Windows paths natively.
   // Git Bash's GNU tar misinterprets drive letters (D:, C:) as remote host references,
@@ -354,18 +352,33 @@ function installCiDeps(versionDir: string, mainTgzPath: string) {
   const vitePlusPkg = JSON.parse(readFileSync(path.join(tempDir, 'package.json'), 'utf-8'));
   rmSync(tempDir, { recursive: true, force: true });
 
+  const wrapperPkg = createCiInstallPackage(vitePlusPkg.dependencies ?? {}, mainTgzPath);
+
+  writeFileSync(path.join(versionDir, 'package.json'), JSON.stringify(wrapperPkg, null, 2) + '\n');
+
+  execSync('npm install --no-audit --no-fund --legacy-peer-deps', {
+    cwd: versionDir,
+    stdio: 'inherit',
+  });
+}
+
+/** Build a CI install manifest from the packed CLI's declared dependencies. */
+export function createCiInstallPackage(vitePlusDeps: Record<string, string>, mainTgzPath: string) {
+  const tgzDir = path.dirname(mainTgzPath);
   // Build wrapper deps: vite-plus from tgz + @voidzero-dev/* from sibling tgz files
   const wrapperDeps: Record<string, string> = {
     'vite-plus': `file:${mainTgzPath}`,
   };
 
-  const vitePlusDeps: Record<string, string> = vitePlusPkg.dependencies ?? {};
-  for (const [name, version] of Object.entries(vitePlusDeps)) {
-    if (!name.startsWith('@voidzero-dev/')) {
+  for (const [name, specifier] of Object.entries(vitePlusDeps)) {
+    const alias = /^npm:(@voidzero-dev\/[^@]+)@(.+)$/.exec(specifier);
+    const packageName = alias?.[1] ?? name;
+    const version = alias?.[2] ?? specifier;
+    if (!packageName.startsWith('@voidzero-dev/')) {
       continue;
     }
     // @voidzero-dev/vite-plus-core@0.0.0 -> voidzero-dev-vite-plus-core-0.0.0.tgz
-    const tgzName = name.replace('@', '').replace('/', '-') + `-${version}.tgz`;
+    const tgzName = packageName.replace('@', '').replace('/', '-') + `-${version}.tgz`;
     const tgzFilePath = path.join(tgzDir, tgzName);
     if (existsSync(tgzFilePath)) {
       wrapperDeps[name] = `file:${tgzFilePath}`;
@@ -375,19 +388,19 @@ function installCiDeps(versionDir: string, mainTgzPath: string) {
     }
   }
 
-  const wrapperPkg = {
+  return {
     name: 'vp-global',
     version: '0.0.0',
     private: true,
     dependencies: wrapperDeps,
+    // Override the CLI's registry dependencies too. A top-level file dependency
+    // alone does not force npm to use that tarball for a transitive npm alias.
+    overrides: Object.fromEntries(
+      Object.keys(wrapperDeps)
+        .filter((name) => name !== 'vite-plus')
+        .map((name) => [name, `$${name}`]),
+    ),
   };
-
-  writeFileSync(path.join(versionDir, 'package.json'), JSON.stringify(wrapperPkg, null, 2) + '\n');
-
-  execSync('npm install --no-audit --no-fund --legacy-peer-deps', {
-    cwd: versionDir,
-    stdio: 'inherit',
-  });
 }
 
 /**
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4aa3b8dab0..15383c0ed5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -356,9 +356,6 @@ importers:
       '@vitest/utils':
         specifier: 'catalog:'
         version: 4.1.11
-      '@voidzero-dev/vite-plus-core':
-        specifier: workspace:*
-        version: link:../core
       oxfmt:
         specifier: 'catalog:'
         version: 0.66.0(vite-plus@packages+cli)
@@ -368,6 +365,9 @@ importers:
       oxlint-tsgolint:
         specifier: 'catalog:'
         version: 7.0.2001
+      vite:
+        specifier: workspace:@voidzero-dev/vite-plus-core@*
+        version: link:../core
       vitest:
         specifier: 'catalog:'
         version: 4.1.11(@edge-runtime/vm@5.0.0)(@opentelemetry/api@1.9.0)(@types/node@24.10.3)(@vitest/browser-playwright@4.1.11)(@vitest/browser-preview@4.1.11)(@vitest/browser-webdriverio@4.1.11)(happy-dom@20.0.10)(jsdom@27.2.0(supports-color@8.1.1))(vite@packages+core)
@@ -444,9 +444,6 @@ importers:
       validate-npm-package-name:
         specifier: 'catalog:'
         version: 7.0.2
-      vite:
-        specifier: workspace:@voidzero-dev/vite-plus-core@*
-        version: link:../core
       yaml:
         specifier: 'catalog:'
         version: 2.9.0
diff --git a/rfcs/vite-core-module-identity.md b/rfcs/vite-core-module-identity.md
index 5e2e294d8d..a4feb6df1b 100644
--- a/rfcs/vite-core-module-identity.md
+++ b/rfcs/vite-core-module-identity.md
@@ -182,6 +182,11 @@ peer dependency would make bundled commands depend on the user's installation.
 Audit the release and preview packers, local npm registry, toolchain manifest,
 and migration metadata readers for canonical-name resolution assumptions.
 Keep standalone core installations and their native binding resolution intact.
+Yarn PnP is not a supported runtime layout. The existing migrator converts it
+to `nodeLinker: node-modules`, as documented in
+[Yarn migration rules](../docs/guide/migrate-rules.md#yarn). This proposal keeps
+that behavior; it does not add PnP runtime support.
+
 Consumers that import core by its published name must declare that dependency;
 they cannot rely on the CLI exposing it through hoisting.
 
@@ -273,16 +278,16 @@ Workspace links can conceal the alias duplication. Add CLI regressions to the
 [PTY snapshot suite](../crates/vp_cli_snapshots/tests/cli_snapshots/README.md)
 and API/type coverage in the corresponding package tests.
 
-| Area                        | Required coverage                                                                                                        |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| SSR regression              | Original TanStack reproduction and latest supported TanStack; HTTP 200 and both guards pass                              |
-| Module identity             | ESM, CommonJS, module-runner, and CLI-created environments share the expected APIs                                       |
-| Package layouts             | Bun, npm, pnpm, Yarn with `node_modules`, Yarn PnP, pnpm global virtual store, and monorepos with separate peer contexts |
-| CLI without a project alias | Install `vite-plus` alone; resolve bundled commands and public APIs from its required dependency                         |
-| Invalid installations       | Missing dependency, upstream Vite override, stale core alias, and version mismatch produce actionable CLI errors         |
-| Types and commands          | Generated declarations, Vite/Vitest config augmentation, `vp dev`, `vp build`, `vp preview`, `vp test`, and `vp pack`    |
-| Distribution                | Release, preview, and local-registry tarballs declare the intended alias and retain standalone core binding support      |
-| Upgrade                     | Reinstall an existing project with the new CLI and matching aliases; exercise migration and version synchronization      |
+| Area                        | Required coverage                                                                                                                                        |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SSR regression              | Original TanStack reproduction and latest supported TanStack; HTTP 200 and both guards pass                                                              |
+| Module identity             | ESM, CommonJS, module-runner, and CLI-created environments share the expected APIs                                                                       |
+| Package layouts             | Bun, npm, pnpm, Yarn with `node_modules`, existing PnP-to-`node_modules` migration, pnpm global virtual store, and monorepos with separate peer contexts |
+| CLI without a project alias | Install `vite-plus` alone; resolve bundled commands and public APIs from its required dependency                                                         |
+| Invalid installations       | Missing dependency, upstream Vite override, stale core alias, and version mismatch produce actionable CLI errors                                         |
+| Types and commands          | Generated declarations, Vite/Vitest config augmentation, `vp dev`, `vp build`, `vp preview`, `vp test`, and `vp pack`                                    |
+| Distribution                | Release, preview, and local-registry tarballs declare the intended alias and retain standalone core binding support                                      |
+| Upgrade                     | Reinstall an existing project with the new CLI and matching aliases; exercise migration and version synchronization                                      |
 
 The release gate is a source-built install that shares runtime identity in the
 supported layouts. If a package manager creates separate peer variants that
@@ -291,7 +296,7 @@ break the regression, resolve that case before shipping or revise this design.
 ## Open questions
 
 1. Can the CLI's alias dependency and each plugin's Vite peer resolve to the
-   same runtime across the supported monorepo and PnP layouts? The prototype
+   same runtime across the supported monorepo layouts? The prototype
    covered single-project installs.
 2. Which existing configuration types require changes when the CLI augments
    `vite` alongside Vitest? Declaration tests must settle this before release.

From 27b1f601ee999d66cbb80908054d4a19e4de7172 Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Sun, 6 Sep 2026 23:44:09 +0800
Subject: [PATCH 3/9] fix(cli): validate installed core versions after
 repacking

---
 .../core_module_identity/snapshots.toml       | 16 +++++
 .../snapshots/core_module_identity_bun.md     |  2 +-
 .../snapshots/core_module_identity_npm.md     |  2 +-
 .../snapshots/core_module_identity_pnpm.md    |  2 +-
 .../core_module_identity_pnpm_global_store.md |  2 +-
 ...core_module_identity_pnpm_peer_contexts.md |  4 +-
 ...core_module_identity_repackaged_version.md | 58 +++++++++++++++++++
 ...e_module_identity_without_project_alias.md |  2 +-
 .../snapshots/core_module_identity_yarn.md    |  2 +-
 .../cli/src/__tests__/resolve-core.spec.ts    | 36 ++++++++++++
 packages/cli/src/resolve-core.ts              | 17 +++---
 11 files changed, 128 insertions(+), 15 deletions(-)
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_repackaged_version.md

diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml
index 526917d5ac..b487006a95 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml
@@ -8,6 +8,22 @@ steps = [
   ["vp", "dev"],
 ]
 
+[[case]]
+name = "core_module_identity_repackaged_version"
+vp = "global"
+local-registry = true
+comment = "CI can stamp the package version after building the CLI. The resolver must compare installed manifests rather than an inlined build-time version."
+steps = [
+  { argv = ["vp", "install", "--ignore-scripts"], snapshot = false },
+  { argv = ["vpt", "json-edit", "node_modules/vite-plus/package.json", "version", "0.0.0"], snapshot = false },
+  { argv = ["vpt", "json-edit", "node_modules/vite-plus/package.json", "dependencies.vite", "npm:@voidzero-dev/vite-plus-core@0.0.0"], snapshot = false },
+  { argv = ["vpt", "json-edit", "node_modules/vite/package.json", "version", "0.0.0"], snapshot = false },
+  ["node", "check-api.mjs"],
+  ["vp", "dev"],
+  ["vp", "build"],
+  ["vp", "pack", "entry.js"],
+]
+
 [[case]]
 name = "core_module_identity_yarn"
 vp = "global"
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_bun.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_bun.md
index ea2f29e682..62e7688c85 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_bun.md
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_bun.md
@@ -13,7 +13,7 @@ Packed alias, ESM, CommonJS, and module-runner identity passed
 
 ```
 
-  VITE <version>
+  VITE+ <version>
 
   ➜  Local:   http://127.0.0.1:<port>/
   ➜  press h + enter to show help
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm.md
index c0f8da3c40..7d894496cf 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm.md
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm.md
@@ -16,7 +16,7 @@ Packed alias, ESM, CommonJS, and module-runner identity passed
 
 ```
 
-  VITE <version>
+  VITE+ <version>
 
   ➜  Local:   http://127.0.0.1:<port>/
   ➜  press h + enter to show help
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm.md
index fb84f9bc81..060f920f18 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm.md
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm.md
@@ -22,7 +22,7 @@ Packed alias, ESM, CommonJS, and module-runner identity passed
 
 ```
 
-  VITE <version>
+  VITE+ <version>
 
   ➜  Local:   http://127.0.0.1:<port>/
   ➜  press h + enter to show help
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_global_store.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_global_store.md
index efff058413..9a56d9db06 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_global_store.md
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_global_store.md
@@ -23,7 +23,7 @@ Packed alias, ESM, CommonJS, and module-runner identity passed
 
 ```
 
-  VITE <version>
+  VITE+ <version>
 
   ➜  Local:   http://127.0.0.1:<port>/
   ➜  press h + enter to show help
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_peer_contexts.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_peer_contexts.md
index 80f7592f84..a956d9a999 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_peer_contexts.md
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_pnpm_peer_contexts.md
@@ -45,7 +45,7 @@ Packed alias, ESM, CommonJS, and module-runner identity passed
 
 ```
 
-  VITE <version>
+  VITE+ <version>
 
   ➜  Local:   http://127.0.0.1:<port>/
   ➜  press h + enter to show help
@@ -62,7 +62,7 @@ Packed alias, ESM, CommonJS, and module-runner identity passed
 
 ```
 
-  VITE <version>
+  VITE+ <version>
 
   ➜  Local:   http://127.0.0.1:<port>/
   ➜  press h + enter to show help
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_repackaged_version.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_repackaged_version.md
new file mode 100644
index 0000000000..cb2e5d51f3
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_repackaged_version.md
@@ -0,0 +1,58 @@
+# core_module_identity_repackaged_version
+
+CI can stamp the package version after building the CLI. The resolver must compare installed manifests rather than an inlined build-time version.
+
+## `vp install --ignore-scripts`
+
+
+## `vpt json-edit node_modules/vite-plus/package.json version 0.0.0`
+
+
+## `vpt json-edit node_modules/vite-plus/package.json dependencies.vite npm:@voidzero-dev/vite-plus-core@0.0.0`
+
+
+## `vpt json-edit node_modules/vite/package.json version 0.0.0`
+
+
+## `node check-api.mjs`
+
+```
+Packed alias, ESM, CommonJS, and module-runner identity passed
+```
+
+## `vp dev`
+
+```
+
+  VITE+ <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
+
+## `vp build`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ 4 modules transformed.
+computing gzip size...
+dist/index.html                <size> kB │ gzip: <size> kB
+dist/assets/index-<hash>.js  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp pack entry.js`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+ℹ entry: entry.js
+ℹ Build start
+ℹ Cleaning <n> files
+ℹ dist/entry.mjs  <size> kB │ gzip: <size> kB
+ℹ 1 files, total: <size> kB
+✔ Build complete in <duration>
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_without_project_alias.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_without_project_alias.md
index a88407b2d0..121227e830 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_without_project_alias.md
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_without_project_alias.md
@@ -27,7 +27,7 @@ Bundled APIs resolve without a project Vite dependency
 
 ```
 
-  VITE <version>
+  VITE+ <version>
 
   ➜  Local:   http://127.0.0.1:<port>/
   ➜  press h + enter to show help
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_yarn.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_yarn.md
index 1292650b63..76c0be09c5 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_yarn.md
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_yarn.md
@@ -24,7 +24,7 @@ Packed alias, ESM, CommonJS, and module-runner identity passed
 
 ```
 
-  VITE <version>
+  VITE+ <version>
 
   ➜  Local:   http://127.0.0.1:<port>/
   ➜  press h + enter to show help
diff --git a/packages/cli/src/__tests__/resolve-core.spec.ts b/packages/cli/src/__tests__/resolve-core.spec.ts
index 168117ebbb..2e22cdb489 100644
--- a/packages/cli/src/__tests__/resolve-core.spec.ts
+++ b/packages/cli/src/__tests__/resolve-core.spec.ts
@@ -25,6 +25,18 @@ function writeCore(
   writeFileSync(join(directory, 'pack.js'), '');
 }
 
+function writeCli(directory: string, version = cliPkg.version) {
+  mkdirSync(directory, { recursive: true });
+  writeFileSync(
+    join(directory, 'package.json'),
+    JSON.stringify({
+      name: 'vite-plus',
+      version,
+      exports: { './package.json': './package.json' },
+    }),
+  );
+}
+
 describe('resolveCore', () => {
   let root: string;
   let project: string;
@@ -37,6 +49,7 @@ describe('resolveCore', () => {
     mkdirSync(project);
     cliModule = join(root, 'cli', 'dist', 'bin.js');
     bundled = join(root, 'cli', 'node_modules', 'vite');
+    writeCli(join(root, 'cli'));
     writeCore(bundled);
   });
 
@@ -54,6 +67,29 @@ describe('resolveCore', () => {
     expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
   });
 
+  it.each(['0.0.0', '0.0.0-commit.1234567'])(
+    'uses the installed CLI manifest after repacking as %s',
+    (version) => {
+      writeCli(join(root, 'cli'), version);
+      writeCore(bundled, '@voidzero-dev/vite-plus-core', version);
+      writeCore(join(project, 'node_modules', 'vite'), '@voidzero-dev/vite-plus-core', version);
+      expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
+      expect(resolveCore('/pack', project, cliModule)).toBe(join(bundled, 'pack.js'));
+    },
+  );
+
+  it.each(['project', 'bundled'])(
+    'still rejects a mismatched %s core after repacking the CLI',
+    (location) => {
+      writeCli(join(root, 'cli'), '0.0.0');
+      writeCore(bundled, '@voidzero-dev/vite-plus-core', '0.0.0');
+      writeCore(location === 'project' ? join(project, 'node_modules', 'vite') : bundled);
+      expect(() => resolveCore('', project, cliModule)).toThrow(
+        `Expected @voidzero-dev/vite-plus-core@0.0.0, but found @voidzero-dev/vite-plus-core@${cliPkg.version}`,
+      );
+    },
+  );
+
   it('does not fall back to the project when the CLI dependency is missing', () => {
     writeCore(join(project, 'node_modules', 'vite'));
     rmSync(bundled, { recursive: true });
diff --git a/packages/cli/src/resolve-core.ts b/packages/cli/src/resolve-core.ts
index aaf2aab3a4..4b0e89d35c 100644
--- a/packages/cli/src/resolve-core.ts
+++ b/packages/cli/src/resolve-core.ts
@@ -2,18 +2,16 @@ import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 
-import cliPkg from '../package.json' with { type: 'json' };
-
 const CORE_PACKAGE_NAME = '@voidzero-dev/vite-plus-core';
 
-function checkCoreVersion(packageJsonPath: string): void {
+function checkCoreVersion(packageJsonPath: string, expectedVersion: string): void {
   const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
     name?: string;
     version?: string;
   };
-  if (pkg.name !== CORE_PACKAGE_NAME || pkg.version !== cliPkg.version) {
+  if (pkg.name !== CORE_PACKAGE_NAME || pkg.version !== expectedVersion) {
     throw new Error(
-      `Expected ${CORE_PACKAGE_NAME}@${cliPkg.version}, but found ${pkg.name}@${pkg.version} at ${packageJsonPath}. ` +
+      `Expected ${CORE_PACKAGE_NAME}@${expectedVersion}, but found ${pkg.name}@${pkg.version} at ${packageJsonPath}. ` +
         'Run `vp migrate` to align the Vite alias, then run `vp install`.',
     );
   }
@@ -26,13 +24,18 @@ export function resolveCore(
   modulePath = import.meta.url,
 ): string {
   const require = createRequire(modulePath);
+  // Read the selected CLI's installed manifest. A static JSON import is inlined
+  // during the build, before CI and preview packers can stamp a new version.
+  const { version: expectedVersion } = JSON.parse(
+    readFileSync(require.resolve('vite-plus/package.json'), 'utf8'),
+  ) as { version: string };
   let packageJsonPath: string;
   try {
     packageJsonPath = require.resolve('vite/package.json');
   } catch (cause) {
     throw new Error('Could not resolve the bundled Vite dependency. Run `vp install`.', { cause });
   }
-  checkCoreVersion(packageJsonPath);
+  checkCoreVersion(packageJsonPath, expectedVersion);
 
   // A migrated project's alias must match the CLI release. Without a project
   // alias, the required dependency above still supplies the bundled commands.
@@ -46,7 +49,7 @@ export function resolveCore(
     }
   }
   if (projectPackageJsonPath && projectPackageJsonPath !== packageJsonPath) {
-    checkCoreVersion(projectPackageJsonPath);
+    checkCoreVersion(projectPackageJsonPath, expectedVersion);
   }
 
   return require.resolve(`vite${subpath}`);

From 4f28a4bdb2882ac50d256312630e3542203b2411 Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Sun, 6 Sep 2026 23:58:53 +0800
Subject: [PATCH 4/9] test: keep Bun registry cache off the Windows Dev Drive

---
 packages/tools/src/local-npm-registry.ts | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/tools/src/local-npm-registry.ts b/packages/tools/src/local-npm-registry.ts
index f294933838..8e8260120f 100644
--- a/packages/tools/src/local-npm-registry.ts
+++ b/packages/tools/src/local-npm-registry.ts
@@ -539,6 +539,11 @@ function buildRegistryEnv(registry: string): Record<string, string> {
   const noProxy = [process.env.NO_PROXY ?? process.env.no_proxy, '127.0.0.1']
     .filter(Boolean)
     .join(',');
+  // Windows snapshot jobs put TEMP on a ReFS Dev Drive, where Bun's
+  // cache/temp renames can fail with ENOTSUP. Keep its throwaway cache in
+  // the user profile and its temporary files on the same filesystem.
+  const bunCacheRoot = process.platform === 'win32' ? homedir() : tmpdir();
+  const bunCacheDir = mkdtempSync(path.join(bunCacheRoot, 'vp-local-registry-bun-'));
   return {
     NPM_CONFIG_REGISTRY: registry,
     npm_config_registry: registry,
@@ -550,7 +555,8 @@ function buildRegistryEnv(registry: string): Record<string, string> {
     NPM_CONFIG_NOPROXY: noProxy,
     npm_config_noproxy: noProxy,
     YARN_GLOBAL_FOLDER: mkdtempSync(path.join(tmpdir(), 'vp-local-registry-yarn-')),
-    BUN_INSTALL_CACHE_DIR: mkdtempSync(path.join(tmpdir(), 'vp-local-registry-bun-')),
+    BUN_INSTALL_CACHE_DIR: bunCacheDir,
+    BUN_TMPDIR: path.join(bunCacheDir, '.tmp'),
   };
 }
 

From 0f801e7e00056c22b12a12fc07a2aa0307cf22ec Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Mon, 7 Sep 2026 11:44:48 +0800
Subject: [PATCH 5/9] fix(cli): support npm installs with hoisted Vite peers

---
 .../core_module_identity/check-config.mts     | 11 +++
 .../core_module_identity/check-npm-layout.mjs | 15 ++++
 .../core_module_identity/snapshots.toml       | 37 +++++++++
 ...odule_identity_npm_cli_only_no_override.md | 75 +++++++++++++++++++
 ...identity_npm_matching_alias_no_override.md | 72 ++++++++++++++++++
 .../core_resolution_errors/package.json       |  5 +-
 .../cli/src/__tests__/resolve-core.spec.ts    | 31 ++++++++
 packages/cli/src/define-config.ts             |  7 ++
 packages/cli/src/resolve-core.ts              | 17 ++++-
 9 files changed, 267 insertions(+), 3 deletions(-)
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-config.mts
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-npm-layout.mjs
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm_cli_only_no_override.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm_matching_alias_no_override.md

diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-config.mts b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-config.mts
new file mode 100644
index 0000000000..fc3d6853f1
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-config.mts
@@ -0,0 +1,11 @@
+import { defineConfig, type UserConfig } from 'vite-plus';
+
+const config: UserConfig = {
+  test: { globals: true },
+  pack: { entry: ['entry.js'] },
+  lint: {},
+  fmt: {},
+  run: { tasks: { hello: { command: 'echo hello' } } },
+};
+defineConfig(config);
+defineConfig({ test: { globals: true } });
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-npm-layout.mjs b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-npm-layout.mjs
new file mode 100644
index 0000000000..ce245adb34
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-npm-layout.mjs
@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cliRequire = createRequire(require.resolve('vite-plus/package.json'));
+const vitestRequire = createRequire(cliRequire.resolve('vitest/package.json'));
+assert.equal(require('./package.json').overrides, undefined);
+assert.equal(cliRequire('vite/package.json').name, '@voidzero-dev/vite-plus-core');
+assert.equal(vitestRequire('vite/package.json').name, 'vite');
+assert.notEqual(cliRequire.resolve('vite/package.json'), vitestRequire.resolve('vite/package.json'));
+if (!require('./package.json').devDependencies.vite) {
+  assert.deepEqual(Object.keys(require('./package.json').devDependencies), ['vite-plus']);
+  assert.equal(require('vite/package.json').name, 'vite');
+}
+console.log('npm installed separate CLI core and upstream Vitest peer without overrides');
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml
index b487006a95..1c4edad856 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots.toml
@@ -107,3 +107,40 @@ steps = [
   { argv = ["node", "check-api.mjs"], cwd = "packages/b" },
   { argv = ["vp", "dev"], cwd = "packages/b" },
 ]
+
+[[case]]
+name = "core_module_identity_npm_cli_only_no_override"
+vp = "global"
+local-registry = true
+steps = [
+  { argv = ["vpt", "write-file", "package.json", "{\"name\":\"core-module-identity\",\"private\":true,\"type\":\"module\",\"packageManager\":\"npm@11.11.0\",\"devDependencies\":{\"vite-plus\":\"latest\"}}\n"], snapshot = false },
+  { argv = ["vpt", "replace-file-content", "vite.config.ts", "from 'vite';", "from 'vite-plus';"], snapshot = false },
+  { argv = ["vp", "install", "--ignore-scripts"], timeout = 120000, snapshot = false },
+  { argv = ["node", "check-npm-layout.mjs"] },
+  { argv = ["node", "check-bundled.mjs"] },
+  { argv = ["vp", "dev"] },
+  { argv = ["vp", "build"] },
+  { argv = ["vp", "pack", "entry.js"] },
+  { argv = ["vpt", "write-file", "typecheck/package.json", "{\"name\":\"typecheck-tools\",\"private\":true,\"dependencies\":{\"typescript\":\"6.0.3\"},\"packageManager\":\"npm@11.11.0\"}\n"], snapshot = false },
+  { argv = ["vp", "install", "--ignore-scripts"], cwd = "typecheck", snapshot = false },
+  { argv = ["vpt", "cp", "check-config.mts", "check-config.cts"], snapshot = false },
+  { argv = ["node", "typecheck/node_modules/typescript/bin/tsc", "--noEmit", "--skipLibCheck", "--module", "NodeNext", "--target", "ESNext", "check-config.mts", "check-config.cts"] },
+]
+
+[[case]]
+name = "core_module_identity_npm_matching_alias_no_override"
+vp = "global"
+local-registry = true
+steps = [
+  { argv = ["vpt", "write-file", "package.json", "{\"name\":\"core-module-identity\",\"private\":true,\"type\":\"module\",\"packageManager\":\"npm@11.11.0\",\"devDependencies\":{\"vite-plus\":\"latest\",\"vite\":\"npm:@voidzero-dev/vite-plus-core@latest\"}}\n"], snapshot = false },
+  { argv = ["vp", "install", "--ignore-scripts"], timeout = 120000, snapshot = false },
+  { argv = ["node", "check-npm-layout.mjs"] },
+  { argv = ["node", "check-api.mjs"] },
+  { argv = ["vp", "dev"] },
+  { argv = ["vp", "build"] },
+  { argv = ["vp", "pack", "entry.js"] },
+  { argv = ["vpt", "write-file", "typecheck/package.json", "{\"name\":\"typecheck-tools\",\"private\":true,\"dependencies\":{\"typescript\":\"6.0.3\"},\"packageManager\":\"npm@11.11.0\"}\n"], snapshot = false },
+  { argv = ["vp", "install", "--ignore-scripts"], cwd = "typecheck", snapshot = false },
+  { argv = ["vpt", "cp", "check-config.mts", "check-config.cts"], snapshot = false },
+  { argv = ["node", "typecheck/node_modules/typescript/bin/tsc", "--noEmit", "--skipLibCheck", "--module", "NodeNext", "--target", "ESNext", "check-config.mts", "check-config.cts"] },
+]
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm_cli_only_no_override.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm_cli_only_no_override.md
new file mode 100644
index 0000000000..c04db3d0b8
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm_cli_only_no_override.md
@@ -0,0 +1,75 @@
+# core_module_identity_npm_cli_only_no_override
+
+## `vpt write-file package.json '{"name":"core-module-identity","private":true,"type":"module","packageManager":"npm@11.11.0","devDependencies":{"vite-plus":"latest"}}
+'`
+
+
+## `vpt replace-file-content vite.config.ts 'from '\''vite'\'';' 'from '\''vite-plus'\'';'`
+
+
+## `vp install --ignore-scripts`
+
+
+## `node check-npm-layout.mjs`
+
+```
+npm installed separate CLI core and upstream Vitest peer without overrides
+```
+
+## `node check-bundled.mjs`
+
+```
+Bundled APIs resolve without a project Vite dependency
+```
+
+## `vp dev`
+
+```
+
+  VITE+ <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
+
+## `vp build`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ 4 modules transformed.
+computing gzip size...
+dist/index.html                <size> kB │ gzip: <size> kB
+dist/assets/index-<hash>.js  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp pack entry.js`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+ℹ entry: entry.js
+ℹ Build start
+ℹ Cleaning <n> files
+ℹ dist/entry.mjs  <size> kB │ gzip: <size> kB
+ℹ 1 files, total: <size> kB
+✔ Build complete in <duration>
+```
+
+## `vpt write-file typecheck/package.json '{"name":"typecheck-tools","private":true,"dependencies":{"typescript":"6.0.3"},"packageManager":"npm@11.11.0"}
+'`
+
+
+## `cd typecheck && vp install --ignore-scripts`
+
+
+## `vpt cp check-config.mts check-config.cts`
+
+
+## `node typecheck/node_modules/typescript/bin/tsc --noEmit --skipLibCheck --module NodeNext --target ESNext check-config.mts check-config.cts`
+
+```
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm_matching_alias_no_override.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm_matching_alias_no_override.md
new file mode 100644
index 0000000000..ad57acf182
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/snapshots/core_module_identity_npm_matching_alias_no_override.md
@@ -0,0 +1,72 @@
+# core_module_identity_npm_matching_alias_no_override
+
+## `vpt write-file package.json '{"name":"core-module-identity","private":true,"type":"module","packageManager":"npm@11.11.0","devDependencies":{"vite-plus":"latest","vite":"npm:@voidzero-dev/vite-plus-core@latest"}}
+'`
+
+
+## `vp install --ignore-scripts`
+
+
+## `node check-npm-layout.mjs`
+
+```
+npm installed separate CLI core and upstream Vitest peer without overrides
+```
+
+## `node check-api.mjs`
+
+```
+Packed alias, ESM, CommonJS, and module-runner identity passed
+```
+
+## `vp dev`
+
+```
+
+  VITE+ <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+SSR environment identity and HTTP response passed
+```
+
+## `vp build`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ 4 modules transformed.
+computing gzip size...
+dist/index.html                <size> kB │ gzip: <size> kB
+dist/assets/index-<hash>.js  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp pack entry.js`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+ℹ entry: entry.js
+ℹ Build start
+ℹ Cleaning <n> files
+ℹ dist/entry.mjs  <size> kB │ gzip: <size> kB
+ℹ 1 files, total: <size> kB
+✔ Build complete in <duration>
+```
+
+## `vpt write-file typecheck/package.json '{"name":"typecheck-tools","private":true,"dependencies":{"typescript":"6.0.3"},"packageManager":"npm@11.11.0"}
+'`
+
+
+## `cd typecheck && vp install --ignore-scripts`
+
+
+## `vpt cp check-config.mts check-config.cts`
+
+
+## `node typecheck/node_modules/typescript/bin/tsc --noEmit --skipLibCheck --module NodeNext --target ESNext check-config.mts check-config.cts`
+
+```
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/package.json b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/package.json
index baf92f8932..8ac96bcdd0 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/package.json
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_resolution_errors/package.json
@@ -1,5 +1,8 @@
 {
   "name": "core-resolution-errors",
   "private": true,
-  "type": "module"
+  "type": "module",
+  "devDependencies": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest"
+  }
 }
diff --git a/packages/cli/src/__tests__/resolve-core.spec.ts b/packages/cli/src/__tests__/resolve-core.spec.ts
index 2e22cdb489..510d54fbe3 100644
--- a/packages/cli/src/__tests__/resolve-core.spec.ts
+++ b/packages/cli/src/__tests__/resolve-core.spec.ts
@@ -47,6 +47,12 @@ describe('resolveCore', () => {
     root = realpathSync(mkdtempSync(join(tmpdir(), 'vp-core-resolver-')));
     project = join(root, 'project');
     mkdirSync(project);
+    writeFileSync(
+      join(project, 'package.json'),
+      JSON.stringify({
+        devDependencies: { vite: `npm:@voidzero-dev/vite-plus-core@${cliPkg.version}` },
+      }),
+    );
     cliModule = join(root, 'cli', 'dist', 'bin.js');
     bundled = join(root, 'cli', 'node_modules', 'vite');
     writeCli(join(root, 'cli'));
@@ -58,10 +64,35 @@ describe('resolveCore', () => {
   });
 
   it('supports a CLI installation without a project-level vite alias', () => {
+    writeFileSync(
+      join(project, 'package.json'),
+      JSON.stringify({ devDependencies: { 'vite-plus': cliPkg.version } }),
+    );
+    expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
+    expect(resolveCore('/pack', project, cliModule)).toBe(join(bundled, 'pack.js'));
+  });
+
+  it('ignores an upstream Vite peer hoisted by npm in a CLI-only project', () => {
+    writeFileSync(
+      join(project, 'package.json'),
+      JSON.stringify({ devDependencies: { 'vite-plus': cliPkg.version } }),
+    );
+    writeCore(join(project, 'node_modules', 'vite'), 'vite', '8.2.2');
     expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
     expect(resolveCore('/pack', project, cliModule)).toBe(join(bundled, 'pack.js'));
   });
 
+  it.each(['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'])(
+    'validates an explicit Vite declaration in %s from a project subdirectory',
+    (field) => {
+      writeFileSync(join(project, 'package.json'), JSON.stringify({ [field]: { vite: '^8.0.0' } }));
+      writeCore(join(project, 'node_modules', 'vite'), 'vite', '8.2.2');
+      const subdirectory = join(project, 'src');
+      mkdirSync(subdirectory);
+      expect(() => resolveCore('', subdirectory, cliModule)).toThrow('found vite@8.2.2');
+    },
+  );
+
   it('keeps the same anchor as static exports when the project has a matching copy', () => {
     writeCore(join(project, 'node_modules', 'vite'));
     expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
diff --git a/packages/cli/src/define-config.ts b/packages/cli/src/define-config.ts
index 058b57afe6..c3f222eedf 100644
--- a/packages/cli/src/define-config.ts
+++ b/packages/cli/src/define-config.ts
@@ -14,6 +14,7 @@ import {
   type UserProjectConfigFn,
   type UserWorkspaceConfig,
 } from 'vitest/config';
+import type { InlineConfig as VitestInlineConfig } from 'vitest/node';
 
 import type { CreateTemplateEntry } from './create/org-manifest.ts';
 import type { PackUserConfig } from './pack.ts';
@@ -23,6 +24,12 @@ import { CONFIG_METADATA_ENV, VITEST_VERSION } from './utils/constants.ts';
 
 declare module 'vite' {
   interface UserConfig {
+    /**
+     * Vitest may augment a separate Vite copy, for example an npm peer dependency.
+     * Keep the public test field on the CLI's core types in that layout too.
+     */
+    test?: VitestInlineConfig;
+
     /**
      * Options for oxlint
      */
diff --git a/packages/cli/src/resolve-core.ts b/packages/cli/src/resolve-core.ts
index 4b0e89d35c..b6e766fd1a 100644
--- a/packages/cli/src/resolve-core.ts
+++ b/packages/cli/src/resolve-core.ts
@@ -2,6 +2,8 @@ import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 
+import { readNearestPackageJson } from './utils/package.ts';
+
 const CORE_PACKAGE_NAME = '@voidzero-dev/vite-plus-core';
 
 function checkCoreVersion(packageJsonPath: string, expectedVersion: string): void {
@@ -37,8 +39,19 @@ export function resolveCore(
   }
   checkCoreVersion(packageJsonPath, expectedVersion);
 
-  // A migrated project's alias must match the CLI release. Without a project
-  // alias, the required dependency above still supplies the bundled commands.
+  // npm can hoist an upstream Vite peer even when the project only declares
+  // vite-plus. Validate Vite only when the nearest package declares it.
+  const projectPackage = readNearestPackageJson(cwd);
+  const declaresVite = [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+    'peerDependencies',
+  ].some((field) => Object.hasOwn(projectPackage?.[field] ?? {}, 'vite'));
+  if (!declaresVite) {
+    return require.resolve(`vite${subpath}`);
+  }
+
   const projectRequire = createRequire(join(cwd, 'package.json'));
   let projectPackageJsonPath: string | undefined;
   try {

From 0af9041134318e55e6796e9891e6bd858449798d Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Mon, 7 Sep 2026 11:45:07 +0800
Subject: [PATCH 6/9] fix(cli): validate Vite aliases in the command target

---
 .../core_command_root/check-layout.mjs        |  12 ++
 .../fixtures/core_command_root/package.json   |  13 ++
 .../core_command_root/packages/app/index.html |   1 +
 .../packages/app/package.json                 |  13 ++
 .../packages/app/src/index.ts                 |   1 +
 .../packages/app/vite.config.ts               |  38 +++++
 .../core_command_root/pnpm-workspace.yaml     |   3 +
 .../fixtures/core_command_root/snapshots.toml |  20 +++
 .../core_command_root_dispatch.global.md      | 146 ++++++++++++++++++
 .../core_command_root_dispatch.local.md       | 126 +++++++++++++++
 .../fixtures/core_command_root/vite.config.ts |   1 +
 packages/cli/binding/index.d.cts              |  18 ++-
 packages/cli/binding/src/cli/execution.rs     |   2 +-
 packages/cli/binding/src/cli/handler.rs       |   3 +-
 packages/cli/binding/src/cli/resolver.rs      |  20 +--
 packages/cli/binding/src/cli/types.rs         |   9 +-
 packages/cli/binding/src/lib.rs               |  31 ++--
 .../cli/src/__tests__/resolve-vite.spec.ts    |  36 +++++
 packages/cli/src/resolve-pack.ts              |  11 +-
 packages/cli/src/resolve-vite.ts              |  38 ++++-
 rfcs/vite-core-module-identity.md             |  19 ++-
 21 files changed, 523 insertions(+), 38 deletions(-)
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/check-layout.mjs
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/package.json
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/index.html
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/package.json
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/src/index.ts
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/vite.config.ts
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/pnpm-workspace.yaml
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots.toml
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots/core_command_root_dispatch.global.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots/core_command_root_dispatch.local.md
 create mode 100644 crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/vite.config.ts
 create mode 100644 packages/cli/src/__tests__/resolve-vite.spec.ts

diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/check-layout.mjs b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/check-layout.mjs
new file mode 100644
index 0000000000..20defe976e
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/check-layout.mjs
@@ -0,0 +1,12 @@
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const appRequire = createRequire(new URL('./packages/app/package.json', import.meta.url));
+const cliRequire = createRequire(require.resolve('vite-plus/package.json'));
+console.log('Root Vite:', require('vite/package.json').name);
+console.log('App Vite:', appRequire('vite/package.json').name);
+console.log('CLI Vite:', cliRequire('vite/package.json').name);
+assert.equal(require('vite/package.json').name, 'vite');
+assert.equal(appRequire('vite/package.json').name, '@voidzero-dev/vite-plus-core');
+assert.equal(cliRequire('vite/package.json').name, '@voidzero-dev/vite-plus-core');
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/package.json b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/package.json
new file mode 100644
index 0000000000..4c25eb2b31
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "core-command-root",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@11.24.0",
+  "workspaces": [
+    "packages/*"
+  ],
+  "devDependencies": {
+    "vite": "8.2.2",
+    "vite-plus": "latest"
+  }
+}
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/index.html b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/index.html
new file mode 100644
index 0000000000..5e11851634
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/index.html
@@ -0,0 +1 @@
+<h1>Correct project root</h1>
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/package.json b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/package.json
new file mode 100644
index 0000000000..2928a52f0e
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vp build",
+    "pack": "vp pack"
+  },
+  "devDependencies": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+    "vite-plus": "latest"
+  }
+}
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/src/index.ts b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/src/index.ts
new file mode 100644
index 0000000000..c6c3f9c8c2
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/src/index.ts
@@ -0,0 +1 @@
+export const message = 'Correct project root';
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/vite.config.ts b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/vite.config.ts
new file mode 100644
index 0000000000..f22279b852
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/packages/app/vite.config.ts
@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict';
+
+export default {
+  server: { host: '127.0.0.1', port: 0 },
+  preview: { host: '127.0.0.1', port: 0 },
+  plugins: [
+    {
+      name: 'check-target-server',
+      configureServer: checkServer,
+      configurePreviewServer: checkServer,
+    },
+  ],
+};
+
+function checkServer(server) {
+  server.httpServer.once('listening', async () => {
+    try {
+      const address = server.httpServer.address();
+      assert.ok(address && typeof address === 'object');
+      const response = await fetch(`http://127.0.0.1:${address.port}/`, {
+        signal: AbortSignal.timeout(10_000),
+      });
+      assert.equal(response.status, 200);
+      assert.match(await response.text(), /Correct project root/);
+      console.log('The target app served HTTP 200');
+    } catch (error) {
+      console.error(error);
+      process.exitCode = 1;
+    } finally {
+      // PreviewServer has no close() method.
+      if (server.close) {
+        await server.close();
+      } else {
+        server.httpServer.close();
+      }
+    }
+  });
+}
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/pnpm-workspace.yaml b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/pnpm-workspace.yaml
new file mode 100644
index 0000000000..ed99ee8054
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/pnpm-workspace.yaml
@@ -0,0 +1,3 @@
+packages:
+  - packages/*
+minimumReleaseAge: 0
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots.toml b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots.toml
new file mode 100644
index 0000000000..d45580d551
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots.toml
@@ -0,0 +1,20 @@
+[[case]]
+name = "core_command_root_dispatch"
+vp = ["local", "global"]
+local-registry = true
+comment = "The workspace declares upstream Vite. Only the target app declares the matching core alias. Check positional roots, -C, defaultPackage, and task dispatch."
+steps = [
+  { argv = ["vp", "install", "--ignore-scripts"], timeout = 120000, snapshot = false },
+  ["node", "check-layout.mjs"],
+  ["vp", "build", "packages/app"],
+  ["vp", "build", "--mode", "production", "--emptyOutDir", "packages/app"],
+  ["vp", "dev", "packages/app"],
+  ["vp", "preview", "--strictPort", "packages/app"],
+  ["vp", "-C", "packages/app", "build"],
+  ["vp", "build"],
+  ["vp", "pack"],
+  ["vp", "run", "--filter", "app", "build"],
+  ["vp", "run", "--filter", "app", "pack"],
+  { argv = ["vp", "build", "."], continue-on-failure = true },
+  ["vp", "-C", ".", "pack", "packages/app/src/index.ts"],
+]
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots/core_command_root_dispatch.global.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots/core_command_root_dispatch.global.md
new file mode 100644
index 0000000000..dd74211ee1
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots/core_command_root_dispatch.global.md
@@ -0,0 +1,146 @@
+# core_command_root_dispatch
+
+The workspace declares upstream Vite. Only the target app declares the matching core alias. Check positional roots, -C, defaultPackage, and task dispatch.
+
+## `vp install --ignore-scripts`
+
+
+## `node check-layout.mjs`
+
+```
+Root Vite: vite
+App Vite: @voidzero-dev/vite-plus-core
+CLI Vite: @voidzero-dev/vite-plus-core
+```
+
+## `vp build packages/app`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ 2 modules transformed.
+computing gzip size...
+packages/app/dist/index.html  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp build --mode production --emptyOutDir packages/app`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ 2 modules transformed.
+computing gzip size...
+packages/app/dist/index.html  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp dev packages/app`
+
+```
+
+  VITE+ <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+The target app served HTTP 200
+```
+
+## `vp preview --strictPort packages/app`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+The target app served HTTP 200
+```
+
+## `vp -C packages/app build`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+note: You are running `vp build` as a Vite+ built-in command. If you meant to run the build npm script, use `vpr build` instead.
+✓ 2 modules transformed.
+computing gzip size...
+dist/index.html  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp build`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+note: vp build: using packages/app (defaultPackage in vite.config.ts)
+✓ 2 modules transformed.
+computing gzip size...
+dist/index.html  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp pack`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+note: vp pack: using packages/app (defaultPackage in vite.config.ts)
+ℹ entry: src/index.ts
+ℹ Build start
+ℹ Cleaning <n> files
+ℹ dist/index.mjs  <size> kB │ gzip: <size> kB
+ℹ 1 files, total: <size> kB
+✔ Build complete in <duration>
+```
+
+## `vp run --filter app build`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+~/packages/app$ vp build ⊘ cache disabled
+✓ 2 modules transformed.
+computing gzip size...
+dist/index.html  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp run --filter app pack`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+~/packages/app$ vp pack ⊘ cache disabled
+ℹ entry: src/index.ts
+ℹ Build start
+ℹ Cleaning <n> files
+ℹ dist/index.mjs  <size> kB │ gzip: <size> kB
+ℹ 1 files, total: <size> kB
+✔ Build complete in <duration>
+```
+
+## `vp build .`
+
+**Exit code:** 1
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+error: Failed to resolve vite command: GenericFailure, Expected @voidzero-dev/vite-plus-core@<version>, but found vite@8.2.2 at <workspace>/node_modules/.pnpm/vite@8.2.2/node_modules/vite/package.json. Run `vp migrate` to align the Vite alias, then run `vp install`.
+```
+
+## `vp -C . pack packages/app/src/index.ts`
+
+**Exit code:** 1
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+error: Failed to resolve pack command: GenericFailure, Expected @voidzero-dev/vite-plus-core@<version>, but found vite@8.2.2 at <workspace>/node_modules/.pnpm/vite@8.2.2/node_modules/vite/package.json. Run `vp migrate` to align the Vite alias, then run `vp install`.
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots/core_command_root_dispatch.local.md b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots/core_command_root_dispatch.local.md
new file mode 100644
index 0000000000..f78225bd16
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/snapshots/core_command_root_dispatch.local.md
@@ -0,0 +1,126 @@
+# core_command_root_dispatch
+
+The workspace declares upstream Vite. Only the target app declares the matching core alias. Check positional roots, -C, defaultPackage, and task dispatch.
+
+## `vp install --ignore-scripts`
+
+
+## `node check-layout.mjs`
+
+```
+Root Vite: vite
+App Vite: @voidzero-dev/vite-plus-core
+CLI Vite: @voidzero-dev/vite-plus-core
+```
+
+## `vp build packages/app`
+
+```
+✓ 2 modules transformed.
+computing gzip size...
+packages/app/dist/index.html  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp build --mode production --emptyOutDir packages/app`
+
+```
+✓ 2 modules transformed.
+computing gzip size...
+packages/app/dist/index.html  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp dev packages/app`
+
+```
+
+  VITE+ <version>
+
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+The target app served HTTP 200
+```
+
+## `vp preview --strictPort packages/app`
+
+```
+  ➜  Local:   http://127.0.0.1:<port>/
+  ➜  press h + enter to show help
+The target app served HTTP 200
+```
+
+## `vp -C packages/app build`
+
+```
+note: You are running `vp build` as a Vite+ built-in command. If you meant to run the build npm script, use `vpr build` instead.
+✓ 2 modules transformed.
+computing gzip size...
+dist/index.html  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp build`
+
+```
+note: vp build: using packages/app (defaultPackage in vite.config.ts)
+✓ 2 modules transformed.
+computing gzip size...
+dist/index.html  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp pack`
+
+```
+note: vp pack: using packages/app (defaultPackage in vite.config.ts)
+ℹ entry: src/index.ts
+ℹ Build start
+ℹ Cleaning <n> files
+ℹ dist/index.mjs  <size> kB │ gzip: <size> kB
+ℹ 1 files, total: <size> kB
+✔ Build complete in <duration>
+```
+
+## `vp run --filter app build`
+
+```
+~/packages/app$ vp build ⊘ cache disabled
+✓ 2 modules transformed.
+computing gzip size...
+dist/index.html  <size> kB │ gzip: <size> kB
+
+✓ built in <duration>
+```
+
+## `vp run --filter app pack`
+
+```
+~/packages/app$ vp pack ⊘ cache disabled
+ℹ entry: src/index.ts
+ℹ Build start
+ℹ Cleaning <n> files
+ℹ dist/index.mjs  <size> kB │ gzip: <size> kB
+ℹ 1 files, total: <size> kB
+✔ Build complete in <duration>
+```
+
+## `vp build .`
+
+**Exit code:** 1
+
+```
+error: Failed to resolve vite command: GenericFailure, Expected @voidzero-dev/vite-plus-core@<version>, but found vite@8.2.2 at <workspace>/node_modules/.pnpm/vite@8.2.2/node_modules/vite/package.json. Run `vp migrate` to align the Vite alias, then run `vp install`.
+```
+
+## `vp -C . pack packages/app/src/index.ts`
+
+**Exit code:** 1
+
+```
+error: Failed to resolve pack command: GenericFailure, Expected @voidzero-dev/vite-plus-core@<version>, but found vite@8.2.2 at <workspace>/node_modules/.pnpm/vite@8.2.2/node_modules/vite/package.json. Run `vp migrate` to align the Vite alias, then run `vp install`.
+```
diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/vite.config.ts b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/vite.config.ts
new file mode 100644
index 0000000000..59c0d3ed84
--- /dev/null
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_command_root/vite.config.ts
@@ -0,0 +1 @@
+export default { defaultPackage: 'packages/app' };
diff --git a/packages/cli/binding/index.d.cts b/packages/cli/binding/index.d.cts
index 8cd94c5e75..cb6d058f30 100644
--- a/packages/cli/binding/index.d.cts
+++ b/packages/cli/binding/index.d.cts
@@ -3456,12 +3456,12 @@ export interface BatchRewriteResult {
 
 /** Configuration options passed from JavaScript to Rust. */
 export interface CliOptions {
-  lint: (err: Error | null) => Promise<JsCommandResolvedResult>;
-  fmt: (err: Error | null) => Promise<JsCommandResolvedResult>;
-  vite: (err: Error | null) => Promise<JsCommandResolvedResult>;
-  test: (err: Error | null) => Promise<JsCommandResolvedResult>;
-  pack: (err: Error | null) => Promise<JsCommandResolvedResult>;
-  doc: (err: Error | null) => Promise<JsCommandResolvedResult>;
+  lint: (err: Error | null, arg: JsCommandContext) => Promise<JsCommandResolvedResult>;
+  fmt: (err: Error | null, arg: JsCommandContext) => Promise<JsCommandResolvedResult>;
+  vite: (err: Error | null, arg: JsCommandContext) => Promise<JsCommandResolvedResult>;
+  test: (err: Error | null, arg: JsCommandContext) => Promise<JsCommandResolvedResult>;
+  pack: (err: Error | null, arg: JsCommandContext) => Promise<JsCommandResolvedResult>;
+  doc: (err: Error | null, arg: JsCommandContext) => Promise<JsCommandResolvedResult>;
   cwd?: string;
   /** Whether the user supplied the global `-C` option. */
   explicitChdir?: boolean;
@@ -3612,6 +3612,12 @@ export interface HooksArgs {
   hooksDir?: string;
 }
 
+/** Execution context after command dispatch selects the working directory. */
+export interface JsCommandContext {
+  cwd: string;
+  args: Array<string>;
+}
+
 /** Result returned by JavaScript resolver functions. */
 export interface JsCommandResolvedResult {
   binPath: string;
diff --git a/packages/cli/binding/src/cli/execution.rs b/packages/cli/binding/src/cli/execution.rs
index 322a88913a..c0ad16f4fe 100644
--- a/packages/cli/binding/src/cli/execution.rs
+++ b/packages/cli/binding/src/cli/execution.rs
@@ -22,7 +22,7 @@ async fn resolve_and_build_command(
     cwd: &AbsolutePathBuf,
 ) -> Result<tokio::process::Command, Error> {
     let resolved = resolver
-        .resolve(subcommand, resolved_vite_config, envs)
+        .resolve(subcommand, resolved_vite_config, envs, cwd)
         .await
         .map_err(|e| Error::Anyhow(e))?;
 
diff --git a/packages/cli/binding/src/cli/handler.rs b/packages/cli/binding/src/cli/handler.rs
index 0811dd5091..a99fc70fa4 100644
--- a/packages/cli/binding/src/cli/handler.rs
+++ b/packages/cli/binding/src/cli/handler.rs
@@ -96,7 +96,8 @@ impl CommandHandler for VitePlusCommandHandler {
                 if super::app_target::needs_elicitation(&subcmd, &command.cwd) {
                     return Ok(HandledCommand::Verbatim);
                 }
-                let resolved = self.resolver.resolve(subcmd, None, &command.envs).await?;
+                let resolved =
+                    self.resolver.resolve(subcmd, None, &command.envs, &command.cwd).await?;
                 Ok(HandledCommand::Synthesized(resolved.into_synthetic_plan_request()))
             }
             CLIArgs::ViteTask(cmd) => Ok(HandledCommand::ViteTaskCommand(cmd)),
diff --git a/packages/cli/binding/src/cli/resolver.rs b/packages/cli/binding/src/cli/resolver.rs
index d5130042ab..64802db27f 100644
--- a/packages/cli/binding/src/cli/resolver.rs
+++ b/packages/cli/binding/src/cli/resolver.rs
@@ -67,8 +67,9 @@ impl SubcommandResolver {
         subcommand: SynthesizableSubcommand,
         resolved_vite_config: Option<&ResolvedUniversalViteConfig>,
         envs: &Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
+        cwd: &AbsolutePath,
     ) -> anyhow::Result<ResolvedSubcommand> {
-        self.resolve_inner(subcommand, resolved_vite_config, envs).await
+        self.resolve_inner(subcommand, resolved_vite_config, envs, cwd).await
     }
 
     async fn resolve_inner(
@@ -76,11 +77,12 @@ impl SubcommandResolver {
         subcommand: SynthesizableSubcommand,
         resolved_vite_config: Option<&ResolvedUniversalViteConfig>,
         envs: &Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
+        cwd: &AbsolutePath,
     ) -> anyhow::Result<ResolvedSubcommand> {
         match subcommand {
             SynthesizableSubcommand::Lint { mut args } => {
                 let cli_options = self.cli_options()?;
-                let resolved = (cli_options.lint)().await?;
+                let resolved = (cli_options.lint)(cwd, &args).await?;
                 let js_path = resolved.bin_path;
                 let js_path_str = js_path
                     .to_str()
@@ -117,7 +119,7 @@ impl SubcommandResolver {
             }
             SynthesizableSubcommand::Fmt { mut args } => {
                 let cli_options = self.cli_options()?;
-                let resolved = (cli_options.fmt)().await?;
+                let resolved = (cli_options.fmt)(cwd, &args).await?;
                 let js_path = resolved.bin_path;
                 let js_path_str = js_path
                     .to_str()
@@ -153,7 +155,7 @@ impl SubcommandResolver {
             }
             SynthesizableSubcommand::Build { args } => {
                 let cli_options = self.cli_options()?;
-                let resolved = (cli_options.vite)().await?;
+                let resolved = (cli_options.vite)(cwd, &args).await?;
                 let js_path = resolved.bin_path;
                 let js_path_str = js_path
                     .to_str()
@@ -182,7 +184,7 @@ impl SubcommandResolver {
             }
             SynthesizableSubcommand::Test { args } => {
                 let cli_options = self.cli_options()?;
-                let resolved = (cli_options.test)().await?;
+                let resolved = (cli_options.test)(cwd, &args).await?;
                 let js_path = resolved.bin_path;
                 let js_path_str = js_path
                     .to_str()
@@ -214,7 +216,7 @@ impl SubcommandResolver {
             }
             SynthesizableSubcommand::Pack { args } => {
                 let cli_options = self.cli_options()?;
-                let resolved = (cli_options.pack)().await?;
+                let resolved = (cli_options.pack)(cwd, &args).await?;
                 let js_path = resolved.bin_path;
                 let js_path_str = js_path
                     .to_str()
@@ -236,7 +238,7 @@ impl SubcommandResolver {
             }
             SynthesizableSubcommand::Dev { args } => {
                 let cli_options = self.cli_options()?;
-                let resolved = (cli_options.vite)().await?;
+                let resolved = (cli_options.vite)(cwd, &args).await?;
                 let js_path = resolved.bin_path;
                 let js_path_str = js_path
                     .to_str()
@@ -254,7 +256,7 @@ impl SubcommandResolver {
             }
             SynthesizableSubcommand::Preview { args } => {
                 let cli_options = self.cli_options()?;
-                let resolved = (cli_options.vite)().await?;
+                let resolved = (cli_options.vite)(cwd, &args).await?;
                 let js_path = resolved.bin_path;
                 let js_path_str = js_path
                     .to_str()
@@ -272,7 +274,7 @@ impl SubcommandResolver {
             }
             SynthesizableSubcommand::Doc { args } => {
                 let cli_options = self.cli_options()?;
-                let resolved = (cli_options.doc)().await?;
+                let resolved = (cli_options.doc)(cwd, &args).await?;
                 let js_path = resolved.bin_path;
                 let js_path_str = js_path
                     .to_str()
diff --git a/packages/cli/binding/src/cli/types.rs b/packages/cli/binding/src/cli/types.rs
index 7c9f3832ef..bae2eb3969 100644
--- a/packages/cli/binding/src/cli/types.rs
+++ b/packages/cli/binding/src/cli/types.rs
@@ -4,6 +4,7 @@ use clap::{Parser, Subcommand};
 use rustc_hash::FxHashMap;
 use serde::{Deserialize, Serialize};
 use vt::{Command, ExitStatus, config::user::UserCacheConfig, plan_request::SyntheticPlanRequest};
+use vt_path::AbsolutePath;
 use vt_str::Str;
 
 /// Resolved configuration from vite.config.ts
@@ -138,8 +139,12 @@ pub(super) enum CLIArgs {
 
 /// Type alias for boxed async resolver function
 /// NOTE: Uses anyhow::Error to avoid NAPI type inference issues
-pub type BoxedResolverFn =
-    Box<dyn Fn() -> Pin<Box<dyn Future<Output = anyhow::Result<ResolveCommandResult>> + 'static>>>;
+pub type BoxedResolverFn = Box<
+    dyn Fn(
+        &AbsolutePath,
+        &[String],
+    ) -> Pin<Box<dyn Future<Output = anyhow::Result<ResolveCommandResult>> + 'static>>,
+>;
 
 /// Type alias for vite config resolver function (takes package path, returns JSON string)
 /// Uses Arc for cloning and Send + Sync for use in UserConfigLoader
diff --git a/packages/cli/binding/src/lib.rs b/packages/cli/binding/src/lib.rs
index dce1ea7586..3c382dfd08 100644
--- a/packages/cli/binding/src/lib.rs
+++ b/packages/cli/binding/src/lib.rs
@@ -67,12 +67,12 @@ pub fn ensure_blocking_stdio() {
 /// Configuration options passed from JavaScript to Rust.
 #[napi(object, object_to_js = false)]
 pub struct CliOptions {
-    pub lint: Arc<ThreadsafeFunction<(), Promise<JsCommandResolvedResult>>>,
-    pub fmt: Arc<ThreadsafeFunction<(), Promise<JsCommandResolvedResult>>>,
-    pub vite: Arc<ThreadsafeFunction<(), Promise<JsCommandResolvedResult>>>,
-    pub test: Arc<ThreadsafeFunction<(), Promise<JsCommandResolvedResult>>>,
-    pub pack: Arc<ThreadsafeFunction<(), Promise<JsCommandResolvedResult>>>,
-    pub doc: Arc<ThreadsafeFunction<(), Promise<JsCommandResolvedResult>>>,
+    pub lint: Arc<ThreadsafeFunction<JsCommandContext, Promise<JsCommandResolvedResult>>>,
+    pub fmt: Arc<ThreadsafeFunction<JsCommandContext, Promise<JsCommandResolvedResult>>>,
+    pub vite: Arc<ThreadsafeFunction<JsCommandContext, Promise<JsCommandResolvedResult>>>,
+    pub test: Arc<ThreadsafeFunction<JsCommandContext, Promise<JsCommandResolvedResult>>>,
+    pub pack: Arc<ThreadsafeFunction<JsCommandContext, Promise<JsCommandResolvedResult>>>,
+    pub doc: Arc<ThreadsafeFunction<JsCommandContext, Promise<JsCommandResolvedResult>>>,
     pub cwd: Option<String>,
     /// Whether the user supplied the global `-C` option.
     pub explicit_chdir: Option<bool>,
@@ -86,6 +86,13 @@ pub struct CliOptions {
     pub resolve_universal_vite_config: Arc<ThreadsafeFunction<String, Promise<String>>>,
 }
 
+/// Execution context after command dispatch selects the working directory.
+#[napi(object, object_from_js = false)]
+pub struct JsCommandContext {
+    pub cwd: String,
+    pub args: Vec<String>,
+}
+
 /// Result returned by JavaScript resolver functions.
 #[napi(object, object_to_js = false)]
 pub struct JsCommandResolvedResult {
@@ -105,15 +112,21 @@ impl From<JsCommandResolvedResult> for ResolveCommandResult {
 /// Create a boxed resolver function from a ThreadsafeFunction
 /// NOTE: Uses anyhow::Error to avoid NAPI type interference with vp_error::Error
 fn create_resolver(
-    tsf: Arc<ThreadsafeFunction<(), Promise<JsCommandResolvedResult>>>,
+    tsf: Arc<ThreadsafeFunction<JsCommandContext, Promise<JsCommandResolvedResult>>>,
     error_message: &'static str,
 ) -> BoxedResolverFn {
-    Box::new(move || {
+    Box::new(move |cwd, args| {
+        let context = cwd
+            .as_path()
+            .to_str()
+            .map(|cwd| JsCommandContext { cwd: cwd.to_string(), args: args.to_vec() });
         let tsf = tsf.clone();
         Box::pin(async move {
             // Call JS function - map napi::Error to anyhow::Error
             let promise: Promise<JsCommandResolvedResult> = tsf
-                .call_async(Ok(()))
+                .call_async(Ok(
+                    context.ok_or_else(|| anyhow::anyhow!("command cwd is not valid UTF-8"))?
+                ))
                 .await
                 .map_err(|e| anyhow::anyhow!("{}: {}", error_message, e))?;
 
diff --git a/packages/cli/src/__tests__/resolve-vite.spec.ts b/packages/cli/src/__tests__/resolve-vite.spec.ts
new file mode 100644
index 0000000000..26e8fc2766
--- /dev/null
+++ b/packages/cli/src/__tests__/resolve-vite.spec.ts
@@ -0,0 +1,36 @@
+import { resolve } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import { resolveViteRoot } from '../resolve-vite.ts';
+
+describe('resolveViteRoot', () => {
+  const cwd = resolve('workspace');
+
+  it.each([
+    [],
+    ['--mode', 'production'],
+    ['--outDir', 'dist', '--emptyOutDir'],
+    ['--host', '127.0.0.1', '--port', '4173'],
+    ['--sourcemap', 'inline'],
+  ])('uses the dispatched cwd for %j', (...args) => {
+    expect(resolveViteRoot({ cwd, args })).toBe(cwd);
+  });
+
+  it.each([
+    ['packages/app'],
+    ['packages/app', '--mode', 'production'],
+    ['--mode', 'production', 'packages/app'],
+    ['-m=production', 'packages/app'],
+    ['--outDir=dist', 'packages/app'],
+    ['--emptyOutDir', 'packages/app'],
+    ['--no-clearScreen', 'packages/app'],
+    ['-w', 'packages/app'],
+    ['--strictPort', 'packages/app'],
+    ['--host', '127.0.0.1', 'packages/app'],
+    ['--sourcemap', 'inline', 'packages/app'],
+    ['packages/app', '--', 'ignored'],
+  ])('resolves the positional root in %j', (...args) => {
+    expect(resolveViteRoot({ cwd, args })).toBe(resolve(cwd, 'packages/app'));
+  });
+});
diff --git a/packages/cli/src/resolve-pack.ts b/packages/cli/src/resolve-pack.ts
index 8bd5a7fc0f..651036d0de 100644
--- a/packages/cli/src/resolve-pack.ts
+++ b/packages/cli/src/resolve-pack.ts
@@ -10,6 +10,7 @@
 
 import { join } from 'node:path';
 
+import type { JsCommandContext } from '../binding/index.js';
 import { resolveCore } from './resolve-core.ts';
 import { DEFAULT_ENVS } from './utils/constants.ts';
 
@@ -22,11 +23,17 @@ import { DEFAULT_ENVS } from './utils/constants.ts';
  *
  * Tsdown is a tool that provides a library for building JavaScript/TypeScript libraries.
  */
-export async function pack(): Promise<{
+export async function pack(
+  err: Error | null,
+  { cwd }: JsCommandContext,
+): Promise<{
   binPath: string;
   envs: Record<string, string>;
 }> {
-  resolveCore('/pack');
+  if (err) {
+    throw err;
+  }
+  resolveCore('/pack', cwd);
   // Resolve the bundled Tsdown CLI
   const binPath = join(import.meta.dirname, 'pack-bin.js');
 
diff --git a/packages/cli/src/resolve-vite.ts b/packages/cli/src/resolve-vite.ts
index 49e8bf03e9..7f633b1d84 100644
--- a/packages/cli/src/resolve-vite.ts
+++ b/packages/cli/src/resolve-vite.ts
@@ -10,11 +10,37 @@
  */
 
 import { existsSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 
+import { cac } from 'cac';
+
+import type { JsCommandContext } from '../binding/index.js';
 import { resolveCore } from './resolve-core.ts';
 import { DEFAULT_ENVS } from './utils/constants.ts';
 
+export function resolveViteRoot({ cwd, args }: JsCommandContext): string {
+  const cli = cac();
+  const command = cli.command('[root]').allowUnknownOptions();
+  // Match Vite's boolean options so cac does not consume the following root
+  // as an option value. Other Vite options accept a required or optional value.
+  for (const flag of [
+    '--clearScreen',
+    '--cors',
+    '--strictPort',
+    '--force',
+    '--experimentalBundle',
+    '--emptyOutDir',
+    '-w, --watch',
+    '--app',
+    '-h, --help',
+    '-v, --version',
+  ]) {
+    command.option(flag, '');
+  }
+  const parsed = cli.parse(['node', 'vite', ...args], { run: false });
+  return resolve(cwd, parsed.args[0] ?? '.');
+}
+
 /**
  * Resolves the Vite binary path and environment variables.
  *
@@ -24,11 +50,17 @@ import { DEFAULT_ENVS } from './utils/constants.ts';
  *
  * The CLI and its public re-exports use the same declared `vite` alias.
  */
-export async function vite(): Promise<{
+export async function vite(
+  err: Error | null,
+  context: JsCommandContext,
+): Promise<{
   binPath: string;
   envs: Record<string, string>;
 }> {
-  const vitePackagePath = dirname(resolveCore());
+  if (err) {
+    throw err;
+  }
+  const vitePackagePath = dirname(resolveCore('', resolveViteRoot(context)));
   const binPath = join(vitePackagePath, 'cli.js');
   if (!existsSync(binPath)) {
     throw new Error(`Could not find the bundled Vite CLI at ${binPath}. Run \`vp install\`.`);
diff --git a/rfcs/vite-core-module-identity.md b/rfcs/vite-core-module-identity.md
index a4feb6df1b..80b2b60897 100644
--- a/rfcs/vite-core-module-identity.md
+++ b/rfcs/vite-core-module-identity.md
@@ -134,7 +134,9 @@ a repository-wide string replacement.
 Review the `UserConfig` augmentation in `define-config.ts` with declaration
 generation enabled. Vitest augments `vite` too, so the implementation must
 check both augmentations together and retain the public Vite+ configuration
-types.
+types. Keep the explicit `test?: VitestInlineConfig` field: npm can install a
+separate upstream Vite peer for Vitest even when the project has a matching
+core alias.
 
 ### Command resolution and version checks
 
@@ -158,13 +160,20 @@ Before invoking a core-specific command entry, read the resolved
 The check must distinguish the core package version from its bundled Vite
 version. For example, core `0.3.0` bundles Vite `8.2.2`.
 
-If the active project's `vite` resolves to upstream Vite or a different core
-version, report the expected and actual packages and their locations. Ask the
-user to align the aliases and reinstall. A project without a resolvable
-top-level `vite` may use the CLI's declared dependency. A matching version in
+Check the nearest package manifest for an explicit `vite` dependency before
+validating the project's resolved copy. If that copy resolves to upstream
+Vite or a different core version, report the expected and actual packages and
+their locations. Ask the user to align the aliases and reinstall. A project
+that declares only `vite-plus` uses the CLI's dependency even if npm hoists an
+upstream Vite peer for Vitest. A matching version in
 a different peer context needs the layout validation described below; version
 equality alone does not establish module identity.
 
+Use the command's execution directory for project validation, including
+`-C`, workspace defaults, and task dispatch. For Vite commands, resolve the
+positional root from that directory. Keep the selected CLI as the anchor for
+its required dependency.
+
 Apply these checks before the CLI starts Vite or loads its packaging entry.
 Retain the distinction between pure `vite.defineConfig()` and the Vite+
 configuration helper, which injects Vite+ plugins.

From 15cc57f55e221b26ca82e7475ce90d22af8b5cd0 Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Mon, 7 Sep 2026 13:22:18 +0800
Subject: [PATCH 7/9] refactor(cli): simplify core resolution and CI packaging

---
 .../core_module_identity/check-npm-layout.mjs |  7 +-
 packages/cli/BUNDLING.md                      | 10 +--
 packages/cli/binding/src/cli/resolver.rs      | 10 ---
 packages/cli/binding/src/lib.rs               | 13 ++-
 packages/cli/build.ts                         | 29 ++-----
 .../cli/src/__tests__/resolve-core.spec.ts    | 83 ++++++++-----------
 .../cli/src/__tests__/resolve-vite.spec.ts    | 46 +++++-----
 packages/cli/src/define-config.ts             | 12 +--
 packages/cli/src/resolve-core.ts              | 53 +++++++-----
 packages/cli/src/resolve-pack.ts              | 37 ++-------
 packages/cli/src/resolve-vite.ts              | 45 ++--------
 packages/tools/src/install-global-cli.ts      | 28 +++++--
 12 files changed, 148 insertions(+), 225 deletions(-)

diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-npm-layout.mjs b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-npm-layout.mjs
index ce245adb34..db39f0147f 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-npm-layout.mjs
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/core_module_identity/check-npm-layout.mjs
@@ -4,12 +4,13 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const cliRequire = createRequire(require.resolve('vite-plus/package.json'));
 const vitestRequire = createRequire(cliRequire.resolve('vitest/package.json'));
-assert.equal(require('./package.json').overrides, undefined);
+const project = require('./package.json');
+assert.equal(project.overrides, undefined);
 assert.equal(cliRequire('vite/package.json').name, '@voidzero-dev/vite-plus-core');
 assert.equal(vitestRequire('vite/package.json').name, 'vite');
 assert.notEqual(cliRequire.resolve('vite/package.json'), vitestRequire.resolve('vite/package.json'));
-if (!require('./package.json').devDependencies.vite) {
-  assert.deepEqual(Object.keys(require('./package.json').devDependencies), ['vite-plus']);
+if (!project.devDependencies.vite) {
+  assert.deepEqual(Object.keys(project.devDependencies), ['vite-plus']);
   assert.equal(require('vite/package.json').name, 'vite');
 }
 console.log('npm installed separate CLI core and upstream Vitest peer without overrides');
diff --git a/packages/cli/BUNDLING.md b/packages/cli/BUNDLING.md
index dd1aea1995..87c16a5564 100644
--- a/packages/cli/BUNDLING.md
+++ b/packages/cli/BUNDLING.md
@@ -21,11 +21,11 @@ alias in packed releases. Runtime imports and generated shims use `vite` and
 its subpaths. This gives the CLI and plugins the same dependency name and
 avoids separate core instances under the alias and canonical package name.
 
-`resolve-core.ts` resolves the alias from the selected CLI package. It checks
-that the dependency and any project-level Vite alias identify the expected
-core release before starting Vite or packaging commands. Keep the canonical
-name in release metadata and alias targets; it identifies the published
-package, not the runtime import specifier.
+`resolve-core.ts` resolves the alias from the selected CLI package and checks
+its core version. It also checks any Vite dependency declared by the command's
+target project. An incidental hoisted peer does not trigger project validation.
+These checks run before Vite or packaging commands start. Keep the canonical
+name in release metadata and alias targets to identify the published package.
 
 ## Build Steps
 
diff --git a/packages/cli/binding/src/cli/resolver.rs b/packages/cli/binding/src/cli/resolver.rs
index 64802db27f..0063540873 100644
--- a/packages/cli/binding/src/cli/resolver.rs
+++ b/packages/cli/binding/src/cli/resolver.rs
@@ -68,16 +68,6 @@ impl SubcommandResolver {
         resolved_vite_config: Option<&ResolvedUniversalViteConfig>,
         envs: &Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
         cwd: &AbsolutePath,
-    ) -> anyhow::Result<ResolvedSubcommand> {
-        self.resolve_inner(subcommand, resolved_vite_config, envs, cwd).await
-    }
-
-    async fn resolve_inner(
-        &self,
-        subcommand: SynthesizableSubcommand,
-        resolved_vite_config: Option<&ResolvedUniversalViteConfig>,
-        envs: &Arc<FxHashMap<Arc<OsStr>, Arc<OsStr>>>,
-        cwd: &AbsolutePath,
     ) -> anyhow::Result<ResolvedSubcommand> {
         match subcommand {
             SynthesizableSubcommand::Lint { mut args } => {
diff --git a/packages/cli/binding/src/lib.rs b/packages/cli/binding/src/lib.rs
index 3c382dfd08..632ca5ba1c 100644
--- a/packages/cli/binding/src/lib.rs
+++ b/packages/cli/binding/src/lib.rs
@@ -119,19 +119,16 @@ fn create_resolver(
         let context = cwd
             .as_path()
             .to_str()
-            .map(|cwd| JsCommandContext { cwd: cwd.to_string(), args: args.to_vec() });
+            .map(|cwd| JsCommandContext { cwd: cwd.to_string(), args: args.to_vec() })
+            .ok_or_else(|| anyhow::anyhow!("command cwd is not valid UTF-8"));
         let tsf = tsf.clone();
         Box::pin(async move {
-            // Call JS function - map napi::Error to anyhow::Error
-            let promise: Promise<JsCommandResolvedResult> = tsf
-                .call_async(Ok(
-                    context.ok_or_else(|| anyhow::anyhow!("command cwd is not valid UTF-8"))?
-                ))
+            let promise = tsf
+                .call_async(Ok(context?))
                 .await
                 .map_err(|e| anyhow::anyhow!("{}: {}", error_message, e))?;
 
-            // Await the promise
-            let resolved: JsCommandResolvedResult =
+            let resolved =
                 promise.await.map_err(|e| anyhow::anyhow!("{}: {}", error_message, e))?;
 
             Ok(resolved.into())
diff --git a/packages/cli/build.ts b/packages/cli/build.ts
index 5f696c406e..e64ec88014 100644
--- a/packages/cli/build.ts
+++ b/packages/cli/build.ts
@@ -221,7 +221,7 @@ function buildWithTsdown() {
  *
  * @throws Error if core package is not built (missing dist directories)
  */
-async function syncCorePackageExports() {
+async function syncCorePackageExports(): Promise<void> {
   console.log('\nSyncing core package exports...');
 
   const distDir = join(projectDir, 'dist');
@@ -248,27 +248,12 @@ async function syncCorePackageExports() {
     `/// <reference types="${CORE_IMPORT_SPECIFIER}/pack/client" />\n`,
   );
 
-  // Create ./module-runner shim
-  console.log('  Creating ./module-runner');
-  await writeFile(
-    join(distDir, 'module-runner.js'),
-    `export * from '${CORE_IMPORT_SPECIFIER}/module-runner';\n`,
-  );
-  await writeFile(
-    join(distDir, 'module-runner.d.ts'),
-    `export * from '${CORE_IMPORT_SPECIFIER}/module-runner';\n`,
-  );
-
-  // Create ./internal shim
-  console.log('  Creating ./internal');
-  await writeFile(
-    join(distDir, 'internal.js'),
-    `export * from '${CORE_IMPORT_SPECIFIER}/internal';\n`,
-  );
-  await writeFile(
-    join(distDir, 'internal.d.ts'),
-    `export * from '${CORE_IMPORT_SPECIFIER}/internal';\n`,
-  );
+  for (const subpath of ['module-runner', 'internal']) {
+    console.log(`  Creating ./${subpath}`);
+    const reExport = `export * from '${CORE_IMPORT_SPECIFIER}/${subpath}';\n`;
+    await writeFile(join(distDir, `${subpath}.js`), reExport);
+    await writeFile(join(distDir, `${subpath}.d.ts`), reExport);
+  }
 
   // Create ./dist/client/* shims by reading core's dist/vite/client files
   console.log('  Creating ./dist/client/*');
diff --git a/packages/cli/src/__tests__/resolve-core.spec.ts b/packages/cli/src/__tests__/resolve-core.spec.ts
index 510d54fbe3..c534804d13 100644
--- a/packages/cli/src/__tests__/resolve-core.spec.ts
+++ b/packages/cli/src/__tests__/resolve-core.spec.ts
@@ -7,34 +7,31 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import cliPkg from '../../package.json' with { type: 'json' };
 import { resolveCore } from '../resolve-core.ts';
 
+function writePackageJson(directory: string, manifest: Record<string, unknown>): void {
+  mkdirSync(directory, { recursive: true });
+  writeFileSync(join(directory, 'package.json'), JSON.stringify(manifest));
+}
+
 function writeCore(
   directory: string,
   name = '@voidzero-dev/vite-plus-core',
   version = cliPkg.version,
-) {
-  mkdirSync(directory, { recursive: true });
-  writeFileSync(
-    join(directory, 'package.json'),
-    JSON.stringify({
-      name,
-      version,
-      exports: { '.': './index.js', './pack': './pack.js', './package.json': './package.json' },
-    }),
-  );
+): void {
+  writePackageJson(directory, {
+    name,
+    version,
+    exports: { '.': './index.js', './pack': './pack.js', './package.json': './package.json' },
+  });
   writeFileSync(join(directory, 'index.js'), '');
   writeFileSync(join(directory, 'pack.js'), '');
 }
 
-function writeCli(directory: string, version = cliPkg.version) {
-  mkdirSync(directory, { recursive: true });
-  writeFileSync(
-    join(directory, 'package.json'),
-    JSON.stringify({
-      name: 'vite-plus',
-      version,
-      exports: { './package.json': './package.json' },
-    }),
-  );
+function writeCli(directory: string, version = cliPkg.version): void {
+  writePackageJson(directory, {
+    name: 'vite-plus',
+    version,
+    exports: { './package.json': './package.json' },
+  });
 }
 
 describe('resolveCore', () => {
@@ -42,19 +39,17 @@ describe('resolveCore', () => {
   let project: string;
   let cliModule: string;
   let bundled: string;
+  let projectCore: string;
 
   beforeEach(() => {
     root = realpathSync(mkdtempSync(join(tmpdir(), 'vp-core-resolver-')));
     project = join(root, 'project');
-    mkdirSync(project);
-    writeFileSync(
-      join(project, 'package.json'),
-      JSON.stringify({
-        devDependencies: { vite: `npm:@voidzero-dev/vite-plus-core@${cliPkg.version}` },
-      }),
-    );
+    writePackageJson(project, {
+      devDependencies: { vite: `npm:@voidzero-dev/vite-plus-core@${cliPkg.version}` },
+    });
     cliModule = join(root, 'cli', 'dist', 'bin.js');
     bundled = join(root, 'cli', 'node_modules', 'vite');
+    projectCore = join(project, 'node_modules', 'vite');
     writeCli(join(root, 'cli'));
     writeCore(bundled);
   });
@@ -64,20 +59,14 @@ describe('resolveCore', () => {
   });
 
   it('supports a CLI installation without a project-level vite alias', () => {
-    writeFileSync(
-      join(project, 'package.json'),
-      JSON.stringify({ devDependencies: { 'vite-plus': cliPkg.version } }),
-    );
+    writePackageJson(project, { devDependencies: { 'vite-plus': cliPkg.version } });
     expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
     expect(resolveCore('/pack', project, cliModule)).toBe(join(bundled, 'pack.js'));
   });
 
   it('ignores an upstream Vite peer hoisted by npm in a CLI-only project', () => {
-    writeFileSync(
-      join(project, 'package.json'),
-      JSON.stringify({ devDependencies: { 'vite-plus': cliPkg.version } }),
-    );
-    writeCore(join(project, 'node_modules', 'vite'), 'vite', '8.2.2');
+    writePackageJson(project, { devDependencies: { 'vite-plus': cliPkg.version } });
+    writeCore(projectCore, 'vite', '8.2.2');
     expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
     expect(resolveCore('/pack', project, cliModule)).toBe(join(bundled, 'pack.js'));
   });
@@ -85,8 +74,8 @@ describe('resolveCore', () => {
   it.each(['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'])(
     'validates an explicit Vite declaration in %s from a project subdirectory',
     (field) => {
-      writeFileSync(join(project, 'package.json'), JSON.stringify({ [field]: { vite: '^8.0.0' } }));
-      writeCore(join(project, 'node_modules', 'vite'), 'vite', '8.2.2');
+      writePackageJson(project, { [field]: { vite: '^8.0.0' } });
+      writeCore(projectCore, 'vite', '8.2.2');
       const subdirectory = join(project, 'src');
       mkdirSync(subdirectory);
       expect(() => resolveCore('', subdirectory, cliModule)).toThrow('found vite@8.2.2');
@@ -94,7 +83,7 @@ describe('resolveCore', () => {
   );
 
   it('keeps the same anchor as static exports when the project has a matching copy', () => {
-    writeCore(join(project, 'node_modules', 'vite'));
+    writeCore(projectCore);
     expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
   });
 
@@ -103,7 +92,7 @@ describe('resolveCore', () => {
     (version) => {
       writeCli(join(root, 'cli'), version);
       writeCore(bundled, '@voidzero-dev/vite-plus-core', version);
-      writeCore(join(project, 'node_modules', 'vite'), '@voidzero-dev/vite-plus-core', version);
+      writeCore(projectCore, '@voidzero-dev/vite-plus-core', version);
       expect(resolveCore('', project, cliModule)).toBe(join(bundled, 'index.js'));
       expect(resolveCore('/pack', project, cliModule)).toBe(join(bundled, 'pack.js'));
     },
@@ -114,7 +103,7 @@ describe('resolveCore', () => {
     (location) => {
       writeCli(join(root, 'cli'), '0.0.0');
       writeCore(bundled, '@voidzero-dev/vite-plus-core', '0.0.0');
-      writeCore(location === 'project' ? join(project, 'node_modules', 'vite') : bundled);
+      writeCore(location === 'project' ? projectCore : bundled);
       expect(() => resolveCore('', project, cliModule)).toThrow(
         `Expected @voidzero-dev/vite-plus-core@0.0.0, but found @voidzero-dev/vite-plus-core@${cliPkg.version}`,
       );
@@ -122,23 +111,19 @@ describe('resolveCore', () => {
   );
 
   it('does not fall back to the project when the CLI dependency is missing', () => {
-    writeCore(join(project, 'node_modules', 'vite'));
+    writeCore(projectCore);
     rmSync(bundled, { recursive: true });
     expect(() => resolveCore('', project, cliModule)).toThrow('Could not resolve the bundled Vite');
   });
 
   it.each(['project', 'bundled'])('rejects upstream Vite in the %s dependency', (location) => {
-    writeCore(
-      location === 'project' ? join(project, 'node_modules', 'vite') : bundled,
-      'vite',
-      '8.2.2',
-    );
+    writeCore(location === 'project' ? projectCore : bundled, 'vite', '8.2.2');
     expect(() => resolveCore('', project, cliModule)).toThrow('found vite@8.2.2');
   });
 
   it.each(['project', 'bundled'])('rejects a stale core in the %s dependency', (location) => {
     writeCore(
-      location === 'project' ? join(project, 'node_modules', 'vite') : bundled,
+      location === 'project' ? projectCore : bundled,
       '@voidzero-dev/vite-plus-core',
       '0.0.0-stale',
     );
@@ -148,7 +133,7 @@ describe('resolveCore', () => {
   });
 
   it('reports a missing core subpath instead of selecting a project copy', () => {
-    writeCore(join(project, 'node_modules', 'vite'));
+    writeCore(projectCore);
     rmSync(join(bundled, 'pack.js'));
     expect(() => resolveCore('/pack', project, cliModule)).toThrow();
   });
diff --git a/packages/cli/src/__tests__/resolve-vite.spec.ts b/packages/cli/src/__tests__/resolve-vite.spec.ts
index 26e8fc2766..78a99efe54 100644
--- a/packages/cli/src/__tests__/resolve-vite.spec.ts
+++ b/packages/cli/src/__tests__/resolve-vite.spec.ts
@@ -7,30 +7,34 @@ import { resolveViteRoot } from '../resolve-vite.ts';
 describe('resolveViteRoot', () => {
   const cwd = resolve('workspace');
 
-  it.each([
-    [],
-    ['--mode', 'production'],
-    ['--outDir', 'dist', '--emptyOutDir'],
-    ['--host', '127.0.0.1', '--port', '4173'],
-    ['--sourcemap', 'inline'],
-  ])('uses the dispatched cwd for %j', (...args) => {
+  it.each(
+    [
+      [],
+      ['--mode', 'production'],
+      ['--outDir', 'dist', '--emptyOutDir'],
+      ['--host', '127.0.0.1', '--port', '4173'],
+      ['--sourcemap', 'inline'],
+    ].map((args) => ({ args })),
+  )('uses the dispatched cwd for $args', ({ args }) => {
     expect(resolveViteRoot({ cwd, args })).toBe(cwd);
   });
 
-  it.each([
-    ['packages/app'],
-    ['packages/app', '--mode', 'production'],
-    ['--mode', 'production', 'packages/app'],
-    ['-m=production', 'packages/app'],
-    ['--outDir=dist', 'packages/app'],
-    ['--emptyOutDir', 'packages/app'],
-    ['--no-clearScreen', 'packages/app'],
-    ['-w', 'packages/app'],
-    ['--strictPort', 'packages/app'],
-    ['--host', '127.0.0.1', 'packages/app'],
-    ['--sourcemap', 'inline', 'packages/app'],
-    ['packages/app', '--', 'ignored'],
-  ])('resolves the positional root in %j', (...args) => {
+  it.each(
+    [
+      ['packages/app'],
+      ['packages/app', '--mode', 'production'],
+      ['--mode', 'production', 'packages/app'],
+      ['-m=production', 'packages/app'],
+      ['--outDir=dist', 'packages/app'],
+      ['--emptyOutDir', 'packages/app'],
+      ['--no-clearScreen', 'packages/app'],
+      ['-w', 'packages/app'],
+      ['--strictPort', 'packages/app'],
+      ['--host', '127.0.0.1', 'packages/app'],
+      ['--sourcemap', 'inline', 'packages/app'],
+      ['packages/app', '--', 'ignored'],
+    ].map((args) => ({ args })),
+  )('resolves the positional root in $args', ({ args }) => {
     expect(resolveViteRoot({ cwd, args })).toBe(resolve(cwd, 'packages/app'));
   });
 });
diff --git a/packages/cli/src/define-config.ts b/packages/cli/src/define-config.ts
index c3f222eedf..0e78fb0347 100644
--- a/packages/cli/src/define-config.ts
+++ b/packages/cli/src/define-config.ts
@@ -24,12 +24,6 @@ import { CONFIG_METADATA_ENV, VITEST_VERSION } from './utils/constants.ts';
 
 declare module 'vite' {
   interface UserConfig {
-    /**
-     * Vitest may augment a separate Vite copy, for example an npm peer dependency.
-     * Keep the public test field on the CLI's core types in that layout too.
-     */
-    test?: VitestInlineConfig;
-
     /**
      * Options for oxlint
      */
@@ -98,6 +92,12 @@ declare module 'vite' {
        */
       templates?: CreateTemplateEntry[];
     };
+
+    /**
+     * Vitest may augment a separate Vite copy, for example an npm peer dependency.
+     * Keep the public test field on the CLI's core types in that layout too.
+     */
+    test?: VitestInlineConfig;
   }
 }
 
diff --git a/packages/cli/src/resolve-core.ts b/packages/cli/src/resolve-core.ts
index b6e766fd1a..c1b9886445 100644
--- a/packages/cli/src/resolve-core.ts
+++ b/packages/cli/src/resolve-core.ts
@@ -19,26 +19,11 @@ function checkCoreVersion(packageJsonPath: string, expectedVersion: string): voi
   }
 }
 
-/** Resolve the same core dependency as the CLI's static `vite` re-exports. */
-export function resolveCore(
-  subpath = '',
-  cwd = process.cwd(),
-  modulePath = import.meta.url,
-): string {
-  const require = createRequire(modulePath);
-  // Read the selected CLI's installed manifest. A static JSON import is inlined
-  // during the build, before CI and preview packers can stamp a new version.
-  const { version: expectedVersion } = JSON.parse(
-    readFileSync(require.resolve('vite-plus/package.json'), 'utf8'),
-  ) as { version: string };
-  let packageJsonPath: string;
-  try {
-    packageJsonPath = require.resolve('vite/package.json');
-  } catch (cause) {
-    throw new Error('Could not resolve the bundled Vite dependency. Run `vp install`.', { cause });
-  }
-  checkCoreVersion(packageJsonPath, expectedVersion);
-
+function checkProjectCoreVersion(
+  cwd: string,
+  corePackageJsonPath: string,
+  expectedVersion: string,
+): void {
   // npm can hoist an upstream Vite peer even when the project only declares
   // vite-plus. Validate Vite only when the nearest package declares it.
   const projectPackage = readNearestPackageJson(cwd);
@@ -49,7 +34,7 @@ export function resolveCore(
     'peerDependencies',
   ].some((field) => Object.hasOwn(projectPackage?.[field] ?? {}, 'vite'));
   if (!declaresVite) {
-    return require.resolve(`vite${subpath}`);
+    return;
   }
 
   const projectRequire = createRequire(join(cwd, 'package.json'));
@@ -61,9 +46,31 @@ export function resolveCore(
       throw cause;
     }
   }
-  if (projectPackageJsonPath && projectPackageJsonPath !== packageJsonPath) {
+  if (projectPackageJsonPath && projectPackageJsonPath !== corePackageJsonPath) {
     checkCoreVersion(projectPackageJsonPath, expectedVersion);
   }
+}
+
+/** Resolve the same core dependency as the CLI's static `vite` re-exports. */
+export function resolveCore(
+  subpath = '',
+  cwd = process.cwd(),
+  modulePath = import.meta.url,
+): string {
+  const cliRequire = createRequire(modulePath);
+  // Read the selected CLI's installed manifest. A static JSON import is inlined
+  // during the build, before CI and preview packers can stamp a new version.
+  const { version: expectedVersion } = JSON.parse(
+    readFileSync(cliRequire.resolve('vite-plus/package.json'), 'utf8'),
+  ) as { version: string };
+  let corePackageJsonPath: string;
+  try {
+    corePackageJsonPath = cliRequire.resolve('vite/package.json');
+  } catch (cause) {
+    throw new Error('Could not resolve the bundled Vite dependency. Run `vp install`.', { cause });
+  }
+  checkCoreVersion(corePackageJsonPath, expectedVersion);
+  checkProjectCoreVersion(cwd, corePackageJsonPath, expectedVersion);
 
-  return require.resolve(`vite${subpath}`);
+  return cliRequire.resolve(`vite${subpath}`);
 }
diff --git a/packages/cli/src/resolve-pack.ts b/packages/cli/src/resolve-pack.ts
index 651036d0de..c6ab2c7fd8 100644
--- a/packages/cli/src/resolve-pack.ts
+++ b/packages/cli/src/resolve-pack.ts
@@ -1,47 +1,20 @@
-/**
- * Tsdown tool resolver for the vite-plus CLI.
- *
- * This module exports a function that resolves the Tsdown binary path
- * using Node.js module resolution. The resolved path is passed back
- * to the Rust core, which then executes Tsdown for running pack.
- *
- * Used for: `vite-plus pack` command
- */
-
 import { join } from 'node:path';
 
-import type { JsCommandContext } from '../binding/index.js';
+import type { JsCommandContext, JsCommandResolvedResult } from '../binding/index.js';
 import { resolveCore } from './resolve-core.ts';
 import { DEFAULT_ENVS } from './utils/constants.ts';
 
-/**
- * Resolves the Tsdown binary path and environment variables.
- *
- * @returns Promise containing:
- *   - binPath: Absolute path to the Tsdown CLI entry point
- *   - envs: Environment variables to set when executing Tsdown
- *
- * Tsdown is a tool that provides a library for building JavaScript/TypeScript libraries.
- */
+/** Validate the target project's core alias before starting the bundled pack entry. */
 export async function pack(
   err: Error | null,
   { cwd }: JsCommandContext,
-): Promise<{
-  binPath: string;
-  envs: Record<string, string>;
-}> {
+): Promise<JsCommandResolvedResult> {
   if (err) {
     throw err;
   }
   resolveCore('/pack', cwd);
-  // Resolve the bundled Tsdown CLI
-  const binPath = join(import.meta.dirname, 'pack-bin.js');
-
   return {
-    binPath,
-    // TODO: provide envs inference API
-    envs: {
-      ...DEFAULT_ENVS,
-    },
+    binPath: join(import.meta.dirname, 'pack-bin.js'),
+    envs: { ...DEFAULT_ENVS },
   };
 }
diff --git a/packages/cli/src/resolve-vite.ts b/packages/cli/src/resolve-vite.ts
index 7f633b1d84..cd5b62eeac 100644
--- a/packages/cli/src/resolve-vite.ts
+++ b/packages/cli/src/resolve-vite.ts
@@ -1,20 +1,9 @@
-/**
- * Vite tool resolver for the vite-plus CLI.
- *
- * This module exports a function that resolves the Vite binary path
- * using Node.js module resolution. The resolved path is passed back
- * to the Rust core, which then executes Vite with the appropriate
- * command and arguments.
- *
- * Used for: `vite-plus build` and potentially `vite-plus dev` commands
- */
-
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
 import { cac } from 'cac';
 
-import type { JsCommandContext } from '../binding/index.js';
+import type { JsCommandContext, JsCommandResolvedResult } from '../binding/index.js';
 import { resolveCore } from './resolve-core.ts';
 import { DEFAULT_ENVS } from './utils/constants.ts';
 
@@ -41,22 +30,11 @@ export function resolveViteRoot({ cwd, args }: JsCommandContext): string {
   return resolve(cwd, parsed.args[0] ?? '.');
 }
 
-/**
- * Resolves the Vite binary path and environment variables.
- *
- * @returns Promise containing:
- *   - binPath: Absolute path to the Vite CLI entry point (vite.js)
- *   - envs: Environment variables to set when executing Vite
- *
- * The CLI and its public re-exports use the same declared `vite` alias.
- */
+/** Resolve the bundled CLI for dev, build, and preview from the selected project root. */
 export async function vite(
   err: Error | null,
   context: JsCommandContext,
-): Promise<{
-  binPath: string;
-  envs: Record<string, string>;
-}> {
+): Promise<JsCommandResolvedResult> {
   if (err) {
     throw err;
   }
@@ -66,16 +44,9 @@ export async function vite(
     throw new Error(`Could not find the bundled Vite CLI at ${binPath}. Run \`vp install\`.`);
   }
 
-  return {
-    binPath,
-    // Pass through source map debugging environment variable if set
-    envs: process.env.DEBUG_DISABLE_SOURCE_MAP
-      ? {
-          ...DEFAULT_ENVS,
-          DEBUG_DISABLE_SOURCE_MAP: process.env.DEBUG_DISABLE_SOURCE_MAP,
-        }
-      : {
-          ...DEFAULT_ENVS,
-        },
-  };
+  const envs: Record<string, string> = { ...DEFAULT_ENVS };
+  if (process.env.DEBUG_DISABLE_SOURCE_MAP) {
+    envs.DEBUG_DISABLE_SOURCE_MAP = process.env.DEBUG_DISABLE_SOURCE_MAP;
+  }
+  return { binPath, envs };
 }
diff --git a/packages/tools/src/install-global-cli.ts b/packages/tools/src/install-global-cli.ts
index e04b3389d7..017b70f20c 100644
--- a/packages/tools/src/install-global-cli.ts
+++ b/packages/tools/src/install-global-cli.ts
@@ -332,7 +332,7 @@ function getWindowsPowerShellCommand(): string {
  * Install dependencies for CI by generating a wrapper package.json with file: protocol
  * references to the main tgz and sibling @voidzero-dev/* tgz files, then running npm install.
  */
-function installCiDeps(versionDir: string, mainTgzPath: string) {
+function installCiDeps(versionDir: string, mainTgzPath: string): void {
   // Extract vite-plus's package.json from the tgz to find @voidzero-dev/* deps
   // On Windows, use the system tar (bsdtar) which handles Windows paths natively.
   // Git Bash's GNU tar misinterprets drive letters (D:, C:) as remote host references,
@@ -362,13 +362,25 @@ function installCiDeps(versionDir: string, mainTgzPath: string) {
   });
 }
 
+interface CiInstallPackage {
+  name: string;
+  version: string;
+  private: boolean;
+  dependencies: Record<string, string>;
+  overrides: Record<string, string>;
+}
+
 /** Build a CI install manifest from the packed CLI's declared dependencies. */
-export function createCiInstallPackage(vitePlusDeps: Record<string, string>, mainTgzPath: string) {
+export function createCiInstallPackage(
+  vitePlusDeps: Record<string, string>,
+  mainTgzPath: string,
+): CiInstallPackage {
   const tgzDir = path.dirname(mainTgzPath);
   // Build wrapper deps: vite-plus from tgz + @voidzero-dev/* from sibling tgz files
   const wrapperDeps: Record<string, string> = {
     'vite-plus': `file:${mainTgzPath}`,
   };
+  const overrides: Record<string, string> = {};
 
   for (const [name, specifier] of Object.entries(vitePlusDeps)) {
     const alias = /^npm:(@voidzero-dev\/[^@]+)@(.+)$/.exec(specifier);
@@ -382,6 +394,10 @@ export function createCiInstallPackage(vitePlusDeps: Record<string, string>, mai
     const tgzFilePath = path.join(tgzDir, tgzName);
     if (existsSync(tgzFilePath)) {
       wrapperDeps[name] = `file:${tgzFilePath}`;
+      // Point transitive aliases at the same tarball as the wrapper dependency.
+      if (name !== 'vite-plus') {
+        overrides[name] = `$${name}`;
+      }
       console.log(`  ${name}: ${version} -> file:${tgzFilePath}`);
     } else {
       console.warn(`Warning: tgz not found for ${name}@${version}: ${tgzFilePath}`);
@@ -393,13 +409,7 @@ export function createCiInstallPackage(vitePlusDeps: Record<string, string>, mai
     version: '0.0.0',
     private: true,
     dependencies: wrapperDeps,
-    // Override the CLI's registry dependencies too. A top-level file dependency
-    // alone does not force npm to use that tarball for a transitive npm alias.
-    overrides: Object.fromEntries(
-      Object.keys(wrapperDeps)
-        .filter((name) => name !== 'vite-plus')
-        .map((name) => [name, `$${name}`]),
-    ),
+    overrides,
   };
 }
 

From 6a8070a2446862fef6d56afe68320b900859abc2 Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Mon, 7 Sep 2026 16:49:32 +0800
Subject: [PATCH 8/9] test: limit Bun home cache workaround to Windows CI

---
 packages/tools/src/local-npm-registry.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/tools/src/local-npm-registry.ts b/packages/tools/src/local-npm-registry.ts
index 8e8260120f..6510fe2503 100644
--- a/packages/tools/src/local-npm-registry.ts
+++ b/packages/tools/src/local-npm-registry.ts
@@ -539,10 +539,11 @@ function buildRegistryEnv(registry: string): Record<string, string> {
   const noProxy = [process.env.NO_PROXY ?? process.env.no_proxy, '127.0.0.1']
     .filter(Boolean)
     .join(',');
-  // Windows snapshot jobs put TEMP on a ReFS Dev Drive, where Bun's
+  // Windows CI snapshot jobs put TEMP on a ReFS Dev Drive, where Bun's
   // cache/temp renames can fail with ENOTSUP. Keep its throwaway cache in
   // the user profile and its temporary files on the same filesystem.
-  const bunCacheRoot = process.platform === 'win32' ? homedir() : tmpdir();
+  const bunCacheRoot =
+    process.platform === 'win32' && process.env.CI != null ? homedir() : tmpdir();
   const bunCacheDir = mkdtempSync(path.join(bunCacheRoot, 'vp-local-registry-bun-'));
   return {
     NPM_CONFIG_REGISTRY: registry,

From 61a012f008620019479e4415a8dd9fdb424daf2c Mon Sep 17 00:00:00 2001
From: MK <fengmk2@gmail.com>
Date: Mon, 7 Sep 2026 20:11:53 +0800
Subject: [PATCH 9/9] test: preserve CI for the snapshot registry helper

---
 crates/vp_cli_snapshots/tests/cli_snapshots/main.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/crates/vp_cli_snapshots/tests/cli_snapshots/main.rs b/crates/vp_cli_snapshots/tests/cli_snapshots/main.rs
index d1803bca86..d096af5f73 100644
--- a/crates/vp_cli_snapshots/tests/cli_snapshots/main.rs
+++ b/crates/vp_cli_snapshots/tests/cli_snapshots/main.rs
@@ -1103,6 +1103,11 @@ fn start_local_registry(
     if let Some(profile) = std::env::var_os("USERPROFILE") {
         cmd.env("USERPROFILE", profile);
     }
+    // The registry uses CI to keep Bun's cache off the Windows Dev Drive.
+    // Preserve it only for this helper; fixture commands stay isolated.
+    if let Some(ci) = std::env::var_os("CI") {
+        cmd.env("CI", ci);
+    }
     group_leader(&mut cmd);
     let mut child = cmd
         .spawn()