vite-plus 1.2.0 → 1.4.0

package/dist/vpx-script-EXgV5QOf.js

@@ -0,0 +1,434 @@
+import path from "node:path";
+import { accessSync, closeSync, constants, openSync, readSync, statSync } from "node:fs";
+// src/vpx-script.ts
+/**
+* Script detection for the project-local `vpx` bin. Mirrors the global CLI in
+* `crates/vp_global_cli/src/commands/vpx_script.rs`; keep the two in sync.
+*/
+const SCRIPT_EXTENSIONS = [
+	".ts",
+	".mts",
+	".cts",
+	".tsx",
+	".js",
+	".mjs",
+	".cjs",
+	".jsx"
+];
+const TS_EXTENSIONS = /* @__PURE__ */ new Set([
+	".ts",
+	".mts",
+	".cts",
+	".tsx"
+]);
+/** Node.js options that take a required value, which may come as the next argument (best effort). */
+const NODE_OPTIONS_WITH_VALUE = /* @__PURE__ */ new Set([
+	"-C",
+	"-e",
+	"-p",
+	"-pe",
+	"-r",
+	"--allow-fs-read",
+	"--allow-fs-write",
+	"--build-sea",
+	"--build-snapshot-config",
+	"--conditions",
+	"--cpu-prof-dir",
+	"--cpu-prof-interval",
+	"--cpu-prof-name",
+	"--debug-port",
+	"--diagnostic-dir",
+	"--disable-proto",
+	"--disable-warning",
+	"--dns-result-order",
+	"--env-file",
+	"--env-file-if-exists",
+	"--eval",
+	"--experimental-config-file",
+	"--experimental-default-type",
+	"--experimental-loader",
+	"--experimental-package-map",
+	"--experimental-sea-config",
+	"--experimental-test-isolation",
+	"--experimental-test-tag-filter",
+	"--heap-prof-dir",
+	"--heap-prof-interval",
+	"--heap-prof-name",
+	"--heapsnapshot-near-heap-limit",
+	"--heapsnapshot-signal",
+	"--icu-data-dir",
+	"--import",
+	"--input-type",
+	"--inspect-port",
+	"--inspect-publish-uid",
+	"--loader",
+	"--localstorage-file",
+	"--max-http-header-size",
+	"--max-old-space-size-percentage",
+	"--network-family-autoselection-attempt-timeout",
+	"--openssl-config",
+	"--print",
+	"--redirect-warnings",
+	"--report-dir",
+	"--report-directory",
+	"--report-filename",
+	"--report-signal",
+	"--require",
+	"--run",
+	"--secure-heap",
+	"--secure-heap-min",
+	"--snapshot-blob",
+	"--test-concurrency",
+	"--test-coverage-branches",
+	"--test-coverage-exclude",
+	"--test-coverage-functions",
+	"--test-coverage-include",
+	"--test-coverage-lines",
+	"--test-global-setup",
+	"--test-isolation",
+	"--test-name-pattern",
+	"--test-random-seed",
+	"--test-reporter",
+	"--test-reporter-destination",
+	"--test-rerun-failures",
+	"--test-shard",
+	"--test-skip-pattern",
+	"--test-timeout",
+	"--title",
+	"--tls-cipher-list",
+	"--tls-keylog",
+	"--trace-event-categories",
+	"--trace-event-file-pattern",
+	"--trace-require-module",
+	"--unhandled-rejections",
+	"--use-largepages",
+	"--v8-pool-size",
+	"--watch-kill-signal",
+	"--watch-path"
+]);
+/**
+* Node.js options after which positionals are not an entry file: the code of `--eval` /
+* `--print` or the package script of `--run` runs instead, and `--test` takes test files
+* and globs.
+*/
+const NODE_OPTIONS_WITHOUT_ENTRY = /* @__PURE__ */ new Set([
+	"-e",
+	"--eval",
+	"-p",
+	"-pe",
+	"--print",
+	"--run",
+	"--test"
+]);
+/**
+* The watcher's options that take a value, which may come as the next argument, so that
+* value is not taken for the script.
+*/
+const WATCH_OPTIONS_WITH_VALUE = /* @__PURE__ */ new Set([
+	"--exclude",
+	"--ignore",
+	"--include",
+	"--kill-signal",
+	"--kill-timeout"
+]);
+/**
+* The option an argument names, without `=value`. Node.js accepts `_` for `-` in long
+* option names, as in `--redirect_warnings`.
+*/
+function nodeOptionName(arg) {
+	const name = arg.split("=", 1)[0];
+	return name.startsWith("--") ? `--${name.slice(2).replaceAll("_", "-")}` : name;
+}
+/**
+* Whether the option `name`, given without `=value`, takes `next` as its value. Node.js
+* 24.19, 26.1, and later read a bare `--experimental-config-file` as `node.config.json`,
+* and older releases take the next argument as the config file, so that argument is its
+* value only when it is a `.json` file, which cannot be the script either way. Mirrors
+* `takes_next_arg` in the global CLI.
+*/
+function takesNextArg(name, next) {
+	if (name === "--experimental-config-file") return next.endsWith(".json") && !next.startsWith("-");
+	return NODE_OPTIONS_WITH_VALUE.has(name) || WATCH_OPTIONS_WITH_VALUE.has(name);
+}
+/** npx-style: flags come before the first positional or unknown flag. */
+function parseVpxArgs(args) {
+	const flags = {
+		packages: [],
+		shellMode: false,
+		silent: false,
+		help: false,
+		version: false
+	};
+	let index = 0;
+	for (; index < args.length; index++) {
+		const arg = args[index];
+		if (arg === "-p" || arg === "--package") {
+			index++;
+			if (index < args.length) flags.packages.push(args[index]);
+		} else if (arg.startsWith("--package=") || arg.startsWith("-p=")) flags.packages.push(arg.slice(arg.indexOf("=") + 1));
+		else if (arg === "-c" || arg === "--shell-mode") flags.shellMode = true;
+		else if (arg === "-s" || arg === "--silent") flags.silent = true;
+		else if (arg === "-h" || arg === "--help") flags.help = true;
+		else if (arg === "-v" || arg === "--version") flags.version = true;
+		else if (arg === "--tsconfig" && index + 1 < args.length) flags.tsconfig = args[++index];
+		else if (arg.startsWith("--tsconfig=")) flags.tsconfig = arg.slice(11);
+		else break;
+	}
+	return {
+		flags,
+		positional: args.slice(index)
+	};
+}
+var ScriptError = class extends Error {};
+/**
+* Decide whether `positional` runs a script; `undefined` means package mode.
+* Throws {@link ScriptError} for a missing script, which must never fall
+* through to a remote package download.
+*/
+function detectScript(positional, cwd) {
+	const [first] = positional;
+	if (first === void 0) return;
+	if (!first.startsWith("-")) return isScript(first, cwd) ? { nodeArgs: [...positional] } : void 0;
+	const nodeArgs = [];
+	let tsconfig;
+	let watch = false;
+	let entry = true;
+	for (let index = 0; index < positional.length; index++) {
+		const arg = positional[index];
+		if (arg === "--" || arg === "-" || !arg.startsWith("-")) {
+			const script = arg === "--" ? positional[index + 1] : arg;
+			if (script !== void 0 && entry) checkScriptAfterOptions(script, cwd);
+			nodeArgs.push(...positional.slice(index));
+			break;
+		}
+		if (arg === "--tsconfig") {
+			if (positional[index + 1] === void 0) throw new ScriptError("--tsconfig requires a path");
+			tsconfig = positional[++index];
+			continue;
+		}
+		if (arg.startsWith("--tsconfig=")) {
+			tsconfig = arg.slice(11);
+			continue;
+		}
+		if (arg === "--watch") {
+			watch = true;
+			continue;
+		}
+		const name = nodeOptionName(arg);
+		watch ||= name === "--watch-path";
+		entry &&= !NODE_OPTIONS_WITHOUT_ENTRY.has(name);
+		nodeArgs.push(arg);
+		const next = positional[index + 1];
+		if (!arg.includes("=") && next !== void 0 && takesNextArg(name, next)) nodeArgs.push(positional[++index]);
+	}
+	return watch ? {
+		nodeArgs,
+		tsconfig,
+		watch
+	} : {
+		nodeArgs,
+		tsconfig
+	};
+}
+/**
+* After Node.js options, only a missing explicit path is an error. A bare name may be
+* the value of an option missing from `NODE_OPTIONS_WITH_VALUE`, such as a coverage
+* glob, and this position never falls back to a package, so Node.js reports a missing
+* one itself.
+*/
+function checkScriptAfterOptions(token, cwd) {
+	if (isExplicitPath(token) && SCRIPT_EXTENSIONS.some((extension) => token.endsWith(extension)) && !isFile(path.resolve(cwd, token))) throw missingScript(token, path.resolve(cwd, token));
+}
+/** The error for a script path that is not a file. */
+function missingScript(token, file) {
+	return new ScriptError(statSync(file, { throwIfNoEntry: false })?.isDirectory() ? `Script is a directory: ${token}` : `Script not found: ${token}`);
+}
+function isScript(token, cwd) {
+	const file = path.resolve(cwd, token);
+	const extension = SCRIPT_EXTENSIONS.find((candidate) => token.endsWith(candidate));
+	if (extension) {
+		if (isFile(file)) return true;
+		if (isExplicitPath(token) || TS_EXTENSIONS.has(extension)) throw missingScript(token, file);
+		return false;
+	}
+	if (!isExplicitPath(token)) return false;
+	const stats = statSync(file, { throwIfNoEntry: false });
+	if (!stats) throw new ScriptError(`Script not found: ${token}`);
+	return stats.isFile() && hasVpxShebang(file);
+}
+function isExplicitPath(token) {
+	if (token.startsWith("./") || token.startsWith("../") || token.startsWith("/")) return true;
+	return process.platform === "win32" && (token.startsWith(".\\") || token.startsWith("..\\") || /^(?:[a-zA-Z]:[\\/]|\\\\)/.test(token));
+}
+function isFile(file) {
+	return statSync(file, { throwIfNoEntry: false })?.isFile() ?? false;
+}
+/** The first `length` bytes of `file`, or none when it cannot be read. */
+function readHead(file, length) {
+	const head = Buffer.alloc(length);
+	try {
+		const fd = openSync(file, "r");
+		try {
+			return head.subarray(0, readSync(fd, head, 0, length, 0));
+		} finally {
+			closeSync(fd);
+		}
+	} catch {
+		return head.subarray(0, 0);
+	}
+}
+function hasVpxShebang(file) {
+	const text = readHead(file, 256).toString("utf8");
+	if (!text.startsWith("#!")) return false;
+	return text.slice(2).split("\n", 1)[0].split(/\s+/).some((word) => {
+		const name = word.split(/[\\/]/).pop();
+		return name === "vpx" || name === "vpx.exe";
+	});
+}
+/** The magic numbers of executables the kernel runs: Mach-O (thin and fat) on macOS, ELF elsewhere. */
+const NATIVE_MAGIC = process.platform === "darwin" ? [
+	"feedface",
+	"feedfacf",
+	"cefaedfe",
+	"cffaedfe",
+	"cafebabe",
+	"bebafeca"
+] : ["7f454c46"];
+function isExecutableFile(file) {
+	try {
+		accessSync(file, constants.X_OK);
+	} catch {
+		return false;
+	}
+	return isFile(file);
+}
+function isNativeExecutable(file) {
+	return isExecutableFile(file) && NATIVE_MAGIC.includes(readHead(file, 4).toString("hex"));
+}
+/**
+* Whether exec can run `file` itself: an executable native binary, or an executable
+* script whose `#!` interpreter is one. A failed `process.execve()` aborts most supported
+* Node.js versions instead of throwing, so the project-local bin runs anything else
+* through `/bin/sh`, which reports a file it cannot run as a terminal does. The
+* interpreter keeps a trailing `\r`, as the kernel reads it.
+*/
+function canExecDirectly(file) {
+	if (!isExecutableFile(file)) return false;
+	const head = readHead(file, 256);
+	if (head.subarray(0, 2).toString("latin1") !== "#!") return isNativeExecutable(file);
+	const interpreter = head.subarray(2).toString("utf8").split("\n", 1)[0].replace(/^[ \t]+/, "").split(/[ \t]/, 1)[0];
+	return path.isAbsolute(interpreter) && isNativeExecutable(interpreter);
+}
+/** Whether a package spec names a version, as in `eslint@9` or `@vue/cli@5`. */
+function hasVersionSpec(spec) {
+	if (spec.startsWith("@")) {
+		const slash = spec.indexOf("/");
+		return slash !== -1 && spec.slice(slash + 1).includes("@");
+	}
+	return spec.includes("@");
+}
+/** The binary name a package spec runs: `eslint@9` → `eslint`, `@vue/cli@5` → `cli`. */
+function commandName(spec) {
+	if (spec.startsWith("@")) {
+		const slash = spec.indexOf("/");
+		return slash === -1 ? spec : spec.slice(slash + 1).split("@")[0];
+	}
+	return spec.split("@")[0];
+}
+/** Every `node_modules/.bin` path from `cwd` up to the root, nearest first, whether or not it exists. */
+function nodeModulesBinPaths(cwd) {
+	const paths = [];
+	for (let dir = cwd;; dir = path.dirname(dir)) {
+		paths.push(path.join(dir, "node_modules", ".bin"));
+		if (path.dirname(dir) === dir) return paths;
+	}
+}
+/** The nearest `node_modules/.bin/<name>` from `cwd` up (`.cmd` on Windows), like the global CLI's `find_local_binary`. */
+function findLocalBin(name, cwd) {
+	const fileName = process.platform === "win32" ? `${name}.cmd` : name;
+	for (const dir of nodeModulesBinPaths(cwd)) {
+		const file = path.join(dir, fileName);
+		const stats = statSync(file, { throwIfNoEntry: false });
+		if (stats?.isFile()) return {
+			file,
+			stats
+		};
+	}
+}
+/** An executable mode bit, as the global CLI checks; always true on Windows. */
+function isExecutable(stats) {
+	return process.platform === "win32" || (stats.mode & 73) !== 0;
+}
+/**
+* Package mode runs an explicit path as a program. An existing file must be executable,
+* and a directory needs a package.json for `vp dlx`, so either fails here with a clear
+* error instead of in `vp dlx`. Mirrors `check_explicit_program` in the global CLI.
+*/
+function checkExplicitProgram(token, cwd) {
+	if (!isExplicitPath(token)) return;
+	const file = path.resolve(cwd, token);
+	const stats = statSync(file, { throwIfNoEntry: false });
+	if (stats?.isDirectory() && !isFile(path.join(file, "package.json"))) return { error: `'${token}' is a directory without a package.json` };
+	if (stats?.isFile() && !isExecutable(stats)) return {
+		error: `'${token}' is not executable`,
+		note: `Make it executable with \`chmod +x ${token}\`.`
+	};
+}
+/**
+* How the project-local bin runs `vpx <pkg> [args...]`. The nearest binary in
+* `node_modules/.bin`, or an existing executable file, runs directly, as the global CLI
+* execs the path it finds. A versioned package, `--package`, `--shell-mode`, or a local
+* package directory runs with this package's `vp dlx`. Global packages and `PATH` are
+* not searched, so a binary that is not installed is an error rather than a download.
+*/
+function packageInvocation(flags, [spec, ...rest], cwd) {
+	const silent = flags.silent ? ["--silent"] : [];
+	if (flags.packages.length > 0 || flags.shellMode || hasVersionSpec(spec)) return {
+		command: "dlx",
+		args: [
+			...flags.packages.flatMap((name) => ["--package", name]),
+			...flags.shellMode ? ["--shell-mode"] : [],
+			...silent,
+			spec,
+			...rest
+		]
+	};
+	if (isExplicitPath(spec)) {
+		const problem = checkExplicitProgram(spec, cwd);
+		if (problem) return problem;
+		const file = path.resolve(cwd, spec);
+		return isFile(file) ? {
+			command: "run",
+			file,
+			args: rest
+		} : {
+			command: "dlx",
+			args: [
+				...silent,
+				spec,
+				...rest
+			]
+		};
+	}
+	const name = commandName(spec);
+	const bin = findLocalBin(name, cwd);
+	if (bin) {
+		if (!isExecutable(bin.stats)) {
+			const relative = path.relative(cwd, bin.file);
+			return {
+				error: `'${relative}' is not executable`,
+				note: `Reinstall dependencies with \`vp install\`, or make it executable with \`chmod +x ${relative}\`.`
+			};
+		}
+		return {
+			command: "run",
+			file: bin.file,
+			args: rest
+		};
+	}
+	return {
+		error: `'${name}' is not installed in node_modules`,
+		note: `Add it to devDependencies, or run \`vp dlx ${spec}\` to download and run it.`
+	};
+}
+export { canExecDirectly as a, nodeModulesBinPaths as c, WATCH_OPTIONS_WITH_VALUE as i, packageInvocation as l, SCRIPT_EXTENSIONS as n, detectScript as o, ScriptError as r, isFile as s, NODE_OPTIONS_WITH_VALUE as t, parseVpxArgs as u };

package/docs/config/run.md

@@ -56,6 +56,10 @@ export default defineConfig({
 
 `cache: true` enables both task and script caching, `cache: false` disables both.
 
+::: warning
+This option can only be set in the workspace root's `vite.config.ts`. Setting it in a package's config will result in an error.
+:::
+
 ## `run.tasks`
 
 - **Type:** `Record<string, Task | string | string[]>`

package/docs/guide/check.md

@@ -16,6 +16,7 @@ We recommend turning both `typeAware` and `typeCheck` on so `vp check` becomes t
 vp check
 vp check --fix              # Format and run autofixers.
 vp check --quiet            # Hide lint warnings; still report and fail on errors.
+vp check --deny-warnings    # Treat lint warnings as errors.
 vp check --no-fmt           # Skip format; run lint (and type-check if enabled).
 vp check --no-lint          # Skip lint rules; keep type-check when enabled.
 vp check --no-fmt --no-lint # Type-check only (requires both `typeAware` and `typeCheck` enabled).

package/docs/guide/ci.md

@@ -4,7 +4,7 @@ You can use `voidzero-dev/setup-vp` to use Vite+ in CI environments.
 
 ## Overview
 
-[`voidzero-dev/setup-vp`](https://github.com/voidzero-dev/setup-vp) provides integrations for GitHub Actions, GitLab CI/CD, and Azure Pipelines. All three install Vite+ and can install project dependencies. The GitHub Action and Azure Pipelines template can also set up Node.js and cache package manager data automatically, while the GitLab CI/CD template uses the Node.js runtime and cache configuration provided by the job.
+[`voidzero-dev/setup-vp`](https://github.com/voidzero-dev/setup-vp) provides integrations for GitHub Actions, GitLab CI/CD, and Azure Pipelines. All three install Vite+, can select the project's Node.js version, and can install project dependencies. The GitHub Action and Azure Pipelines template can also cache package-manager data automatically. GitLab CI/CD uses the job's native cache configuration and requires Node.js to start the setup runtime.
 
 ## setup-vp Versioning
 
@@ -12,6 +12,16 @@ Set `<setup-vp-version>` in each example to an exact version from the [`setup-vp
 
 Run `vp migrate` to replace exact `voidzero-dev/setup-vp@v1` references in GitHub Actions workflows and composite actions under `.github` with the latest exact release known to your Vite+ version. Existing exact versions and commit SHAs remain unchanged.
 
+## Node.js During Installation
+
+The Vite+ installer uses the latest Node.js LTS by default. With versions that support [`VP_SETUP_NODE_VERSION`](/guide/global-cli#vp-setup-node-version), `setup-vp` can use the project's version for installation too. This avoids a second Node.js download when that version supports both the global CLI and its pinned `pnpm`.
+
+`setup-vp` selects the version before it starts the installer. An explicit Node.js version takes precedence over a version-file input. Without either input, it checks the working directory and its parents using the [project declaration order](/guide/env#node-js-selection). The integration passes the selection through `VP_SETUP_NODE_VERSION`; the installer itself does not read project declarations.
+
+Without a selection, with Node.js management disabled, or when the selected version is incompatible, installation uses LTS. Older installers keep their existing behavior. Automatic project discovery does not create a session override, so later commands retain normal directory-based version selection.
+
+The integration handles these installer variables automatically. Configure `node-version` or `node-version-file` in GitHub Actions and GitLab CI/CD, or `nodeVersion` or `nodeVersionFile` in Azure Pipelines. See the [`setup-vp` documentation](https://github.com/voidzero-dev/setup-vp#inputs) for the complete input reference.
+
 ## GitHub Actions
 
 The GitHub Action sets up Vite+, the required Node.js version, and the package manager. This means you usually do not need separate `setup-node`, package-manager setup, dependency installation, or manual dependency caching steps in your workflow.
@@ -53,7 +63,7 @@ test:
 
 The GitLab CI/CD integration differs from the GitHub Action in a few ways:
 
-- The template does not install Node.js. Use a Node.js image, as shown above, or otherwise provide Node.js in the job.
+- The template requires Node.js to start the setup runtime. Use a Node.js image, as shown above, or otherwise provide Node.js in the job. Use `node-version` or `node-version-file` to select a managed project runtime with `vp env use`.
 - Configure dependency caching with the job's GitLab [`cache`](https://docs.gitlab.com/ci/yaml/#cache) keyword.
 - Use a Unix-like runner environment with Bash and either `curl` or `wget`.
 
@@ -90,7 +100,7 @@ steps:
 
 Pin `ref` and `setupRef` to the same tag or commit SHA for strict reproducibility.
 
-The Azure Pipelines template supports Microsoft-hosted Linux, macOS, and Windows agents. It uses Azure's native `UseNode@1` and `Cache@2` tasks to set up Node.js and cache package-manager data.
+The Azure Pipelines template supports Microsoft-hosted Linux, macOS, and Windows agents. `UseNode@1` provides Node.js to start the setup runtime through `bootstrapNodeVersion`. The `nodeVersion` and `nodeVersionFile` parameters select the managed project runtime with `vp env use`. `Cache@2` caches package-manager data.
 
 For advanced configuration and the complete parameter reference, see the [`setup-vp` Azure Pipelines documentation](https://github.com/voidzero-dev/setup-vp#azure-pipelines).
 

package/docs/guide/create.md

@@ -20,6 +20,40 @@ vp create <template>
 vp create <template> -- <template-options>
 ```
 
+### Without the Global CLI
+
+If you haven't installed [the global `vp`](/guide/global-cli) yet. Vite+ provides `create-vite-plus` package running `vp create` through your package manager.
+
+::: code-group
+
+```bash [pnpm]
+pnpm create vite-plus
+```
+
+```bash [npm]
+npm create vite-plus@latest
+```
+
+```bash [Yarn]
+yarn create vite-plus
+```
+
+```bash [Bun]
+bun create vite-plus
+```
+
+:::
+
+The new project uses the package manager that ran the command, unless you pass `--package-manager` or create it inside an existing workspace. Arguments are forwarded to `vp create` unchanged, so the first argument is the template, not the target directory:
+
+```bash
+pnpm create vite-plus vite:application --directory my-app
+```
+
+If you are using npm, there is a `--` needed before options meant for `vp create`, for example `npm create vite-plus@latest -- vite:application --directory my-app`.
+
+After creating the project, run `vp` through your package manager, for example `pnpm exec vp run`.
+
 ## Built-in Templates
 
 Vite+ ships with these built-in templates:

package/docs/guide/env.md

@@ -41,18 +41,23 @@ To select the project's Node.js version, Vite+ checks the current directory firs
 
 If no directory declares a version, Vite+ uses the global default (`vp env default`) and then the latest LTS.
 
+These rules select Node.js for project commands. The installer uses the latest LTS by default. Only [`VP_SETUP_NODE_VERSION`](/guide/global-cli#vp-setup-node-version) changes its dependency-installation runtime; [`setup-vp`](/guide/ci#node-js-during-installation) supplies this override from the CI inputs or project declarations.
+
 `devEngines.runtime` ranks above `engines.node` because it declares the development-environment requirement, while `engines.node` is a consumer-facing support range. `vp env doctor` warns when declared sources conflict.
 
 ::: tip Using pnpm with Vite+ runtime management
 pnpm can also manage the runtime declared in `devEngines.runtime`. When both pnpm and Vite+ manage Node.js, they can download the same version separately or select different versions, causing inconsistent behavior between commands.
 
-If you want Vite+ to manage Node.js, pnpm 11+ supports disabling pnpm's automatic runtime management globally with [`runtimeOnFail`](https://pnpm.io/settings/cli#runtimeonfail):
+If your project uses Vite+ to manage Node.js and pnpm versions, add these settings to the project's `pnpm-workspace.yaml` (pnpm 11+):
 
-```bash
-pnpm config set --global runtimeOnFail ignore
+```yaml
+runtimeOnFail: ignore
+pmOnFail: ignore
 ```
 
-This setting also disables pnpm's automatic management of other declared runtimes, including Bun and Deno. Consider whether any of your projects rely on that behavior before setting it globally.
+[`runtimeOnFail`](https://pnpm.io/settings/cli#runtimeonfail) disables pnpm's automatic management of declared runtimes. [`pmOnFail`](https://pnpm.io/settings/cli#pmonfail) prevents pnpm from switching to the package-manager version declared in `package.json`. Commit these settings so the project shares the same policy.
+
+`runtimeOnFail: ignore` also affects other declared runtimes, including Bun and Deno. If the project relies on pnpm to manage them, consider that before enabling this setting. Switching an existing project to this policy can change runtime entries in `pnpm-lock.yaml` on the next install; review and commit those changes with the configuration.
 :::
 
 ## Package-Manager Selection
@@ -76,7 +81,7 @@ Package-manager selection uses this priority:
 | `VP_YARN_VERSION` | `yarn`, `yarnpkg`           |
 | `VP_BUN_VERSION`  | `bun`, `bunx`               |
 
-These variables accept a version or range, such as `10.18.0`, `10`, or `latest`, and override the matching shim's project and default versions. They do not change the manager or version selected by `vp install`.
+These variables accept a version, range, or npm dist-tag, such as `10.18.0`, `10`, `latest`, or `latest-10`, and override the matching shim's project and default versions. They do not change the manager or version selected by `vp install`.
 
 `vp env use pnpm@10.20.0` sets `VP_PNPM_VERSION` for the current shell, just as `vp env use node@22` sets `VP_NODE_VERSION`. Each package manager has its own override, so switching Yarn does not clear a pnpm override. `vp env use` does not set or clear `VP_PACKAGE_MANAGER`.
 
@@ -87,12 +92,14 @@ VP_PACKAGE_MANAGER=pnpm@10.18.0 vp install
 VP_PNPM_VERSION=10.20.0 pnpm --version
 ```
 
-The overrides apply in managed mode. A package manager can also perform its own version switching after Vite+ launches it; for example, pnpm's `managePackageManagerVersions` setting may switch back to the version in `package.json`.
+The overrides apply in managed mode. A package manager can also perform its own version switching after Vite+ launches it; for example, pnpm 11+'s [`pmOnFail`](https://pnpm.io/settings/cli#pmonfail) defaults to `download` and may switch back to the version in `package.json`. To let Vite+ control the pnpm version, set `pmOnFail: ignore` in the project's `pnpm-workspace.yaml`. In pnpm 10, the corresponding setting is `managePackageManagerVersions`.
 
 A project selection applies only to its matching shims. For example, pnpm controls `pnpm`, `pnpx`, `pn`, and `pnx`; invoking `npm` still resolves npm independently. Without a matching project selection, a named shim uses its configured default version and otherwise uses the latest release without prompting. The npm shim falls back to Node's bundled npm. `vp env use npm` selects standalone npm's latest release for the current shell when no project version or global default is configured.
 
-::: details Latest-version caching
-When a named shim falls back to the latest release, the resolved version is cached for one hour. An expired cache remains available when the registry cannot be reached.
+Package-manager specs follow npm's order: an exact version, then a semver range, then a dist-tag. `default` is an alias of `latest`, except for npm, where it selects the npm on `PATH`.
+
+::: details Dist-tag caching
+When a package-manager dist-tag such as `latest` or `latest-10` is resolved, including a named shim falling back to the latest release, the resolved version is cached for one hour. An expired cache remains available when the registry cannot be reached.
 :::
 
 `pn` runs the same managed binary as `pnpm`, and `pnx` runs the same managed binary as `pnpx` (`pnpm dlx`). These aliases also work with managed pnpm versions older than v11.
@@ -176,20 +183,25 @@ In CI, `vp env use` can run without shell initialization. It writes a temporary
 The global CLI supports Tab completion in Bash, Zsh, Fish, Nushell, and PowerShell. Run `vp env setup` and follow its printed shell setup instructions to enable it. Press Tab to complete commands, or project task names after `vp run` and `vpr`.
 
 - **Zsh**: Run `autoload -Uz compinit; compinit` before loading the setup script if your shell has not initialized completion.
-- **Nushell**: Completion requires `fish` on `PATH`.
+- **Nushell**: Completion requires `fish` on `PATH`. Use Nushell 0.112.1 or later; see [Nushell version](/guide/global-cli#nushell-version).
 
 ### Manage
 
 - `vp env default` shows the global Node.js default and each configured package-manager version. Bare versions set Node.js; qualified specs such as `pnpm@10.18.0` set that package manager's shim default without replacing the defaults for Bun, Yarn, or npm. `--unset` clears all defaults unless scoped.
-- `vp env default <lts|latest>` and `<package-manager>@latest` re-resolve on each use, so the default follows new releases, including new majors. Other versions and ranges, such as `24` or `pnpm@10`, resolve to an exact version when set.
-- `vp env pin` shows or writes project pins. Existing `.node-version` and top-level `packageManager` fields keep being updated for compatibility. An existing `.nvmrc` is updated when it is the effective Node source in the current directory; its comments and other non-version content are preserved. Otherwise Vite+ writes the matching `devEngines` entry. Use `--target node-version`, `--target nvmrc`, `--target dev-engines`, or `--target package-manager` to choose explicitly. Pinning in a child directory does not modify an inherited `.nvmrc`.
-- `vp env unpin` removes both effective pins by default; append a selector to remove one. Lower-priority declarations are not deleted.
+- `vp env default <lts|latest>` and package-manager dist-tags such as `pnpm@latest` or `pnpm@latest-10` re-resolve on each use, so the default follows the tag, including new majors for `latest`. Other versions and ranges, such as `24` or `pnpm@10`, resolve to an exact version when set.
+- `vp env pin` shows or writes project pins. 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.
+
+  Existing `.node-version` and top-level `packageManager` fields keep being updated for compatibility. An existing `.nvmrc` is updated when it is the effective Node source in the current directory. Its comments and other non-version content are preserved. Otherwise Vite+ writes the matching `devEngines` entry.
+
+  Use `--target node-version`, `--target nvmrc`, `--target dev-engines`, or `--target package-manager` to choose the pin source explicitly. This does not change the project directory. Package-manager output shows the file path relative to the current working directory and the field that was updated, or the target before an existing overwrite prompt. Pinning in a child directory does not modify an inherited `.nvmrc`.
+
+- `vp env unpin` (alias for `vp env pin --unpin`) removes both effective pins by default. Append a selector to remove one. Node.js removal uses the current directory. Package-manager removal uses the workspace root manifest, or the current project manifest outside a workspace. `--target` selects the pin source within that scope. The output identifies the removed package-manager field, or the fields checked when no matching pin is found. Lower-priority declarations are not deleted.
 - `vp env use` activates the complete project environment. Explicit specs override selected components; `--unset` clears both unless scoped.
 - `vp env install` installs the complete resolved environment, a selected component, or explicit specs.
 - `vp env uninstall` removes the Node.js version resolved from an explicit version or selector, such as `22` or `lts`. Package managers require a qualified exact version, such as `pnpm@10.18.0`.
 - `vp env clean` removes unused installs. Use `clean node`, `clean pm`, or a concrete manager. Current and configured-default versions are preserved.
 - `vp env exec` runs a command in the resolved environment. Use `--node` and `--package-manager`; `--npm` is an alias for `--package-manager npm@…`.
-- `vp node` uses the resolved Node.js runtime and exposes the selected package-manager path to child processes.
+- `vp node` uses the resolved Node.js runtime and exposes the selected package-manager path to child processes. It runs Node.js as is, so TypeScript files get Node.js type stripping only; [`vpx <file>`](/guide/vpx#running-scripts) runs them on the same runtime with full TypeScript support.
 
 ### Inspect
 
@@ -217,7 +229,9 @@ vp env print                  # Print PATH setup for both components
 
 # Manage
 vp env pin lts                # Pin Node.js only to an exact version
+vp env pin node@26            # Pin Node.js 26 to an exact version
 vp env pin lts pnpm@10        # Pin both project components to exact versions
+vp env pin pnpm@latest-10     # Pin pnpm to the version of its latest-10 dist-tag
 vp env install                # Install the complete resolved environment
 vp env use 20 pnpm@10         # Override both components for this shell
 vp env use --unset pnpm       # Remove only the pnpm session version