fix(migrate): keep existing .nvmrc pins

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_upgrade_hooks_flag_pnpm/package.json

@@ -11,5 +11,8 @@
       "version": "10.33.0",
       "onFail": "download"
     }
+  },
+  "volta": {
+    "node": "24.11.0"
   }
 }

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_upgrade_hooks_flag_pnpm/snapshots.toml

@@ -6,6 +6,5 @@ steps = [
   { argv = ["vp", "migrate", "--hooks", "--no-interactive"], comment = "existing Vite+ project: upgrade plus only the git hooks action", continue-on-failure = true },
   { argv = ["git", "config", "--local", "core.hooksPath"], comment = "hooks configured to .vite-hooks/_", continue-on-failure = true },
   { argv = ["vpt", "print-file", ".vite-hooks/pre-commit"], comment = "pre-commit hook runs vp staged", continue-on-failure = true },
-  { argv = ["vpt", "stat-file", ".nvmrc", "--assert", "file"], comment = "node version file is not migrated without --full", continue-on-failure = true },
-  { argv = ["vpt", "stat-file", ".node-version", "--assert-not", "file"], comment = "only the hooks action ran", continue-on-failure = true },
+  { argv = ["vpt", "stat-file", ".node-version", "--assert-not", "file"], comment = "volta.node is not migrated without --full", continue-on-failure = true },
 ]

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_upgrade_hooks_flag_pnpm/snapshots/migration_upgrade_hooks_flag_pnpm.md

@@ -36,17 +36,9 @@ pre-commit hook runs vp staged
 vp staged
 ```
 
-## `vpt stat-file .nvmrc --assert file`
-
-node version file is not migrated without --full
-
-```
-.nvmrc: file
-```
-
 ## `vpt stat-file .node-version --assert-not file`
 
-only the hooks action ran
+volta.node is not migrated without --full
 
 ```
 .node-version: missing

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_upgrade_setup_full_pnpm/package.json

@@ -11,5 +11,8 @@
       "version": "10.33.0",
       "onFail": "download"
     }
+  },
+  "volta": {
+    "node": "24.11.0"
   }
 }

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_upgrade_setup_full_pnpm/snapshots.toml

@@ -6,7 +6,6 @@ steps = [
   { argv = ["vpt", "chmod", "+x", "fix-baseurl.mjs"], comment = "stub the baseUrl fixer so the dlx stays offline", continue-on-failure = true },
   { argv = ["vp", "migrate", "--full", "--no-interactive"], comment = "existing Vite+ project: upgrade plus the full setup", continue-on-failure = true },
   { argv = ["vpt", "print-file", "package.json"], comment = "vite-plus version upgrade is applied", continue-on-failure = true },
-  { argv = ["vpt", "print-file", ".node-version"], comment = ".nvmrc is migrated to .node-version by the full setup", continue-on-failure = true },
-  { argv = ["vpt", "stat-file", ".nvmrc", "--assert-not", "file"], comment = "the original .nvmrc is removed", continue-on-failure = true },
+  { argv = ["vpt", "print-file", ".node-version"], comment = "volta.node is migrated to .node-version by the full setup", continue-on-failure = true },
   { argv = ["vpt", "print-file", "tsconfig.json"], comment = "tsconfig baseUrl is removed by the full setup", continue-on-failure = true },
 ]

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_upgrade_setup_full_pnpm/snapshots/migration_upgrade_setup_full_pnpm.md

@@ -22,6 +22,8 @@ VITE+ - The Unified Toolchain for the Web
 • 2 config updates applied
 • Node version manager file migrated to .node-version
 • Package manager settings configured
+→ Manual follow-up:
+  - Remove the "volta" field from package.json
 ```
 
 ## `vpt print-file package.json`
@@ -42,6 +44,9 @@ vite-plus version upgrade is applied
       "onFail": "download"
     }
   },
+  "volta": {
+    "node": "24.11.0"
+  },
   "scripts": {
     "prepare": "vp config"
   }
@@ -50,20 +55,12 @@ vite-plus version upgrade is applied
 
 ## `vpt print-file .node-version`
 
-.nvmrc is migrated to .node-version by the full setup
+volta.node is migrated to .node-version by the full setup
 
 ```
 24.11.0
 ```
 
-## `vpt stat-file .nvmrc --assert-not file`
-
-the original .nvmrc is removed
-
-```
-.nvmrc: missing
-```
-
 ## `vpt print-file tsconfig.json`
 
 tsconfig baseUrl is removed by the full setup

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_upgrade_setup_skipped_default_pnpm/package.json

@@ -11,5 +11,8 @@
       "version": "10.33.0",
       "onFail": "download"
     }
+  },
+  "volta": {
+    "node": "24.11.0"
   }
 }

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_upgrade_setup_skipped_default_pnpm/snapshots.toml

@@ -5,7 +5,6 @@ steps = [
   { argv = ["vp", "migrate", "--no-interactive"], comment = "existing Vite+ project: upgrade the toolchain version only, skip the full setup", continue-on-failure = true },
   { argv = ["vpt", "print-file", "package.json"], comment = "vite-plus version upgrade is applied", continue-on-failure = true },
   { argv = ["vpt", "print-file", "pnpm-workspace.yaml"], comment = "pnpm settings consolidated by the version upgrade", continue-on-failure = true },
-  { argv = ["vpt", "stat-file", ".nvmrc", "--assert", "file"], comment = ".nvmrc is left untouched without --full", continue-on-failure = true },
-  { argv = ["vpt", "stat-file", ".node-version", "--assert-not", "file"], comment = "no .node-version is written", continue-on-failure = true },
+  { argv = ["vpt", "stat-file", ".node-version", "--assert-not", "file"], comment = "volta.node is not migrated without --full", continue-on-failure = true },
   { argv = ["vpt", "print-file", "tsconfig.json"], comment = "tsconfig baseUrl is left untouched without --full", continue-on-failure = true },
 ]

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_upgrade_setup_skipped_default_pnpm/snapshots/migration_upgrade_setup_skipped_default_pnpm.md

@@ -33,6 +33,9 @@ vite-plus version upgrade is applied
       "version": "<version>",
       "onFail": "download"
     }
+  },
+  "volta": {
+    "node": "24.11.0"
   }
 }
 ```
@@ -54,17 +57,9 @@ catalog:
   vite-plus: <version>
 ```
 
-## `vpt stat-file .nvmrc --assert file`
-
-.nvmrc is left untouched without --full
-
-```
-.nvmrc: file
-```
-
 ## `vpt stat-file .node-version --assert-not file`
 
-no .node-version is written
+volta.node is not migrated without --full
 
 ```
 .node-version: missing

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_volta_with_nvmrc/snapshots.toml

@@ -2,8 +2,8 @@
 name = "migration_volta_with_nvmrc"
 vp = "global"
 steps = [
-  { argv = ["vp", "migrate", "--no-interactive"], comment = ".nvmrc should take priority over volta.node", continue-on-failure = true },
-  { argv = ["vpt", "print-file", ".node-version"], comment = "check .node-version comes from .nvmrc (v24.11.0), not volta.node (18.0.0)", continue-on-failure = true },
-  { argv = ["vpt", "stat-file", ".nvmrc", "--assert-not", "file"], comment = "check .nvmrc is removed", continue-on-failure = true },
+  { argv = ["vp", "migrate", "--no-interactive"], comment = "an existing .nvmrc is kept and volta.node is not converted", continue-on-failure = true },
+  { argv = ["vpt", "stat-file", ".node-version", "--assert-not", "file"], comment = "no .node-version is written to shadow .nvmrc", continue-on-failure = true },
+  { argv = ["vpt", "print-file", ".nvmrc"], comment = ".nvmrc is left untouched", continue-on-failure = true },
   { argv = ["vpt", "print-file", "package.json"], comment = "volta field must remain intact", continue-on-failure = true },
 ]

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/migration_volta_with_nvmrc/snapshots/migration_volta_with_nvmrc.md

@@ -2,33 +2,30 @@
 
 ## `vp migrate --no-interactive`
 
-.nvmrc should take priority over volta.node
+an existing .nvmrc is kept and volta.node is not converted
 
 ```
 VITE+ - The Unified Toolchain for the Web
 
 ◇ Migrated . to Vite+ <version>
 • Node <version>  pnpm <version>
 • 2 config updates applied
-• Node version manager file migrated to .node-version
-→ Manual follow-up:
-  - Remove the "volta" field from package.json
 ```
 
-## `vpt print-file .node-version`
+## `vpt stat-file .node-version --assert-not file`
 
-check .node-version comes from .nvmrc (v24.11.0), not volta.node (18.0.0)
+no .node-version is written to shadow .nvmrc
 
 ```
-24.11.0
+.node-version: missing
 ```
 
-## `vpt stat-file .nvmrc --assert-not file`
+## `vpt print-file .nvmrc`
 
-check .nvmrc is removed
+.nvmrc is left untouched
 
 ```
-.nvmrc: missing
+<version>
 ```
 
 ## `vpt print-file package.json`

docs/guide/migrate-rules.md

@@ -18,7 +18,7 @@ Migration is idempotent: running it again after a successful migration should no
 
 On a project that already depends on `vite-plus`, `vp migrate` performs an upgrade only: it updates dependencies and package-manager configuration and finalizes imports. It does not touch project setup.
 
-- `--full` also runs the setup actions: git hooks, editor config, agent files, ESLint, Prettier, and tsup migration, framework shims, the tsconfig `baseUrl` fix, and the `.nvmrc`/Volta to `.node-version` conversion.
+- `--full` also runs the setup actions: git hooks, editor config, agent files, ESLint, Prettier, and tsup migration, framework shims, the tsconfig `baseUrl` fix, and the Volta to `.node-version` conversion.
 - `--hooks`, `--agent`, and `--editor` opt into a single setup action without `--full`.
 
 When a default upgrade skips setup actions that would apply, it prints a hint to run `vp migrate --full`. Fresh (non Vite+) projects always run the full migration.
@@ -257,10 +257,9 @@ Migration replaces exact `voidzero-dev/setup-vp@v1` references in GitHub Actions
 
 ## Node.js Version Rules
 
-Migration converts legacy Node.js version-manager files to `.node-version`, the format Vite+ reads. On an existing Vite+ project this conversion is part of the full setup bucket, so it runs with `vp migrate --full`; fresh migrations run it unconditionally.
+Migration converts the Volta `volta.node` pin to `.node-version`, because Vite+ does not read Volta. On an existing Vite+ project this conversion is part of the full setup bucket, so it runs with `vp migrate --full`; fresh migrations run it unconditionally.
 
-- `.nvmrc` and Volta `volta.node` pins are converted to `.node-version`. An existing `.node-version` is kept.
-- When `.nvmrc` is removed, any `actions/setup-node` `node-version-file: .nvmrc` reference in `.github/workflows/*.{yml,yaml}` and composite actions under `.github` (`.github/**/action.{yml,yaml}`) is repointed to `.node-version` so CI does not fail with "node version file ... does not exist".
+- When `.node-version` or `.nvmrc` exists, migration keeps it and skips the Volta conversion. Vite+ reads both files directly (see [Node.js Selection](/guide/env#node-js-selection)).
 
 ## Package-Manager Rules