vite-plus 1.3.0 → 1.5.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/check.md

@@ -2,6 +2,8 @@
 
 `vp check` runs format, lint, and type checks together. The `check` block in `vite.config.ts` sets defaults for the composite command, mirroring the `--no-fmt` and `--no-lint` CLI flags.
 
+See [Check usage](/guide/check#usage) for the execution order and how to skip formatting after a failure.
+
 This is useful when a project wants to keep most of the toolchain but skip one step by default. For example, a team that lints but does not format can disable `check.fmt` so a plain `vp check` (the command agents and contributors run most) only lints, without anyone needing to remember `--no-fmt`.
 
 ## Example

package/docs/config/fmt.md

@@ -21,4 +21,4 @@ export default defineConfig({
 
 For file- or package-specific formatting settings, use [`fmt.overrides`](/guide/monorepo#format-overrides) from the root `vite.config.ts`.
 
-Oxfmt disables nested configs in Vite+ mode, so nested format configs do not override settings for individual files. See [troubleshooting](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) for details.
+Oxfmt disables nested configs in Vite+ mode, so nested format configs do not override settings for individual files. See [Troubleshooting](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) for details.

package/docs/config/lint.md

@@ -27,4 +27,4 @@ We recommend enabling both `options.typeAware` and `options.typeCheck` so `vp li
 
 For file- or package-specific lint rules, use [`lint.overrides`](/guide/monorepo#root-config-with-overrides) from the root `vite.config.ts`.
 
-Oxlint disables nested configs in Vite+ mode, so nested lint configs do not override settings for individual files. See [troubleshooting](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) for details.
+Oxlint disables nested configs in Vite+ mode, so nested lint configs do not override settings for individual files. See [Troubleshooting](/guide/troubleshooting#nested-lint-or-format-config-is-not-applied) for details.

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[]>`
@@ -86,7 +90,11 @@ Use the object form when a task needs other fields like `cache`, `dependsOn`, or
 
 - **Type:** `string | string[]`
 
-Defines the shell command to run for the task. The string is interpreted by a shell, so spaces, quoting, `&&`, pipes, and redirects all work as written on the command line.
+Defines the command to run for the task.
+
+::: info
+Vite Task parses simple commands and `&&` chains itself instead of passing them to a shell, so they behave the same on every platform. Other shell syntax, such as pipes or redirects, may behave differently across platforms.
+:::
 
 ```ts [vite.config.ts]
 tasks: {
@@ -113,7 +121,7 @@ tasks: {
 
 Each task defined in `vite.config.ts` must include its own `command`. You cannot define a task in both `vite.config.ts` and `package.json` with the same task name.
 
-Commands joined with `&&` (or supplied as an array) are automatically split into independently cached sub-tasks. See [Compound Commands](/guide/run#compound-commands).
+Array entries, and `&&` chains without other shell syntax, are automatically split into independently cached sub-tasks. See [Compound Commands](/guide/run#compound-commands).
 
 ### `dependsOn`
 

package/docs/config/staged.md

@@ -1,6 +1,6 @@
 # Staged Config
 
-`vp staged` reads staged-file rules from the `staged` block in `vite.config.ts`. See the [Commit hooks guide](/guide/commit-hooks).
+`vp staged` reads staged-file rules from the `staged` block in `vite.config.ts`. See the [Commit Hooks](/guide/commit-hooks).
 
 ## Example
 

package/docs/guide/check.md

@@ -16,11 +16,16 @@ 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).
 ```
 
+If formatting fails, `vp check` stops before lint and type checks run. To fix formatting and apply available lint fixes, run `vp check --fix`. This command changes files. To skip formatting and run the remaining enabled checks, run `vp check --no-fmt`.
+
+Put `vp check` flags before file paths. For example, use `vp check --fix src/index.ts`. Arguments after the first path go to the format and lint tools instead of `vp check`.
+
 ## Configuration
 
 `vp check` uses the same configuration you already define for linting and formatting:
@@ -60,4 +65,4 @@ export default defineConfig({
 });
 ```
 
-These options only affect `vp check`; standalone `vp fmt` and `vp lint` still run normally. A step is skipped if it is disabled in config or the matching `--no-fmt` / `--no-lint` flag is passed. Because the defaults apply to every `vp check` run, a pre-commit hook that calls `vp check` will skip the disabled step too. See [Check config](/config/check) for the full reference.
+These options only affect `vp check`; standalone `vp fmt` and `vp lint` still run normally. A step is skipped if it is disabled in config or the matching `--no-fmt` / `--no-lint` flag is passed. Because the defaults apply to every `vp check` run, a pre-commit hook that calls `vp check` will skip the disabled step too. See [Check Config](/config/check) for the full reference.

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 Node.js version pinned in the repository's [`.node-version`](https://github.com/voidzero-dev/vite-plus/blob/main/.node-version) by default. Each Vite+ release embeds this version at build time. The dependency-upgrade workflow keeps this pin up to date. 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 the embedded default. 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

@@ -95,7 +95,7 @@ Run `vp create --list` to see the built-in templates and the common shorthand te
 `--git` and `--no-git` are not available when adding a package to an existing monorepo.
 :::
 
-After create, manage the dispatcher with `vp hooks status`, `vp hooks disable`, and `vp hooks enable`. See the [Commit hooks guide](/guide/commit-hooks).
+After create, manage the dispatcher with `vp hooks status`, `vp hooks disable`, and `vp hooks enable`. See the [Commit Hooks](/guide/commit-hooks).
 
 ### Dependency build scripts
 

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.
 
+The `lts` alias selects the newest LTS release. The `latest` alias selects the newest stable release, LTS or not, and skips pre-releases such as `27.0.0-alpha.0.0.0`. To use a pre-release, specify its exact version.
+
 `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