pnpm-settings-migrator 0.6.1 → 0.8.0

package/dist/cli.mjs

@@ -1,19 +1,20 @@
 import process from "node:process";
 import { cac } from "cac";
 import consola$1, { consola } from "consola";
-import { isPlainObject, isUndefined, pick } from "@ntnyq/utils";
-import { defu } from "defu";
-import detectIndent from "detect-indent";
 import { resolve } from "pathe";
-import { Document, parse } from "yaml";
-import { access, readFile, writeFile } from "node:fs/promises";
+import { Document, parse, stringify } from "yaml";
+import { access, readFile, rm, writeFile } from "node:fs/promises";
 import { getColor } from "consola/utils";
+import { isPlainObject, isUndefined, pick } from "@ntnyq/utils";
+import { defu } from "defu";
 import camelcaseKeys from "camelcase-keys";
 import { readIniFile } from "read-ini-file";
 import { kebabCase } from "uncase";
+import { isDeepStrictEqual } from "node:util";
+import detectIndent from "detect-indent";
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.6.1";
+var version = "0.8.0";
 //#endregion
 //#region src/constants.ts
 const NPMRC = ".npmrc";
@@ -60,6 +61,7 @@ const PNPM_SETTINGS_FIELDS = [
 	"httpProxy",
 	"httpsProxy",
 	"ignoredBuiltDependencies",
+	"ignoreDepScripts",
 	"ignoreDeps",
 	"ignoredOptionalDependencies",
 	"ignorePatchFailures",
@@ -87,11 +89,14 @@ const PNPM_SETTINGS_FIELDS = [
 	"overrides",
 	"packageExtensions",
 	"packageImportMethod",
+	"packageManagerStrict",
+	"packageManagerStrictVersion",
 	"patchedDependencies",
 	"peerDependencyRules",
 	"peersSuffixMaxLength",
 	"pnpmfile",
 	"pnpmfileIgnorePkgManifest",
+	"pmOnFail",
 	"preferFrozenLockfile",
 	"preferWorkspacePackages",
 	"production",
@@ -130,11 +135,17 @@ const PNPM_SETTINGS_FIELDS = [
 ];
 const PNPM_V11_REMOVED_SETTINGS = [
 	"allowNonAppliedPatches",
+	"executionEnv",
+	"ignoreDepScripts",
 	"ignorePatchFailures",
 	"ignoredBuiltDependencies",
+	"managePackageManagerVersions",
 	"neverBuiltDependencies",
 	"onlyBuiltDependencies",
-	"onlyBuiltDependenciesFile"
+	"onlyBuiltDependenciesFile",
+	"packageManagerStrict",
+	"packageManagerStrictVersion",
+	"useNodeVersion"
 ];
 //#endregion
 //#region src/options.ts
@@ -148,6 +159,7 @@ const DEFAULT_OPTIONS = {
 	cwd: process.cwd(),
 	newlineBetween: true,
 	replaceDeprecated: false,
+	showChanges: true,
 	sortKeys: false,
 	strategy: "merge",
 	yarnResolutions: true
@@ -160,8 +172,19 @@ const VALID_STRATEGIES = [
 const VALID_COMPATIBILITIES = [
 	"auto",
 	"v10",
-	"v11"
+	"v11",
+	"v12"
 ];
+function resolveCompatibility(compatibility) {
+	if (!compatibility) return DEFAULT_OPTIONS.compatibility;
+	if (VALID_COMPATIBILITIES.includes(compatibility)) return compatibility;
+	throw new Error(`Invalid compatibility: ${compatibility}. Expected one of: ${VALID_COMPATIBILITIES.join(", ")}`);
+}
+function resolveStrategy(strategy) {
+	if (!strategy) return DEFAULT_OPTIONS.strategy;
+	if (VALID_STRATEGIES.includes(strategy)) return strategy;
+	throw new Error(`Invalid strategy: ${strategy}. Expected one of: ${VALID_STRATEGIES.join(", ")}`);
+}
 /**
 * Resolve and normalize migration options with defaults.
 *
@@ -189,6 +212,7 @@ function resolveOptions(options = {}) {
 		compatibility: resolveCompatibility(options.compatibility),
 		cwd: options.cwd ?? DEFAULT_OPTIONS.cwd,
 		newlineBetween: options.newlineBetween ?? DEFAULT_OPTIONS.newlineBetween,
+		showChanges: options.showChanges ?? DEFAULT_OPTIONS.showChanges,
 		sortKeys: options.sortKeys ?? DEFAULT_OPTIONS.sortKeys,
 		strategy: resolveStrategy(options.strategy),
 		yarnResolutions: options.yarnResolutions ?? DEFAULT_OPTIONS.yarnResolutions,
@@ -196,83 +220,269 @@ function resolveOptions(options = {}) {
 		replaceDeprecated: options.replaceDeprecated ?? DEFAULT_OPTIONS.replaceDeprecated
 	};
 }
-function resolveCompatibility(compatibility) {
-	if (!compatibility) return DEFAULT_OPTIONS.compatibility;
-	if (VALID_COMPATIBILITIES.includes(compatibility)) return compatibility;
-	throw new Error(`Invalid compatibility: ${compatibility}. Expected one of: ${VALID_COMPATIBILITIES.join(", ")}`);
-}
-function resolveStrategy(strategy) {
-	if (!strategy) return DEFAULT_OPTIONS.strategy;
-	if (VALID_STRATEGIES.includes(strategy)) return strategy;
-	throw new Error(`Invalid strategy: ${strategy}. Expected one of: ${VALID_STRATEGIES.join(", ")}`);
-}
 //#endregion
 //#region src/utils/fs.ts
 /**
-* Check if a path exists
-* @param path - given path
-* @returns `true` if exists, false otherwise
+* Check whether a filesystem path exists.
+*
+* @param path - Filesystem path to check
+*
+* @returns `true` when the path is accessible, otherwise `false`
 */
 async function fsExists(path) {
 	return access(path).then(() => true).catch(() => false);
 }
 /**
-* Read file content
-* @param path - file path
-* @returns content of given file
+* Read a UTF-8 text file.
+*
+* @param path - Filesystem path to read
+*
+* @returns Text content of the file
 */
 async function fsReadFile(path) {
 	return await readFile(path, "utf-8");
 }
 /**
-* Write file
-* @param path - file path
-* @param content - file content
+* Remove a file if it exists.
+*
+* @param path - Filesystem path to remove
+*
+* @returns A promise that resolves after the file is removed
+*/
+async function fsRemoveFile(path) {
+	await rm(path, { force: true });
+}
+/**
+* Write a normalized UTF-8 text file with one trailing newline.
+*
+* @param path - Filesystem path to write
+* @param content - Text content to write
+*
+* @returns A promise that resolves after the file is written
 */
 async function fsWriteFile(path, content) {
 	await writeFile(path, `${content.trimEnd()}\n`, "utf-8");
 }
 getColor("cyan");
 getColor("yellow");
+/**
+* Apply dim terminal styling to a value.
+*/
 const dim = getColor("dim");
+/**
+* Apply green terminal styling to a value.
+*/
 const green = getColor("green");
+/**
+* Apply red terminal styling to a value.
+*/
 const red = getColor("red");
+/**
+* Apply bold terminal styling to a value.
+*/
 const bold = getColor("bold");
+/**
+* Apply magenta terminal styling to a value.
+*/
 const magenta = getColor("magenta");
 //#endregion
-//#region src/utils/merge.ts
+//#region src/utils/compatibility.ts
 /**
-* Merge two objects based on the specified strategy.
+* Legacy build settings that can be replaced for pnpm v10.
+*/
+const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
+	"allowNonAppliedPatches",
+	"ignoredBuiltDependencies",
+	"neverBuiltDependencies",
+	"onlyBuiltDependencies",
+	"onlyBuiltDependenciesFile"
+];
+/**
+* Read packages listed by the legacy `onlyBuiltDependenciesFile` setting.
 *
-* @param existing - Existing pnpm-workspace.yaml content
-* @param incoming - New settings from package.json and .npmrc
-* @param strategy - Merge strategy to use
+* @param cwd - Working directory used to resolve the referenced file
+* @param file - Relative path stored in `onlyBuiltDependenciesFile`
 *
-* @returns Merged pnpm workspace configuration
+* @returns Package names read from the referenced JSON file
 *
-* @example
-* ```ts
-* // Discard strategy - keep existing values
-* mergeByStrategy({ packages: ['a'] }, { packages: ['b'] }, 'discard')
-* // => { packages: ['a'] }
+* @throws {TypeError} When the referenced JSON value is not a string array
+* @throws {SyntaxError} When the referenced file contains invalid JSON
+*/
+async function readOnlyBuiltDependenciesFile(cwd, file) {
+	if (!file) return [];
+	const path = resolve(cwd, file);
+	const value = JSON.parse(await fsReadFile(path));
+	if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) throw new TypeError(`Invalid onlyBuiltDependenciesFile: ${file}. Expected a JSON array of package names.`);
+	return value;
+}
+/**
+* Build an `allowBuilds` map from legacy build-script settings.
 *
-* // Merge strategy - combine arrays with deduplication
-* mergeByStrategy({ packages: ['a'] }, { packages: ['b'] }, 'merge')
-* // => { packages: ['a', 'b'] }
+* @param incomingSettings - Settings containing legacy build declarations
+* @param cwd - Working directory used to resolve referenced files
 *
-* // Overwrite strategy - use incoming values
-* mergeByStrategy({ packages: ['a'] }, { packages: ['b'] }, 'overwrite')
-* // => { packages: ['b'] }
-* ```
+* @returns Package-to-permission map, or `undefined` when no entries exist
 */
-function mergeByStrategy(existing, incoming, strategy) {
-	switch (strategy) {
-		case "discard": return discardMerge(existing, incoming);
-		case "merge": return mergeWithArrayDedupe(existing, incoming);
-		case "overwrite": return discardMerge(incoming, existing);
-		default: return defu(existing, incoming);
+async function collectAllowBuildsFromLegacy(incomingSettings, cwd) {
+	const allowBuilds = {};
+	const allowedFromFile = await readOnlyBuiltDependenciesFile(cwd, incomingSettings.onlyBuiltDependenciesFile);
+	for (const name of [...incomingSettings.onlyBuiltDependencies || [], ...allowedFromFile]) allowBuilds[name] = true;
+	for (const name of incomingSettings.ignoredBuiltDependencies || []) allowBuilds[name] = false;
+	for (const name of incomingSettings.neverBuiltDependencies || []) allowBuilds[name] = false;
+	return Object.keys(allowBuilds).length ? allowBuilds : void 0;
+}
+/**
+* Resolve the pnpm v11 replacement for legacy package-manager settings.
+*
+* @param settings - Settings containing legacy package-manager declarations
+*
+* @returns Resolved `pmOnFail` behavior, or `undefined` when not configured
+*/
+function resolvePmOnFail(settings) {
+	if (settings.pmOnFail) return settings.pmOnFail;
+	if (settings.packageManagerStrictVersion === true) return "error";
+	if (settings.packageManagerStrict === false) return "warn";
+	if (settings.managePackageManagerVersions === false) return "ignore";
+	if (settings.managePackageManagerVersions === true) return "download";
+}
+/**
+* Rename legacy audit settings while preserving values for manual ID updates.
+*
+* @param settings - Settings whose audit configuration may be normalized
+* @param warnings - Warning collection updated with manual follow-up guidance
+*
+* @returns Nothing; the settings and warning collection are mutated in place
+*/
+function normalizeAuditConfig(settings, warnings) {
+	const { auditConfig } = settings;
+	const ignoreCves = auditConfig?.ignoreCves;
+	if (!ignoreCves) return;
+	auditConfig.ignoreGhsas ??= ignoreCves;
+	Reflect.deleteProperty(auditConfig, "ignoreCves");
+	warnings.push("auditConfig.ignoreCves was renamed to auditConfig.ignoreGhsas; replace each CVE ID with its corresponding GHSA ID.");
+}
+/**
+* Resolve a removed Node.js runtime setting for migration to `package.json`.
+*
+* @param settings - Settings containing legacy runtime declarations
+* @param warnings - Warning collection updated when declarations conflict
+*
+* @returns Runtime version to migrate, or `undefined` when not configured
+*/
+function resolveRuntimeVersion(settings, warnings) {
+	const { useNodeVersion } = settings;
+	const executionEnvNodeVersion = settings.executionEnv?.nodeVersion;
+	if (useNodeVersion && executionEnvNodeVersion && useNodeVersion !== executionEnvNodeVersion) warnings.push(`Both useNodeVersion (${useNodeVersion}) and executionEnv.nodeVersion (${executionEnvNodeVersion}) were found; useNodeVersion takes precedence.`);
+	return useNodeVersion || executionEnvNodeVersion;
+}
+/**
+* Normalize settings according to the selected compatibility target.
+*
+* @param incomingSettings - Settings to normalize in place
+* @param options - Compatibility target and normalization context
+*
+* @returns Normalization result, extracted runtime version, and warnings
+*/
+async function normalizeIncomingSettings(incomingSettings, options) {
+	const { compatibility, cwd, replaceDeprecated } = options;
+	const before = JSON.stringify(incomingSettings);
+	const warnings = [];
+	if (compatibility === "v10" && !replaceDeprecated) return {
+		changed: false,
+		warnings
+	};
+	if (incomingSettings.allowNonAppliedPatches !== void 0) incomingSettings.allowUnusedPatches ??= incomingSettings.allowNonAppliedPatches;
+	const allowBuildsFromLegacy = await collectAllowBuildsFromLegacy(incomingSettings, cwd);
+	if (allowBuildsFromLegacy) incomingSettings.allowBuilds = {
+		...allowBuildsFromLegacy,
+		...incomingSettings.allowBuilds || {}
+	};
+	if (compatibility === "v10") {
+		for (const key of PNPM_REPLACEABLE_IN_V10_SETTINGS) Reflect.deleteProperty(incomingSettings, key);
+		return {
+			changed: before !== JSON.stringify(incomingSettings),
+			warnings
+		};
 	}
+	const pmOnFail = resolvePmOnFail(incomingSettings);
+	if (pmOnFail) incomingSettings.pmOnFail = pmOnFail;
+	normalizeAuditConfig(incomingSettings, warnings);
+	const runtimeVersion = resolveRuntimeVersion(incomingSettings, warnings);
+	if (incomingSettings.ignoreDepScripts !== void 0) warnings.push("ignoreDepScripts was removed in pnpm v11 and has no direct replacement.");
+	if (incomingSettings.ignorePatchFailures !== void 0) warnings.push("ignorePatchFailures was removed in pnpm v11; patch failures now always throw.");
+	for (const key of PNPM_V11_REMOVED_SETTINGS) Reflect.deleteProperty(incomingSettings, key);
+	return {
+		changed: before !== JSON.stringify(incomingSettings),
+		runtimeVersion,
+		warnings
+	};
 }
+//#endregion
+//#region src/utils/compatibility-runtime.ts
+/**
+* Move a removed Node.js runtime setting to `package.json#devEngines.runtime`.
+*
+* @param packageJson - Package manifest to update in place
+* @param runtimeVersion - Node.js runtime version extracted from pnpm settings
+*
+* @returns Migration result indicating whether the manifest changed
+*/
+function migrateRuntimeToPackageJson(packageJson, runtimeVersion) {
+	if (!runtimeVersion) return { changed: false };
+	if (packageJson.devEngines?.runtime) return {
+		changed: false,
+		warning: "A devEngines.runtime declaration already exists; the removed pnpm Node.js runtime setting was not applied."
+	};
+	packageJson.devEngines = {
+		...packageJson.devEngines,
+		runtime: {
+			name: "node",
+			version: runtimeVersion
+		}
+	};
+	return { changed: true };
+}
+/**
+* Select the runtime setting that wins under the configured merge strategy.
+*
+* @param existingVersion - Runtime version from existing workspace settings
+* @param incomingVersion - Runtime version from incoming settings
+* @param strategy - Merge strategy controlling value precedence
+*
+* @returns Selected runtime version, or `undefined` when neither source has one
+*/
+function resolveRuntimeVersionByStrategy(existingVersion, incomingVersion, strategy) {
+	if (strategy === "overwrite") return incomingVersion ?? existingVersion;
+	return existingVersion ?? incomingVersion;
+}
+//#endregion
+//#region src/utils/compatibility-target.ts
+/**
+* pnpm major version that introduced the v11 settings schema.
+*/
+const PNPM_V11_MAJOR = 11;
+/**
+* pnpm major version that introduced the v12 compatibility target.
+*/
+const PNPM_V12_MAJOR = 12;
+/**
+* Resolve final compatibility target from user option and package manager hint.
+*
+* @param compatibility - Explicit or automatically detected compatibility target
+* @param packageManager - `packageManager` declaration from `package.json`
+* @param devPackageManager - Package manager declaration from `devEngines`
+*
+* @returns Resolved concrete compatibility target
+*/
+function resolveCompatibilityTarget(compatibility, packageManager, devPackageManager) {
+	if (compatibility !== "auto") return compatibility;
+	const match = (packageManager || (devPackageManager?.name === "pnpm" ? `pnpm@${devPackageManager.version}` : void 0))?.match(/^pnpm@[\s<=>^~]*(?<major>\d+)(?:\.|\s|$)/u);
+	const major = Number(match?.groups?.major);
+	if (major >= PNPM_V12_MAJOR) return "v12";
+	return major >= PNPM_V11_MAJOR ? "v11" : "v10";
+}
+//#endregion
+//#region src/utils/merge.ts
 /**
 * Merge objects with priority to the first argument.
 * Only adds keys from second argument that don't exist in first.
@@ -314,8 +524,43 @@ function mergeWithArrayDedupe(existing, incoming) {
 	}
 	return result;
 }
+/**
+* Merge two objects based on the specified strategy.
+*
+* @param existing - Existing pnpm-workspace.yaml content
+* @param incoming - New settings from package.json and .npmrc
+* @param strategy - Merge strategy to use
+*
+* @returns Merged pnpm workspace configuration
+*
+* @example
+* ```ts
+* // Discard strategy - keep existing values
+* mergeByStrategy({ packages: ['a'] }, { packages: ['b'] }, 'discard')
+* // => { packages: ['a'] }
+*
+* // Merge strategy - combine arrays with deduplication
+* mergeByStrategy({ packages: ['a'] }, { packages: ['b'] }, 'merge')
+* // => { packages: ['a', 'b'] }
+*
+* // Overwrite strategy - use incoming values
+* mergeByStrategy({ packages: ['a'] }, { packages: ['b'] }, 'overwrite')
+* // => { packages: ['b'] }
+* ```
+*/
+function mergeByStrategy(existing, incoming, strategy) {
+	switch (strategy) {
+		case "discard": return discardMerge(existing, incoming);
+		case "merge": return mergeWithArrayDedupe(existing, incoming);
+		case "overwrite": return discardMerge(incoming, existing);
+		default: return defu(existing, incoming);
+	}
+}
 //#endregion
 //#region src/utils/npmrc.ts
+/**
+* Authentication and registry keys that must remain in `.npmrc`.
+*/
 const NPMRC_AUTH_OR_REGISTRY_KEYS = [
 	"_auth",
 	"_authtoken",
@@ -333,6 +578,48 @@ const NPMRC_AUTH_OR_REGISTRY_KEYS = [
 	"username"
 ];
 /**
+* Pattern for pnpm's channel-specific Node.js mirror keys.
+*/
+const NODE_MIRROR_KEY_PATTERN = /^node-mirror:(?<channel>.+)$/iu;
+/**
+* Normalize `.npmrc` key for case-insensitive matching.
+*
+* @param key - Raw `.npmrc` key
+*
+* @returns Trimmed lower-case key without an array suffix
+*/
+function normalizeNpmrcKey(key) {
+	return key.trim().replace(/\[\]$/u, "").toLowerCase();
+}
+/**
+* Extract key name from a raw `.npmrc` line.
+*
+* @param line - Raw line from an `.npmrc` file
+*
+* @returns Normalized key, or `undefined` for comments and invalid lines
+*/
+function getNpmrcLineKey(line) {
+	const trimmed = line.trim();
+	if (!trimmed || trimmed.startsWith(";") || trimmed.startsWith("#")) return;
+	const index = trimmed.indexOf("=");
+	if (index <= 0) return;
+	return normalizeNpmrcKey(trimmed.slice(0, index));
+}
+/**
+* Check whether a `.npmrc` key is auth/registry-related and should stay in
+* pnpm v11 and newer.
+*
+* @param key - Raw or normalized `.npmrc` key
+*
+* @returns `true` when the key must remain in `.npmrc`
+*/
+function isNpmrcAuthOrRegistryKey(key) {
+	const normalized = normalizeNpmrcKey(key);
+	if (normalized.startsWith("//")) return true;
+	if (normalized === "registry" || normalized.endsWith(":registry")) return true;
+	return NPMRC_AUTH_OR_REGISTRY_KEYS.some((authKey) => normalized === authKey || normalized.endsWith(`:${authKey}`));
+}
+/**
 * Remove pnpm-related settings from `.npmrc` file.
 *
 * This function reads the `.npmrc` file, filters out all lines that start with
@@ -340,6 +627,8 @@ const NPMRC_AUTH_OR_REGISTRY_KEYS = [
 * writes the cleaned content back to the file.
 *
 * @param path - Absolute path to the `.npmrc` file
+* @param compatibility - Concrete pnpm compatibility target
+* @param migratedKeys - Original `.npmrc` keys that were migrated
 *
 * @returns A promise that resolves when the file has been pruned
 *
@@ -351,87 +640,261 @@ const NPMRC_AUTH_OR_REGISTRY_KEYS = [
 * ```
 */
 async function pruneNpmrc(path, compatibility = "v10", migratedKeys = []) {
-	const pnpmSettingsFields = PNPM_SETTINGS_FIELDS.map((v) => kebabCase(v));
+	const pnpmSettingsFields = PNPM_SETTINGS_FIELDS.map((field) => kebabCase(field));
 	const migratedKeySet = new Set(migratedKeys.map(normalizeNpmrcKey));
-	await fsWriteFile(path, (await fsReadFile(path)).split(/\r?\n/).filter((line) => {
+	const updatedContent = (await fsReadFile(path)).split(/\r?\n/u).filter((line) => {
 		const key = getNpmrcLineKey(line);
 		if (!key) return true;
-		if (compatibility === "v11") return !migratedKeySet.has(normalizeNpmrcKey(key));
-		return !pnpmSettingsFields.some((v) => key.startsWith(v));
-	}).join("\n"));
+		if (compatibility !== "v10") return !migratedKeySet.has(normalizeNpmrcKey(key));
+		return !pnpmSettingsFields.some((field) => key.startsWith(field));
+	}).join("\n").trimEnd();
+	if (compatibility !== "v10" && !updatedContent.trim()) {
+		await fsRemoveFile(path);
+		return;
+	}
+	await fsWriteFile(path, updatedContent);
 }
 /**
-* Read and parse `.npmrc` file with camelCase key conversion.
+* Read `.npmrc` and return settings that should be migrated into workspace config.
 *
-* This function reads an `.npmrc` INI-format file and parses it into an object.
-* All keys are automatically converted from kebab-case to camelCase for easier
-* JavaScript consumption (e.g., `allow-builds` → `allowBuilds`).
+* - `v10`: returns settings from the legacy whitelist.
+* - `v11+`: excludes auth/registry keys because pnpm still reads them from
+*   `.npmrc`.
 *
 * @param path - Absolute path to the `.npmrc` file
+* @param compatibility - Concrete pnpm compatibility target
 *
-* @returns A promise that resolves to the parsed `.npmrc` configuration object with camelCase keys
+* @returns Migratable settings and their original `.npmrc` keys
 *
 * @throws {Error} When file reading or INI parsing fails
-*
-* @example
-* ```ts
-* const config = await readNpmrc('/path/to/.npmrc')
-* // config.allowBuilds, config.packageExtensions, etc.
-* ```
-*/
-/**
-* Read `.npmrc` and return settings that should be migrated into workspace config.
-*
-* - `v10`: returns all keys (legacy whitelist filtering happens in caller).
-* - `v11`: excludes auth/registry keys because pnpm still reads them from `.npmrc`.
 */
 async function readMigratableNpmrc(path, compatibility) {
 	const raw = await readIniFile(path);
-	if (compatibility === "v10") return {
-		keys: Object.keys(raw),
-		settings: camelcaseKeys(raw)
-	};
+	if (compatibility === "v10") {
+		const settings = camelcaseKeys(raw);
+		return {
+			keys: PNPM_SETTINGS_FIELDS,
+			settings: pick(settings, PNPM_SETTINGS_FIELDS)
+		};
+	}
 	const migratable = {};
 	const keys = [];
+	const nodeDownloadMirrors = {};
 	for (const [key, value] of Object.entries(raw)) if (!isNpmrcAuthOrRegistryKey(key)) {
-		migratable[key] = value;
 		keys.push(key);
+		const nodeMirrorMatch = normalizeNpmrcKey(key).match(NODE_MIRROR_KEY_PATTERN);
+		if (nodeMirrorMatch?.groups?.channel) nodeDownloadMirrors[nodeMirrorMatch.groups.channel] = String(value);
+		else migratable[key] = value;
 	}
+	const settings = camelcaseKeys(migratable);
+	if (Object.keys(nodeDownloadMirrors).length) settings.nodeDownloadMirrors = nodeDownloadMirrors;
 	return {
 		keys,
-		settings: camelcaseKeys(migratable)
+		settings
 	};
 }
-async function readNpmrc(path) {
-	return camelcaseKeys(await readIniFile(path));
+//#endregion
+//#region src/utils/settings-change.ts
+/**
+* Collect changed root settings between two workspace configurations.
+*
+* @param before - Workspace settings before migration
+* @param after - Workspace settings after migration
+*
+* @returns Changed root settings with their before and after values
+*/
+function collectSettingsChanges(before, after) {
+	const beforeSettings = { ...before };
+	const afterSettings = { ...after };
+	const keys = /* @__PURE__ */ new Set([...Object.keys(beforeSettings), ...Object.keys(afterSettings)]);
+	return Array.from(keys).filter((key) => !isDeepStrictEqual(beforeSettings[key], afterSettings[key])).map((key) => ({
+		after: afterSettings[key],
+		before: beforeSettings[key],
+		key
+	}));
 }
 /**
-* Extract key name from a raw `.npmrc` line.
+* Create a line-based diff using the longest common subsequence.
+*
+* @param beforeLines - YAML lines before migration
+* @param afterLines - YAML lines after migration
+*
+* @returns Classified diff lines in display order
 */
-function getNpmrcLineKey(line) {
-	const trimmed = line.trim();
-	if (!trimmed || trimmed.startsWith(";") || trimmed.startsWith("#")) return;
-	const index = trimmed.indexOf("=");
-	if (index <= 0) return;
-	return normalizeNpmrcKey(trimmed.slice(0, index));
+function createLineDiff(beforeLines, afterLines) {
+	const lengths = Array.from({ length: beforeLines.length + 1 }, () => Array(afterLines.length + 1).fill(0));
+	for (let beforeIndex = beforeLines.length - 1; beforeIndex >= 0; beforeIndex--) for (let afterIndex = afterLines.length - 1; afterIndex >= 0; afterIndex--) lengths[beforeIndex][afterIndex] = beforeLines[beforeIndex] === afterLines[afterIndex] ? lengths[beforeIndex + 1][afterIndex + 1] + 1 : Math.max(lengths[beforeIndex + 1][afterIndex], lengths[beforeIndex][afterIndex + 1]);
+	const diff = [];
+	let beforeIndex = 0;
+	let afterIndex = 0;
+	while (beforeIndex < beforeLines.length && afterIndex < afterLines.length) if (beforeLines[beforeIndex] === afterLines[afterIndex]) {
+		diff.push({
+			kind: "unchanged",
+			value: beforeLines[beforeIndex]
+		});
+		beforeIndex++;
+		afterIndex++;
+	} else if (lengths[beforeIndex + 1][afterIndex] >= lengths[beforeIndex][afterIndex + 1]) {
+		diff.push({
+			kind: "removed",
+			value: beforeLines[beforeIndex]
+		});
+		beforeIndex++;
+	} else {
+		diff.push({
+			kind: "added",
+			value: afterLines[afterIndex]
+		});
+		afterIndex++;
+	}
+	while (beforeIndex < beforeLines.length) {
+		diff.push({
+			kind: "removed",
+			value: beforeLines[beforeIndex]
+		});
+		beforeIndex++;
+	}
+	while (afterIndex < afterLines.length) {
+		diff.push({
+			kind: "added",
+			value: afterLines[afterIndex]
+		});
+		afterIndex++;
+	}
+	return diff;
 }
 /**
-* Check whether a `.npmrc` key is auth/registry-related and should stay in v11.
+* Format one root setting as YAML lines.
+*
+* @param key - Root setting key
+* @param value - Setting value, or `undefined` when the key is absent
+*
+* @returns YAML lines for the setting, or an empty array when absent
 */
-function isNpmrcAuthOrRegistryKey(key) {
-	const normalized = normalizeNpmrcKey(key);
-	if (normalized.startsWith("//")) return true;
-	if (normalized === "registry" || normalized.endsWith(":registry")) return true;
-	return NPMRC_AUTH_OR_REGISTRY_KEYS.some((v) => normalized === v || normalized.endsWith(`:${v}`));
+function formatSettingLines(key, value) {
+	if (value === void 0) return [];
+	return stringify({ [key]: value }).trimEnd().split("\n");
 }
 /**
-* Normalize `.npmrc` key for case-insensitive matching.
+* Format a setting change as a GitHub-style YAML diff.
+*
+* @param change - Root setting change to format
+*
+* @returns Classified YAML diff lines
 */
-function normalizeNpmrcKey(key) {
-	return key.trim().replace(/\[\]$/, "").toLowerCase();
+function createSettingsDiffLines(change) {
+	return createLineDiff(formatSettingLines(change.key, change.before), formatSettingLines(change.key, change.after));
+}
+/**
+* Print a summary and GitHub-style YAML diff for every changed setting.
+*
+* @param changes - Root setting changes to report
+*
+* @returns Nothing; output is written through consola
+*/
+function reportSettingsChanges(changes) {
+	consola$1.info(`${changes.length} ${changes.length === 1 ? "setting" : "settings"} changed`);
+	for (const [index, change] of changes.entries()) {
+		if (index > 0) consola$1.log("");
+		for (const line of createSettingsDiffLines(change)) if (line.kind === "added") consola$1.log(green(`+ ${line.value}`));
+		else if (line.kind === "removed") consola$1.log(red(`- ${line.value}`));
+		else consola$1.log(dim(`  ${line.value}`));
+	}
+}
+//#endregion
+//#region src/utils/config.ts
+/**
+* Resolve the indentation width for a YAML document.
+*
+* @param content - Raw YAML content
+*
+* @returns Detected indentation width or the project default
+*/
+function resolveYamlIndent(content) {
+	const detectedIndent = detectIndent(content).amount;
+	return detectedIndent > 0 ? detectedIndent : 2;
+}
+/**
+* Read and parse a package manifest when it exists.
+*
+* @param path - Absolute path to `package.json`
+* @param exists - Whether the package manifest exists
+*
+* @returns Parsed package manifest and detected indentation
+*
+* @throws {SyntaxError} When the package manifest contains invalid JSON
+*/
+async function readPackageJson(path, exists) {
+	if (!exists) return {
+		indent: 2,
+		value: {}
+	};
+	const content = await fsReadFile(path);
+	return {
+		indent: detectIndent(content).indent,
+		value: JSON.parse(content)
+	};
+}
+/**
+* Read and parse a pnpm workspace manifest when it exists.
+*
+* @param path - Absolute path to `pnpm-workspace.yaml`
+* @param exists - Whether the workspace manifest exists
+*
+* @returns Parsed workspace settings and detected indentation
+*
+* @throws {Error} When the workspace manifest contains invalid YAML
+*/
+async function readPnpmWorkspace(path, exists) {
+	if (!exists) return {
+		indent: 2,
+		value: {}
+	};
+	const content = await fsReadFile(path);
+	return {
+		indent: resolveYamlIndent(content),
+		value: parse(content) ?? {}
+	};
+}
+/**
+* Resolve migratable pnpm settings from a package manifest.
+*
+* Yarn resolutions are merged into pnpm overrides when enabled. Empty
+* overrides are removed from the result.
+*
+* @param packageJson - Parsed package manifest
+* @param yarnResolutions - Whether to convert Yarn resolutions to pnpm overrides
+*
+* @returns Pnpm workspace settings resolved from the package manifest
+*/
+function resolvePackageJsonSettings(packageJson, yarnResolutions) {
+	const pnpmSettings = yarnResolutions && packageJson.resolutions ? {
+		...packageJson.pnpm,
+		overrides: defu(packageJson.pnpm?.overrides, packageJson.resolutions)
+	} : { ...packageJson.pnpm };
+	if (pnpmSettings.overrides && !Object.keys(pnpmSettings.overrides).length) delete pnpmSettings.overrides;
+	return pnpmSettings;
 }
 //#endregion
 //#region src/core.ts
+function hasSettingsSources(npmrcExists, packageJsonExists, pnpmWorkspaceExists) {
+	if (!npmrcExists) consola$1.info(`${dim(NPMRC)} not found`);
+	if (!packageJsonExists) consola$1.info(`${dim(PACKAGE_JSON)} not found`);
+	if (npmrcExists || packageJsonExists || pnpmWorkspaceExists) return true;
+	consola$1.warn("No pnpm settings files to migrate");
+	return false;
+}
+function hasMigratableSettings(sources) {
+	const { existingSettingsChanged, packageJson, pnpmSettingsInNpmrc, yarnResolutions } = sources;
+	return Boolean(existingSettingsChanged || packageJson.pnpm || yarnResolutions && packageJson.resolutions || Object.keys(pnpmSettingsInNpmrc).length);
+}
+function assertCanMigrateRuntime(runtimeVersion, packageJsonExists) {
+	if (runtimeVersion && !packageJsonExists) throw new Error("Cannot migrate the removed Node.js runtime setting without a package.json file.");
+}
+function reportMigrationChanges(showChanges, before = {}, after = {}) {
+	if (!showChanges) return;
+	reportSettingsChanges(collectSettingsChanges(before, after));
+}
 /**
 * Migrate pnpm settings from legacy locations to `pnpm-workspace.yaml`.
 *
@@ -440,6 +903,7 @@ function normalizeNpmrcKey(key) {
 * - `package.json` pnpm field
 * - `.npmrc` pnpm-related settings
 * - `package.json` resolutions (optional, converts to pnpm overrides)
+* - deprecated settings already present in `pnpm-workspace.yaml`
 *
 * @param rawOptions - Migration options
 * @param rawOptions.cwd - Current working directory (default: process.cwd())
@@ -448,6 +912,7 @@ function normalizeNpmrcKey(key) {
 * @param rawOptions.yarnResolutions - Whether to migrate resolutions field (default: true)
 * @param rawOptions.sortKeys - Whether to sort keys in output YAML (default: false)
 * @param rawOptions.newlineBetween - Add newlines between root keys (default: true)
+* @param rawOptions.showChanges - Show settings changes after migration (default: true)
 *
 * @returns A promise that resolves when migration is complete
 *
@@ -477,53 +942,48 @@ async function migratePnpmSettings(rawOptions = {}) {
 			fsExists(packageJsonPath),
 			fsExists(pnpmWorkspaceYamlPath)
 		]);
-		if (!npmrcExists) consola$1.info(`${dim(NPMRC)} not found`);
-		if (!packageJsonExists) consola$1.info(`${dim(PACKAGE_JSON)} not found`);
-		if (!npmrcExists && !packageJsonExists) {
-			consola$1.warn("No pnpm settings files to migrate");
+		if (!hasSettingsSources(npmrcExists, packageJsonExists, pnpmWorkspaceExists)) {
+			reportMigrationChanges(options.showChanges);
 			return;
 		}
-		let packageJsonIndent = 2;
-		let packageJsonObject = {};
-		let pnpmWorkspaceYamlIndent = 2;
-		let pnpmWorkspaceYamlObject = {};
-		if (packageJsonExists) {
-			const content = await fsReadFile(packageJsonPath);
-			packageJsonIndent = detectIndent(content).indent;
-			packageJsonObject = JSON.parse(content);
-		}
-		if (pnpmWorkspaceExists) {
-			const content = await fsReadFile(pnpmWorkspaceYamlPath);
-			pnpmWorkspaceYamlIndent = resolveYamlIndent(content);
-			pnpmWorkspaceYamlObject = parse(content) ?? {};
-		}
-		const compatibility = resolveCompatibilityTarget(options.compatibility, packageJsonObject.packageManager);
-		const npmrcMigratable = npmrcExists ? compatibility === "v10" ? {
-			keys: PNPM_SETTINGS_FIELDS,
-			settings: pick(await readNpmrc(npmrcPath), PNPM_SETTINGS_FIELDS)
-		} : await readMigratableNpmrc(npmrcPath, compatibility) : {
+		const [packageJson, pnpmWorkspace] = await Promise.all([readPackageJson(packageJsonPath, packageJsonExists), readPnpmWorkspace(pnpmWorkspaceYamlPath, pnpmWorkspaceExists)]);
+		const pnpmWorkspaceBefore = structuredClone(pnpmWorkspace.value);
+		const compatibility = resolveCompatibilityTarget(options.compatibility, packageJson.value.packageManager, packageJson.value.devEngines?.packageManager);
+		const npmrcMigratable = npmrcExists ? await readMigratableNpmrc(npmrcPath, compatibility) : {
 			keys: [],
 			settings: {}
 		};
 		const pnpmSettingsInNpmrc = npmrcMigratable.settings;
-		const hasPnpmInPackageJson = !!packageJsonObject.pnpm;
-		const hasResolutions = options.yarnResolutions && !!packageJsonObject.resolutions;
-		const hasNpmrcSettings = Object.keys(pnpmSettingsInNpmrc).length > 0;
-		if (!hasPnpmInPackageJson && !hasResolutions && !hasNpmrcSettings) {
-			consola$1.warn("No pnpm settings fields to migrate");
-			return;
-		}
-		const pnpmSettingsInPackageJson = options.yarnResolutions && packageJsonObject.resolutions ? {
-			...packageJsonObject.pnpm,
-			overrides: defu(packageJsonObject.pnpm?.overrides, packageJsonObject.resolutions)
-		} : { ...packageJsonObject.pnpm };
-		if (pnpmSettingsInPackageJson.overrides && !Object.keys(pnpmSettingsInPackageJson.overrides).length) delete pnpmSettingsInPackageJson.overrides;
+		const pnpmSettingsInPackageJson = resolvePackageJsonSettings(packageJson.value, options.yarnResolutions);
 		const incomingSettings = {
 			...pnpmSettingsInNpmrc,
 			...pnpmSettingsInPackageJson
 		};
-		normalizeIncomingSettings(incomingSettings, compatibility, options.replaceDeprecated);
-		const pnpmWorkspaceResult = mergeByStrategy(pnpmWorkspaceYamlObject, incomingSettings, options.strategy);
+		const [existingNormalization, incomingNormalization] = await Promise.all([normalizeIncomingSettings(pnpmWorkspace.value, {
+			compatibility,
+			cwd: options.cwd,
+			replaceDeprecated: options.replaceDeprecated
+		}), normalizeIncomingSettings(incomingSettings, {
+			compatibility,
+			cwd: options.cwd,
+			replaceDeprecated: options.replaceDeprecated
+		})]);
+		for (const warning of [...existingNormalization.warnings, ...incomingNormalization.warnings]) consola$1.warn(warning);
+		const runtimeVersion = resolveRuntimeVersionByStrategy(existingNormalization.runtimeVersion, incomingNormalization.runtimeVersion, options.strategy);
+		assertCanMigrateRuntime(runtimeVersion, packageJsonExists);
+		const runtimeMigration = migrateRuntimeToPackageJson(packageJson.value, runtimeVersion);
+		if (runtimeMigration.warning) consola$1.warn(runtimeMigration.warning);
+		if (!hasMigratableSettings({
+			existingSettingsChanged: existingNormalization.changed,
+			packageJson: packageJson.value,
+			pnpmSettingsInNpmrc,
+			yarnResolutions: options.yarnResolutions
+		})) {
+			consola$1.warn("No pnpm settings fields to migrate");
+			reportMigrationChanges(options.showChanges);
+			return;
+		}
+		const pnpmWorkspaceResult = mergeByStrategy(pnpmWorkspace.value, incomingSettings, options.strategy);
 		const yamlDocument = new Document({}, { sortMapEntries: options.sortKeys });
 		Object.entries(pnpmWorkspaceResult).forEach(([key, value]) => {
 			yamlDocument.add({
@@ -531,58 +991,29 @@ async function migratePnpmSettings(rawOptions = {}) {
 				value
 			});
 		});
-		const yamlContent = yamlDocument.toString({ indent: pnpmWorkspaceYamlIndent });
-		await fsWriteFile(pnpmWorkspaceYamlPath, options.newlineBetween ? yamlContent.replace(/\n(?=[^\s#][^:\n]*:)/g, "\n\n") : yamlContent);
+		const yamlContent = yamlDocument.toString({ indent: pnpmWorkspace.indent });
+		await fsWriteFile(pnpmWorkspaceYamlPath, options.newlineBetween ? yamlContent.replace(/\n(?=[^\s#][^:\n]*:)/gu, "\n\n") : yamlContent);
 		if (npmrcExists && options.cleanNpmrc) await pruneNpmrc(npmrcPath, compatibility, npmrcMigratable.keys);
-		if (packageJsonExists && options.cleanPackageJson && (packageJsonObject.pnpm || packageJsonObject.resolutions)) {
-			delete packageJsonObject.pnpm;
-			if (options.yarnResolutions) delete packageJsonObject.resolutions;
-			await fsWriteFile(packageJsonPath, JSON.stringify(packageJsonObject, null, packageJsonIndent));
+		let packageJsonChanged = runtimeMigration.changed;
+		if (packageJsonExists && options.cleanPackageJson) {
+			if (packageJson.value.pnpm) packageJsonChanged = true;
+			delete packageJson.value.pnpm;
+			if (options.yarnResolutions && packageJson.value.resolutions) {
+				packageJsonChanged = true;
+				delete packageJson.value.resolutions;
+			}
 		}
+		if (packageJsonExists && packageJsonChanged) await fsWriteFile(packageJsonPath, JSON.stringify(packageJson.value, null, packageJson.indent));
+		reportMigrationChanges(options.showChanges, pnpmWorkspaceBefore, pnpmWorkspaceResult);
 	} catch (err) {
 		consola$1.error("Failed to migrate pnpm settings:", err);
 		throw err;
 	}
 }
-/**
-* Build v11 `allowBuilds` map from legacy build-script settings.
-*/
-function collectAllowBuildsFromLegacy(incomingSettings) {
-	const allowBuilds = {};
-	for (const name of incomingSettings.onlyBuiltDependencies || []) allowBuilds[name] = true;
-	for (const name of incomingSettings.ignoredBuiltDependencies || []) allowBuilds[name] = false;
-	for (const name of incomingSettings.neverBuiltDependencies || []) allowBuilds[name] = false;
-	return Object.keys(allowBuilds).length ? allowBuilds : void 0;
-}
-/**
-* Normalize incoming settings according to compatibility target.
-*/
-function normalizeIncomingSettings(incomingSettings, compatibility, replaceDeprecated) {
-	if (compatibility === "v10" && !replaceDeprecated) return;
-	if (incomingSettings.allowNonAppliedPatches !== void 0) incomingSettings.allowUnusedPatches = incomingSettings.allowUnusedPatches ?? incomingSettings.allowNonAppliedPatches;
-	const allowBuildsFromLegacy = collectAllowBuildsFromLegacy(incomingSettings);
-	if (allowBuildsFromLegacy) incomingSettings.allowBuilds = {
-		...allowBuildsFromLegacy,
-		...incomingSettings.allowBuilds || {}
-	};
-	for (const key of PNPM_V11_REMOVED_SETTINGS) delete incomingSettings[key];
-}
-/**
-* Resolve final compatibility target from user option and package manager hint.
-*/
-function resolveCompatibilityTarget(compatibility, packageManager) {
-	if (compatibility !== "auto") return compatibility;
-	const [, major] = (packageManager || "").match(/^pnpm@(\d+)(?:\.|$)/) || [];
-	return Number(major) >= 11 ? "v11" : "v10";
-}
-function resolveYamlIndent(content) {
-	const detectedIndent = detectIndent(content).amount;
-	return detectedIndent > 0 ? detectedIndent : 2;
-}
 //#endregion
 //#region src/cli.ts
 const cli = cac(name);
-cli.version(version).option("--cwd [cwd]", "Current working directory").option("--sort-keys", "Sort keys when write pnpm-workspace.yaml").option("--compatibility <compatibility>", "Compatibility target (auto, v10, v11)").option("--replace-deprecated", "Replace deprecated pnpm settings with new ones and remove old keys").option("--strategy <strategy>", "Strategy to handle conflicts (discard, merge, overwrite)").option("--no-yarn-resolutions", "Disable migrating resolutions field in package.json").option("--no-newline-between", "Disable adding newlines between each root keys").option("--no-clean-npmrc", "Disable removing pnpm settings in .npmrc file").option("--no-clean-package-json", "Disable removing pnpm fields in package.json").help();
+cli.version(version).option("--cwd [cwd]", "Current working directory").option("--sort-keys", "Sort keys when write pnpm-workspace.yaml").option("--compatibility <compatibility>", "Compatibility target (auto, v10, v11, v12)").option("--replace-deprecated", "Replace deprecated pnpm settings with new ones and remove old keys").option("--strategy <strategy>", "Strategy to handle conflicts (discard, merge, overwrite)").option("--no-yarn-resolutions", "Disable migrating resolutions field in package.json").option("--no-newline-between", "Disable adding newlines between each root keys").option("--no-show-changes", "Disable showing settings changes").option("--no-clean-npmrc", "Disable removing pnpm settings in .npmrc file").option("--no-clean-package-json", "Disable removing pnpm fields in package.json").help();
 cli.command("").action(async (options) => {
 	try {
 		consola.log(`\n${bold(magenta(name))} ${dim(`v${version}`)}`);