vite-plus 1.3.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/env.md

@@ -41,6 +41,8 @@ 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
@@ -181,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 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. 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 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
 

package/docs/guide/global-cli.md

@@ -71,6 +71,8 @@ irm https://vite.plus/ps1 | iex
 
 On Windows, you can instead download and run [`vp-setup.exe`](https://setup.viteplus.dev).
 
+The installer uses the latest Node.js LTS to install its JavaScript dependencies. CI integrations can select another compatible version through [`VP_SETUP_NODE_VERSION`](#vp-setup-node-version).
+
 After installation, open a new shell and run:
 
 ```bash
@@ -105,6 +107,47 @@ These variables control the installer scripts and the standalone Windows install
   $env:VP_VERSION = "1.2.3"; irm https://vite.plus/ps1 | iex
   ```
 
+#### `VP_SETUP_NODE_VERSION`
+
+- **Purpose**: Select the Node.js version used to install the global CLI's JavaScript dependencies. CI integrations such as [`setup-vp`](/guide/ci#node-js-during-installation) set this variable to reuse the project's runtime.
+- **Values**: An exact version, a version range, or an alias such as `22.23.1`, `22`, `^22.18.0`, `lts`, or `latest`. The installer resolves the value once to an exact version.
+- **Default**: Unset or empty (use the latest Node.js LTS). Project files, `VP_NODE_VERSION`, session overrides, and the user-level default do not change this default.
+- **Compatibility**: The resolved version must meet the Node.js requirements of both the global CLI and its pinned `pnpm`. Otherwise, the installer uses LTS. An invalid or unresolvable value causes an error.
+- **Scope**: Initial dependency installation only. This variable does not set a project pin, session override, or global default. `vp upgrade` and legacy installers continue to use LTS.
+
+#### `VP_SETUP_NODE_VERSION_FILE`
+
+- **Purpose**: Optional output file for integrations that need the exact version resolved from `VP_SETUP_NODE_VERSION`.
+- **Contents**: The resolved version, such as `22.23.1`, written after successful dependency installation. If compatibility requires LTS for installation, the file still contains the requested version's resolution.
+- **Default**: Unset (write no file). The installer also writes no file when `VP_SETUP_NODE_VERSION` is unset or empty, or when dependency installation is skipped.
+
+`setup-vp` manages this file automatically. Use its Node.js inputs to configure CI jobs.
+
+#### `VP_SETUP_SKIP_INSTALL_LOCKFILE`
+
+Set this variable to `1` to recover from a lockfile-related error during global CLI installation or `vp upgrade`. All other values, including unset or empty, keep the published installation lockfile enabled.
+
+The installer prints a warning and resolves dependencies without reading or recovering the installation lockfile. The requested CLI version stays pinned, but its dependency versions can differ from the release lockfile. Registry, authentication, and proxy settings remain in effect. This option does not affect project installations such as `vp install`.
+
+```bash
+# Retry installation without the bundled lockfile.
+curl -fsSL https://vite.plus | VP_SETUP_SKIP_INSTALL_LOCKFILE=1 bash
+
+# Or retry an upgrade, including the currently installed version.
+VP_SETUP_SKIP_INSTALL_LOCKFILE=1 vp upgrade --force
+```
+
+```powershell
+$env:VP_SETUP_SKIP_INSTALL_LOCKFILE = "1"
+try {
+  irm https://vite.plus/ps1 | iex
+} finally {
+  Remove-Item Env:VP_SETUP_SKIP_INSTALL_LOCKFILE
+}
+```
+
+Keep this override temporary. Later installations and upgrades use the published lockfile again when the variable is unset. To reinstall an affected version with its lockfile, unset the variable and run `vp upgrade <version> --force`.
+
 #### `VP_HOME`
 
 - **Purpose**: Optional pin for the single-root layout. Set it to an absolute path. Vite+ then puts bin, data, cache, config, and state under that directory. The installed CLI reads the same variable. See [Environment](/guide/env).
@@ -227,6 +270,7 @@ These variables configure the installed Vite+ CLI. `VP_HOME` (above) also applie
 
 - **Purpose**: Override Node.js version
 - **Default**: None (auto-detected)
+- **Scope**: Runtime commands. For the installer's dependency installation, use [`VP_SETUP_NODE_VERSION`](#vp-setup-node-version).
 - **Example**:
   ```bash
   # Run a command with a specific Node.js version
@@ -347,6 +391,14 @@ source ~/.config/vite-plus/env.nu
 
 For a custom `XDG_CONFIG_HOME`, use the absolute path to `<XDG_CONFIG_HOME>/vite-plus/env.nu` as resolved during installation. For an installation under `VP_HOME` or an existing `~/.vite-plus` installation, use `<VP_HOME>/env.nu` or `~/.vite-plus/env.nu` instead. Replace placeholders with actual paths and quote paths containing spaces. Open a new Nushell session and run `vp help` to verify the configuration.
 
+#### Nushell version
+
+Use Nushell 0.112.1 or later. In Nushell, a custom command or alias can have the same name as a built-in command, for example `def update []`. Nushell reads the Vite+ `env.nu` after your configuration. Thus, `env.nu` must call the built-in commands with the [`%` sigil](https://www.nushell.sh/lang-guide/chapters/custom_commands.html#calling-custom-commands), which Nushell 0.112.1 added.
+
+`vp env setup` checks the `nu` on `PATH`. With an earlier Nushell, it writes `env.nu` without the sigil. That `env.nu` still works, but a custom command with the name of a built-in command can stop Nushell at startup with `nu::parser::extra_positional` or a similar parse error. After you upgrade Nushell, run `vp env setup` again.
+
+If you have more than one Nushell installation, make sure that the `nu` on `PATH` during `vp env setup` is the Nushell that you start. A Nushell earlier than 0.112.1 cannot parse an `env.nu` that `vp env setup` wrote for a later version.
+
 #### `CI`
 
 - **Purpose**: Indicates running in CI environment