pnpm-settings-migrator 0.8.0 → 0.8.1

package/README.md

@@ -57,8 +57,8 @@ Compatibility target for migrated settings:
 - `v10`: keep legacy settings as-is and migrate schema-aligned pnpm config keys from `.npmrc`
 - `v11`: normalize to v11-compatible settings (`allowBuilds`, `allowUnusedPatches`, etc.)
   and migrate all non auth/registry `.npmrc` entries to `pnpm-workspace.yaml`
-- `v12`: apply the same settings migration as `v11`. pnpm 12 keeps pnpm 11's
-  settings and lockfile format.
+- `v12`: use the same settings-key migration as `v11`. Lockfile migration and
+  validation are outside this tool's scope.
 
 In `v11` and `v12` modes, normalization is applied both to settings read from
 legacy files and to deprecated settings already present in

package/dist/cli.mjs

@@ -1,87 +1,133 @@
 import process from "node:process";
-import { cac } from "cac";
 import consola$1, { consola } from "consola";
-import { resolve } from "pathe";
-import { Document, parse, stringify } from "yaml";
-import { access, readFile, rm, writeFile } from "node:fs/promises";
+import { cac } from "cac";
+import { basename, dirname, join, resolve } from "pathe";
+import { randomUUID } from "node:crypto";
+import { access, chmod, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 import { getColor } from "consola/utils";
-import { isPlainObject, isUndefined, pick } from "@ntnyq/utils";
+import { isPlainObject, isUndefined } 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 { Document, isMap, isNode, isScalar, isSeq, parseDocument, stringify } from "yaml";
 import detectIndent from "detect-indent";
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.8.0";
+var version = "0.8.1";
+//#endregion
+//#region src/cli-options.ts
+/**
+* Create the command-line parser shared by the executable and parser tests.
+*/
+function createCli() {
+	const cli = cac(name).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");
+	cli.help((sections) => {
+		if (!(cli.commands.length > 0 && cli.commands.every((command) => command.isDefaultCommand))) return sections;
+		return sections.filter((section) => section.title !== "Commands" && !section.title?.startsWith("For more info"));
+	});
+	return cli;
+}
 //#endregion
 //#region src/constants.ts
 const NPMRC = ".npmrc";
 const PACKAGE_JSON = "package.json";
 const PNPM_WORKSPACE_YAML = "pnpm-workspace.yaml";
 /**
-* @see {@link https://github.com/pnpm/pnpm/blob/main/packages/types/src/package.ts}
-* Schema-aligned pnpm config fields that can be migrated from `.npmrc`.
+* @see {@link https://pnpm.io/10.x/settings}
+* Documented pnpm v10 config fields that can be migrated from `.npmrc`.
 *
 * Intentionally excluded workspace manifest-only fields:
 * - `catalog`
-* - `catalogMode`
 * - `catalogs`
-* - `cleanupUnusedCatalogs`
 * - `packages`
 */
-const PNPM_SETTINGS_FIELDS = [
+const PNPM_V10_NPMRC_SETTINGS_FIELDS = [
 	"allowBuilds",
 	"allowedDeprecatedVersions",
 	"allowNonAppliedPatches",
 	"allowUnusedPatches",
 	"auditConfig",
+	"auditLevel",
+	"autoInstallPeers",
+	"blockExoticSubdeps",
+	"cacheDir",
+	"catalogMode",
+	"childConcurrency",
+	"ci",
+	"cleanupUnusedCatalogs",
+	"color",
 	"configDependencies",
+	"dangerouslyAllowAllBuilds",
 	"dedupeDirectDeps",
 	"dedupeInjectedDeps",
 	"dedupePeerDependents",
 	"deployAllFiles",
+	"disallowWorkspaceCycles",
+	"dlxCacheMaxAge",
+	"enableGlobalVirtualStore",
+	"enableModulesDir",
+	"enablePrePostScripts",
 	"engineStrict",
 	"executionEnv",
+	"extendNodePath",
+	"failIfNoMatch",
 	"fetchMinSpeedKiBps",
+	"fetchRetries",
 	"fetchRetryFactor",
 	"fetchRetryMaxtimeout",
 	"fetchRetryMintimeout",
-	"fetchRetryTimeout",
+	"fetchTimeout",
 	"fetchWarnTimeoutMs",
 	"forceLegacyDeploy",
+	"frozenLockfile",
+	"gitBranchLockfile",
 	"gitChecks",
 	"gitShallowHosts",
-	"globalVirtualStore",
+	"globalBinDir",
+	"globalDir",
+	"globalPnpmfile",
 	"globalVirtualStoreDir",
 	"hoist",
 	"hoistPattern",
 	"hoistWorkspacePackages",
 	"httpProxy",
 	"httpsProxy",
+	"ignoreCompatibilityDb",
 	"ignoredBuiltDependencies",
 	"ignoreDepScripts",
-	"ignoreDeps",
 	"ignoredOptionalDependencies",
 	"ignorePatchFailures",
+	"ignorePnpmfile",
+	"ignoreScripts",
 	"ignoreWorkspaceCycles",
+	"ignoreWorkspaceRootCheck",
+	"includeWorkspaceRoot",
 	"injectWorkspacePackages",
 	"linkWorkspacePackages",
+	"localAddress",
 	"lockfile",
 	"lockfileDir",
+	"lockfileIncludeTarballUrl",
+	"loglevel",
 	"managePackageManagerVersions",
+	"maxsockets",
 	"mergeGitBranchLockfiles",
 	"mergeGitBranchLockfilesBranchPattern",
+	"minimumReleaseAge",
+	"minimumReleaseAgeExclude",
 	"modulesCacheMaxAge",
+	"modulesDir",
 	"networkConcurrency",
 	"neverBuiltDependencies",
-	"nodeDownloadMirrors",
 	"nodeLinker",
-	"noproxy",
+	"nodeOptions",
+	"nodeVersion",
 	"noProxy",
+	"noproxy",
 	"npmPath",
-	"npmrcAuthFile",
 	"onlyBuiltDependencies",
 	"onlyBuiltDependenciesFile",
 	"optimisticRepeatInstall",
@@ -95,38 +141,46 @@ const PNPM_SETTINGS_FIELDS = [
 	"peerDependencyRules",
 	"peersSuffixMaxLength",
 	"pnpmfile",
-	"pnpmfileIgnorePkgManifest",
-	"pmOnFail",
 	"preferFrozenLockfile",
+	"preferSymlinkedExecutables",
 	"preferWorkspacePackages",
 	"production",
 	"proxy",
 	"publicHoistPattern",
 	"recursiveInstall",
-	"registries",
+	"registrySupportsTimeField",
 	"requiredScripts",
 	"resolutionMode",
 	"resolvePeersFromWorkspaceRoot",
 	"saveExact",
 	"savePrefix",
+	"saveWorkspaceProtocol",
 	"scriptShell",
 	"shamefullyHoist",
 	"sharedWorkspaceLockfile",
 	"shellEmulator",
 	"sideEffectsCache",
 	"sideEffectsCacheReadonly",
+	"stateDir",
 	"storeDir",
 	"strictDepBuilds",
 	"strictPeerDependencies",
 	"strictSsl",
+	"strictStorePkgContentCheck",
 	"supportedArchitectures",
+	"symlink",
 	"syncInjectedDepsAfterScripts",
 	"tag",
-	"targetDependenciesField",
-	"timeout",
+	"trustPolicy",
+	"trustPolicyExclude",
+	"trustPolicyIgnoreAfter",
+	"unsafePerm",
 	"updateConfig",
+	"updateNotifier",
 	"useBetaCli",
 	"useNodeVersion",
+	"useRunningStoreServer",
+	"useStderr",
 	"verifyDepsBeforeRun",
 	"verifyStoreIntegrity",
 	"virtualStoreDir",
@@ -156,7 +210,6 @@ const DEFAULT_OPTIONS = {
 	cleanNpmrc: true,
 	cleanPackageJson: true,
 	compatibility: "auto",
-	cwd: process.cwd(),
 	newlineBetween: true,
 	replaceDeprecated: false,
 	showChanges: true,
@@ -210,7 +263,7 @@ function resolveOptions(options = {}) {
 	return {
 		cleanNpmrc: options.cleanNpmrc ?? DEFAULT_OPTIONS.cleanNpmrc,
 		compatibility: resolveCompatibility(options.compatibility),
-		cwd: options.cwd ?? DEFAULT_OPTIONS.cwd,
+		cwd: options.cwd ?? process.cwd(),
 		newlineBetween: options.newlineBetween ?? DEFAULT_OPTIONS.newlineBetween,
 		showChanges: options.showChanges ?? DEFAULT_OPTIONS.showChanges,
 		sortKeys: options.sortKeys ?? DEFAULT_OPTIONS.sortKeys,
@@ -223,6 +276,28 @@ function resolveOptions(options = {}) {
 //#endregion
 //#region src/utils/fs.ts
 /**
+* Modulus that isolates Unix permission bits from a stat mode.
+*/
+const FILE_PERMISSION_MODULUS = 512;
+/**
+* Resolve a filesystem path to a string suitable for a sibling temp file.
+*/
+function resolvePathString(path) {
+	if (path instanceof URL) return fileURLToPath(path);
+	return typeof path === "string" ? path : path.toString();
+}
+/**
+* Read an existing file's permission bits, if the file exists.
+*/
+async function resolveExistingMode(path) {
+	try {
+		return (await stat(path)).mode % FILE_PERMISSION_MODULUS;
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+/**
 * Check whether a filesystem path exists.
 *
 * @param path - Filesystem path to check
@@ -261,10 +336,22 @@ async function fsRemoveFile(path) {
 * @returns A promise that resolves after the file is written
 */
 async function fsWriteFile(path, content) {
-	await writeFile(path, `${content.trimEnd()}\n`, "utf-8");
+	const pathString = resolvePathString(path);
+	const temporaryPath = join(dirname(pathString), `.${basename(pathString)}.${process.pid}.${randomUUID()}.tmp`);
+	const mode = await resolveExistingMode(path);
+	try {
+		await writeFile(temporaryPath, `${content.trimEnd()}\n`, {
+			encoding: "utf-8",
+			mode
+		});
+		if (mode !== void 0) await chmod(temporaryPath, mode);
+		await rename(temporaryPath, pathString);
+	} finally {
+		await rm(temporaryPath, { force: true });
+	}
 }
-getColor("cyan");
-getColor("yellow");
+//#endregion
+//#region src/utils/color.ts
 /**
 * Apply dim terminal styling to a value.
 */
@@ -286,27 +373,9 @@ const bold = getColor("bold");
 */
 const magenta = getColor("magenta");
 //#endregion
-//#region src/utils/compatibility.ts
-/**
-* Legacy build settings that can be replaced for pnpm v10.
-*/
-const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
-	"allowNonAppliedPatches",
-	"ignoredBuiltDependencies",
-	"neverBuiltDependencies",
-	"onlyBuiltDependencies",
-	"onlyBuiltDependenciesFile"
-];
+//#region src/utils/legacy-build-settings.ts
 /**
 * Read packages listed by the legacy `onlyBuiltDependenciesFile` setting.
-*
-* @param cwd - Working directory used to resolve the referenced file
-* @param file - Relative path stored in `onlyBuiltDependenciesFile`
-*
-* @returns Package names read from the referenced JSON file
-*
-* @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 [];
@@ -316,21 +385,44 @@ async function readOnlyBuiltDependenciesFile(cwd, file) {
 	return value;
 }
 /**
+* Read and validate one legacy build dependency list. Configuration files are
+* external input, so their runtime shape can differ from its declared type.
+*/
+function readLegacyBuildDependencyList(settings, key) {
+	const value = settings[key];
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+		const npmrcKey = key.replace(/[A-Z]/gu, (character) => `-${character.toLowerCase()}`);
+		throw new TypeError(`Invalid ${key}: expected an array of package names. In .npmrc, use ${npmrcKey}[]=<package>.`);
+	}
+	return value;
+}
+/**
 * Build an `allowBuilds` map from legacy build-script settings.
-*
-* @param incomingSettings - Settings containing legacy build declarations
-* @param cwd - Working directory used to resolve referenced files
-*
-* @returns Package-to-permission map, or `undefined` when no entries exist
 */
 async function collectAllowBuildsFromLegacy(incomingSettings, cwd) {
 	const allowBuilds = {};
+	const allowed = readLegacyBuildDependencyList(incomingSettings, "onlyBuiltDependencies");
+	const ignored = readLegacyBuildDependencyList(incomingSettings, "ignoredBuiltDependencies");
+	const neverBuilt = readLegacyBuildDependencyList(incomingSettings, "neverBuiltDependencies");
 	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;
+	for (const name of [...allowed, ...allowedFromFile]) allowBuilds[name] = true;
+	for (const name of ignored) allowBuilds[name] = false;
+	for (const name of neverBuilt) allowBuilds[name] = false;
 	return Object.keys(allowBuilds).length ? allowBuilds : void 0;
 }
+//#endregion
+//#region src/utils/compatibility.ts
+/**
+* Legacy build settings that can be replaced for pnpm v10.
+*/
+const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
+	"allowNonAppliedPatches",
+	"ignoredBuiltDependencies",
+	"neverBuiltDependencies",
+	"onlyBuiltDependencies",
+	"onlyBuiltDependenciesFile"
+];
 /**
 * Resolve the pnpm v11 replacement for legacy package-manager settings.
 *
@@ -466,6 +558,20 @@ const PNPM_V11_MAJOR = 11;
 */
 const PNPM_V12_MAJOR = 12;
 /**
+* Resolve a pnpm major from a package manager declaration.
+*/
+function resolvePnpmMajor(hint) {
+	const match = hint?.match(/^pnpm@[\s<=>^~]*(?<major>\d+)(?:\.|\s|$)/u);
+	return match?.groups?.major ? Number(match.groups.major) : void 0;
+}
+/**
+* Normalize the single-or-array devEngines declaration.
+*/
+function normalizePackageManagers(value) {
+	if (Array.isArray(value)) return value;
+	return value ? [value] : [];
+}
+/**
 * Resolve final compatibility target from user option and package manager hint.
 *
 * @param compatibility - Explicit or automatically detected compatibility target
@@ -476,10 +582,11 @@ const PNPM_V12_MAJOR = 12;
 */
 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";
+	const packageManagerMajor = resolvePnpmMajor(packageManager);
+	const devPackageManagerMajors = normalizePackageManagers(devPackageManager).filter((item) => item.name === "pnpm").map((item) => resolvePnpmMajor(`pnpm@${item.version ?? ""}`)).filter((major) => major !== void 0);
+	const major = packageManagerMajor ?? (devPackageManagerMajors.length ? Math.max(...devPackageManagerMajors) : void 0);
+	if (major !== void 0 && major >= PNPM_V12_MAJOR) return "v12";
+	return major !== void 0 && major >= PNPM_V11_MAJOR ? "v11" : "v10";
 }
 //#endregion
 //#region src/utils/merge.ts
@@ -622,9 +729,8 @@ function isNpmrcAuthOrRegistryKey(key) {
 /**
 * Remove pnpm-related settings from `.npmrc` file.
 *
-* This function reads the `.npmrc` file, filters out all lines that start with
-* pnpm-specific configuration keys (as defined in PNPM_SETTINGS_FIELDS), and
-* writes the cleaned content back to the file.
+* This function reads the `.npmrc` file, removes lines whose exact normalized
+* keys were migrated, and writes the cleaned content back to the file.
 *
 * @param path - Absolute path to the `.npmrc` file
 * @param compatibility - Concrete pnpm compatibility target
@@ -636,17 +742,15 @@ function isNpmrcAuthOrRegistryKey(key) {
 *
 * @example
 * ```ts
-* await pruneNpmrc('/path/to/.npmrc')
+* await pruneNpmrc('/path/to/.npmrc', 'v10', ['node-linker'])
 * ```
 */
-async function pruneNpmrc(path, compatibility = "v10", migratedKeys = []) {
-	const pnpmSettingsFields = PNPM_SETTINGS_FIELDS.map((field) => kebabCase(field));
+async function pruneNpmrc(path, compatibility, migratedKeys) {
 	const migratedKeySet = new Set(migratedKeys.map(normalizeNpmrcKey));
 	const updatedContent = (await fsReadFile(path)).split(/\r?\n/u).filter((line) => {
 		const key = getNpmrcLineKey(line);
 		if (!key) return true;
-		if (compatibility !== "v10") return !migratedKeySet.has(normalizeNpmrcKey(key));
-		return !pnpmSettingsFields.some((field) => key.startsWith(field));
+		return !migratedKeySet.has(key);
 	}).join("\n").trimEnd();
 	if (compatibility !== "v10" && !updatedContent.trim()) {
 		await fsRemoveFile(path);
@@ -671,10 +775,12 @@ async function pruneNpmrc(path, compatibility = "v10", migratedKeys = []) {
 async function readMigratableNpmrc(path, compatibility) {
 	const raw = await readIniFile(path);
 	if (compatibility === "v10") {
-		const settings = camelcaseKeys(raw);
+		const pnpmSettingsFields = new Set(PNPM_V10_NPMRC_SETTINGS_FIELDS.map((field) => normalizeNpmrcKey(kebabCase(field))));
+		const keys = Object.keys(raw).filter((key) => pnpmSettingsFields.has(normalizeNpmrcKey(key)));
+		const migratable = Object.fromEntries(keys.map((key) => [key, raw[key]]));
 		return {
-			keys: PNPM_SETTINGS_FIELDS,
-			settings: pick(settings, PNPM_SETTINGS_FIELDS)
+			keys,
+			settings: camelcaseKeys(migratable)
 		};
 	}
 	const migratable = {};
@@ -696,6 +802,15 @@ async function readMigratableNpmrc(path, compatibility) {
 //#endregion
 //#region src/utils/settings-change.ts
 /**
+* Maximum dynamic-programming cells used for an exact line diff.
+*/
+const MAX_LCS_CELLS = 1e6;
+/**
+* URL userinfo can contain proxy usernames and passwords. It must never be
+* printed in a migration report.
+*/
+const URL_USERINFO_PATTERN = /(?<scheme>[a-z][a-z\d+.-]*:\/\/)[^/\s@]+@/giu;
+/**
 * Collect changed root settings between two workspace configurations.
 *
 * @param before - Workspace settings before migration
@@ -714,6 +829,38 @@ function collectSettingsChanges(before, after) {
 	}));
 }
 /**
+* Create a bounded-memory diff that retains shared prefixes and suffixes.
+*
+* This fallback deliberately gives up the exact LCS for unusually large
+* settings to keep reporting from exhausting memory after migration writes.
+*/
+function createLinearLineDiff(beforeLines, afterLines) {
+	let prefixLength = 0;
+	const maximumPrefixLength = Math.min(beforeLines.length, afterLines.length);
+	while (prefixLength < maximumPrefixLength && beforeLines[prefixLength] === afterLines[prefixLength]) prefixLength++;
+	let suffixLength = 0;
+	const maximumSuffixLength = maximumPrefixLength - prefixLength;
+	while (suffixLength < maximumSuffixLength && beforeLines[beforeLines.length - suffixLength - 1] === afterLines[afterLines.length - suffixLength - 1]) suffixLength++;
+	return [
+		...beforeLines.slice(0, prefixLength).map((value) => ({
+			kind: "unchanged",
+			value
+		})),
+		...beforeLines.slice(prefixLength, beforeLines.length - suffixLength).map((value) => ({
+			kind: "removed",
+			value
+		})),
+		...afterLines.slice(prefixLength, afterLines.length - suffixLength).map((value) => ({
+			kind: "added",
+			value
+		})),
+		...beforeLines.slice(beforeLines.length - suffixLength).map((value) => ({
+			kind: "unchanged",
+			value
+		}))
+	];
+}
+/**
 * Create a line-based diff using the longest common subsequence.
 *
 * @param beforeLines - YAML lines before migration
@@ -722,6 +869,7 @@ function collectSettingsChanges(before, after) {
 * @returns Classified diff lines in display order
 */
 function createLineDiff(beforeLines, afterLines) {
+	if (beforeLines.length * afterLines.length > MAX_LCS_CELLS) return createLinearLineDiff(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 = [];
@@ -776,6 +924,17 @@ function formatSettingLines(key, value) {
 	return stringify({ [key]: value }).trimEnd().split("\n");
 }
 /**
+* Remove credentials embedded in URLs while preserving enough context to
+* identify the changed setting.
+*
+* @param value - Rendered YAML diff line
+*
+* @returns Diff line safe to print to a terminal or CI log
+*/
+function redactUrlCredentials(value) {
+	return value.replace(URL_USERINFO_PATTERN, "$<scheme>***@");
+}
+/**
 * Format a setting change as a GitHub-style YAML diff.
 *
 * @param change - Root setting change to format
@@ -783,7 +942,10 @@ function formatSettingLines(key, value) {
 * @returns Classified YAML diff lines
 */
 function createSettingsDiffLines(change) {
-	return createLineDiff(formatSettingLines(change.key, change.before), formatSettingLines(change.key, change.after));
+	return createLineDiff(formatSettingLines(change.key, change.before), formatSettingLines(change.key, change.after)).map((line) => ({
+		kind: line.kind,
+		value: redactUrlCredentials(line.value)
+	}));
 }
 /**
 * Print a summary and GitHub-style YAML diff for every changed setting.
@@ -802,6 +964,39 @@ function reportSettingsChanges(changes) {
 	}
 }
 //#endregion
+//#region src/utils/yaml-document.ts
+/**
+* Sort every mapping in a YAML node without replacing its comments or anchors.
+*/
+function sortYamlMappings(node) {
+	if (isMap(node)) {
+		node.items.sort((left, right) => {
+			const leftKey = isScalar(left.key) ? String(left.key.value) : "";
+			const rightKey = isScalar(right.key) ? String(right.key.value) : "";
+			return leftKey.localeCompare(rightKey);
+		});
+		for (const pair of node.items) if (isNode(pair.value)) sortYamlMappings(pair.value);
+	} else if (isSeq(node)) {
+		for (const item of node.items) if (isNode(item)) sortYamlMappings(item);
+	}
+}
+/**
+* Apply semantic root changes to the parsed document while retaining untouched
+* YAML nodes and their source metadata.
+*/
+function updateYamlDocument(document, options) {
+	const { after, before, sortKeys } = options;
+	for (const key of Object.keys(before)) if (!Object.hasOwn(after, key)) document.delete(key);
+	for (const [key, value] of Object.entries(after)) if (!Object.hasOwn(before, key) || !isDeepStrictEqual(Reflect.get(before, key), value)) document.set(key, value);
+	if (sortKeys) sortYamlMappings(document.contents);
+}
+/**
+* Normalize blank lines immediately before root mapping keys.
+*/
+function formatRootSpacing(content, newlineBetween) {
+	return content.replace(/\n+(?=[^\s#][^:\n]*:)/gu, newlineBetween ? "\n\n" : "\n");
+}
+//#endregion
 //#region src/utils/config.ts
 /**
 * Resolve the indentation width for a YAML document.
@@ -847,13 +1042,21 @@ async function readPackageJson(path, exists) {
 */
 async function readPnpmWorkspace(path, exists) {
 	if (!exists) return {
+		document: new Document({}),
 		indent: 2,
 		value: {}
 	};
 	const content = await fsReadFile(path);
+	const document = parseDocument(content);
+	const [parseError] = document.errors;
+	if (parseError) throw parseError;
+	const parsedValue = document.toJS();
+	if (parsedValue !== null && !isMap(document.contents)) throw new TypeError("pnpm-workspace.yaml must contain a root mapping.");
+	if (parsedValue === null) document.contents = document.createNode({});
 	return {
+		document,
 		indent: resolveYamlIndent(content),
-		value: parse(content) ?? {}
+		value: parsedValue ?? {}
 	};
 }
 /**
@@ -954,11 +1157,7 @@ async function migratePnpmSettings(rawOptions = {}) {
 			settings: {}
 		};
 		const pnpmSettingsInNpmrc = npmrcMigratable.settings;
-		const pnpmSettingsInPackageJson = resolvePackageJsonSettings(packageJson.value, options.yarnResolutions);
-		const incomingSettings = {
-			...pnpmSettingsInNpmrc,
-			...pnpmSettingsInPackageJson
-		};
+		const incomingSettings = mergeByStrategy(resolvePackageJsonSettings(packageJson.value, options.yarnResolutions), pnpmSettingsInNpmrc, "merge");
 		const [existingNormalization, incomingNormalization] = await Promise.all([normalizeIncomingSettings(pnpmWorkspace.value, {
 			compatibility,
 			cwd: options.cwd,
@@ -984,16 +1183,12 @@ async function migratePnpmSettings(rawOptions = {}) {
 			return;
 		}
 		const pnpmWorkspaceResult = mergeByStrategy(pnpmWorkspace.value, incomingSettings, options.strategy);
-		const yamlDocument = new Document({}, { sortMapEntries: options.sortKeys });
-		Object.entries(pnpmWorkspaceResult).forEach(([key, value]) => {
-			yamlDocument.add({
-				key,
-				value
-			});
+		updateYamlDocument(pnpmWorkspace.document, {
+			after: pnpmWorkspaceResult,
+			before: pnpmWorkspaceBefore,
+			sortKeys: options.sortKeys
 		});
-		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);
+		const finalYamlContent = formatRootSpacing(pnpmWorkspace.document.toString({ indent: pnpmWorkspace.indent }), options.newlineBetween);
 		let packageJsonChanged = runtimeMigration.changed;
 		if (packageJsonExists && options.cleanPackageJson) {
 			if (packageJson.value.pnpm) packageJsonChanged = true;
@@ -1003,7 +1198,9 @@ async function migratePnpmSettings(rawOptions = {}) {
 				delete packageJson.value.resolutions;
 			}
 		}
+		await fsWriteFile(pnpmWorkspaceYamlPath, finalYamlContent);
 		if (packageJsonExists && packageJsonChanged) await fsWriteFile(packageJsonPath, JSON.stringify(packageJson.value, null, packageJson.indent));
+		if (npmrcExists && options.cleanNpmrc) await pruneNpmrc(npmrcPath, compatibility, npmrcMigratable.keys);
 		reportMigrationChanges(options.showChanges, pnpmWorkspaceBefore, pnpmWorkspaceResult);
 	} catch (err) {
 		consola$1.error("Failed to migrate pnpm settings:", err);
@@ -1012,9 +1209,8 @@ async function migratePnpmSettings(rawOptions = {}) {
 }
 //#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, 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) => {
+const cli = createCli();
+cli.command("").usage("[options]").action(async (options) => {
 	try {
 		consola.log(`\n${bold(magenta(name))} ${dim(`v${version}`)}`);
 		consola.log(dim("\n--------------\n"));

package/dist/index.d.mts

@@ -91,7 +91,7 @@ interface PackageJson {
    * Development tool declarations.
    */
   devEngines?: {
-    packageManager?: PackageManagerEngine;
+    packageManager?: PackageManagerEngine | PackageManagerEngine[];
     runtime?: RuntimeEngine | RuntimeEngine[];
     [key: string]: unknown;
   };
@@ -128,7 +128,7 @@ type NpmRC = Record<string, any>;
 interface PackageManagerEngine {
   name: string;
   onFail?: 'download' | 'error' | 'ignore' | 'warn';
-  version: string;
+  version?: string;
 }
 /**
  * Runtime declaration stored in `package.json#devEngines.runtime`.

package/dist/index.mjs

@@ -1,82 +1,115 @@
 import consola from "consola";
-import { resolve } from "pathe";
-import { Document, parse, stringify } from "yaml";
+import { basename, dirname, join, resolve } from "pathe";
 import process from "node:process";
-import { access, readFile, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { access, chmod, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 import { getColor } from "consola/utils";
-import { isPlainObject, isUndefined, pick } from "@ntnyq/utils";
+import { isPlainObject, isUndefined } 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 { Document, isMap, isNode, isScalar, isSeq, parseDocument, stringify } from "yaml";
 import detectIndent from "detect-indent";
 //#region src/constants.ts
 const NPMRC = ".npmrc";
 const PACKAGE_JSON = "package.json";
 const PNPM_WORKSPACE_YAML = "pnpm-workspace.yaml";
 /**
-* @see {@link https://github.com/pnpm/pnpm/blob/main/packages/types/src/package.ts}
-* Schema-aligned pnpm config fields that can be migrated from `.npmrc`.
+* @see {@link https://pnpm.io/10.x/settings}
+* Documented pnpm v10 config fields that can be migrated from `.npmrc`.
 *
 * Intentionally excluded workspace manifest-only fields:
 * - `catalog`
-* - `catalogMode`
 * - `catalogs`
-* - `cleanupUnusedCatalogs`
 * - `packages`
 */
-const PNPM_SETTINGS_FIELDS = [
+const PNPM_V10_NPMRC_SETTINGS_FIELDS = [
 	"allowBuilds",
 	"allowedDeprecatedVersions",
 	"allowNonAppliedPatches",
 	"allowUnusedPatches",
 	"auditConfig",
+	"auditLevel",
+	"autoInstallPeers",
+	"blockExoticSubdeps",
+	"cacheDir",
+	"catalogMode",
+	"childConcurrency",
+	"ci",
+	"cleanupUnusedCatalogs",
+	"color",
 	"configDependencies",
+	"dangerouslyAllowAllBuilds",
 	"dedupeDirectDeps",
 	"dedupeInjectedDeps",
 	"dedupePeerDependents",
 	"deployAllFiles",
+	"disallowWorkspaceCycles",
+	"dlxCacheMaxAge",
+	"enableGlobalVirtualStore",
+	"enableModulesDir",
+	"enablePrePostScripts",
 	"engineStrict",
 	"executionEnv",
+	"extendNodePath",
+	"failIfNoMatch",
 	"fetchMinSpeedKiBps",
+	"fetchRetries",
 	"fetchRetryFactor",
 	"fetchRetryMaxtimeout",
 	"fetchRetryMintimeout",
-	"fetchRetryTimeout",
+	"fetchTimeout",
 	"fetchWarnTimeoutMs",
 	"forceLegacyDeploy",
+	"frozenLockfile",
+	"gitBranchLockfile",
 	"gitChecks",
 	"gitShallowHosts",
-	"globalVirtualStore",
+	"globalBinDir",
+	"globalDir",
+	"globalPnpmfile",
 	"globalVirtualStoreDir",
 	"hoist",
 	"hoistPattern",
 	"hoistWorkspacePackages",
 	"httpProxy",
 	"httpsProxy",
+	"ignoreCompatibilityDb",
 	"ignoredBuiltDependencies",
 	"ignoreDepScripts",
-	"ignoreDeps",
 	"ignoredOptionalDependencies",
 	"ignorePatchFailures",
+	"ignorePnpmfile",
+	"ignoreScripts",
 	"ignoreWorkspaceCycles",
+	"ignoreWorkspaceRootCheck",
+	"includeWorkspaceRoot",
 	"injectWorkspacePackages",
 	"linkWorkspacePackages",
+	"localAddress",
 	"lockfile",
 	"lockfileDir",
+	"lockfileIncludeTarballUrl",
+	"loglevel",
 	"managePackageManagerVersions",
+	"maxsockets",
 	"mergeGitBranchLockfiles",
 	"mergeGitBranchLockfilesBranchPattern",
+	"minimumReleaseAge",
+	"minimumReleaseAgeExclude",
 	"modulesCacheMaxAge",
+	"modulesDir",
 	"networkConcurrency",
 	"neverBuiltDependencies",
-	"nodeDownloadMirrors",
 	"nodeLinker",
-	"noproxy",
+	"nodeOptions",
+	"nodeVersion",
 	"noProxy",
+	"noproxy",
 	"npmPath",
-	"npmrcAuthFile",
 	"onlyBuiltDependencies",
 	"onlyBuiltDependenciesFile",
 	"optimisticRepeatInstall",
@@ -90,38 +123,46 @@ const PNPM_SETTINGS_FIELDS = [
 	"peerDependencyRules",
 	"peersSuffixMaxLength",
 	"pnpmfile",
-	"pnpmfileIgnorePkgManifest",
-	"pmOnFail",
 	"preferFrozenLockfile",
+	"preferSymlinkedExecutables",
 	"preferWorkspacePackages",
 	"production",
 	"proxy",
 	"publicHoistPattern",
 	"recursiveInstall",
-	"registries",
+	"registrySupportsTimeField",
 	"requiredScripts",
 	"resolutionMode",
 	"resolvePeersFromWorkspaceRoot",
 	"saveExact",
 	"savePrefix",
+	"saveWorkspaceProtocol",
 	"scriptShell",
 	"shamefullyHoist",
 	"sharedWorkspaceLockfile",
 	"shellEmulator",
 	"sideEffectsCache",
 	"sideEffectsCacheReadonly",
+	"stateDir",
 	"storeDir",
 	"strictDepBuilds",
 	"strictPeerDependencies",
 	"strictSsl",
+	"strictStorePkgContentCheck",
 	"supportedArchitectures",
+	"symlink",
 	"syncInjectedDepsAfterScripts",
 	"tag",
-	"targetDependenciesField",
-	"timeout",
+	"trustPolicy",
+	"trustPolicyExclude",
+	"trustPolicyIgnoreAfter",
+	"unsafePerm",
 	"updateConfig",
+	"updateNotifier",
 	"useBetaCli",
 	"useNodeVersion",
+	"useRunningStoreServer",
+	"useStderr",
 	"verifyDepsBeforeRun",
 	"verifyStoreIntegrity",
 	"virtualStoreDir",
@@ -151,7 +192,6 @@ const DEFAULT_OPTIONS = {
 	cleanNpmrc: true,
 	cleanPackageJson: true,
 	compatibility: "auto",
-	cwd: process.cwd(),
 	newlineBetween: true,
 	replaceDeprecated: false,
 	showChanges: true,
@@ -205,7 +245,7 @@ function resolveOptions(options = {}) {
 	return {
 		cleanNpmrc: options.cleanNpmrc ?? DEFAULT_OPTIONS.cleanNpmrc,
 		compatibility: resolveCompatibility(options.compatibility),
-		cwd: options.cwd ?? DEFAULT_OPTIONS.cwd,
+		cwd: options.cwd ?? process.cwd(),
 		newlineBetween: options.newlineBetween ?? DEFAULT_OPTIONS.newlineBetween,
 		showChanges: options.showChanges ?? DEFAULT_OPTIONS.showChanges,
 		sortKeys: options.sortKeys ?? DEFAULT_OPTIONS.sortKeys,
@@ -218,6 +258,28 @@ function resolveOptions(options = {}) {
 //#endregion
 //#region src/utils/fs.ts
 /**
+* Modulus that isolates Unix permission bits from a stat mode.
+*/
+const FILE_PERMISSION_MODULUS = 512;
+/**
+* Resolve a filesystem path to a string suitable for a sibling temp file.
+*/
+function resolvePathString(path) {
+	if (path instanceof URL) return fileURLToPath(path);
+	return typeof path === "string" ? path : path.toString();
+}
+/**
+* Read an existing file's permission bits, if the file exists.
+*/
+async function resolveExistingMode(path) {
+	try {
+		return (await stat(path)).mode % FILE_PERMISSION_MODULUS;
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+/**
 * Check whether a filesystem path exists.
 *
 * @param path - Filesystem path to check
@@ -256,10 +318,22 @@ async function fsRemoveFile(path) {
 * @returns A promise that resolves after the file is written
 */
 async function fsWriteFile(path, content) {
-	await writeFile(path, `${content.trimEnd()}\n`, "utf-8");
+	const pathString = resolvePathString(path);
+	const temporaryPath = join(dirname(pathString), `.${basename(pathString)}.${process.pid}.${randomUUID()}.tmp`);
+	const mode = await resolveExistingMode(path);
+	try {
+		await writeFile(temporaryPath, `${content.trimEnd()}\n`, {
+			encoding: "utf-8",
+			mode
+		});
+		if (mode !== void 0) await chmod(temporaryPath, mode);
+		await rename(temporaryPath, pathString);
+	} finally {
+		await rm(temporaryPath, { force: true });
+	}
 }
-getColor("cyan");
-getColor("yellow");
+//#endregion
+//#region src/utils/color.ts
 /**
 * Apply dim terminal styling to a value.
 */
@@ -275,27 +349,9 @@ const red = getColor("red");
 getColor("bold");
 getColor("magenta");
 //#endregion
-//#region src/utils/compatibility.ts
-/**
-* Legacy build settings that can be replaced for pnpm v10.
-*/
-const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
-	"allowNonAppliedPatches",
-	"ignoredBuiltDependencies",
-	"neverBuiltDependencies",
-	"onlyBuiltDependencies",
-	"onlyBuiltDependenciesFile"
-];
+//#region src/utils/legacy-build-settings.ts
 /**
 * Read packages listed by the legacy `onlyBuiltDependenciesFile` setting.
-*
-* @param cwd - Working directory used to resolve the referenced file
-* @param file - Relative path stored in `onlyBuiltDependenciesFile`
-*
-* @returns Package names read from the referenced JSON file
-*
-* @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 [];
@@ -305,21 +361,44 @@ async function readOnlyBuiltDependenciesFile(cwd, file) {
 	return value;
 }
 /**
+* Read and validate one legacy build dependency list. Configuration files are
+* external input, so their runtime shape can differ from its declared type.
+*/
+function readLegacyBuildDependencyList(settings, key) {
+	const value = settings[key];
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+		const npmrcKey = key.replace(/[A-Z]/gu, (character) => `-${character.toLowerCase()}`);
+		throw new TypeError(`Invalid ${key}: expected an array of package names. In .npmrc, use ${npmrcKey}[]=<package>.`);
+	}
+	return value;
+}
+/**
 * Build an `allowBuilds` map from legacy build-script settings.
-*
-* @param incomingSettings - Settings containing legacy build declarations
-* @param cwd - Working directory used to resolve referenced files
-*
-* @returns Package-to-permission map, or `undefined` when no entries exist
 */
 async function collectAllowBuildsFromLegacy(incomingSettings, cwd) {
 	const allowBuilds = {};
+	const allowed = readLegacyBuildDependencyList(incomingSettings, "onlyBuiltDependencies");
+	const ignored = readLegacyBuildDependencyList(incomingSettings, "ignoredBuiltDependencies");
+	const neverBuilt = readLegacyBuildDependencyList(incomingSettings, "neverBuiltDependencies");
 	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;
+	for (const name of [...allowed, ...allowedFromFile]) allowBuilds[name] = true;
+	for (const name of ignored) allowBuilds[name] = false;
+	for (const name of neverBuilt) allowBuilds[name] = false;
 	return Object.keys(allowBuilds).length ? allowBuilds : void 0;
 }
+//#endregion
+//#region src/utils/compatibility.ts
+/**
+* Legacy build settings that can be replaced for pnpm v10.
+*/
+const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
+	"allowNonAppliedPatches",
+	"ignoredBuiltDependencies",
+	"neverBuiltDependencies",
+	"onlyBuiltDependencies",
+	"onlyBuiltDependenciesFile"
+];
 /**
 * Resolve the pnpm v11 replacement for legacy package-manager settings.
 *
@@ -455,6 +534,20 @@ const PNPM_V11_MAJOR = 11;
 */
 const PNPM_V12_MAJOR = 12;
 /**
+* Resolve a pnpm major from a package manager declaration.
+*/
+function resolvePnpmMajor(hint) {
+	const match = hint?.match(/^pnpm@[\s<=>^~]*(?<major>\d+)(?:\.|\s|$)/u);
+	return match?.groups?.major ? Number(match.groups.major) : void 0;
+}
+/**
+* Normalize the single-or-array devEngines declaration.
+*/
+function normalizePackageManagers(value) {
+	if (Array.isArray(value)) return value;
+	return value ? [value] : [];
+}
+/**
 * Resolve final compatibility target from user option and package manager hint.
 *
 * @param compatibility - Explicit or automatically detected compatibility target
@@ -465,10 +558,11 @@ const PNPM_V12_MAJOR = 12;
 */
 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";
+	const packageManagerMajor = resolvePnpmMajor(packageManager);
+	const devPackageManagerMajors = normalizePackageManagers(devPackageManager).filter((item) => item.name === "pnpm").map((item) => resolvePnpmMajor(`pnpm@${item.version ?? ""}`)).filter((major) => major !== void 0);
+	const major = packageManagerMajor ?? (devPackageManagerMajors.length ? Math.max(...devPackageManagerMajors) : void 0);
+	if (major !== void 0 && major >= PNPM_V12_MAJOR) return "v12";
+	return major !== void 0 && major >= PNPM_V11_MAJOR ? "v11" : "v10";
 }
 //#endregion
 //#region src/utils/merge.ts
@@ -611,9 +705,8 @@ function isNpmrcAuthOrRegistryKey(key) {
 /**
 * Remove pnpm-related settings from `.npmrc` file.
 *
-* This function reads the `.npmrc` file, filters out all lines that start with
-* pnpm-specific configuration keys (as defined in PNPM_SETTINGS_FIELDS), and
-* writes the cleaned content back to the file.
+* This function reads the `.npmrc` file, removes lines whose exact normalized
+* keys were migrated, and writes the cleaned content back to the file.
 *
 * @param path - Absolute path to the `.npmrc` file
 * @param compatibility - Concrete pnpm compatibility target
@@ -625,17 +718,15 @@ function isNpmrcAuthOrRegistryKey(key) {
 *
 * @example
 * ```ts
-* await pruneNpmrc('/path/to/.npmrc')
+* await pruneNpmrc('/path/to/.npmrc', 'v10', ['node-linker'])
 * ```
 */
-async function pruneNpmrc(path, compatibility = "v10", migratedKeys = []) {
-	const pnpmSettingsFields = PNPM_SETTINGS_FIELDS.map((field) => kebabCase(field));
+async function pruneNpmrc(path, compatibility, migratedKeys) {
 	const migratedKeySet = new Set(migratedKeys.map(normalizeNpmrcKey));
 	const updatedContent = (await fsReadFile(path)).split(/\r?\n/u).filter((line) => {
 		const key = getNpmrcLineKey(line);
 		if (!key) return true;
-		if (compatibility !== "v10") return !migratedKeySet.has(normalizeNpmrcKey(key));
-		return !pnpmSettingsFields.some((field) => key.startsWith(field));
+		return !migratedKeySet.has(key);
 	}).join("\n").trimEnd();
 	if (compatibility !== "v10" && !updatedContent.trim()) {
 		await fsRemoveFile(path);
@@ -660,10 +751,12 @@ async function pruneNpmrc(path, compatibility = "v10", migratedKeys = []) {
 async function readMigratableNpmrc(path, compatibility) {
 	const raw = await readIniFile(path);
 	if (compatibility === "v10") {
-		const settings = camelcaseKeys(raw);
+		const pnpmSettingsFields = new Set(PNPM_V10_NPMRC_SETTINGS_FIELDS.map((field) => normalizeNpmrcKey(kebabCase(field))));
+		const keys = Object.keys(raw).filter((key) => pnpmSettingsFields.has(normalizeNpmrcKey(key)));
+		const migratable = Object.fromEntries(keys.map((key) => [key, raw[key]]));
 		return {
-			keys: PNPM_SETTINGS_FIELDS,
-			settings: pick(settings, PNPM_SETTINGS_FIELDS)
+			keys,
+			settings: camelcaseKeys(migratable)
 		};
 	}
 	const migratable = {};
@@ -685,6 +778,15 @@ async function readMigratableNpmrc(path, compatibility) {
 //#endregion
 //#region src/utils/settings-change.ts
 /**
+* Maximum dynamic-programming cells used for an exact line diff.
+*/
+const MAX_LCS_CELLS = 1e6;
+/**
+* URL userinfo can contain proxy usernames and passwords. It must never be
+* printed in a migration report.
+*/
+const URL_USERINFO_PATTERN = /(?<scheme>[a-z][a-z\d+.-]*:\/\/)[^/\s@]+@/giu;
+/**
 * Collect changed root settings between two workspace configurations.
 *
 * @param before - Workspace settings before migration
@@ -703,6 +805,38 @@ function collectSettingsChanges(before, after) {
 	}));
 }
 /**
+* Create a bounded-memory diff that retains shared prefixes and suffixes.
+*
+* This fallback deliberately gives up the exact LCS for unusually large
+* settings to keep reporting from exhausting memory after migration writes.
+*/
+function createLinearLineDiff(beforeLines, afterLines) {
+	let prefixLength = 0;
+	const maximumPrefixLength = Math.min(beforeLines.length, afterLines.length);
+	while (prefixLength < maximumPrefixLength && beforeLines[prefixLength] === afterLines[prefixLength]) prefixLength++;
+	let suffixLength = 0;
+	const maximumSuffixLength = maximumPrefixLength - prefixLength;
+	while (suffixLength < maximumSuffixLength && beforeLines[beforeLines.length - suffixLength - 1] === afterLines[afterLines.length - suffixLength - 1]) suffixLength++;
+	return [
+		...beforeLines.slice(0, prefixLength).map((value) => ({
+			kind: "unchanged",
+			value
+		})),
+		...beforeLines.slice(prefixLength, beforeLines.length - suffixLength).map((value) => ({
+			kind: "removed",
+			value
+		})),
+		...afterLines.slice(prefixLength, afterLines.length - suffixLength).map((value) => ({
+			kind: "added",
+			value
+		})),
+		...beforeLines.slice(beforeLines.length - suffixLength).map((value) => ({
+			kind: "unchanged",
+			value
+		}))
+	];
+}
+/**
 * Create a line-based diff using the longest common subsequence.
 *
 * @param beforeLines - YAML lines before migration
@@ -711,6 +845,7 @@ function collectSettingsChanges(before, after) {
 * @returns Classified diff lines in display order
 */
 function createLineDiff(beforeLines, afterLines) {
+	if (beforeLines.length * afterLines.length > MAX_LCS_CELLS) return createLinearLineDiff(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 = [];
@@ -765,6 +900,17 @@ function formatSettingLines(key, value) {
 	return stringify({ [key]: value }).trimEnd().split("\n");
 }
 /**
+* Remove credentials embedded in URLs while preserving enough context to
+* identify the changed setting.
+*
+* @param value - Rendered YAML diff line
+*
+* @returns Diff line safe to print to a terminal or CI log
+*/
+function redactUrlCredentials(value) {
+	return value.replace(URL_USERINFO_PATTERN, "$<scheme>***@");
+}
+/**
 * Format a setting change as a GitHub-style YAML diff.
 *
 * @param change - Root setting change to format
@@ -772,7 +918,10 @@ function formatSettingLines(key, value) {
 * @returns Classified YAML diff lines
 */
 function createSettingsDiffLines(change) {
-	return createLineDiff(formatSettingLines(change.key, change.before), formatSettingLines(change.key, change.after));
+	return createLineDiff(formatSettingLines(change.key, change.before), formatSettingLines(change.key, change.after)).map((line) => ({
+		kind: line.kind,
+		value: redactUrlCredentials(line.value)
+	}));
 }
 /**
 * Print a summary and GitHub-style YAML diff for every changed setting.
@@ -791,6 +940,39 @@ function reportSettingsChanges(changes) {
 	}
 }
 //#endregion
+//#region src/utils/yaml-document.ts
+/**
+* Sort every mapping in a YAML node without replacing its comments or anchors.
+*/
+function sortYamlMappings(node) {
+	if (isMap(node)) {
+		node.items.sort((left, right) => {
+			const leftKey = isScalar(left.key) ? String(left.key.value) : "";
+			const rightKey = isScalar(right.key) ? String(right.key.value) : "";
+			return leftKey.localeCompare(rightKey);
+		});
+		for (const pair of node.items) if (isNode(pair.value)) sortYamlMappings(pair.value);
+	} else if (isSeq(node)) {
+		for (const item of node.items) if (isNode(item)) sortYamlMappings(item);
+	}
+}
+/**
+* Apply semantic root changes to the parsed document while retaining untouched
+* YAML nodes and their source metadata.
+*/
+function updateYamlDocument(document, options) {
+	const { after, before, sortKeys } = options;
+	for (const key of Object.keys(before)) if (!Object.hasOwn(after, key)) document.delete(key);
+	for (const [key, value] of Object.entries(after)) if (!Object.hasOwn(before, key) || !isDeepStrictEqual(Reflect.get(before, key), value)) document.set(key, value);
+	if (sortKeys) sortYamlMappings(document.contents);
+}
+/**
+* Normalize blank lines immediately before root mapping keys.
+*/
+function formatRootSpacing(content, newlineBetween) {
+	return content.replace(/\n+(?=[^\s#][^:\n]*:)/gu, newlineBetween ? "\n\n" : "\n");
+}
+//#endregion
 //#region src/utils/config.ts
 /**
 * Resolve the indentation width for a YAML document.
@@ -836,13 +1018,21 @@ async function readPackageJson(path, exists) {
 */
 async function readPnpmWorkspace(path, exists) {
 	if (!exists) return {
+		document: new Document({}),
 		indent: 2,
 		value: {}
 	};
 	const content = await fsReadFile(path);
+	const document = parseDocument(content);
+	const [parseError] = document.errors;
+	if (parseError) throw parseError;
+	const parsedValue = document.toJS();
+	if (parsedValue !== null && !isMap(document.contents)) throw new TypeError("pnpm-workspace.yaml must contain a root mapping.");
+	if (parsedValue === null) document.contents = document.createNode({});
 	return {
+		document,
 		indent: resolveYamlIndent(content),
-		value: parse(content) ?? {}
+		value: parsedValue ?? {}
 	};
 }
 /**
@@ -943,11 +1133,7 @@ async function migratePnpmSettings(rawOptions = {}) {
 			settings: {}
 		};
 		const pnpmSettingsInNpmrc = npmrcMigratable.settings;
-		const pnpmSettingsInPackageJson = resolvePackageJsonSettings(packageJson.value, options.yarnResolutions);
-		const incomingSettings = {
-			...pnpmSettingsInNpmrc,
-			...pnpmSettingsInPackageJson
-		};
+		const incomingSettings = mergeByStrategy(resolvePackageJsonSettings(packageJson.value, options.yarnResolutions), pnpmSettingsInNpmrc, "merge");
 		const [existingNormalization, incomingNormalization] = await Promise.all([normalizeIncomingSettings(pnpmWorkspace.value, {
 			compatibility,
 			cwd: options.cwd,
@@ -973,16 +1159,12 @@ async function migratePnpmSettings(rawOptions = {}) {
 			return;
 		}
 		const pnpmWorkspaceResult = mergeByStrategy(pnpmWorkspace.value, incomingSettings, options.strategy);
-		const yamlDocument = new Document({}, { sortMapEntries: options.sortKeys });
-		Object.entries(pnpmWorkspaceResult).forEach(([key, value]) => {
-			yamlDocument.add({
-				key,
-				value
-			});
+		updateYamlDocument(pnpmWorkspace.document, {
+			after: pnpmWorkspaceResult,
+			before: pnpmWorkspaceBefore,
+			sortKeys: options.sortKeys
 		});
-		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);
+		const finalYamlContent = formatRootSpacing(pnpmWorkspace.document.toString({ indent: pnpmWorkspace.indent }), options.newlineBetween);
 		let packageJsonChanged = runtimeMigration.changed;
 		if (packageJsonExists && options.cleanPackageJson) {
 			if (packageJson.value.pnpm) packageJsonChanged = true;
@@ -992,7 +1174,9 @@ async function migratePnpmSettings(rawOptions = {}) {
 				delete packageJson.value.resolutions;
 			}
 		}
+		await fsWriteFile(pnpmWorkspaceYamlPath, finalYamlContent);
 		if (packageJsonExists && packageJsonChanged) await fsWriteFile(packageJsonPath, JSON.stringify(packageJson.value, null, packageJson.indent));
+		if (npmrcExists && options.cleanNpmrc) await pruneNpmrc(npmrcPath, compatibility, npmrcMigratable.keys);
 		reportMigrationChanges(options.showChanges, pnpmWorkspaceBefore, pnpmWorkspaceResult);
 	} catch (err) {
 		consola.error("Failed to migrate pnpm settings:", err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pnpm-settings-migrator",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Move pnpm settings from `pnpm` field in `package.json` and `.npmrc` file to `pnpm-workspace.yaml`",
   "keywords": [
     "migrator",
@@ -67,6 +67,9 @@
     "*.{js,ts,mjs,tsx}": "oxlint --fix",
     "*": "oxfmt --no-error-on-unmatched-pattern"
   },
+  "engines": {
+    "node": "^22.19.0 || >=24.11.0"
+  },
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",