feat(env)!: manage package manager environments

.github/workflows/e2e-test.yml

@@ -382,11 +382,6 @@ jobs:
           - name: varlet
             node-version: 22
             command: |
-              # scripts/bootstrap.mjs spawns `pnpm build` via tinyexec and needs
-              # pnpm on PATH (not exposed by the vp install itself). corepack
-              # enable creates a pnpm launcher in the vp bin dir that resolves
-              # the project's pinned packageManager version (pnpm@9.15.9).
-              corepack enable
               node scripts/bootstrap.mjs
               # Report-only: oxlint 1.68.0 surfaces ts1038 ("A 'declare' modifier
               # cannot be used in an already ambient context.") on varlet's

README.md

@@ -15,7 +15,7 @@ _runtime and package management, create, dev, check, test, build, pack, and mono
 
 Vite+ is the unified entry point for local web development. It combines [Vite](https://vite.dev/), [Vitest](https://vitest.dev/), [Oxlint](https://oxc.rs/docs/guide/usage/linter.html), [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html), [Rolldown](https://rolldown.rs/), [tsdown](https://tsdown.dev/), and [Vite Task](https://github.com/voidzero-dev/vite-task) into one zero-config toolchain that also manages runtime and package manager workflows:
 
-- **`vp env`:** Manage Node.js globally and per project
+- **`vp env`:** Manage Node.js and package managers globally and per project
 - **`vp install`:** Install dependencies with automatic package manager detection
 - **`vp dev`:** Run Vite's fast native ESM dev server with instant HMR
 - **`vp check`:** Run formatting, linting, and type checks in one command
@@ -105,7 +105,7 @@ Use `vp migrate` to migrate to Vite+. It merges tool-specific config files such
 - **hooks** - Manage the Git hook dispatcher
 - **staged** - Run linters on staged files
 - **install** (`i`) - Install dependencies
-- **env** - Manage Node.js versions
+- **env** - Manage Node.js and package managers
 
 #### Develop
 

crates/vp_cli_snapshots/tests/cli_snapshots/README.md

@@ -126,9 +126,8 @@ A step is a bare argv array or a table:
 
 `argv[0]` may be `vpt`, a runner-approved shell (including system `cmd.exe`
 exposed as `cmd`), or any executable exposed by the case's Vite+ installation,
-including default shims such as `vp`, `node`, and `corepack` and globally
-installed package binaries.
-There is no shell: no `&&`, no
+such as `vp`, `node`, `npm`, and `pnpm` and globally installed package
+binaries. There is no shell: no `&&`, no
 redirects, no globs. File setup and assertions go through `vpt` so behavior
 is identical on every platform:
 

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

@@ -16,7 +16,7 @@ Start:
   hooks       Manage the Git hook dispatcher
   staged      Run linters on staged files
   install, i  Install all dependencies, or add packages if package names are provided
-  env         Manage Node.js versions
+  env         Manage Node.js and package managers
 
 Develop:
   dev          Run the development server
@@ -460,54 +460,57 @@ VITE+ - The Unified Toolchain for the Web
 
 Usage: vp env [COMMAND]
 
-Manage Node.js versions
+Manage Node.js and package-manager environments
 
 Setup:
   setup  Create or update shims in VP_HOME/bin
-  on     Enable managed mode - shims always use vite-plus managed Node.js
-  off    Enable system-first mode - shims prefer system Node.js, fallback to managed
-  print  Print shell snippet to set environment for current session
+  on     Enable managed mode for Node.js and package managers
+  off    Enable system-first mode for Node.js and package managers
+  print  Print PATH setup for the resolved environment
 
 Manage:
-  default         Set or show the global default Node.js version
-  pin             Pin a Node.js version in the current directory
-  unpin           Remove the Node.js pin from the current directory (alias for `pin --unpin`)
-  use             Use a specific Node.js version for this shell session
-  install, i      Install a Node.js version
-  uninstall, uni  Uninstall a Node.js version
-  clean           Remove unused managed runtimes and package manager caches
-  exec, run       Execute a command with a specific Node.js version
+  default         Set or show global environment defaults
+  pin             Pin Node.js and package-manager versions in the project
+  unpin           Remove project environment pins (alias for `pin --unpin`)
+  use             Activate an environment for this shell session
+  install, i      Install a resolved or explicit environment
+  uninstall, uni  Uninstall explicit component versions
+  clean           Remove unused runtimes and package managers
+  exec, run       Execute a command in a resolved or explicit environment
 
 Inspect:
   current                 Show current environment information
   doctor                  Run diagnostics and show environment status
   which                   Show path to the tool that would be executed
-  list, ls                List locally installed Node.js versions
-  list-remote, ls-remote  List available Node.js versions from the registry
+  list, ls                List locally installed environment components
+  list-remote, ls-remote  List available versions from component registries
 
 Examples:
   Setup:
-    vp env setup                  # Create shims for node, npm, npx, corepack
-    vp env on                     # Use vite-plus managed Node.js
-    vp env print                  # Print shell snippet for this session
+    vp env setup                  # Create Node.js and package-manager shims
+    vp env on                     # Manage Node.js and package managers
+    vp env off pm                 # Prefer system package managers only
+    vp env print                  # Print PATH setup for both components
 
   Manage:
-    vp env pin lts                # Pin to latest LTS version
-    vp env install                # Install version from .node-version / package.json / .nvmrc
-    vp env use 20                 # Use Node.js 20 for this shell session
-    vp env use --unset            # Remove session override
-    vp env clean                  # Remove unused managed caches
+    vp env default 22.19.0        # Set the Node.js default
+    vp env default pnpm@12        # Set the package-manager default
+    vp env pin 22.19.0            # Pin Node.js for this project
+    vp env use 22.19.0            # Use Node.js in this shell
+    vp env clean                  # Clean all unused managed versions
 
   Inspect:
     vp env current                # Show current resolved environment
     vp env current --json         # JSON output for automation
     vp env doctor                 # Check environment configuration
     vp env which node             # Show which node binary will be used
-    vp env list-remote --lts      # List only LTS versions
+    vp env list node              # List only Node.js installations
+    vp env list-remote --lts      # List only Node.js LTS versions
 
   Execute:
-    vp env exec --node lts npm i  # Execute 'npm i' with latest LTS
-    vp env exec node -v           # Shim mode (version auto-resolved)
+    vp env exec --node lts node -v               # Override Node.js
+    vp env exec --package-manager pnpm@12 pnpm i # Override the package manager
+    vp env exec node -v                          # Resolve both components
 
 Related Commands:
   vp install -g <package>       # Install a package globally

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

@@ -4,4 +4,7 @@ vp = "global"
 seed-runtime = false
 steps = [
   { argv = ["vp", "env", "clean"], comment = "Clean isolated Vite+ caches" },
+  { argv = ["vp", "env", "clean", "node"], comment = "Clean only Node.js runtimes" },
+  { argv = ["vp", "env", "clean", "pm"], comment = "Clean all package-manager families" },
+  { argv = ["vp", "env", "clean", "pnpm"], comment = "Clean one package-manager family" },
 ]

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

@@ -10,3 +10,33 @@ VITE+ - The Unified Toolchain for the Web
 ✓ Removed 0 Node.js runtimes
 ✓ Removed 0 package manager installs
 ```
+
+## `vp env clean node`
+
+Clean only Node.js runtimes
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ Removed 0 Node.js runtimes
+```
+
+## `vp env clean pm`
+
+Clean all package-manager families
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ Removed 0 package manager installs
+```
+
+## `vp env clean pnpm`
+
+Clean one package-manager family
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ Removed 0 package manager installs
+```

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

@@ -6,7 +6,7 @@ verifies vp-use.cmd explicit, unset, file-based, failure status, and session-onl
 
 ```
 Using Node.js <version> (resolved from 20.18.0)
-Reverted to file-based Node.js version resolution
+Reverted selected components to project environment resolution
 Using Node.js <version> (resolved from .node-version)
 Command Prompt environment use checks passed
 ```

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

@@ -4,4 +4,6 @@ vp = "global"
 skip-platforms = ["windows"]
 steps = [
   { argv = ["node", "-e", "const {execFileSync}=require('node:child_process');const text=execFileSync('vp',['env','doctor'],{encoding:'utf8'}).replace(/\\u001b\\[[0-9;]*m/g,'');const lines=text.split('\\n');const start=lines.findIndex(l=>l.trim()==='devEngines');if(start===-1){console.error('devEngines section not found in doctor output');process.exit(1);}const out=[];for(let i=start;i<lines.length;i++){if(i>start&&lines[i].trim()===''){break;}out.push(lines[i].trimEnd());}console.log(out.join('\\n'));"], comment = "print only the deterministic devEngines section of vp env doctor (the other sections are environment-dependent)", continue-on-failure = true },
+  { argv = ["node", "-e", "const {execFileSync}=require('node:child_process');const text=execFileSync('vp',['env','doctor','node'],{encoding:'utf8'}).replace(/\\u001b\\[[0-9;]*m/g,'');const lines=text.split('\\n');const start=lines.findIndex(l=>l.trim()==='devEngines');if(start===-1){console.error('devEngines section not found in doctor output');process.exit(1);}const out=[];for(let i=start;i<lines.length;i++){if(i>start&&lines[i].trim()===''){break;}out.push(lines[i].trimEnd());}console.log(out.join('\\n'));"], comment = "node-scoped doctor output excludes package-manager findings", continue-on-failure = true },
+  { argv = ["node", "-e", "const {execFileSync}=require('node:child_process');const text=execFileSync('vp',['env','doctor','pm'],{encoding:'utf8'}).replace(/\\u001b\\[[0-9;]*m/g,'');const lines=text.split('\\n');const start=lines.findIndex(l=>l.trim()==='devEngines');if(start===-1){console.error('devEngines section not found in doctor output');process.exit(1);}const out=[];for(let i=start;i<lines.length;i++){if(i>start&&lines[i].trim()===''){break;}out.push(lines[i].trimEnd());}console.log(out.join('\\n'));"], comment = "package-manager-scoped doctor output excludes runtime findings", continue-on-failure = true },
 ]

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

@@ -10,3 +10,22 @@ devEngines
   ⚠ PackageManager    packageManager is "npm@10.5.0" but devEngines.packageManager requires "pnpm"
   note: This will become an error in a future release.
 ```
+
+## `node -e 'const {execFileSync}=require('\''node:child_process'\'');const text=execFileSync('\''vp'\'',['\''env'\'','\''doctor'\'','\''node'\''],{encoding:'\''utf8'\''}).replace(/\u001b\[[0-9;]*m/g,'\'''\'');const lines=text.split('\''\n'\'');const start=lines.findIndex(l=>l.trim()==='\''devEngines'\'');if(start===-1){console.error('\''devEngines section not found in doctor output'\'');process.exit(1);}const out=[];for(let i=start;i<lines.length;i++){if(i>start&&lines[i].trim()==='\'''\''){break;}out.push(lines[i].trimEnd());}console.log(out.join('\''\n'\''));'`
+
+node-scoped doctor output excludes package-manager findings
+
+```
+devEngines
+  ⚠ Runtime           .node-version (20.18.0) does not satisfy devEngines.runtime "^24.0.0"
+```
+
+## `node -e 'const {execFileSync}=require('\''node:child_process'\'');const text=execFileSync('\''vp'\'',['\''env'\'','\''doctor'\'','\''pm'\''],{encoding:'\''utf8'\''}).replace(/\u001b\[[0-9;]*m/g,'\'''\'');const lines=text.split('\''\n'\'');const start=lines.findIndex(l=>l.trim()==='\''devEngines'\'');if(start===-1){console.error('\''devEngines section not found in doctor output'\'');process.exit(1);}const out=[];for(let i=start;i<lines.length;i++){if(i>start&&lines[i].trim()==='\'''\''){break;}out.push(lines[i].trimEnd());}console.log(out.join('\''\n'\''));'`
+
+package-manager-scoped doctor output excludes runtime findings
+
+```
+devEngines
+  ⚠ PackageManager    packageManager is "npm@10.5.0" but devEngines.packageManager requires "pnpm"
+  note: This will become an error in a future release.
+```

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_env_fish/snapshots/command_env_fish_use.md

@@ -15,7 +15,7 @@ verifies the Fish wrapper help, explicit use, unset, file-based use, and failure
 
 ```
 Using Node.js <version> (resolved from 20.18.0)
-Reverted to file-based Node.js version resolution
+Reverted selected components to project environment resolution
 Using Node.js <version> (resolved from .node-version)
 error: Unexpected argument '--invalid-option'
 

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

@@ -5,4 +5,7 @@ skip-platforms = ["windows"]
 seed-runtime = false
 steps = [
   { argv = ["vp", "env", "install"], comment = "Install version from .node-version (22.x)", continue-on-failure = true },
+  { argv = ["vp", "env", "use", "22", "--no-install"], snapshot = false },
+  { argv = ["vp", "env", "install"], comment = "An implicit install identifies an active session override", continue-on-failure = true },
+  { argv = ["vp", "env", "uninstall", "22"], comment = "Node.js uninstall accepts the same major-version selectors as install", continue-on-failure = true },
 ]

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

@@ -10,3 +10,29 @@ VITE+ - The Unified Toolchain for the Web
 Installing Node.js <version>...
 Installed Node.js <version>
 ```
+
+## `vp env use 22 --no-install`
+
+
+## `vp env install`
+
+An implicit install identifies an active session override
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+Installing Node.js <version>...
+Installed Node.js <version>
+Note: Installed from session override.
+Run `vp env use --unset` to revert to project version resolution.
+```
+
+## `vp env uninstall 22`
+
+Node.js uninstall accepts the same major-version selectors as install
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+Uninstalled Node.js <version>
+```

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

@@ -4,7 +4,27 @@ vp = "global"
 skip-platforms = ["windows"]
 seed-runtime = false
 steps = [
+  { argv = ["vp", "env", "default", "node"], comment = "An unconfigured Node.js default explains the effective fallback without claiming it was set in config", continue-on-failure = true },
   { argv = ["vp", "env", "install", "lts"], comment = "Install an LTS Node.js version locally", continue-on-failure = true },
   { argv = ["vp", "env", "default", "lts"], comment = "Set it as the global default (stored as the `lts` alias)", continue-on-failure = true },
-  { argv = ["node", "-e", "const {execFileSync}=require('node:child_process'); const {versions}=JSON.parse(execFileSync('vp',['env','list-remote','--lts','--json'],{encoding:'utf8'})); console.log('installed marked:', versions.some(v=>v.installed)); console.log('current marked:', versions.some(v=>v.current)); console.log('default marked:', versions.some(v=>v.default));"], comment = "installed/current/default flags should all resolve, including the `lts` default alias", continue-on-failure = true },
+  { argv = ["vp", "env", "default", "node"], comment = "A configured Node.js alias shows its current resolution and config source", continue-on-failure = true },
+  { argv = ["vp", "env", "default", "pnpm@10.18.0"], comment = "Package-manager default updates identify the selected package and version", continue-on-failure = true },
+  { argv = ["node", "-e", "const {execFileSync}=require('node:child_process'); const {node}=JSON.parse(execFileSync('vp',['env','list-remote','--lts','--json'],{encoding:'utf8'})); console.log('installed marked:', node.some(v=>v.installed)); console.log('current marked:', node.some(v=>v.current)); console.log('default marked:', node.some(v=>v.default));"], comment = "the unified JSON node entries resolve installed/current/default flags, including the `lts` default alias", continue-on-failure = true },
+  { argv = ["vp", "env", "list-remote", "node", "22.11.0"], comment = "Human-readable Node.js results keep the v prefix, LTS codename, and interactive formatting", formatted-snapshot = true, continue-on-failure = true },
+  { argv = ["vp", "env", "list-remote", "pnpm", "10.18.0"], comment = "Human-readable package-manager results retain current-version formatting", formatted-snapshot = true, continue-on-failure = true },
+  { argv = ["vp", "env", "list-remote", "node", "999"], comment = "An empty Node.js result includes actionable feedback", continue-on-failure = true },
+]
+
+[[case]]
+name = "command_env_list_format"
+vp = "global"
+skip-platforms = ["windows"]
+seed-runtime = false
+steps = [
+  { argv = ["vpt", "mkdir", "-p", "$VP_HOME/js_runtime/node/22.11.0"], snapshot = false },
+  { argv = ["vpt", "write-file", "$VP_HOME/package_manager/pnpm/10.18.0/pnpm/bin/pnpm", "#!/bin/sh\n"], snapshot = false },
+  { argv = ["vpt", "write-file", "$VP_HOME/package_manager/pnpm/10.18.0/pnpm/bin/pnpx", "#!/bin/sh\n"], snapshot = false },
+  { argv = ["vp", "env", "default", "22.11.0", "pnpm@10.18.0"], snapshot = false },
+  { argv = ["vp", "env", "list", "node"], comment = "Installed Node.js versions retain their interactive formatting", formatted-snapshot = true },
+  { argv = ["vp", "env", "list", "pnpm"], comment = "Installed package-manager versions use the same interactive formatting", formatted-snapshot = true },
 ]

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_env_list_remote/snapshots/command_env_list_format.md

@@ -0,0 +1,41 @@
+# command_env_list_format
+
+## `vpt mkdir -p $VP_HOME/js_runtime/node/22.11.0`
+
+
+## `vpt write-file $VP_HOME/package_manager/pnpm/10.18.0/pnpm/bin/pnpm '#'\!'/bin/sh
+'`
+
+
+## `vpt write-file $VP_HOME/package_manager/pnpm/10.18.0/pnpm/bin/pnpx '#'\!'/bin/sh
+'`
+
+
+## `vp env default 22.11.0 pnpm@10.18.0`
+
+
+## `vp env list node`
+
+Installed Node.js versions retain their interactive formatting
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+Node.js
+  * \x1b[94mv22.11.0 \x1b[2mcurrent default
+
+\x1b[2mnote: Run `vp env clean` to free disk space from unused managed runtimes and package manager caches.
+```
+
+## `vp env list pnpm`
+
+Installed package-manager versions use the same interactive formatting
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+pnpm
+  * \x1b[94m10.18.0 \x1b[2mcurrent default
+
+\x1b[2mnote: Run `vp env clean` to free disk space from unused managed runtimes and package manager caches.
+```