@mawesome/npm-vm 0.0.0-stage → 0.1.0

package/dist/internal.js

@@ -0,0 +1,2706 @@
+import { A as newToken, B as lockedMessage, C as verifySignatures, D as parseSpecs, E as SpecError, F as shellBinary, G as EXIT, H as redactUrls, I as findOwnNpm, K as NpmVmError, L as abiMessage, M as ownerRecord, N as isLive, O as parseVersionSpec, P as powershellPath, R as changedMessage, S as safeExtract, T as sriHex, U as restartMessage, V as provenanceMessage, W as transportMessage, _ as withSharingRetry, a as createInstaller, b as fileDigests, c as newWorkDir, d as resolveDirs, f as lastUsed, g as removeWithRetry, h as atomicWrite, i as createContext, j as ownerLive, k as listLeases, l as transportUsable, m as atomicRename, n as resolveNpmWith, o as loadKeyring, p as pruneCache, q as isNpmVmError, r as findProject, s as Transport, t as resolveNpm, u as loadNpmConfig, v as listEntries, w as selectCandidate, x as readVerified, y as stagingDir, z as dirPermsMessage } from "./src-NhNG2mnQ.js";
+import { accessSync, chmodSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, posix, win32 } from "node:path";
+import { createHash } from "node:crypto";
+import semver from "semver";
+import { homedir } from "node:os";
+import { execFile, execFileSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline/promises";
+import { Agent, ProxyAgent, request } from "undici";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+const SHIM_DIR = "shims";
+const LAUNCHERS_DIR = "launchers";
+const SELECTORS = [
+	"npm",
+	"npx",
+	"npm-vm"
+];
+const UNSAFE = /[\n\r"'`$%!]/;
+/** Refuses a home no quoting makes safe in all four shells and cmd (spec SET-2, M-HOMEPATH). */
+function assertSafeHome(home) {
+	const match = UNSAFE.exec(home);
+	if (match !== null) {
+		const shown = match[0] === "\n" || match[0] === "\r" ? "a line break" : `"${match[0]}"`;
+		throw new NpmVmError("M-HOMEPATH", EXIT.usage, `The npm-vm home ${home} contains ${shown}, which cannot be quoted safely in every shell. Set NPM_VM_HOME to a plain path and run setup again.`);
+	}
+}
+function selectorOf(name) {
+	return name === "npm-vm" ? "cli" : name;
+}
+/**
+* The launcher templates shipped beside this code: `src/launchers/` from source, `dist/runtime/launchers/`
+* from the bin, and `launchers/` beside an installed `runtime.cjs`.
+*/
+function templatesDir() {
+	const here = import.meta.dirname;
+	for (const candidate of [
+		join(here, LAUNCHERS_DIR),
+		join(here, "..", LAUNCHERS_DIR),
+		join(here, "runtime", LAUNCHERS_DIR)
+	]) if (existsSync(join(candidate, "sh.tmpl"))) return candidate;
+	throw new Error(`npm-vm launcher templates not found near ${here}`);
+}
+function readTemplate(dir, kind) {
+	const text = readFileSync(join(dir, `${kind}.tmpl`), "utf8");
+	return kind === "sh" ? text.replace(/\r\n/g, "\n") : text;
+}
+/** Fills one launcher template; the ABI comes from the launcher generation the templates belong to. */
+function renderTemplate(template, values) {
+	return template.replace(/\{\{ABI\}\}/g, String(values.abi)).replace(/\{\{BOOTSTRAP\}\}/g, values.bootstrap).replace(/\{\{SELECTOR\}\}/g, values.selector);
+}
+/** The POSIX shim: `sh` on every OS, so Git Bash and MSYS on Windows get one too. */
+function posixShim(home, name, templates = templatesDir(), abi = 1, platform = process.platform) {
+	const { join: joinPath } = platform === "win32" ? win32 : posix;
+	return renderTemplate(readTemplate(templates, "sh"), {
+		bootstrap: joinPath(home, "bootstrap.cjs"),
+		selector: selectorOf(name),
+		abi
+	});
+}
+/**
+* The cmd shim resolves node.exe through PATH only (`%~$PATH:i`): cmd would otherwise run a `node.exe`
+* committed to the current directory. One command line, so `%*` keeps its quoting.
+*/
+function cmdShim(home, name, templates = templatesDir(), abi = 1) {
+	return renderTemplate(readTemplate(templates, "cmd"), {
+		bootstrap: win32.join(home, "bootstrap.cjs"),
+		selector: selectorOf(name),
+		abi
+	});
+}
+/** PowerShell never searches the current directory for a command, so `Get-Command` is enough. */
+function powershellShim(home, name, templates = templatesDir(), abi = 1) {
+	return renderTemplate(readTemplate(templates, "ps1"), {
+		bootstrap: win32.join(home, "bootstrap.cjs"),
+		selector: selectorOf(name),
+		abi
+	});
+}
+/** Every shim file for the platform (spec SET-2); `.ps1` files are included only when the policy allows them (WIN-2). */
+function renderShims(home, platform, options = {}) {
+	assertSafeHome(home);
+	const templates = options.templates ?? templatesDir();
+	const abi = options.abi ?? 1;
+	const files = [];
+	for (const name of SELECTORS) {
+		files.push({
+			name,
+			content: posixShim(home, name, templates, abi, platform),
+			mode: 493
+		});
+		if (platform === "win32") {
+			files.push({
+				name: `${name}.cmd`,
+				content: cmdShim(home, name, templates, abi),
+				mode: 420
+			});
+			if (options.powershell !== false) files.push({
+				name: `${name}.ps1`,
+				content: powershellShim(home, name, templates, abi),
+				mode: 420
+			});
+		}
+	}
+	return files;
+}
+/** The ABI a shim or bootstrap file declares, or null when the file is not ours. */
+function shimAbi(content) {
+	const match = /npm-vm launcher abi=(\d+)|LAUNCHER_ABI = (\d+)/.exec(content);
+	return match === null ? null : Number(match[1] ?? match[2]);
+}
+function shimDir(home) {
+	return join(home, SHIM_DIR);
+}
+/** Our `.ps1` shims left from a permissive policy; PowerShell would still prefer them over `.cmd` (WIN-2). */
+function stalePowershellShims(home) {
+	return SELECTORS.map((name) => join(shimDir(home), `${name}.ps1`)).filter((file) => {
+		try {
+			return shimAbi(readFileSync(file, "utf8")) !== null;
+		} catch {
+			return false;
+		}
+	});
+}
+//#endregion
+//#region src/setup/shell.ts
+const SHELLS = [
+	"zsh",
+	"bash",
+	"fish",
+	"powershell"
+];
+function isShell(value) {
+	return SHELLS.includes(value);
+}
+const BLOCK_START = "# >>> npm-vm >>>";
+const BLOCK_END = "# <<< npm-vm <<<";
+/** Escapes a path for use inside a bash or zsh `${var//pattern/}` pattern, where `/` and glob characters are special. */
+function patternOf(path) {
+	return path.replace(/[\\/*?[\]]/g, (char) => `\\${char}`);
+}
+/** Adds `shims/` to the front of PATH when absent; sourcing it twice changes nothing (spec SH-1). */
+function shimsFor(shell, home) {
+	if (shell === "powershell") return win32.join(home, SHIM_DIR);
+	return process.platform === "win32" ? shimDir(home).replace(/\\/g, "/") : shimDir(home);
+}
+function pathSnippet(shell, home) {
+	assertSafeHome(home);
+	const shims = shimsFor(shell, home);
+	switch (shell) {
+		case "zsh":
+		case "bash": return [
+			`case ":$PATH:" in`,
+			`  *":${shims}:"*) ;;`,
+			`  *) export PATH="${shims}:$PATH" ;;`,
+			"esac",
+			""
+		].join("\n");
+		case "fish": return [
+			`if not contains -- "${shims}" $PATH`,
+			`    set -gx PATH "${shims}" $PATH`,
+			"end",
+			""
+		].join("\n");
+		case "powershell": return [
+			`if (($env:Path -split [IO.Path]::PathSeparator) -notcontains '${shims}') {`,
+			`    $env:Path = '${shims}' + [IO.Path]::PathSeparator + $env:Path`,
+			"}",
+			""
+		].join("\n");
+	}
+}
+/**
+* The prompt hook (spec SH-2): moves `shims/` back to the front when something prepended over it,
+* with parameter expansion only, keeping `$?` and chaining whatever hook was there.
+*/
+function hookSnippet(shell, home) {
+	assertSafeHome(home);
+	const shims = shimsFor(shell, home);
+	switch (shell) {
+		case "zsh": return [
+			"_npm_vm_guard() {",
+			"  local ret=$?",
+			`  if [[ "$path[1]" != "${shims}" ]]; then`,
+			`    path=("${shims}" \${path:#${shims}})`,
+			"  fi",
+			"  return $ret",
+			"}",
+			"if [[ -z \"${precmd_functions[(r)_npm_vm_guard]}\" ]]; then",
+			"  precmd_functions+=(_npm_vm_guard)",
+			"fi",
+			""
+		].join("\n");
+		case "bash": return [
+			"_npm_vm_guard() {",
+			"  local ret=$?",
+			`  case ":$PATH:" in`,
+			`    ":${shims}:"*) ;;`,
+			"    *)",
+			"      local rest=\":$PATH:\"",
+			`      rest="\${rest//:${patternOf(shims)}:/:}"`,
+			"      rest=\"${rest#:}\"",
+			"      rest=\"${rest%:}\"",
+			`      PATH="${shims}\${rest:+:$rest}"`,
+			"      ;;",
+			"  esac",
+			"  return $ret",
+			"}",
+			"case \";${PROMPT_COMMAND};\" in",
+			"  *\";_npm_vm_guard;\"*) ;;",
+			"  *) PROMPT_COMMAND=\"_npm_vm_guard${PROMPT_COMMAND:+;$PROMPT_COMMAND}\" ;;",
+			"esac",
+			""
+		].join("\n");
+		case "fish": return [
+			"if status is-interactive",
+			"    function _npm_vm_guard --on-event fish_prompt",
+			`        if test "$PATH[1]" != "${shims}"`,
+			`            set -l found (contains -i -- "${shims}" $PATH)`,
+			"            if test -n \"$found\"",
+			"                set -e PATH[$found]",
+			"            end",
+			`            set -gx PATH "${shims}" $PATH`,
+			"        end",
+			"    end",
+			"end",
+			""
+		].join("\n");
+		case "powershell": return [
+			"if (-not (Test-Path Function:\\global:_npm_vm_original_prompt)) {",
+			"    $prev = Get-Item Function:\\prompt -ErrorAction SilentlyContinue",
+			"    if ($prev) { Set-Item Function:\\global:_npm_vm_original_prompt $prev.ScriptBlock }",
+			"    else { function global:_npm_vm_original_prompt { \"PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) \" } }",
+			"    function global:prompt {",
+			"        $ok = $?",
+			"        $exit = $global:LASTEXITCODE",
+			`        $shims = '${shims}'`,
+			"        $parts = @($env:Path -split [IO.Path]::PathSeparator)",
+			"        if ($parts.Length -eq 0 -or $parts[0] -ne $shims) {",
+			"            $env:Path = (@($shims) + @($parts | Where-Object { $_ -ne $shims })) -join [IO.Path]::PathSeparator",
+			"        }",
+			"        $out = & $function:global:_npm_vm_original_prompt",
+			"        $global:LASTEXITCODE = $exit",
+			"        $out",
+			"        if (-not $ok) { Write-Error 'npm-vm: preserving $?' -ErrorAction SilentlyContinue }",
+			"    }",
+			"}",
+			""
+		].join("\n");
+	}
+}
+/** Both snippets inside the marked block `setup` writes and `uninstall` removes (spec SH-4). */
+function profileBlock(shell, home, parts) {
+	const body = [parts.path ? pathSnippet(shell, home) : "", parts.hook ? hookSnippet(shell, home) : ""].filter((text) => text !== "").join("");
+	return `${BLOCK_START}\n${body}${BLOCK_END}\n`;
+}
+//#endregion
+//#region src/state/meta.ts
+function sha256(content) {
+	return createHash("sha256").update(content).digest("hex");
+}
+function isUtf8(content) {
+	return !content.includes(0) && Buffer.from(content.toString("utf8"), "utf8").equals(content);
+}
+function lineEndingsOf(text) {
+	const crlf = (text.match(/\r\n/g) ?? []).length;
+	const lf = (text.match(/\n/g) ?? []).length - crlf;
+	if (crlf === 0 && lf === 0) return "none";
+	if (crlf > 0 && lf > 0) return "mixed";
+	return crlf > 0 ? "crlf" : "lf";
+}
+const MISSING = {
+	type: "missing",
+	mode: 0,
+	sha256: null,
+	encoding: null,
+	lineEndings: null,
+	symlinkTarget: null
+};
+/** Captures `path` without following symlinks; a missing path is a valid state, not an error. */
+function captureMeta(path) {
+	let stat;
+	try {
+		stat = lstatSync(path);
+	} catch {
+		return MISSING;
+	}
+	const mode = process.platform === "win32" ? 0 : stat.mode & 4095;
+	if (stat.isSymbolicLink()) return {
+		type: "symlink",
+		mode,
+		sha256: null,
+		encoding: null,
+		lineEndings: null,
+		symlinkTarget: readlinkSync(path)
+	};
+	if (stat.isDirectory()) return {
+		type: "directory",
+		mode,
+		sha256: null,
+		encoding: null,
+		lineEndings: null,
+		symlinkTarget: null
+	};
+	if (!stat.isFile()) return {
+		type: "other",
+		mode,
+		sha256: null,
+		encoding: null,
+		lineEndings: null,
+		symlinkTarget: null
+	};
+	const content = readFileSync(path);
+	const utf8 = isUtf8(content);
+	return {
+		type: "file",
+		mode,
+		sha256: sha256(content),
+		encoding: utf8 ? "utf8" : "binary",
+		lineEndings: utf8 ? lineEndingsOf(content.toString("utf8")) : null,
+		symlinkTarget: null
+	};
+}
+/** Whether the path still holds exactly what `meta` recorded (spec MUT-5): same type, same bytes or link target. */
+function metaMatches(path, meta) {
+	const now = captureMeta(path);
+	return now.type === meta.type && now.sha256 === meta.sha256 && now.symlinkTarget === meta.symlinkTarget;
+}
+//#endregion
+//#region src/state/journal.ts
+function journalPath(journalDir, id) {
+	return join(journalDir, `${id}.json`);
+}
+function readJournal(file) {
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		return typeof parsed.id === "string" && typeof parsed.target === "string" ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+function listJournals(journalDir) {
+	let names;
+	try {
+		names = readdirSync(journalDir);
+	} catch {
+		return [];
+	}
+	return names.filter((name) => name.endsWith(".json")).map((name) => readJournal(join(journalDir, name))).filter((journal) => journal !== null);
+}
+/**
+* Applies one file change under a journal: backup and staged copy first, the journal, then the write.
+* The journal and its sidecars disappear only after the target holds the intended bytes.
+*/
+function mutateFile(journalDir, kind, owner, target, content, mode = 420) {
+	mkdirSync(journalDir, {
+		recursive: true,
+		mode: 448
+	});
+	const id = `${kind}-${newToken()}`;
+	const original = captureMeta(target);
+	let backup = null;
+	if (original.type === "file") {
+		backup = join(journalDir, `${id}.bak`);
+		copyFileSync(target, backup);
+	}
+	let staged = null;
+	if (content !== null) {
+		staged = join(journalDir, `${id}.new`);
+		atomicWrite(staged, content, 384);
+	}
+	const journal = {
+		id,
+		kind,
+		owner,
+		target,
+		original,
+		intended: content === null ? null : sha256(content),
+		staged,
+		backup,
+		mode,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	atomicWrite(journalPath(journalDir, id), JSON.stringify(journal), 384);
+	apply(journal, content);
+	discard(journalDir, journal);
+}
+function apply(journal, content) {
+	if (content === null) {
+		withSharingRetry(() => {
+			if (existsSync(journal.target)) unlinkSync(journal.target);
+		});
+		return;
+	}
+	atomicWrite(journal.target, content, journal.mode);
+}
+function discard(journalDir, journal) {
+	for (const sidecar of [journal.backup, journal.staged]) if (sidecar !== null) rmSync(sidecar, { force: true });
+	rmSync(journalPath(journalDir, journal.id), { force: true });
+}
+function targetSha(target) {
+	const meta = captureMeta(target);
+	return meta.type === "file" ? meta.sha256 : null;
+}
+/**
+* Finishes one journal (spec MUT-2): a target already at the intended bytes is done; one still at the
+* original is replayed from the staged copy; anything else is left alone and reported as changed (MUT-5).
+*/
+function recoverJournal(journalDir, journal, report) {
+	const current = targetSha(journal.target);
+	const exists = captureMeta(journal.target).type !== "missing";
+	if (journal.intended === null ? !exists : current === journal.intended) {
+		discard(journalDir, journal);
+		report.finished.push(journal.id);
+		return;
+	}
+	if (metaMatches(journal.target, journal.original)) {
+		if (journal.intended === null) {
+			apply(journal, null);
+			report.replayed.push(journal.id);
+		} else if (journal.staged !== null && existsSync(journal.staged) && sha256(readFileSync(journal.staged)) === journal.intended) {
+			apply(journal, readFileSync(journal.staged));
+			report.replayed.push(journal.id);
+		} else report.rolledBack.push(journal.id);
+		discard(journalDir, journal);
+		return;
+	}
+	report.changed.push(journal.target);
+	discard(journalDir, journal);
+}
+/** Recovers every journal whose owner is dead on this machine; foreign and live ones are skipped. */
+function recoverDeadJournals(journalDir, machineId, kinds) {
+	const report = {
+		finished: [],
+		replayed: [],
+		rolledBack: [],
+		changed: [],
+		skipped: []
+	};
+	for (const journal of listJournals(journalDir)) {
+		if (kinds !== void 0 && !kinds.includes(journal.kind)) continue;
+		if (journal.owner.machineId !== machineId || isLive(journal.owner)) {
+			report.skipped.push(journal.id);
+			continue;
+		}
+		recoverJournal(journalDir, journal, report);
+	}
+	return report;
+}
+/** Recovers one journal the operator vouched for, whatever machine owns it (the `recover` command). */
+function recoverForeignJournal(journalDir, id, confirmedMachineId) {
+	const report = {
+		finished: [],
+		replayed: [],
+		rolledBack: [],
+		changed: [],
+		skipped: []
+	};
+	const journal = readJournal(journalPath(journalDir, id));
+	if (journal === null) throw new Error(`no journal ${id} in ${journalDir}`);
+	if (journal.owner.machineId !== confirmedMachineId) throw new Error(`journal ${id} belongs to machine ${journal.owner.machineId}, not ${confirmedMachineId}`);
+	recoverJournal(journalDir, journal, report);
+	return report;
+}
+//#endregion
+//#region src/state/lock.ts
+const LOCK_FILE = "lock";
+const WAIT_LIMIT_MS = 1e4;
+function lockPath(stateDir) {
+	return join(stateDir, LOCK_FILE);
+}
+function readLock(stateDir) {
+	try {
+		const parsed = JSON.parse(readFileSync(lockPath(stateDir), "utf8"));
+		if (typeof parsed.pid !== "number" || typeof parsed.token !== "string") return null;
+		return {
+			pid: parsed.pid,
+			start: typeof parsed.start === "string" ? parsed.start : null,
+			host: typeof parsed.host === "string" ? parsed.host : "?",
+			machineId: typeof parsed.machineId === "string" ? parsed.machineId : "?",
+			createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : "",
+			token: parsed.token
+		};
+	} catch {
+		return null;
+	}
+}
+/** Whether the lock owner can be shown to be dead: only on this machine, and only by PROC-1. */
+function lockOwnerLive(record, machineId) {
+	if (record === null) return true;
+	if (record.machineId !== machineId) return true;
+	return isLive(record);
+}
+function tryCreate(path, record) {
+	try {
+		writeFileSync(path, JSON.stringify(record), {
+			flag: "wx",
+			mode: 384
+		});
+	} catch (error) {
+		if (error.code === "EEXIST") return false;
+		rmSync(path, { force: true });
+		throw error;
+	}
+	return true;
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Takes the exclusive lock (spec MUT-1): created with O_EXCL, released only by its owner, never reclaimed.
+* Waits with backoff for up to 10 s, then fails with M-LOCKED naming the file and whether the owner is live.
+*/
+async function acquireLock(stateDir, owner, options = {}) {
+	mkdirSync(stateDir, {
+		recursive: true,
+		mode: 448
+	});
+	const path = lockPath(stateDir);
+	const record = {
+		...owner,
+		token: newToken()
+	};
+	const deadline = Date.now() + (options.waitMs ?? WAIT_LIMIT_MS);
+	let delay = 50;
+	for (;;) {
+		if (tryCreate(path, record)) return {
+			path,
+			release() {
+				if (readLock(stateDir)?.token === record.token) rmSync(path, { force: true });
+			}
+		};
+		if (Date.now() + delay > deadline) {
+			const holder = readLock(stateDir);
+			const foreign = holder !== null && holder.machineId !== owner.machineId;
+			const live = lockOwnerLive(holder, owner.machineId);
+			throw new NpmVmError("M-LOCKED", EXIT.problems, lockedMessage(path, holder, live, foreign));
+		}
+		await sleep(delay);
+		delay = Math.min(delay * 2, 1e3);
+	}
+}
+//#endregion
+//#region src/commands/cache.ts
+const DAY_MS = 864e5;
+/** `install [<spec>]`: fetches and verifies the project's npm, or the given spec, into the cache. */
+async function install(context, spec, cwd = process.cwd()) {
+	const env = spec === void 0 ? context.env : {
+		...context.env,
+		NPM_VM_VERSION: spec
+	};
+	const installer = createInstaller(createContext(env, context.dirs.home));
+	const result = await resolveNpmWith([], cwd, { env }, installer);
+	if (result.selection === null) {
+		context.io.out(context.json ? JSON.stringify(result) : `Node's own npm ${result.version} satisfies the requirement; nothing to download.`);
+		return EXIT.ok;
+	}
+	const ensured = await installer.ensure(result.selection);
+	ensured.lease.release();
+	context.io.out(context.json ? JSON.stringify({
+		...result,
+		entryPath: ensured.entryPath
+	}) : `npm ${result.version} is ready in ${ensured.entryPath}`);
+	return EXIT.ok;
+}
+function cacheList(context) {
+	const entries = listEntries(context.dirs.cache).map((entry) => {
+		const used = lastUsed(entry.entryPath);
+		return {
+			version: entry.version,
+			integrity: entry.integrity,
+			path: entry.entryPath,
+			lastUsed: used === null ? null : new Date(used).toISOString(),
+			liveLeases: listLeases(entry.entryPath).filter((lease) => ownerLive(lease)).length,
+			verifiedAt: readVerified(entry.entryPath)?.verifiedAt ?? ""
+		};
+	});
+	if (context.json) context.io.out(JSON.stringify({
+		cache: context.dirs.cache,
+		entries
+	}, null, 2));
+	else {
+		const lines = [`${context.dirs.cache}`];
+		for (const entry of entries) lines.push(`  npm ${entry.version}  ${entry.path}  last used ${entry.lastUsed ?? "never"}${entry.liveLeases > 0 ? `  in use by ${entry.liveLeases}` : ""}`);
+		if (entries.length === 0) lines.push("  (empty)");
+		context.io.out(lines.join("\n"));
+	}
+	return EXIT.ok;
+}
+async function cachePrune(context, olderThanDays = 90) {
+	if (!Number.isFinite(olderThanDays) || olderThanDays < 0) throw new NpmVmError("M-NOMATCH", EXIT.usage, "--older-than needs a non-negative number of days.");
+	const lock = await acquireLock(context.dirs.state, context.owner);
+	try {
+		recoverDeadJournals(context.dirs.journal, context.dirs.machine.id);
+		const cacheLock = await acquireLock(context.dirs.cache, context.owner);
+		let report;
+		try {
+			report = pruneCache(context.dirs.cache, context.owner, { maxAgeMs: olderThanDays * DAY_MS });
+		} finally {
+			cacheLock.release();
+		}
+		context.io.out(context.json ? JSON.stringify(report, null, 2) : `Removed ${report.removed.length}, kept ${report.kept.length}, skipped ${report.skipped.length} (in use).`);
+	} finally {
+		lock.release();
+	}
+	return EXIT.ok;
+}
+/** `recover --journal <id> --confirm-dead-machine <machine-id>` (spec PROC-1, CLI). */
+async function recover(context, journalId, confirmedMachine) {
+	const journal = listJournals(context.dirs.journal).find((entry) => entry.id === journalId);
+	if (journal === void 0) throw new NpmVmError("M-NOMATCH", EXIT.usage, `No journal ${journalId} under ${context.dirs.journal}.`);
+	if (journal.owner.machineId !== confirmedMachine) throw new NpmVmError("M-NOMATCH", EXIT.usage, `Journal ${journalId} belongs to machine ${journal.owner.machineId}, not ${confirmedMachine}.`);
+	if (journal.owner.machineId === context.dirs.machine.id && isLive(journal.owner)) throw new NpmVmError("M-LOCKED", EXIT.problems, `Journal ${journalId} belongs to PID ${journal.owner.pid} on this machine, which is still running.`);
+	const lock = await acquireLock(context.dirs.state, context.owner);
+	try {
+		const report = recoverForeignJournal(context.dirs.journal, journalId, confirmedMachine);
+		context.io.out(context.json ? JSON.stringify(report) : `Recovered ${journalId}: ${describeReport(report)}`);
+	} finally {
+		lock.release();
+	}
+	return EXIT.ok;
+}
+function describeReport(report) {
+	if (report.replayed.length > 0) return "replayed";
+	if (report.rolledBack.length > 0) return "rolled back";
+	if (report.changed.length > 0) return "target changed since, left untouched";
+	return "already finished";
+}
+//#endregion
+//#region src/commands/context.ts
+function terminalIo() {
+	const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+	return {
+		out: (text) => process.stdout.write(`${text}\n`),
+		err: (text) => process.stderr.write(`${text}\n`),
+		interactive,
+		async confirm(question) {
+			if (!interactive) return false;
+			const rl = createInterface({
+				input: process.stdin,
+				output: process.stdout
+			});
+			try {
+				const answer = await rl.question(`${question} [y/N] `);
+				return /^y(es)?$/i.test(answer.trim());
+			} finally {
+				rl.close();
+			}
+		}
+	};
+}
+function createCommandContext(options) {
+	const env = options.env ?? process.env;
+	const dirs = resolveDirs(env, options.home);
+	return {
+		dirs,
+		env,
+		platform: process.platform,
+		owner: ownerRecord(dirs.machine.id),
+		io: options.io ?? terminalIo(),
+		json: options.json ?? false,
+		version: options.version
+	};
+}
+//#endregion
+//#region src/setup/link.ts
+const ORIGINAL_SUFFIX = ".npm-vm-original";
+const LINKS_FILE = "links.json";
+function versionsUnder(dir) {
+	try {
+		return readdirSync(dir).filter((name) => /^v?\d+\.\d+\.\d+$/.test(name));
+	} catch {
+		return [];
+	}
+}
+function fnmDir(env, platform, home) {
+	if (env["FNM_DIR"]) return env["FNM_DIR"];
+	if (platform === "win32") return join(env["APPDATA"] ?? join(home, "AppData", "Roaming"), "fnm");
+	if (platform === "darwin") return join(home, "Library", "Application Support", "fnm");
+	return join(env["XDG_DATA_HOME"] || join(home, ".local", "share"), "fnm");
+}
+/** The root nvm-windows keeps its versions in, from its settings.txt (spec LNK-1). */
+function nvmWindowsRoot(env) {
+	const nvmHome = env["NVM_HOME"];
+	if (!nvmHome) return null;
+	try {
+		const settings = readFileSync(join(nvmHome, "settings.txt"), "utf8");
+		return /^root:\s*(.+)$/m.exec(settings)?.[1]?.trim() ?? nvmHome;
+	} catch {
+		return nvmHome;
+	}
+}
+/** Windows paths resolved through junctions and compared without case, so one install is never linked twice (LNK-4). */
+function installKey(binDir, platform) {
+	let real = binDir;
+	try {
+		real = realpathSync(binDir);
+	} catch {}
+	return platform === "win32" ? real.toLowerCase() : real;
+}
+function findNodeInstalls(env = process.env, platform = process.platform, home = env["HOME"] || homedir()) {
+	const installs = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = (install) => {
+		const key = installKey(install.binDir, platform);
+		if (!seen.has(key) && existsSync(install.binDir)) {
+			seen.add(key);
+			installs.push(install);
+		}
+	};
+	const nvmDir = env["NVM_DIR"] || join(home, ".nvm");
+	for (const version of versionsUnder(join(nvmDir, "versions", "node"))) add({
+		manager: "nvm",
+		version: version.replace(/^v/, ""),
+		binDir: join(nvmDir, "versions", "node", version, "bin")
+	});
+	const fnm = join(fnmDir(env, platform, home), "node-versions");
+	for (const version of versionsUnder(fnm)) {
+		const installation = join(fnm, version, "installation");
+		add({
+			manager: "fnm",
+			version: version.replace(/^v/, ""),
+			binDir: platform === "win32" ? installation : join(installation, "bin")
+		});
+	}
+	if (platform === "win32") {
+		const root = nvmWindowsRoot(env);
+		if (root !== null) for (const version of versionsUnder(root)) add({
+			manager: "nvm-windows",
+			version: version.replace(/^v/, ""),
+			binDir: join(root, version)
+		});
+	}
+	return installs;
+}
+/** The files `--link` replaces in one install; blocked `.ps1` files are moved aside so `.cmd` wins. */
+function linkTargets(home, platform, powershell) {
+	const targets = [];
+	for (const name of ["npm", "npx"]) {
+		targets.push({
+			name,
+			content: posixShim(home, name),
+			mode: 493
+		});
+		if (platform === "win32") {
+			targets.push({
+				name: `${name}.cmd`,
+				content: cmdShim(home, name),
+				mode: 420
+			});
+			targets.push({
+				name: `${name}.ps1`,
+				content: powershell ? powershellShim(home, name) : null,
+				mode: 420
+			});
+		}
+	}
+	return targets;
+}
+/** Keeps a copy of the original beside the target; a symlink is copied as a symlink. */
+function preserveOriginal(path, originalPath, meta) {
+	if (meta.type === "symlink") symlinkSync(readlinkSync(path), originalPath);
+	else copyFileSync(path, originalPath);
+}
+/** Puts the preserved original back in place of whatever is (or is not) at the target. */
+function restoreOriginal(dirs, owner, entry) {
+	const originalPath = entry.originalPath;
+	if (entry.original.type === "symlink") {
+		mutateFile(dirs.journal, "link", owner, entry.target, null);
+		withSharingRetry(() => renameSync(originalPath, entry.target));
+		return;
+	}
+	mutateFile(dirs.journal, "link", owner, entry.target, readFileSync(originalPath), entry.original.mode || 493);
+	rmSync(originalPath, { force: true });
+}
+/**
+* Replaces one entry point with a shim (spec LNK-2, LNK-3). The original is copied beside the target and
+* recorded before the journaled write, so a crash at any step leaves either a restorable original or the shim.
+* A file matching neither our shim nor the recorded original is reported and left alone.
+*/
+function linkOne(dirs, owner, binDir, target) {
+	const path = join(binDir, target.name);
+	const originalPath = `${path}${ORIGINAL_SUFFIX}`;
+	const known = readLinks(dirs).entries.find((entry) => entry.target === path);
+	let current = captureMeta(path);
+	if (current.type === "missing" && known !== void 0 && known.shim.type !== "missing" && known.originalPath !== null && existsSync(known.originalPath)) {
+		restoreOriginal(dirs, owner, known);
+		forget$1(dirs, known);
+		current = captureMeta(path);
+	}
+	if (target.content === null) return moveAside(dirs, owner, binDir, target.name, known);
+	if (current.type === "missing" && known !== void 0 && known.shim.type === "missing" && known.originalPath !== null && metaMatches(known.originalPath, known.original)) {
+		mutateFile(dirs.journal, "link", owner, path, Buffer.from(target.content, "utf8"), target.mode);
+		record(dirs, {
+			...known,
+			shim: captureMeta(path),
+			linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return {
+			target: path,
+			outcome: "linked"
+		};
+	}
+	if (current.type === "missing") return {
+		target: path,
+		outcome: "missing"
+	};
+	if (current.type === "file" && readFileSync(path, "utf8") === target.content) {
+		if (known === void 0) record(dirs, {
+			binDir,
+			name: target.name,
+			target: path,
+			originalPath: existsSync(originalPath) ? originalPath : null,
+			original: captureMeta(originalPath),
+			shim: current,
+			linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		else if (known.shim.type === "missing") record(dirs, {
+			...known,
+			shim: current,
+			linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return {
+			target: path,
+			outcome: "already"
+		};
+	}
+	if (known !== void 0 && metaMatches(path, known.shim)) {
+		mutateFile(dirs.journal, "link", owner, path, Buffer.from(target.content, "utf8"), target.mode);
+		record(dirs, {
+			...known,
+			shim: captureMeta(path),
+			linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return {
+			target: path,
+			outcome: "linked"
+		};
+	}
+	if (known !== void 0 && !metaMatches(path, known.original)) return {
+		target: path,
+		outcome: "foreign",
+		detail: "changed since npm-vm linked it"
+	};
+	if (existsSync(originalPath) && !metaMatches(originalPath, current)) return {
+		target: path,
+		outcome: "foreign",
+		detail: `${originalPath} already exists`
+	};
+	try {
+		if (!existsSync(originalPath)) preserveOriginal(path, originalPath, current);
+	} catch (error) {
+		return {
+			target: path,
+			outcome: "unwritable",
+			detail: error.message
+		};
+	}
+	const entry = {
+		binDir,
+		name: target.name,
+		target: path,
+		originalPath,
+		original: current,
+		shim: MISSING,
+		linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	record(dirs, entry);
+	try {
+		mutateFile(dirs.journal, "link", owner, path, Buffer.from(target.content, "utf8"), target.mode);
+	} catch (error) {
+		return {
+			target: path,
+			outcome: "unwritable",
+			detail: error.message
+		};
+	}
+	record(dirs, {
+		...entry,
+		shim: captureMeta(path)
+	});
+	return {
+		target: path,
+		outcome: "linked"
+	};
+}
+/** Moves a file aside without a replacement, for Node's `.ps1` entry points when scripts are blocked. */
+function moveAside(dirs, owner, binDir, name, known) {
+	const path = join(binDir, name);
+	const originalPath = `${path}${ORIGINAL_SUFFIX}`;
+	const current = captureMeta(path);
+	if (known !== void 0 && known.shim.type !== "missing" && metaMatches(path, known.shim)) {
+		mutateFile(dirs.journal, "link", owner, path, null);
+		record(dirs, {
+			...known,
+			shim: MISSING,
+			linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return {
+			target: path,
+			outcome: "linked"
+		};
+	}
+	if (current.type === "missing") {
+		if (known === void 0 && existsSync(originalPath)) {
+			record(dirs, {
+				binDir,
+				name,
+				target: path,
+				originalPath,
+				original: captureMeta(originalPath),
+				shim: MISSING,
+				linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			return {
+				target: path,
+				outcome: "already"
+			};
+		}
+		return {
+			target: path,
+			outcome: known !== void 0 && existsSync(originalPath) ? "already" : "missing"
+		};
+	}
+	if (known !== void 0 && !metaMatches(path, known.original)) return {
+		target: path,
+		outcome: "foreign",
+		detail: "changed since npm-vm linked it"
+	};
+	if (existsSync(originalPath) && !metaMatches(originalPath, current)) return {
+		target: path,
+		outcome: "foreign",
+		detail: `${originalPath} already exists`
+	};
+	try {
+		withSharingRetry(() => renameSync(path, originalPath));
+	} catch (error) {
+		return {
+			target: path,
+			outcome: "unwritable",
+			detail: error.message
+		};
+	}
+	record(dirs, {
+		binDir,
+		name,
+		target: path,
+		originalPath,
+		original: current,
+		shim: MISSING,
+		linkedAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	return {
+		target: path,
+		outcome: "linked"
+	};
+}
+/** Puts the original back only when the shim is still ours (spec MUT-5); a replaced file is left as is. */
+function unlinkOne(dirs, owner, entry) {
+	const current = captureMeta(entry.target);
+	const hasOriginal = entry.originalPath !== null && existsSync(entry.originalPath);
+	if (current.type === "missing") {
+		if (hasOriginal && metaMatches(entry.originalPath, entry.original)) {
+			restoreOriginal(dirs, owner, entry);
+			forget$1(dirs, entry);
+			return "restored";
+		}
+		if (hasOriginal) return "changed";
+		forget$1(dirs, entry);
+		return "missing";
+	}
+	if (entry.shim.type === "missing") return "changed";
+	if (!metaMatches(entry.target, entry.shim)) return "changed";
+	if (hasOriginal) restoreOriginal(dirs, owner, entry);
+	else mutateFile(dirs.journal, "link", owner, entry.target, null);
+	forget$1(dirs, entry);
+	return "restored";
+}
+function record(dirs, entry) {
+	const links = readLinks(dirs);
+	links.entries = [...links.entries.filter((item) => item.target !== entry.target), entry];
+	writeLinks(dirs, links);
+}
+function forget$1(dirs, entry) {
+	const links = readLinks(dirs);
+	links.entries = links.entries.filter((item) => item.target !== entry.target);
+	writeLinks(dirs, links);
+}
+function readLinks(dirs) {
+	try {
+		const parsed = JSON.parse(readFileSync(join(dirs.state, LINKS_FILE), "utf8"));
+		return Array.isArray(parsed.entries) ? parsed : {
+			version: 1,
+			entries: []
+		};
+	} catch {
+		return {
+			version: 1,
+			entries: []
+		};
+	}
+}
+function writeLinks(dirs, links) {
+	atomicWrite(join(dirs.state, LINKS_FILE), JSON.stringify(links, null, "	"), 384);
+}
+/** Whether a recorded link still holds our shim, for `doctor` (spec CLI). */
+function linkState(entry) {
+	const type = captureMeta(entry.target).type;
+	if (entry.shim.type === "missing") {
+		const preserved = entry.originalPath !== null && metaMatches(entry.originalPath, entry.original);
+		return type === "missing" ? preserved ? "intact" : "missing" : "changed";
+	}
+	if (type === "missing") return "missing";
+	return metaMatches(entry.target, entry.shim) ? "intact" : "changed";
+}
+//#endregion
+//#region src/setup/layout.ts
+const BOOTSTRAP_FILE = "bootstrap.cjs";
+const CURRENT_FILE = "current";
+const PREVIOUS_FILE = "previous";
+const MANIFEST_FILE = "manifest.json";
+const VERSIONS_DIR = "versions";
+/**
+* Where this code's runtime build lives: beside an installed `runtime.cjs`, under `dist/runtime/` for the
+* bin, or `../../dist/runtime/` when running from source. Null when nothing has been built.
+*/
+function runtimeDistDir() {
+	const here = import.meta.dirname;
+	const candidates = [
+		here,
+		join(here, "runtime"),
+		join(here, "..", "dist", "runtime"),
+		join(here, "..", "..", "dist", "runtime")
+	];
+	for (const candidate of candidates) if (existsSync(join(candidate, "runtime.cjs")) && existsSync(join(candidate, "bootstrap.cjs"))) return candidate;
+	return null;
+}
+function versionDir(home, version) {
+	return join(home, VERSIONS_DIR, version);
+}
+function copyTree(from, to, files, prefix = "") {
+	mkdirSync(to, {
+		recursive: true,
+		mode: 493
+	});
+	for (const name of readdirSync(from)) {
+		const source = join(from, name);
+		const target = join(to, name);
+		if (statSync(source).isDirectory()) copyTree(source, target, files, `${prefix}${name}/`);
+		else {
+			copyFileSync(source, target);
+			files.push(`${prefix}${name}`);
+		}
+	}
+}
+/**
+* Installs one runtime version under `versions/<version>/` atomically (spec SET-1): copied into a
+* temp dir beside it and renamed into place, so a crash never leaves a half-written version.
+*/
+function installVersion(home, version, distDir, abi) {
+	const versions = join(home, VERSIONS_DIR);
+	mkdirSync(versions, {
+		recursive: true,
+		mode: 493
+	});
+	const target = versionDir(home, version);
+	const staging = join(versions, `.${version}.${process.pid}.${Date.now()}`);
+	rmSync(staging, {
+		recursive: true,
+		force: true
+	});
+	const files = [];
+	copyTree(distDir, staging, files);
+	const manifest = {
+		version,
+		abi,
+		files: files.toSorted()
+	};
+	writeFileSync(join(staging, MANIFEST_FILE), JSON.stringify(manifest, null, "	"));
+	const replaced = join(versions, `.${version}.replaced.${process.pid}.${Date.now()}`);
+	if (existsSync(target)) atomicRename(target, replaced);
+	try {
+		atomicRename(staging, target);
+	} catch (error) {
+		if (existsSync(replaced)) atomicRename(replaced, target);
+		throw error;
+	}
+	removeWithRetry(replaced);
+	return target;
+}
+function readCurrent(home) {
+	try {
+		return readFileSync(join(home, CURRENT_FILE), "utf8").trim();
+	} catch {
+		return null;
+	}
+}
+function readPrevious(home) {
+	try {
+		return readFileSync(join(home, PREVIOUS_FILE), "utf8").trim();
+	} catch {
+		return null;
+	}
+}
+function readManifest(home, version) {
+	try {
+		return JSON.parse(readFileSync(join(versionDir(home, version), MANIFEST_FILE), "utf8"));
+	} catch {
+		return null;
+	}
+}
+/** Removes copies a crashed reinstall moved aside; the launcher only reads them while `versions/<v>` is missing. */
+function sweepReplaced(home) {
+	let names;
+	try {
+		names = readdirSync(join(home, VERSIONS_DIR));
+	} catch {
+		return;
+	}
+	for (const name of names) {
+		const match = /^\.(.+)\.replaced\./.exec(name);
+		if (match !== null && existsSync(join(home, "versions", match[1], "runtime.cjs"))) removeWithRetry(join(home, VERSIONS_DIR, name));
+	}
+}
+/** The ABI an installed runtime declares, read from its manifest. */
+function runtimeAbi(home, version) {
+	return readManifest(home, version)?.abi ?? null;
+}
+//#endregion
+//#region src/setup/profile.ts
+const PROFILES_FILE = "profiles.json";
+const BLOCK_RE = /^# >>> npm-vm >>>\n[\s\S]*?^# <<< npm-vm <<<\n?/m;
+function bashLoginFile(home) {
+	for (const name of [
+		".bash_profile",
+		".bash_login",
+		".profile"
+	]) if (existsSync(join(home, name))) return join(home, name);
+	return join(home, ".bash_profile");
+}
+/** The user profile of one PowerShell host, asked with `-NoProfile` so nothing of the user's runs (spec SEC-8). */
+function powershellProfile(host, env, platform = process.platform) {
+	const bin = host === "powershell" ? powershellPath(env) : shellBinary("powershell", env, platform);
+	if (bin === null) return null;
+	try {
+		const out = execFileSync(bin, [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			"$PROFILE.CurrentUserAllHosts"
+		], {
+			encoding: "utf8",
+			env,
+			windowsHide: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+		return out === "" ? null : out;
+	} catch {
+		return null;
+	}
+}
+/** The files to edit for `shells` (spec SH-3); PowerShell hosts that are not installed yield nothing. */
+function profileTargets(shells, env = process.env, platform = process.platform, home = env["HOME"] || homedir()) {
+	const targets = [];
+	for (const shell of shells) switch (shell) {
+		case "zsh": {
+			const zdot = env["ZDOTDIR"] || home;
+			targets.push({
+				shell,
+				file: join(zdot, ".zshenv"),
+				parts: {
+					path: true,
+					hook: false
+				}
+			});
+			targets.push({
+				shell,
+				file: join(zdot, ".zshrc"),
+				parts: {
+					path: false,
+					hook: true
+				}
+			});
+			break;
+		}
+		case "bash": {
+			targets.push({
+				shell,
+				file: join(home, ".bashrc"),
+				parts: {
+					path: true,
+					hook: true
+				}
+			});
+			const login = bashLoginFile(home);
+			if (login !== join(home, ".bashrc")) targets.push({
+				shell,
+				file: login,
+				parts: {
+					path: true,
+					hook: false
+				}
+			});
+			break;
+		}
+		case "fish": {
+			const config = env["XDG_CONFIG_HOME"] || join(home, ".config");
+			targets.push({
+				shell,
+				file: join(config, "fish", "conf.d", "npm-vm.fish"),
+				parts: {
+					path: true,
+					hook: true
+				}
+			});
+			break;
+		}
+		case "powershell": {
+			const hosts = platform === "win32" ? ["powershell", "pwsh"] : ["pwsh"];
+			for (const host of hosts) {
+				const file = powershellProfile(host, env, platform);
+				if (file !== null && !targets.some((target) => target.file === file)) targets.push({
+					shell,
+					file,
+					parts: {
+						path: true,
+						hook: true
+					}
+				});
+			}
+			break;
+		}
+	}
+	return targets;
+}
+/** Why a profile is printed instead of edited (spec SH-5), or null when editing it is fine. */
+function profileGuard(file, env = process.env, platform = process.platform) {
+	let stat;
+	try {
+		stat = lstatSync(file);
+	} catch {
+		stat = null;
+	}
+	if (stat !== null && stat.isSymbolicLink()) return "it is a symlink, so a dotfile manager probably owns it";
+	let probe = stat === null ? dirname(file) : file;
+	while (!existsSync(probe) && dirname(probe) !== probe) probe = dirname(probe);
+	try {
+		accessSync(probe, constants.W_OK);
+	} catch {
+		return "it is not writable";
+	}
+	try {
+		if (realpathSync(probe).startsWith("/nix/store")) return "it lives in the Nix store (home-manager)";
+	} catch {}
+	const chezmoi = join(env["HOME"] || homedir(), ".local", "share", "chezmoi");
+	if (existsSync(join(chezmoi, `dot_${basename(file).replace(/^\./, "")}`))) return "chezmoi manages it";
+	if (platform === "win32" && stat !== null && file.endsWith(".ps1")) {
+		if (readFileSync(file, "utf8").includes("# SIG # Begin signature block") && executionPolicy(env) === "AllSigned") return "it is signed and the execution policy is AllSigned";
+	}
+	return null;
+}
+/** The effective PowerShell execution policy, asked without a profile (spec WIN-2). */
+function executionPolicy(env = process.env) {
+	try {
+		return execFileSync(powershellPath(env), [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			"Get-ExecutionPolicy"
+		], {
+			encoding: "utf8",
+			windowsHide: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+/** The content with our block replaced or appended; a trailing newline is guaranteed before the block. */
+function withBlock(content, block) {
+	const text = content ?? "";
+	if (BLOCK_RE.test(text)) return text.replace(BLOCK_RE, block);
+	return `${text}${text === "" || text.endsWith("\n") ? "" : "\n"}${text === "" ? "" : "\n"}${block}`;
+}
+/** The content without our block and the blank line that separated it; nothing else moves. */
+function withoutBlock(content) {
+	const match = BLOCK_RE.exec(content);
+	if (match === null) return content;
+	let before = content.slice(0, match.index).replace(/\n+$/, "\n");
+	if (before === "\n") before = "";
+	const after = content.slice(match.index + match[0].length);
+	return before !== "" && after !== "" ? `${before}\n${after}` : `${before}${after}`;
+}
+function currentBlock(content) {
+	const match = BLOCK_RE.exec(content);
+	return match === null ? null : match[0];
+}
+function renderDiff(file, before, after) {
+	const oldBlock = before === null ? null : currentBlock(before);
+	const newBlock = currentBlock(after) ?? "";
+	const lines = [`--- ${file}`, `+++ ${file}`];
+	if (oldBlock !== null) lines.push(...oldBlock.trimEnd().split("\n").map((line) => `-${line}`));
+	lines.push(...newBlock.trimEnd().split("\n").map((line) => `+${line}`));
+	return `${lines.join("\n")}\n`;
+}
+/** What `setup` would write for `target`, or null when the file already holds exactly this block. */
+function planProfileEdit(target, home) {
+	const before = existsSync(target.file) ? readFileSync(target.file, "utf8") : null;
+	const after = withBlock(before, profileBlock(target.shell, home, target.parts));
+	if (before === after) return null;
+	return {
+		target,
+		before,
+		after,
+		diff: renderDiff(target.file, before, after)
+	};
+}
+function uniqueBackup(file) {
+	const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+	let candidate = `${file}.npm-vm-backup-${stamp}`;
+	let counter = 1;
+	while (existsSync(candidate)) {
+		candidate = `${file}.npm-vm-backup-${stamp}-${counter}`;
+		counter += 1;
+	}
+	return candidate;
+}
+/** Applies one consented edit under a journal and a unique backup, and records it (spec SH-4). */
+function applyProfileEdit(dirs, owner, edit) {
+	let backup = null;
+	if (edit.before !== null) {
+		backup = uniqueBackup(edit.target.file);
+		atomicWrite(backup, edit.before, 384);
+	}
+	const mode = edit.before === null ? 420 : captureMeta(edit.target.file).mode || 420;
+	mutateFile(dirs.journal, "profile", owner, edit.target.file, Buffer.from(edit.after, "utf8"), mode);
+	const record = {
+		file: edit.target.file,
+		shell: edit.target.shell,
+		parts: edit.target.parts,
+		writtenSha256: sha256(edit.after),
+		backup,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	const profiles = readProfiles(dirs);
+	profiles.entries = [...profiles.entries.filter((entry) => entry.file !== record.file), record];
+	writeProfiles(dirs, profiles);
+	return record;
+}
+/** Removes our block only when the file is still what we wrote (spec MUT-5); otherwise it is left alone. */
+function removeProfileBlock(dirs, owner, record) {
+	if (!existsSync(record.file)) {
+		forget(dirs, record);
+		return "missing";
+	}
+	const content = readFileSync(record.file, "utf8");
+	if (sha256(content) !== record.writtenSha256) return "changed";
+	const after = withoutBlock(content);
+	mutateFile(dirs.journal, "profile", owner, record.file, after.trim() === "" ? null : Buffer.from(after, "utf8"), captureMeta(record.file).mode || 420);
+	forget(dirs, record);
+	return "removed";
+}
+function forget(dirs, record) {
+	const profiles = readProfiles(dirs);
+	profiles.entries = profiles.entries.filter((entry) => entry.file !== record.file);
+	writeProfiles(dirs, profiles);
+}
+function readProfiles(dirs) {
+	try {
+		const parsed = JSON.parse(readFileSync(join(dirs.state, PROFILES_FILE), "utf8"));
+		return Array.isArray(parsed.entries) ? parsed : {
+			version: 1,
+			entries: []
+		};
+	} catch {
+		return {
+			version: 1,
+			entries: []
+		};
+	}
+}
+function writeProfiles(dirs, profiles) {
+	atomicWrite(join(dirs.state, PROFILES_FILE), JSON.stringify(profiles, null, "	"), 384);
+}
+//#endregion
+//#region src/setup/windows.ts
+function powershell(env, command) {
+	return execFileSync(powershellPath(env), [
+		"-NoProfile",
+		"-NonInteractive",
+		"-Command",
+		command
+	], {
+		encoding: "utf8",
+		env,
+		windowsHide: true,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	}).trim();
+}
+function regExe(env) {
+	return join(env["SystemRoot"] ?? "C:\\Windows", "System32", "reg.exe");
+}
+function quote(value) {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+function readUserPath(env) {
+	return powershell(env, "[Environment]::GetEnvironmentVariable('Path', 'User')");
+}
+function writeUserPath(env, value) {
+	powershell(env, `[Environment]::SetEnvironmentVariable('Path', ${quote(value)}, 'User')`);
+}
+function sameDir(a, b) {
+	return a.replace(/[\\/]+$/, "").toLowerCase() === b.replace(/[\\/]+$/, "").toLowerCase();
+}
+/** Prepends `dir` to the user PATH unless present; returns whether anything changed. */
+function addToUserPath(env, dir) {
+	const parts = readUserPath(env).split(";").filter((part) => part !== "");
+	if (parts.some((part) => sameDir(part, dir))) return false;
+	writeUserPath(env, [dir, ...parts].join(";"));
+	return true;
+}
+function removeFromUserPath(env, dir) {
+	const parts = readUserPath(env).split(";").filter((part) => part !== "");
+	const kept = parts.filter((part) => !sameDir(part, dir));
+	if (kept.length === parts.length) return false;
+	writeUserPath(env, kept.join(";"));
+	return true;
+}
+const AUTORUN_KEY = "HKCU\\Software\\Microsoft\\Command Processor";
+const AUTORUN_MARK = "npm-vm";
+function readCmdAutoRun(env) {
+	try {
+		const out = execFileSync(regExe(env), [
+			"query",
+			AUTORUN_KEY,
+			"/v",
+			"AutoRun"
+		], {
+			encoding: "utf8",
+			windowsHide: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+		return /AutoRun\s+REG_(?:EXPAND_)?SZ\s+(.*)$/m.exec(out)?.[1]?.trim() ?? null;
+	} catch {
+		return null;
+	}
+}
+/** The cmd AutoRun entry that puts shims first in every cmd session; only with `--cmd-autorun` (WIN-3). */
+function autoRunCommand(shimsDir) {
+	return `set "PATH=${shimsDir};%PATH%" & rem ${AUTORUN_MARK}`;
+}
+/** `value` without the fragment `autoRunCommand` generated, whatever home it named; the user's own commands stay. */
+function withoutAutoRunCommand(value) {
+	if (value === null) return "";
+	return value.replace(/^set "PATH=[^"]*;%PATH%" & rem npm-vm(?: & )?/, "").trim();
+}
+function setCmdAutoRun(env, shimsDir) {
+	const ours = autoRunCommand(shimsDir);
+	const kept = withoutAutoRunCommand(readCmdAutoRun(env));
+	const value = kept === "" ? ours : `${ours} & ${kept}`;
+	execFileSync(regExe(env), [
+		"add",
+		AUTORUN_KEY,
+		"/v",
+		"AutoRun",
+		"/t",
+		"REG_SZ",
+		"/d",
+		value,
+		"/f"
+	], {
+		windowsHide: true,
+		stdio: "ignore"
+	});
+}
+function clearCmdAutoRun(env) {
+	const existing = readCmdAutoRun(env);
+	if (existing === null || !existing.includes(`rem ${AUTORUN_MARK}`)) return false;
+	const rest = withoutAutoRunCommand(existing);
+	if (rest === "") execFileSync(regExe(env), [
+		"delete",
+		AUTORUN_KEY,
+		"/v",
+		"AutoRun",
+		"/f"
+	], {
+		windowsHide: true,
+		stdio: "ignore"
+	});
+	else execFileSync(regExe(env), [
+		"add",
+		AUTORUN_KEY,
+		"/v",
+		"AutoRun",
+		"/t",
+		"REG_SZ",
+		"/d",
+		rest,
+		"/f"
+	], {
+		windowsHide: true,
+		stdio: "ignore"
+	});
+	return true;
+}
+/** Whether the effective execution policy lets our unsigned `.ps1` shims run (spec WIN-2). */
+function powershellAllowsScripts(policy) {
+	return policy !== null && ![
+		"Restricted",
+		"AllSigned",
+		"Undefined"
+	].includes(policy);
+}
+/** Which `npm` each Windows context resolves first, for `doctor`. */
+function windowsWinners(env) {
+	const results = [];
+	try {
+		const out = execFileSync(join(env["SystemRoot"] ?? "C:\\Windows", "System32", "where.exe"), ["npm"], {
+			encoding: "utf8",
+			env,
+			windowsHide: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+		results.push({
+			context: "cmd",
+			path: out.split(/\r?\n/)[0] ?? null
+		});
+	} catch {
+		results.push({
+			context: "cmd",
+			path: null
+		});
+	}
+	try {
+		results.push({
+			context: "PowerShell",
+			path: powershell(env, "(Get-Command npm -All | Select-Object -First 1).Source") || null
+		});
+	} catch {
+		results.push({
+			context: "PowerShell",
+			path: null
+		});
+	}
+	return results;
+}
+//#endregion
+//#region src/commands/doctor.ts
+const PROBE_TIMEOUT_MS = 5e3;
+/** The `npm` an interactive login shell resolves, by asking that shell (its profiles decide the PATH). */
+function shellWinner(shell, env) {
+	const bin = shellBinary(shell, env);
+	if (bin === null) return null;
+	const args = shell === "fish" ? [
+		"-l",
+		"-i",
+		"-c",
+		"emit fish_prompt; command -v npm"
+	] : shell === "powershell" ? [
+		"-NoProfile",
+		"-Command",
+		"(Get-Command npm).Source"
+	] : shell === "zsh" ? [
+		"-l",
+		"-i",
+		"-c",
+		"for f in $precmd_functions; do \"$f\"; done; command -v npm"
+	] : [
+		"-l",
+		"-i",
+		"-c",
+		"eval \"$PROMPT_COMMAND\"; command -v npm"
+	];
+	try {
+		const out = execFileSync(bin, args, {
+			encoding: "utf8",
+			env,
+			timeout: PROBE_TIMEOUT_MS,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim().split("\n").pop();
+		return out === void 0 || out === "" ? null : out;
+	} catch {
+		return null;
+	}
+}
+/** A Windows path for comparison: `where` answers with the long name, the home may carry an 8.3 short name. */
+function canonical(path) {
+	try {
+		return realpathSync.native(path).toLowerCase();
+	} catch {
+		return path.toLowerCase();
+	}
+}
+/** What `command -v npm` printed: an alias or a function wins over PATH, so no PATH fix can help. */
+function winnerKind(winner) {
+	if (winner.startsWith("alias ")) return "alias";
+	return winner === "npm" ? "function" : "path";
+}
+function samePath(a, b, platform) {
+	return platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+async function collect(context) {
+	const { dirs, env, platform } = context;
+	const report = {
+		home: dirs.home,
+		version: readCurrent(dirs.home),
+		problems: [],
+		notes: []
+	};
+	const setupHint = "Run `npx --prefix ~ -y @mawesome/npm-vm setup`.";
+	const problem = (check, detail, fix) => {
+		report.problems.push({
+			check,
+			detail,
+			fix
+		});
+	};
+	if (report.version === null || readManifest(dirs.home, report.version) === null) problem("runtime", `no runtime is installed under ${dirs.home}`, setupHint);
+	else {
+		const root = join(dirs.home, BOOTSTRAP_FILE);
+		const shipped = join(versionDir(dirs.home, report.version), BOOTSTRAP_FILE);
+		if (!existsSync(root) || !readFileSync(root).equals(readFileSync(shipped))) problem("launcher", `${root} differs from the installed version's launcher`, setupHint);
+	}
+	for (const name of SELECTORS) {
+		const file = join(shimDir(dirs.home), name);
+		const abi = existsSync(file) ? shimAbi(readFileSync(file, "utf8")) : null;
+		if (abi === null) problem("shims", `${file} is missing or not an npm-vm shim`, setupHint);
+		else if (abi !== 1) problem("shims", `${file} declares launcher ABI ${abi}, this version needs 1`, setupHint);
+	}
+	if (dirs.machine.fallback) report.notes.push("The machine id falls back to the hostname; cloned machines or containers sharing this home could collide in the cache.");
+	const lock = readLock(dirs.state);
+	if (lock !== null && !lockOwnerLive(lock, dirs.machine.id)) problem("lock", `${lockPath(dirs.state)} is held by PID ${lock.pid}, which no longer runs`, `Delete ${lockPath(dirs.state)}.`);
+	for (const journal of listJournals(dirs.journal)) {
+		const foreign = journal.owner.machineId !== dirs.machine.id;
+		problem("journal", `${journal.id} (${journal.kind}) for ${journal.target} was left by ${foreign ? `another machine (${journal.owner.host})` : `PID ${journal.owner.pid}`}`, foreign ? `Confirm no npm-vm runs on ${journal.owner.host}, then run \`npm-vm recover --journal ${journal.id} --confirm-dead-machine ${journal.owner.machineId}\`.` : "Run any npm-vm command; dead owners are recovered automatically.");
+	}
+	const profiles = readProfiles(dirs);
+	for (const entry of profiles.entries) if (!existsSync(entry.file) || !readFileSync(entry.file, "utf8").includes("# >>> npm-vm >>>")) problem("profile", `${entry.file} no longer holds the npm-vm block`, `Run \`npm-vm init ${entry.shell}\` and add the block, or run setup again.`);
+	const shimsDir = shimDir(dirs.home);
+	if (platform === "win32") {
+		const shimsCanonical = canonical(shimsDir);
+		for (const winner of windowsWinners(env)) if (winner.path === null || !canonical(winner.path).startsWith(shimsCanonical)) problem("path", `${winner.context} resolves npm to ${winner.path ?? "nothing"}`, "Run setup again, then restart the terminal (M-RESTART).");
+	} else {
+		const login = basename(env["SHELL"] ?? "");
+		const shells = /* @__PURE__ */ new Set([...profiles.entries.map((entry) => entry.shell), ...isShell(login) ? [login] : []]);
+		for (const shell of shells) {
+			if (shell === "powershell") continue;
+			const winner = shellWinner(shell, env);
+			if (winner === null) continue;
+			const kind = winnerKind(winner);
+			if (kind !== "path") problem("path", `${shell} resolves npm to a shell ${kind}: ${winner}`, `A shell ${kind} wins over PATH. Remove it from your ${shell} profile, or make it run ${join(shimsDir, "npm")}.`);
+			else if (!samePath(winner, join(shimsDir, "npm"), platform)) problem("path", `${shell} resolves npm to ${winner}${winner.includes("corepack") ? " (a Corepack shim)" : ""}`, `Add the snippet from \`npm-vm init ${shell}\` after your Node manager's init line, or run setup with --link.`);
+		}
+	}
+	const links = readLinks(dirs);
+	if (links.entries.length > 0) {
+		for (const entry of links.entries) {
+			const state = linkState(entry);
+			if (state !== "intact") problem("link", `${entry.target} is ${state === "missing" ? "missing" : "no longer the npm-vm shim"}`, "Run `npm-vm setup --link` to relink, or `npm-vm uninstall` to stop linking.");
+		}
+		const linked = new Set(links.entries.map((entry) => entry.binDir));
+		for (const install of findNodeInstalls(env, platform)) if (!linked.has(install.binDir)) problem("link", `${install.manager} ${install.version} at ${install.binDir} is not linked`, "Run `npm-vm setup --link`.");
+	}
+	report.notes.push(...findNodeInstalls(env, platform).map((install) => `Found ${install.manager} ${install.version} at ${install.binDir}`));
+	const project = findProject([], process.cwd(), env);
+	if (existsSync(join(project.root, "node_modules", ".bin", "npm"))) report.notes.push(`${project.root}/node_modules/.bin/npm exists; npm scripts in this project run it instead of the shim.`);
+	return report;
+}
+async function doctor(context, options = {}) {
+	const report = await collect(context);
+	if (options.quiet) return report.problems.length === 0 ? EXIT.ok : EXIT.problems;
+	if (context.json) context.io.out(JSON.stringify(report, null, 2));
+	else {
+		const lines = [`npm-vm ${report.version ?? "(not installed)"} in ${report.home}`];
+		for (const problem of report.problems) lines.push(`  problem [${problem.check}]: ${problem.detail}`, `    fix: ${problem.fix}`);
+		for (const note of report.notes) lines.push(`  note: ${note}`);
+		lines.push(report.problems.length === 0 ? "  healthy" : `  ${report.problems.length} problem(s)`);
+		context.io.out(lines.join("\n"));
+	}
+	return report.problems.length === 0 ? EXIT.ok : EXIT.problems;
+}
+//#endregion
+//#region src/commands/pin.ts
+/** The indentation and newline a JSON file uses, so the rewrite keeps its shape. */
+function detectFormat(text) {
+	return {
+		indent: /^[ \t]+(?=")/m.exec(text)?.[0] ?? "  ",
+		newline: text.includes("\r\n") ? "\r\n" : "\n",
+		trailingNewline: text.endsWith("\n")
+	};
+}
+/** `devEngines.packageManager` with one npm entry, keeping other managers and the field's shape. */
+function pinnedManifest(pkg, version) {
+	const entry = {
+		name: "npm",
+		version,
+		onFail: "error"
+	};
+	const devEngines = typeof pkg["devEngines"] === "object" && pkg["devEngines"] !== null ? { ...pkg["devEngines"] } : {};
+	const existing = devEngines["packageManager"];
+	if (Array.isArray(existing)) devEngines["packageManager"] = [...existing.filter((item) => !(typeof item === "object" && item !== null && item.name === "npm")), entry];
+	else if (typeof existing === "object" && existing !== null && existing.name !== "npm") devEngines["packageManager"] = [existing, entry];
+	else devEngines["packageManager"] = entry;
+	return {
+		...pkg,
+		devEngines
+	};
+}
+function nearestManifestDir(cwd) {
+	let dir = cwd;
+	for (;;) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+/** `^<latest npm whose engines accept the active Node>`, asked from the registry. */
+async function defaultRange(context) {
+	const latest = (await createInstaller(createContext(context.env, context.dirs.home)).registry([parseVersionSpec(">=8", "pin")])).filter((candidate) => candidate.enginesNode === null || semver.satisfies(process.version, candidate.enginesNode, { includePrerelease: true })).map((candidate) => candidate.version).toSorted(semver.rcompare)[0];
+	if (latest === void 0) throw new NpmVmError("M-NOMATCH", EXIT.resolution, `No npm release supports Node ${process.version}.`);
+	return `^${latest}`;
+}
+async function pin(context, range, cwd = process.cwd()) {
+	const project = findProject([], cwd, context.env);
+	const nearest = nearestManifestDir(cwd);
+	if (nearest !== null && nearest !== project.root) throw new NpmVmError("M-NOMATCH", EXIT.usage, `${nearest} is a workspace of ${project.root}; npm reads devEngines from the root. Run pin from ${project.root} to pin it there.`);
+	const file = join(project.root, "package.json");
+	if (!existsSync(file)) throw new NpmVmError("M-NOMATCH", EXIT.usage, `No package.json in ${project.root}.`);
+	const version = range ?? await defaultRange(context);
+	try {
+		parseVersionSpec(version, "pin");
+	} catch (error) {
+		throw new NpmVmError("M-NOMATCH", EXIT.usage, error.message);
+	}
+	const lock = await acquireLock(context.dirs.state, context.owner);
+	try {
+		recoverDeadJournals(context.dirs.journal, context.dirs.machine.id);
+		const text = readFileSync(file, "utf8");
+		let pkg;
+		try {
+			pkg = JSON.parse(text);
+		} catch (error) {
+			throw new NpmVmError("M-NOMATCH", EXIT.usage, `${file} is not valid JSON: ${error.message}`);
+		}
+		const format = detectFormat(text);
+		const output = `${JSON.stringify(pinnedManifest(pkg, version), null, format.indent).replace(/\n/g, format.newline)}${format.trailingNewline ? format.newline : ""}`;
+		if (output !== text) {
+			const mode = process.platform === "win32" ? 420 : statSync(file).mode & 4095;
+			mutateFile(context.dirs.journal, "project", context.owner, file, Buffer.from(output, "utf8"), mode);
+		}
+	} finally {
+		lock.release();
+	}
+	context.io.out(context.json ? JSON.stringify({
+		file,
+		version
+	}) : `Pinned npm ${version} in ${file}`);
+	return EXIT.ok;
+}
+//#endregion
+//#region src/install/provenance.ts
+var provenance_exports = /* @__PURE__ */ __exportAll({
+	PROVENANCE_IDENTITY: () => PROVENANCE_IDENTITY,
+	PROVENANCE_ISSUER: () => PROVENANCE_ISSUER,
+	SLSA_PREDICATE: () => SLSA_PREDICATE,
+	attestationUrl: () => attestationUrl,
+	childEnv: () => childEnv,
+	fetchAttestations: () => fetchAttestations,
+	identityPattern: () => identityPattern,
+	noProxyMatches: () => noProxyMatches,
+	selfCommand: () => selfCommand,
+	tlsOptions: () => tlsOptions,
+	verifierLaunch: () => verifierLaunch,
+	verifyBundle: () => verifyBundle,
+	verifyBundleHere: () => verifyBundleHere,
+	verifyProvenance: () => verifyProvenance
+});
+/** What the attestation must say about this repository's release workflow (spec SUP-2). */
+const PROVENANCE_ISSUER = "https://token.actions.githubusercontent.com";
+const PROVENANCE_IDENTITY = "https://github.com/mawesomedev/mawesome/.github/workflows/release.yml@refs/heads/main";
+const SLSA_PREDICATE = "https://slsa.dev/provenance/v1";
+function failure(name, version, detail) {
+	return new NpmVmError("M-PROVENANCE", EXIT.verification, provenanceMessage(name, version, detail));
+}
+/** Resolves the attestation path against the configured registry: never another origin (spec SUP-2). */
+function attestationUrl(input, registry) {
+	const base = new URL(registry);
+	const url = new URL(base);
+	if (input.attestationsUrl !== null) {
+		const given = new URL(input.attestationsUrl, base);
+		url.pathname = given.pathname;
+		url.search = given.search;
+	} else {
+		url.pathname = `${base.pathname.replace(/\/$/, "")}/-/npm/v1/attestations/${encodeURIComponent(input.name)}@${input.version}`;
+		url.search = "";
+	}
+	url.hash = "";
+	url.username = "";
+	url.password = "";
+	if (url.origin !== base.origin) throw new Error(`attestation URL ${redactUrls(url.href)} leaves the registry origin ${base.origin}`);
+	return url;
+}
+/** TLS settings npm itself would use: `ca` and `cafile`, `strict-ssl`, and the registry's client certificate (spec DL-2). */
+function tlsOptions(config) {
+	const ca = [...config.ca ?? []];
+	if (config.cafile !== null) ca.push(readFileSync(config.cafile, "utf8"));
+	const { certfile, keyfile } = config.credentials;
+	return {
+		rejectUnauthorized: config.strictSsl,
+		...ca.length === 0 ? {} : { ca },
+		...certfile !== void 0 && keyfile !== void 0 ? {
+			cert: readFileSync(certfile, "utf8"),
+			key: readFileSync(keyfile, "utf8")
+		} : {}
+	};
+}
+/** `noproxy` the way @npmcli/agent reads it: comma or space separated, `*` for all, `host[:port]`, leading dots and `*.`. */
+function noProxyMatches(noproxy, url) {
+	const port = url.port || (url.protocol === "https:" ? "443" : "80");
+	return (noproxy ?? "").split(/[\s,]+/).map((item) => item.trim().toLowerCase()).filter((item) => item !== "").some((item) => {
+		if (item === "*") return true;
+		const [host, itemPort] = item.split(":");
+		if (itemPort !== void 0 && itemPort !== port) return false;
+		const bare = host.replace(/^\*?\./, "");
+		return url.hostname === bare || url.hostname.endsWith(`.${bare}`);
+	});
+}
+function dispatcherFor(config, url) {
+	const proxy = url.protocol === "https:" ? config.httpsProxy ?? config.proxy : config.proxy;
+	const bypass = noProxyMatches(config.noproxy, url);
+	const tls = tlsOptions(config);
+	if (proxy !== null && !bypass) return new ProxyAgent({
+		uri: proxy,
+		requestTls: tls
+	});
+	return new Agent({ connect: tls });
+}
+function authHeader(config) {
+	const { token, username, password, auth } = config.credentials;
+	if (token !== void 0) return { authorization: `Bearer ${token}` };
+	if (auth !== void 0) return { authorization: `Basic ${auth}` };
+	if (username !== void 0 && password !== void 0) return { authorization: `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}` };
+	return {};
+}
+/** Fetches the attestations with the user's registry credentials, sent to that origin only (spec DL-2). */
+const fetchAttestations = async (url, config) => {
+	const dispatcher = dispatcherFor(config, url);
+	try {
+		const response = await request(url, {
+			dispatcher,
+			headers: {
+				accept: "application/json",
+				...authHeader(config)
+			}
+		});
+		if (response.statusCode !== 200) {
+			await response.body.dump();
+			throw new Error(`registry answered ${response.statusCode} for ${url.pathname}`);
+		}
+		const body = await response.body.json();
+		return (Array.isArray(body.attestations) ? body.attestations : []).filter((item) => typeof item === "object" && item !== null && typeof item.predicateType === "string" && "bundle" in item);
+	} finally {
+		await dispatcher.close();
+	}
+};
+/** sigstore's verifier with this repository's identity pinned; the TUF cache lives under the state dir. */
+/** sigstore matches the identity as an unanchored regular expression, so the exact SAN is escaped and anchored. */
+function identityPattern(identity = PROVENANCE_IDENTITY) {
+	return `^${identity.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`;
+}
+/** The in-process verifier, run by the `verify-attestation` child command. */
+async function verifyBundleHere(bundle, tufCachePath) {
+	await (await import("sigstore")).verify(bundle, {
+		certificateIssuer: PROVENANCE_ISSUER,
+		certificateIdentityURI: identityPattern(),
+		tufCachePath
+	});
+}
+/** How to reach this program again from a child process: the entry argv plus the `cli` selector under the launcher. */
+function selfCommand() {
+	const entry = process.argv[1] ?? "";
+	return entry.endsWith("bootstrap.cjs") ? [entry, "cli"] : [entry];
+}
+/**
+* Runs the verifier in a child Node (spec DL-2): sigstore reaches TUF through make-fetch-happen, which reads
+* proxies from the env, and Node reads NODE_EXTRA_CA_CERTS only at start. The child's env carries nothing else.
+*/
+const verifyBundle = async (bundle, options) => {
+	const dir = mkdtempSync(join(options.tufCachePath, "bundle-"));
+	const file = join(dir, "bundle.json");
+	writeFileSync(file, JSON.stringify(bundle), { mode: 384 });
+	const { args, env } = verifierLaunch(file, options, dir);
+	try {
+		await new Promise((resolve, reject) => {
+			execFile(process.execPath, args, {
+				env,
+				encoding: "utf8",
+				timeout: 3e5,
+				windowsHide: true
+			}, (error, stdout, stderr) => {
+				if (error === null) {
+					resolve();
+					return;
+				}
+				reject(new Error(`${stderr.trim() || stdout.trim() || error.message}`.replace(/^npm-vm: /, "")));
+			});
+		});
+	} finally {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+};
+/** The verifier child's argv and env for one bundle file; `dir` is private to this run and holds any CA bundle. */
+function verifierLaunch(file, options, dir) {
+	const [entry, ...prefix] = selfCommand();
+	return {
+		args: [
+			entry,
+			...prefix,
+			"verify-attestation",
+			"--bundle",
+			file,
+			"--tuf-cache",
+			options.tufCachePath
+		],
+		env: childEnv(options.config, options.env, dir)
+	};
+}
+const PROXY_KEYS = /^(https?_proxy|all_proxy|no_proxy|proxy|node_extra_ca_certs|node_options)$/i;
+/** The child's env: the parent's minus every proxy and Node override, plus only what the npm config says. */
+function childEnv(config, env, bundleDir = null) {
+	const child = {};
+	for (const [key, value] of Object.entries(env)) if (!PROXY_KEYS.test(key) && !/^npm_config_/i.test(key)) child[key] = value;
+	const httpsProxy = config.httpsProxy ?? config.proxy;
+	if (httpsProxy !== null) child["https_proxy"] = httpsProxy;
+	if (config.proxy !== null) child["http_proxy"] = config.proxy;
+	if (config.noproxy !== null) child["no_proxy"] = config.noproxy;
+	if (config.ca !== null && config.ca.length > 0 && bundleDir !== null) {
+		const bundle = join(bundleDir, "ca-bundle.pem");
+		const parts = [...config.ca];
+		if (config.cafile !== null) parts.push(readFileSync(config.cafile, "utf8"));
+		writeFileSync(bundle, `${parts.map((part) => part.trim()).join("\n")}\n`, { mode: 384 });
+		child["NODE_EXTRA_CA_CERTS"] = bundle;
+	} else if (config.cafile !== null) child["NODE_EXTRA_CA_CERTS"] = config.cafile;
+	return child;
+}
+function isSubject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const { name, digest } = value;
+	return typeof name === "string" && typeof digest === "object" && digest !== null && !Array.isArray(digest);
+}
+function statementOf(bundle) {
+	const payload = bundle.dsseEnvelope?.payload;
+	if (typeof payload !== "string") return null;
+	try {
+		const parsed = JSON.parse(Buffer.from(payload, "base64").toString("utf8"));
+		if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.subject)) return null;
+		return {
+			predicateType: typeof parsed.predicateType === "string" ? parsed.predicateType : "",
+			subject: parsed.subject.filter(isSubject).map((subject) => ({
+				name: subject.name,
+				digest: Object.fromEntries(Object.entries(subject.digest).filter(([, value]) => typeof value === "string"))
+			}))
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Verifies the SLSA provenance of a release (spec SUP-2): fetched from the registry origin, signed by this
+* repository's release workflow on main, and naming exactly this package version and tarball digest.
+*/
+async function verifyProvenance(input, deps = {}) {
+	const { name, version } = input;
+	let url;
+	try {
+		url = attestationUrl(input, input.config.registry);
+	} catch (error) {
+		throw failure(name, version, `bad attestation URL: ${redactUrls(error.message)}`);
+	}
+	let attestations;
+	try {
+		attestations = await (deps.fetch ?? fetchAttestations)(url, input.config);
+	} catch (error) {
+		throw failure(name, version, `cannot fetch attestations: ${redactUrls(error.message)}`);
+	}
+	const provenance = attestations.find((item) => item.predicateType === SLSA_PREDICATE);
+	if (provenance === void 0) throw failure(name, version, "the registry holds no SLSA provenance attestation for it");
+	const statement = statementOf(provenance.bundle);
+	if (statement === null) throw failure(name, version, "the attestation bundle carries no readable in-toto statement");
+	if (statement.predicateType !== "https://slsa.dev/provenance/v1") throw failure(name, version, `the signed statement is ${statement.predicateType}, not SLSA provenance`);
+	const expectedSubject = `pkg:npm/${name.replace(/^@/, "%40")}@${version}`;
+	const subject = statement.subject.find((item) => item.name === expectedSubject);
+	if (subject === void 0) throw failure(name, version, `the attestation names ${statement.subject.map((item) => item.name).join(", ") || "nothing"}, not ${expectedSubject}`);
+	if (subject.digest["sha512"] !== input.sha512hex) throw failure(name, version, "the attested tarball digest differs from the downloaded tarball");
+	const tufCachePath = join(input.stateDir, "sigstore");
+	mkdirSync(tufCachePath, {
+		recursive: true,
+		mode: 448
+	});
+	try {
+		await (deps.verify ?? verifyBundle)(provenance.bundle, {
+			tufCachePath,
+			config: input.config,
+			env: deps.env ?? process.env
+		});
+	} catch (error) {
+		throw failure(name, version, `signature verification failed: ${redactUrls(error.message)}`);
+	}
+}
+//#endregion
+//#region src/commands/self-update.ts
+const PACKAGE_NAME = "@mawesome/npm-vm";
+function run$1(file, args) {
+	return new Promise((resolve) => {
+		execFile(process.execPath, [file, ...args], {
+			encoding: "utf8",
+			timeout: 6e4,
+			windowsHide: true
+		}, (error, stdout, stderr) => {
+			resolve({
+				code: error === null ? 0 : error.code ?? 1,
+				stdout,
+				stderr
+			});
+		});
+	});
+}
+/** The launcher generation a bootstrap file belongs to, read from its `LAUNCHER_ABI` constant. */
+function launcherAbiOf(bootstrapFile) {
+	const abi = shimAbi(readFileSync(bootstrapFile, "utf8"));
+	if (abi === null) throw new NpmVmError("M-ABI", EXIT.abi, abiMessage(`${bootstrapFile} declares no launcher ABI`));
+	return abi;
+}
+/**
+* Replaces the home's launcher files with those of `version` (spec SUP-3): the bootstrap at the root and
+* every shim, rendered from that version's templates, each under a journal.
+*/
+function installLaunchers(context, version) {
+	const { dirs, platform, env } = context;
+	const dir = versionDir(dirs.home, version);
+	const bootstrap = join(dir, BOOTSTRAP_FILE);
+	const abi = launcherAbiOf(bootstrap);
+	mutateFile(dirs.journal, "launcher", context.owner, join(dirs.home, BOOTSTRAP_FILE), readFileSync(bootstrap), 420);
+	const powershell = platform !== "win32" || powershellAllowsScripts(executionPolicy(env));
+	mkdirSync(shimDir(dirs.home), {
+		recursive: true,
+		mode: 493
+	});
+	for (const file of renderShims(dirs.home, platform, {
+		powershell,
+		templates: join(dir, LAUNCHERS_DIR),
+		abi
+	})) mutateFile(dirs.journal, "launcher", context.owner, join(shimDir(dirs.home), file.name), Buffer.from(file.content), file.mode);
+	if (platform === "win32" && !powershell) for (const stale of stalePowershellShims(dirs.home)) mutateFile(dirs.journal, "launcher", context.owner, stale, null);
+}
+function currentLauncherAbi(context) {
+	const file = join(context.dirs.home, BOOTSTRAP_FILE);
+	return existsSync(file) ? shimAbi(readFileSync(file, "utf8")) : null;
+}
+async function selfUpdate(context, options, deps = {}) {
+	const lock = await acquireLock(context.dirs.state, context.owner);
+	try {
+		recoverDeadJournals(context.dirs.journal, context.dirs.machine.id);
+		return options.rollback ? rollback(context) : await update(context, deps);
+	} finally {
+		lock.release();
+	}
+}
+/** `self-update --rollback` (spec SUP-4): offline, swaps `current` back and restores the previous launchers if the ABI differs. */
+function rollback(context) {
+	const { dirs, io } = context;
+	const current = readCurrent(dirs.home);
+	const previous = readPrevious(dirs.home);
+	if (previous === null || !existsSync(versionDir(dirs.home, previous)) || current === null) throw new NpmVmError("M-ABI", EXIT.usage, "No previous version to roll back to.");
+	mutateFile(dirs.journal, "launcher", context.owner, join(dirs.home, "current"), Buffer.from(`${previous}\n`));
+	if (launcherAbiOf(join(versionDir(dirs.home, previous), "bootstrap.cjs")) !== currentLauncherAbi(context)) installLaunchers(context, previous);
+	atomicWrite(join(dirs.home, PREVIOUS_FILE), `${current}\n`);
+	io.out(context.json ? JSON.stringify({
+		current: previous,
+		previous: current
+	}) : `Rolled back to npm-vm ${previous} (from ${current}).`);
+	return EXIT.ok;
+}
+async function update(context, deps) {
+	const { dirs, env, io } = context;
+	const installed = readCurrent(dirs.home) ?? context.version;
+	const own = findOwnNpm();
+	const found = own?.version ?? null;
+	if (!transportUsable(own)) throw new NpmVmError("M-TRANSPORT", EXIT.transport, transportMessage(found, "too old or missing"));
+	const work = newWorkDir(dirs.tmp);
+	try {
+		const config = await loadNpmConfig(own, env, work);
+		const transport = new Transport(own, config, env, dirs.tmp);
+		const latest = (await transport.viewPackage(PACKAGE_NAME, "latest"))[0];
+		if (latest === void 0) throw new NpmVmError("M-TRANSPORT", EXIT.transport, transportMessage(own.version, `${PACKAGE_NAME}@latest is not published`));
+		if (!semver.gt(latest.version, installed)) {
+			io.out(context.json ? JSON.stringify({
+				current: installed,
+				latest: latest.version,
+				updated: false
+			}) : `npm-vm ${installed} is up to date (latest is ${latest.version}).`);
+			return EXIT.ok;
+		}
+		const packed = await transport.packPackage(PACKAGE_NAME, latest.version, work);
+		const digests = await fileDigests(packed.file);
+		if (digests.sha512 !== latest.integrity) throw new NpmVmError("M-INTEGRITY", EXIT.verification, `${PACKAGE_NAME}@${latest.version}: tarball does not match the registry integrity.`);
+		await verifySignatures({
+			name: PACKAGE_NAME,
+			version: latest.version,
+			integrity: latest.integrity,
+			signatures: latest.signatures,
+			publishedAt: async () => null,
+			keys: loadKeyring(dirs.state),
+			registry: config.registry,
+			pinned: false
+		});
+		await verifyProvenance({
+			name: PACKAGE_NAME,
+			version: latest.version,
+			sha512hex: digests.sha512hex,
+			attestationsUrl: latest.attestationsUrl,
+			config,
+			stateDir: dirs.state
+		}, {
+			...deps.fetchAttestations === void 0 ? {} : { fetch: deps.fetchAttestations },
+			...deps.verifyBundle === void 0 ? {} : { verify: deps.verifyBundle },
+			env
+		});
+		const extracted = join(work, "package");
+		mkdirSync(extracted, { mode: 448 });
+		await safeExtract(packed.file, extracted);
+		const runtimeSource = join(extracted, "dist", "runtime");
+		if (!existsSync(join(runtimeSource, "runtime.cjs")) || !existsSync(join(runtimeSource, "bootstrap.cjs"))) throw new NpmVmError("M-INTEGRITY", EXIT.verification, `${PACKAGE_NAME}@${latest.version} ships no runtime build.`);
+		const candidateAbi = launcherAbiOf(join(runtimeSource, BOOTSTRAP_FILE));
+		const installedRuntimeAbi = runtimeAbi(dirs.home, installed) ?? currentLauncherAbi(context) ?? candidateAbi;
+		if (installedRuntimeAbi < candidateAbi - 1) throw new NpmVmError("M-ABI", EXIT.abi, abiMessage(`npm-vm ${latest.version} skips launcher generations (${installedRuntimeAbi} to ${candidateAbi})`));
+		if (candidateAbi < installedRuntimeAbi) throw new NpmVmError("M-ABI", EXIT.abi, abiMessage(`npm-vm ${latest.version} ships launcher ABI ${candidateAbi}, older than the installed runtime's ${installedRuntimeAbi}`));
+		const target = installVersion(dirs.home, latest.version, runtimeSource, candidateAbi);
+		const health = await run$1(join(target, BOOTSTRAP_FILE), [
+			"--candidate",
+			"cli",
+			"--version"
+		]);
+		if (health.code !== 0 || health.stdout.trim() !== latest.version) {
+			rmSync(target, {
+				recursive: true,
+				force: true
+			});
+			throw new NpmVmError("M-ABI", EXIT.abi, abiMessage(`the downloaded runtime failed its health check: ${health.stderr.trim() || health.stdout.trim() || `exit ${health.code}`}`));
+		}
+		if (candidateAbi !== currentLauncherAbi(context)) installLaunchers(context, latest.version);
+		atomicWrite(join(dirs.home, PREVIOUS_FILE), `${installed}\n`);
+		mutateFile(dirs.journal, "launcher", context.owner, join(dirs.home, "current"), Buffer.from(`${latest.version}\n`));
+		io.out(context.json ? JSON.stringify({
+			current: latest.version,
+			previous: installed,
+			updated: true
+		}) : `Updated npm-vm ${installed} to ${latest.version}.`);
+		return EXIT.ok;
+	} finally {
+		rmSync(work, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/commands/setup.ts
+/** Refuses a home or cache another user could write to (spec SEC-9). */
+function assertPrivateDir(dir, platform) {
+	if (platform === "win32") return;
+	const stat = statSync(dir);
+	if (process.getuid !== void 0 && stat.uid !== process.getuid()) throw new NpmVmError("M-DIRPERMS", EXIT.problems, dirPermsMessage(dir, "is not owned by you", `chown $(id -u) ${dir}`));
+	if ((stat.mode & 18) !== 0) throw new NpmVmError("M-DIRPERMS", EXIT.problems, dirPermsMessage(dir, "is writable by other users", `chmod go-w ${dir}`));
+}
+function ensurePrivateDir(dir, platform) {
+	if (!existsSync(dir)) {
+		mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		if (platform !== "win32") chmodSync(dir, 448);
+	}
+	assertPrivateDir(dir, platform);
+}
+/** The shells to configure: `--shell` values, else the login shell, plus PowerShell on Windows. */
+function defaultShells(env, platform) {
+	if (platform === "win32") return ["powershell"];
+	const login = basename(env["SHELL"] ?? "");
+	return isShell(login) ? [login] : ["bash"];
+}
+function sameFiles(home, version, distDir) {
+	const manifest = readManifest(home, version);
+	if (manifest === null) return false;
+	return manifest.files.every((file) => {
+		try {
+			return readFileSync(join(distDir, file)).equals(readFileSync(join(versionDir(home, version), file)));
+		} catch {
+			return false;
+		}
+	});
+}
+async function setup(context, options) {
+	const { dirs, env, platform, io } = context;
+	assertSafeHome(dirs.home);
+	const distDir = runtimeDistDir();
+	if (distDir === null) throw new NpmVmError("M-ABI", EXIT.problems, "This npm-vm installation ships no runtime build; reinstall the package.");
+	for (const dir of [
+		dirs.home,
+		dirs.state,
+		dirs.cache
+	]) if (options.dryRun) {
+		if (existsSync(dir)) assertPrivateDir(dir, platform);
+	} else ensurePrivateDir(dir, platform);
+	const report = {
+		home: dirs.home,
+		version: context.version,
+		profiles: [],
+		links: [],
+		skipped: 0
+	};
+	const shells = options.shells ?? defaultShells(env, platform);
+	const targets = options.modifyProfile ? profileTargets(shells, env, platform) : [];
+	const policy = platform === "win32" ? executionPolicy(env) : null;
+	const powershell = platform !== "win32" || powershellAllowsScripts(policy);
+	const plans = targets.map((target) => ({
+		target,
+		guard: profileGuard(target.file, env, platform),
+		edit: planProfileEdit(target, dirs.home)
+	}));
+	const lock = options.dryRun ? null : await acquireLock(dirs.state, context.owner);
+	try {
+		if (lock !== null) recoverDeadJournals(dirs.journal, dirs.machine.id);
+		if (!options.dryRun) {
+			installRuntime(context, distDir);
+			mkdirSync(shimDir(dirs.home), {
+				recursive: true,
+				mode: 493
+			});
+			for (const file of renderShims(dirs.home, platform, { powershell })) mutateFile(dirs.journal, "launcher", context.owner, join(shimDir(dirs.home), file.name), Buffer.from(file.content), file.mode);
+			if (platform === "win32" && !powershell) for (const stale of stalePowershellShims(dirs.home)) mutateFile(dirs.journal, "launcher", context.owner, stale, null);
+		}
+		for (const plan of plans) report.profiles.push(await applyPlan(context, options, plan));
+		if (options.link) for (const install of findNodeInstalls(env, platform)) for (const target of linkTargets(dirs.home, platform, powershell)) if (options.dryRun) report.links.push({
+			target: join(install.binDir, target.name),
+			outcome: "linked",
+			detail: "dry run"
+		});
+		else report.links.push(linkOne(dirs, context.owner, install.binDir, target));
+		if (platform === "win32" && !options.dryRun && options.userPath) {
+			if (addToUserPath(env, shimDir(dirs.home))) {
+				env["Path"] = `${shimDir(dirs.home)};${env["Path"] ?? ""}`;
+				io.err(restartMessage());
+			}
+			if (options.cmdAutorun) setCmdAutoRun(env, shimDir(dirs.home));
+			if (!powershell) io.err(`PowerShell's execution policy (${policy ?? "unknown"}) blocks unsigned scripts, so no .ps1 shims were installed; cmd shims take over.`);
+		}
+	} finally {
+		lock?.release();
+	}
+	report.skipped = report.profiles.filter((entry) => entry.outcome === "printed" || entry.outcome === "declined" || entry.outcome === "changed").length + report.links.filter((link) => [
+		"foreign",
+		"unwritable",
+		"missing"
+	].includes(link.outcome)).length;
+	if (context.json) io.out(JSON.stringify(report, null, 2));
+	else io.out(describe$1(report));
+	if (!options.dryRun) {
+		if (await doctor(context, { quiet: context.json }) !== EXIT.ok && options.strict) return EXIT.partial;
+	}
+	return options.strict && report.skipped > 0 ? EXIT.partial : EXIT.ok;
+}
+/** Installs this version's runtime and launcher unless the identical files are already in place. */
+function installRuntime(context, distDir) {
+	const { dirs, version } = context;
+	if (!sameFiles(dirs.home, version, distDir)) installVersion(dirs.home, version, distDir, 1);
+	sweepReplaced(dirs.home);
+	if (readCurrent(dirs.home) !== version) mutateFile(dirs.journal, "launcher", context.owner, join(dirs.home, "current"), Buffer.from(`${version}\n`));
+	const bootstrap = readFileSync(join(versionDir(dirs.home, version), BOOTSTRAP_FILE));
+	const installed = existsSync(join(dirs.home, "bootstrap.cjs")) ? readFileSync(join(dirs.home, BOOTSTRAP_FILE)) : null;
+	if (installed === null || !installed.equals(bootstrap)) mutateFile(dirs.journal, "launcher", context.owner, join(dirs.home, BOOTSTRAP_FILE), bootstrap, 420);
+}
+async function applyPlan(context, options, plan) {
+	const { io, dirs } = context;
+	const { target } = plan;
+	if (plan.guard !== null) {
+		io.out(`Not editing ${target.file}: ${plan.guard}. Add this yourself:\n${profileBlock(target.shell, dirs.home, target.parts)}`);
+		return {
+			file: target.file,
+			outcome: "printed",
+			reason: plan.guard
+		};
+	}
+	if (plan.edit === null) return {
+		file: target.file,
+		outcome: "unchanged"
+	};
+	if (options.dryRun) {
+		io.out(`Would edit ${target.file}:\n${plan.edit.diff}`);
+		return {
+			file: target.file,
+			outcome: "dry-run"
+		};
+	}
+	if (!options.yes) {
+		io.out(plan.edit.diff);
+		if (!await io.confirm(`Apply this change to ${target.file}?`)) {
+			io.out(`Skipped ${target.file}. Add this yourself:\n${profileBlock(target.shell, dirs.home, target.parts)}`);
+			return {
+				file: target.file,
+				outcome: "declined"
+			};
+		}
+	}
+	const guard = profileGuard(target.file, context.env, context.platform);
+	const fresh = planProfileEdit(target, dirs.home);
+	if (fresh === null) return {
+		file: target.file,
+		outcome: "unchanged"
+	};
+	if (guard !== null || fresh.before !== plan.edit.before && !options.yes) {
+		io.out(`${target.file} changed while the prompt was open; run setup again to review the new change.`);
+		return {
+			file: target.file,
+			outcome: "changed"
+		};
+	}
+	applyProfileEdit(dirs, context.owner, fresh);
+	return {
+		file: target.file,
+		outcome: "written"
+	};
+}
+function describe$1(report) {
+	const lines = [`npm-vm ${report.version} installed in ${report.home}`];
+	for (const profile of report.profiles) lines.push(`  ${profile.file}: ${profile.outcome}${profile.reason ? ` (${profile.reason})` : ""}`);
+	for (const link of report.links) lines.push(`  ${link.target}: ${link.outcome}${link.detail ? ` (${link.detail})` : ""}`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/uninstall.ts
+/** Removes the cache's directories only while empty: an npm publishing right now keeps its entry. */
+function removeEmptyTree(cache) {
+	for (const dir of [
+		join(cache, "npm"),
+		stagingDir(cache),
+		cache
+	]) try {
+		rmdirSync(dir);
+	} catch {}
+}
+async function uninstall(context, options) {
+	const { dirs, env, platform, io } = context;
+	if (!options.yes) {
+		if (!await io.confirm(`Remove npm-vm from ${dirs.home}, its profile blocks and links${options.purgeCache ? ", and the cache" : ""}?`)) {
+			io.out("Nothing removed.");
+			return EXIT.ok;
+		}
+	}
+	const report = {
+		profiles: [],
+		links: [],
+		homeRemoved: false,
+		cacheRemoved: false,
+		cacheKept: []
+	};
+	const lock = await acquireLock(dirs.state, context.owner);
+	let clean = true;
+	try {
+		recoverDeadJournals(dirs.journal, dirs.machine.id);
+		for (const entry of readProfiles(dirs).entries) {
+			const outcome = removeProfileBlock(dirs, context.owner, entry);
+			report.profiles.push({
+				file: entry.file,
+				outcome
+			});
+			if (outcome === "changed") {
+				clean = false;
+				io.err(changedMessage(entry.file, "npm-vm block"));
+			}
+		}
+		for (const entry of readLinks(dirs).entries) {
+			const outcome = unlinkOne(dirs, context.owner, entry);
+			report.links.push({
+				target: entry.target,
+				outcome
+			});
+			if (outcome === "changed") {
+				clean = false;
+				io.err(changedMessage(entry.target, "shim"));
+			}
+		}
+		if (platform === "win32") {
+			removeFromUserPath(env, shimDir(dirs.home));
+			clearCmdAutoRun(env);
+		}
+		if (options.purgeCache) {
+			const cacheLock = await acquireLock(dirs.cache, context.owner);
+			try {
+				const pruned = pruneCache(dirs.cache, context.owner, { maxAgeMs: 0 });
+				report.cacheKept = pruned.kept.concat(pruned.skipped);
+				if (report.cacheKept.length === 0) {
+					removeEmptyTree(dirs.cache);
+					report.cacheRemoved = true;
+				}
+			} finally {
+				cacheLock.release();
+			}
+			if (report.cacheRemoved) removeEmptyTree(dirs.cache);
+			if (report.cacheKept.length > 0) {
+				clean = false;
+				io.err(`Cache kept: ${report.cacheKept.join(", ")} ${report.cacheKept.length === 1 ? "is" : "are"} in use by a running npm.`);
+			}
+		}
+		const tombstone = `${dirs.home}.removing.${process.pid}.${Date.now()}`;
+		atomicRename(dirs.home, tombstone);
+		removeWithRetry(tombstone);
+		report.homeRemoved = true;
+	} finally {
+		lock.release();
+	}
+	io.out(context.json ? JSON.stringify(report, null, 2) : describe(report, dirs.cache));
+	return clean ? EXIT.ok : EXIT.problems;
+}
+function describe(report, cache) {
+	const lines = ["npm-vm removed."];
+	for (const profile of report.profiles) lines.push(`  ${profile.file}: ${profile.outcome}`);
+	for (const link of report.links) lines.push(`  ${link.target}: ${link.outcome}`);
+	if (report.cacheRemoved) lines.push(`  cache removed (${cache})`);
+	else if (report.cacheKept.length > 0) lines.push(`  cache kept at ${cache}: ${report.cacheKept.join(", ")} in use by a running npm`);
+	else lines.push(`  cache kept at ${cache}; add --purge-cache to remove it`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/dispatch.ts
+const VERSION = readSelfVersion();
+const USAGE = `npm-vm v${VERSION}: run the npm version a project declares in devEngines
+
+Usage:
+  npm-vm <command> [options]
+
+Commands:
+  setup                  Install the launcher, shims and shell snippets; --link also replaces npm
+                         inside every nvm/fnm Node. --shell <s> (repeatable), --yes, --dry-run,
+                         --no-modify-profile, --cmd-autorun and --no-user-path (Windows), --strict (exit 2 on skips).
+  init <shell>           Print the snippet for zsh, bash, fish or powershell (--path, --hook; default both).
+  doctor                 Check the installation; exit 1 when something needs fixing.
+  which                  Print the npm that would run for the current directory.
+  pin [<range>]          Write devEngines.packageManager for npm into the project's package.json.
+  install [<spec>]       Download and verify the project's npm, or <spec>, into the cache.
+  cache list             List cached npm versions.
+  cache prune            Remove unused entries; --older-than <days> (default 90).
+  self-update            Update npm-vm with provenance verification; --rollback restores the previous version.
+  recover                Finish a journal left by another machine: --journal <id> --confirm-dead-machine <id>.
+  uninstall              Remove npm-vm (--yes to skip the prompt, --purge-cache to drop the cache too).
+
+Global options:
+  --json                 Machine-readable output where a command offers it.
+  --version, -v          Print the version.
+  --help, -h             Print this help.
+
+Environment:
+  NPM_VM_VERSION        Use this range or version instead of the project's.
+  NPM_VM_DISABLE        Any value: always run Node's own npm.
+  NPM_VM_OFFLINE        Any value: never contact the registry.
+  NPM_VM_HOME           The home directory (setup only).
+
+Exit codes: 0 ok, 1 problems found, 2 partial setup under --strict, 3 resolution failed, 4 transport
+unavailable, 5 verification failed, 6 launcher mismatch, 64 usage error.`;
+function parse(argv) {
+	return parseArgs({
+		args: argv,
+		allowPositionals: true,
+		allowNegative: true,
+		options: {
+			json: { type: "boolean" },
+			path: { type: "boolean" },
+			hook: { type: "boolean" },
+			link: { type: "boolean" },
+			shell: {
+				type: "string",
+				multiple: true
+			},
+			yes: { type: "boolean" },
+			"dry-run": { type: "boolean" },
+			"modify-profile": { type: "boolean" },
+			"cmd-autorun": { type: "boolean" },
+			"user-path": { type: "boolean" },
+			strict: { type: "boolean" },
+			"older-than": { type: "string" },
+			rollback: { type: "boolean" },
+			journal: { type: "string" },
+			"confirm-dead-machine": { type: "string" },
+			"purge-cache": { type: "boolean" },
+			bundle: { type: "string" },
+			"tuf-cache": { type: "string" },
+			version: {
+				type: "boolean",
+				short: "v"
+			},
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+}
+/** Command-specific options, so a flag meant for another command is an error rather than silently ignored. */
+const COMMAND_OPTIONS = {
+	setup: [
+		"link",
+		"shell",
+		"yes",
+		"dry-run",
+		"modify-profile",
+		"cmd-autorun",
+		"user-path",
+		"strict"
+	],
+	init: ["path", "hook"],
+	doctor: [],
+	which: [],
+	pin: [],
+	install: [],
+	cache: ["older-than"],
+	"self-update": ["rollback"],
+	recover: ["journal", "confirm-dead-machine"],
+	uninstall: ["yes", "purge-cache"],
+	"verify-attestation": ["bundle", "tuf-cache"]
+};
+function misplacedOptions(command, values) {
+	const allowed = new Set(COMMAND_OPTIONS[command] ?? []);
+	return Object.values(COMMAND_OPTIONS).flat().filter((option) => !allowed.has(option) && values[option] !== void 0).map((option) => `--${option}`);
+}
+async function run(argv, options) {
+	let parsed;
+	try {
+		parsed = parse(argv);
+	} catch (error) {
+		console.error(error.message);
+		console.error(USAGE);
+		return EXIT.usage;
+	}
+	const { values, positionals } = parsed;
+	if (values.version) {
+		console.log(VERSION);
+		return EXIT.ok;
+	}
+	const command = positionals[0];
+	if (values.help || command === void 0) {
+		console.log(USAGE);
+		return command === void 0 && !values.help ? EXIT.usage : EXIT.ok;
+	}
+	if (COMMAND_OPTIONS[command] === void 0) {
+		console.error(`Unknown command: ${command}`);
+		console.error(USAGE);
+		return EXIT.usage;
+	}
+	const misplaced = misplacedOptions(command, values);
+	if (misplaced.length > 0) {
+		console.error(`${misplaced.join(", ")} cannot be used with ${command}`);
+		return EXIT.usage;
+	}
+	const context = createCommandContext({
+		...options.home === void 0 ? {} : { home: options.home },
+		...options.env === void 0 ? {} : { env: options.env },
+		...options.io === void 0 ? {} : { io: options.io },
+		json: values.json ?? false,
+		version: VERSION
+	});
+	try {
+		return await dispatch(command, positionals.slice(1), values, context, options);
+	} catch (error) {
+		return reportError(error, context);
+	}
+}
+async function dispatch(command, rest, values, context, options) {
+	switch (command) {
+		case "setup": {
+			const shells = values.shell ?? null;
+			const bad = shells?.filter((shell) => !isShell(shell)) ?? [];
+			if (bad.length > 0) {
+				context.io.err(`--shell needs one of: ${SHELLS.join(", ")} (got ${bad.join(", ")})`);
+				return EXIT.usage;
+			}
+			return setup(context, {
+				link: values.link ?? false,
+				shells,
+				yes: values.yes ?? false,
+				dryRun: values["dry-run"] ?? false,
+				modifyProfile: values["modify-profile"] ?? true,
+				cmdAutorun: values["cmd-autorun"] ?? false,
+				strict: values.strict ?? false,
+				userPath: values["user-path"] ?? true
+			});
+		}
+		case "init": {
+			const shell = rest[0];
+			if (shell === void 0 || !isShell(shell)) {
+				context.io.err(`init needs one of: ${SHELLS.join(", ")}`);
+				return EXIT.usage;
+			}
+			const both = values.path !== true && values.hook !== true;
+			process.stdout.write(profileBlock(shell, context.dirs.home, {
+				path: both || values.path === true,
+				hook: both || values.hook === true
+			}));
+			return EXIT.ok;
+		}
+		case "doctor": return doctor(context);
+		case "which": {
+			const result = await resolveNpm([], process.cwd(), {
+				home: context.dirs.home,
+				...options.env === void 0 ? {} : { env: options.env }
+			});
+			context.io.out(context.json ? JSON.stringify(result, null, 2) : describeWhich(result));
+			return EXIT.ok;
+		}
+		case "pin": return pin(context, rest[0]);
+		case "install": return install(context, rest[0]);
+		case "cache":
+			if (rest[0] === "list") return cacheList(context);
+			if (rest[0] === "prune") return cachePrune(context, values["older-than"] === void 0 ? 90 : Number(values["older-than"]));
+			context.io.err("cache needs list or prune");
+			return EXIT.usage;
+		case "self-update": return selfUpdate(context, { rollback: values.rollback ?? false });
+		case "recover":
+			if (values.journal === void 0 || values["confirm-dead-machine"] === void 0) {
+				context.io.err("recover needs --journal <id> and --confirm-dead-machine <machine-id>");
+				return EXIT.usage;
+			}
+			return recover(context, values.journal, values["confirm-dead-machine"]);
+		case "verify-attestation": {
+			if (values.bundle === void 0 || values["tuf-cache"] === void 0) return EXIT.usage;
+			const { verifyBundleHere } = await Promise.resolve().then(() => provenance_exports);
+			await verifyBundleHere(JSON.parse(readFileSync(values.bundle, "utf8")), values["tuf-cache"]);
+			return EXIT.ok;
+		}
+		case "uninstall": return uninstall(context, {
+			yes: values.yes ?? false,
+			purgeCache: values["purge-cache"] ?? false
+		});
+		default: return EXIT.usage;
+	}
+}
+function describeWhich(result) {
+	const where = result.kind === "own" ? "Node's own npm" : result.kind === "cached" ? "cached" : "to download";
+	const from = result.source === null ? "no project requirement" : `${result.source.field} in ${result.source.file}`;
+	const lines = [`npm ${result.version} (${where}): ${result.cliPath}`, `Source: ${from}`];
+	if (result.warning !== null) lines.push(`Warning: ${result.warning}`);
+	return lines.join("\n");
+}
+function reportError(error, context) {
+	if (isNpmVmError(error)) {
+		context.io.err(`npm-vm: ${error.message}`);
+		return error.exitCode;
+	}
+	context.io.err(`npm-vm: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+	return EXIT.problems;
+}
+/** The build injects the package version; running from source reads the manifest instead. */
+function readSelfVersion() {
+	return "0.1.0";
+}
+//#endregion
+export { EXIT, NpmVmError, SpecError, createContext, createInstaller, findProject, isNpmVmError, parseSpecs, parseVersionSpec, resolveNpmWith, run as runCommand, selectCandidate, sriHex };
+
+//# sourceMappingURL=internal.js.map