fengmk2 · Oct 20, 2026 · Oct 18, 2026 · Oct 18, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/...age_manager_mismatch/snapshots/env_pin_package_manager_requires_confirmation.md b/...age_manager_mismatch/snapshots/env_pin_package_manager_requires_confirmation.md
@@ -9,6 +9,8 @@ declining the overwrite prompt preserves the existing package-manager pin
 VITE+ - The Unified Toolchain for the Web
 
 warn: Current environment resolves to pnpm from packageManager, but yarn was requested.
+  File: package.json
+  Field: packageManager
 Package manager already pinned to pnpm@10.18.0
 Overwrite with yarn@4.12.0? (Y/n): Cancelled.
 ```

diff --git a/...kage_manager_mismatch/snapshots/env_pin_warns_for_lockfile_selection_offline.md b/...kage_manager_mismatch/snapshots/env_pin_warns_for_lockfile_selection_offline.md
@@ -16,5 +16,7 @@ VITE+ - The Unified Toolchain for the Web
 
 warn: Current environment resolves to pnpm from lockfile or config, but yarn was requested.
 ✓ Pinned package manager to yarn@4.12.0
+  File: package.json
+  Field: devEngines.packageManager
 note: Package manager will be downloaded on first use.
 ```
diff --git a/...ackage_manager_mismatch/snapshots/env_pin_warns_when_package_manager_differs.md b/...ackage_manager_mismatch/snapshots/env_pin_warns_when_package_manager_differs.md
@@ -9,5 +9,7 @@ VITE+ - The Unified Toolchain for the Web
 
 warn: Current environment resolves to pnpm from packageManager, but yarn was requested.
 ✓ Pinned package manager to yarn@4.12.0
+  File: package.json
+  Field: packageManager
 note: Package manager will be downloaded on first use.
 ```
diff --git a/...cli_snapshots/tests/cli_snapshots/fixtures/command_env_pin_package_manager/snapshots.toml b/...cli_snapshots/tests/cli_snapshots/fixtures/command_env_pin_package_manager/snapshots.toml
@@ -48,3 +48,93 @@ steps = [
   { argv = ["vp", "env", "pin", "pnpm@11.0.0", "--target", "dev-engines", "--no-install", "--force"], comment = "pinning a shadowed same-family devEngines version explains which declaration remains effective" },
   { argv = ["vpt", "print-file", "package.json"], comment = "both explicitly targeted declarations remain unchanged except for the new devEngines pin" },
 ]
+
+[[case]]
+name = "env_unpin_package_manager_from_nested_workspace"
+vp = "global"
+seed-runtime = false
+cwd = "packages/app"
+steps = [
+  { argv = ["vp", "env", "unpin", "pm"] },
+  { argv = ["vpt", "print-file", "../../package.json", "package.json"], comment = "remove the root manager and preserve the member manifest and sibling manager" },
+]
+
+[[case]]
+name = "env_pin_mixed_components_from_nested_workspace"
+vp = "global"
+seed-runtime = false
+cwd = "packages/app"
+steps = [
+  { argv = ["vp", "env", "pin", "22.13.0", "yarn@4.12.0", "--no-install", "--force"] },
+  { argv = ["vpt", "print-file", "../../package.json", "package.json"], comment = "Node is local while the package manager belongs to the workspace" },
+  { argv = ["vp", "env", "pin", "--unpin"] },
+  { argv = ["vpt", "print-file", "../../package.json", "package.json"], comment = "mixed removal uses the same separate targets" },
+]
+
+[[case]]
+name = "env_unpin_scoped_manager_falls_back_to_dev_engines"
+vp = "global"
+seed-runtime = false
+steps = [
+  { argv = ["vpt", "write-file", "package.json", "{\"packageManager\": \"pnpm@10.18.0\", \"devEngines\": {\"packageManager\": [{\"name\": \"npm\", \"version\": \"11.0.0\"}, {\"name\": \"yarn\", \"version\": \"4.12.0\"}]}}\n"], snapshot = false },
+  { argv = ["vp", "env", "unpin", "yarn"] },
+  { argv = ["vpt", "print-file", "package.json"], comment = "only the matching devEngines entry was removed" },
+  { argv = ["vp", "env", "unpin", "yarn"], comment = "a miss reports both searched fields and the explicit scope" },
+  { argv = ["vp", "env", "unpin", "yarn", "--target", "package-manager"], comment = "an explicit top-level target checks only that field" },
+]
+
+[[case]]
+name = "env_pin_top_level_no_op_and_overwrite"
+vp = "global"
+seed-runtime = false
+steps = [
+  { argv = ["vpt", "write-file", "package.json", "{\"packageManager\": \"pnpm@10.18.0+sha512.keep\"}\n"], snapshot = false },
+  { argv = ["vp", "env", "pin", "pnpm@10.18.0", "--no-install"], comment = "same-value pin preserves the integrity suffix and reports no changes" },
+  { argv = ["vpt", "print-file", "package.json"], comment = "the no-op preserves the original declaration" },
+  { argv = ["vpt", "pipe-stdin", "y\n", "--", "vp", "env", "pin", "pnpm@10.19.0", "--no-install"], comment = "the target precedes confirmation and follows success" },
+  { argv = ["vpt", "print-file", "package.json"] },
+]
+
+[[case]]
+name = "env_pin_same_version_dev_engines_keeps_write_behavior"
+vp = "global"
+seed-runtime = false
+steps = [
+  { argv = ["vpt", "write-file", "package.json", "{\"devEngines\": {\"packageManager\": [{\"name\": \"pnpm\", \"version\": \"10.18.0\", \"onFail\": \"error\"}, {\"name\": \"yarn\", \"version\": \"4.12.0\"}]}}\n"], snapshot = false },
+  { argv = ["vp", "env", "pin", "pnpm@10.18.0", "--no-install"], comment = "equal versions retain the existing write path rather than reporting a no-op" },
+  { argv = ["vpt", "print-file", "package.json"] },
+]
+
+[[case]]
+name = "env_unpin_reports_empty_and_missing_manifest"
+vp = "global"
+seed-runtime = false
+steps = [
+  { argv = ["vpt", "write-file", "package.json", "{\"name\": \"empty\"}\n"], snapshot = false },
+  { argv = ["vp", "env", "unpin", "pm"] },
+  { argv = ["vp", "env", "unpin", "yarn", "--target", "dev-engines"] },
+  { argv = ["vp", "env", "unpin", "pm", "--target", "package-manager"] },
+  { argv = ["vpt", "rm", "package.json"] },
+  { argv = ["vp", "env", "unpin", "pm"], comment = "a missing file is distinct from a readable manifest with no matching pin" },
+]
+
+[[case]]
+name = "env_pin_scope_help"
+vp = "global"
+seed-runtime = false
+steps = [
+  { argv = ["vp", "env", "pin", "--help"] },
+  { argv = ["vp", "env", "unpin", "--help"] },
+]
+
+[[case]]
+name = "env_pin_standalone_package_manager_target"
+vp = "global"
+seed-runtime = false
+steps = [
+  { argv = ["vpt", "write-file", "package.json", "{\"name\": \"standalone\"}\n"], snapshot = false },
+  { argv = ["vp", "env", "pin", "yarn@4.12.0", "--no-install"], comment = "first write uses this project manifest without a confirmation" },
+  { argv = ["vpt", "print-file", "package.json"] },
+  { argv = ["vp", "env", "unpin", "pm"] },
+  { argv = ["vpt", "print-file", "package.json"] },
+]
diff --git a/...anager/snapshots/env_pin_dev_engines_warns_when_top_level_version_shadows_it.md b/...anager/snapshots/env_pin_dev_engines_warns_when_top_level_version_shadows_it.md
@@ -12,6 +12,8 @@ pinning a shadowed same-family devEngines version explains which declaration rem
 VITE+ - The Unified Toolchain for the Web
 
 ✓ Pinned package manager to pnpm@11.0.0
+  File: package.json
+  Field: devEngines.packageManager
 warn: Top-level packageManager pnpm@10.18.0 remains effective; remove or update it to use devEngines.packageManager pnpm@11.0.0.
 note: Package manager will be downloaded on first use.
 ```

diff --git a/...kage_manager/snapshots/env_pin_makes_requested_dev_engines_manager_effective.md b/...kage_manager/snapshots/env_pin_makes_requested_dev_engines_manager_effective.md
@@ -9,6 +9,8 @@ VITE+ - The Unified Toolchain for the Web
 
 warn: Current environment resolves to npm from devEngines.packageManager, but pnpm was requested.
 ✓ Pinned package manager to pnpm@10.18.0
+  File: package.json
+  Field: devEngines.packageManager
 note: Package manager will be downloaded on first use.
 ```
 

diff --git a/...pin_package_manager/snapshots/env_pin_mixed_components_from_nested_workspace.md b/...pin_package_manager/snapshots/env_pin_mixed_components_from_nested_workspace.md
@@ -0,0 +1,103 @@
+# env_pin_mixed_components_from_nested_workspace
+
+## `vp env pin 22.13.0 yarn@4.12.0 --no-install --force`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ Pinned Node.js version to 22.13.0
+  Updated devEngines.runtime in <workspace>/packages/app/package.json
+note: Version will be downloaded on first use.
+warn: Current environment resolves to npm from devEngines.packageManager, but yarn was requested.
+✓ Pinned package manager to yarn@4.12.0
+  File: ../../package.json
+  Field: devEngines.packageManager
+note: Package manager will be downloaded on first use.
+```
+
+## `vpt print-file ../../package.json package.json`
+
+Node is local while the package manager belongs to the workspace
+
+```
+{
+  "name": "command-env-pin-package-manager",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ],
+  "devEngines": {
+    "packageManager": [
+      {
+        "name": "yarn",
+        "version": "<version>",
+        "onFail": "download"
+      },
+      {
+        "name": "npm",
+        "version": "<version>",
+        "onFail": "error"
+      },
+      {
+        "name": "pnpm",
+        "version": "<version>",
+        "onFail": "download"
+      }
+    ]
+  }
+}
+{
+  "name": "app",
+  "private": true,
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": "<version>",
+      "onFail": "download"
+    }
+  }
+}
+```
+
+## `vp env pin --unpin`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ Removed devEngines.runtime node entry from <workspace>/packages/app/package.json
+✓ Removed package-manager pin
+  File: ../../package.json
+  Field: devEngines.packageManager
+```
+
+## `vpt print-file ../../package.json package.json`
+
+mixed removal uses the same separate targets
+
+```
+{
+  "name": "command-env-pin-package-manager",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ],
+  "devEngines": {
+    "packageManager": [
+      {
+        "name": "npm",
+        "version": "<version>",
+        "onFail": "error"
+      },
+      {
+        "name": "pnpm",
+        "version": "<version>",
+        "onFail": "download"
+      }
+    ]
+  }
+}
+{
+  "name": "app",
+  "private": true
+}
+```
diff --git a/..._pin_package_manager/snapshots/env_pin_package_manager_from_nested_workspace.md b/..._pin_package_manager/snapshots/env_pin_package_manager_from_nested_workspace.md
@@ -9,6 +9,8 @@ VITE+ - The Unified Toolchain for the Web
 
 warn: Current environment resolves to npm from devEngines.packageManager, but yarn was requested.
 ✓ Pinned package manager to yarn@4.12.0
+  File: ../../package.json
+  Field: devEngines.packageManager
 note: Package manager will be downloaded on first use.
 ```
 

diff --git a/...kage_manager/snapshots/env_pin_same_version_dev_engines_keeps_write_behavior.md b/...kage_manager/snapshots/env_pin_same_version_dev_engines_keeps_write_behavior.md
@@ -0,0 +1,38 @@
+# env_pin_same_version_dev_engines_keeps_write_behavior
+
+## `vpt write-file package.json '{"devEngines": {"packageManager": [{"name": "pnpm", "version": "10.18.0", "onFail": "error"}, {"name": "yarn", "version": "4.12.0"}]}}
+'`
+
+
+## `vp env pin pnpm@10.18.0 --no-install`
+
+equal versions retain the existing write path rather than reporting a no-op
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+✓ Pinned package manager to pnpm@10.18.0
+  File: package.json
+  Field: devEngines.packageManager
+note: Package manager will be downloaded on first use.
+```
+
+## `vpt print-file package.json`
+
+```
+{
+  "devEngines": {
+    "packageManager": [
+      {
+        "name": "pnpm",
+        "version": "<version>",
+        "onFail": "error"
+      },
+      {
+        "name": "yarn",
+        "version": "<version>"
+      }
+    ]
+  }
+}
+```
diff --git a/...pshots/fixtures/command_env_pin_package_manager/snapshots/env_pin_scope_help.md b/...pshots/fixtures/command_env_pin_package_manager/snapshots/env_pin_scope_help.md
@@ -0,0 +1,73 @@
+# env_pin_scope_help
+
+## `vp env pin --help`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+Usage: vp env pin [OPTIONS] [SPECS]...
+
+Pin Node.js locally and package-manager versions at the workspace root
+
+Arguments:
+  [SPECS]...  Versions to pin. Bare versions select Node.js; package managers use name@version
+
+Options:
+  --unpin                                                        Remove Node.js pins locally and package-manager pins at the workspace root
+  --no-install                                                   Skip pre-downloading the pinned version
+  --force                                                        Overwrite an existing pin without confirmation
+  --target <TARGET>                                              Explicitly choose the write target (overrides the default selection)
+                                                                 Possible values:
+  - node-version:                                                Pin via the .node-version file
+  - nvmrc:                                                       Pin via the .nvmrc file
+  - dev-engines:                                                 Pin via package.json#devEngines (runtime or packageManager)
+  - package-manager: Pin via the top-level packageManager field
+  -h, --help                                                     Print help (see a summary with '-h')
+
+Examples:
+  vp env pin lts                  # Pin Node.js to latest LTS
+  vp env pin pnpm@10              # Pin the package manager
+  vp env pin 22 pnpm@10           # Pin both components
+  vp env pin --unpin              # Remove both effective pins
+  vp env pin "^20.0.0" --force    # Overwrite existing pin
+  vp env pin 24 --target node-version   # Force the .node-version file
+Node.js pins use the current directory. Package-manager pins use the workspace
+root package.json, or the current project package.json outside a workspace.
+Pinning both components can update two different files. --target selects a pin
+source, not a project directory.
+The Node.js write target follows the compatibility-first rule: an existing
+.node-version keeps being updated, as does an effective .nvmrc in the current
+directory.
+Otherwise the pin is written to package.json#devEngines.runtime, or .node-version
+when the directory has no package.json.
+
+Documentation: https://viteplus.dev/guide/env
+```
+
+## `vp env unpin --help`
+
+```
+VITE+ - The Unified Toolchain for the Web
+
+Usage: vp env unpin [OPTIONS] [SCOPE]
+
+Remove Node.js pins locally and package-manager pins at the workspace root
+
+Arguments:
+  [SCOPE]  Limit removal to node, pm, or a package-manager family
+
+Options:
+  --target <TARGET>                                                               Explicitly choose which pin source to remove
+                                                                                  Possible values:
+  - node-version:                                                                 Pin via the .node-version file
+  - nvmrc:                                                                        Pin via the .nvmrc file
+  - dev-engines:                                                                  Pin via package.json#devEngines (runtime or packageManager)
+  - package-manager: Pin via the top-level packageManager field
+  -h, --help                                                                      Print help (see a summary with '-h')
+  Alias for pin --unpin. Node.js pins use the current directory. Package-manager
+  pins use the workspace root package.json, or the current project package.json
+  outside a workspace. Removing both components can update two different files.
+  --target selects a pin source, not a project directory.
+
+Documentation: https://viteplus.dev/guide/env
+```