pnpm-settings-migrator 0.8.0 → 0.9.0

package/dist/cli.mjs

@@ -1,87 +1,136 @@
 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, relative, resolve } from "pathe";
+import camelcaseKeys from "camelcase-keys";
+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 { glob } from "tinyglobby";
 import detectIndent from "detect-indent";
+import { Document, isMap, isNode, isScalar, isSeq, parseDocument, stringify } from "yaml";
+import { isDeepStrictEqual } from "node:util";
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.8.0";
+var version = "0.9.0";
+//#endregion
+//#region src/cli-options.ts
+/**
+* Create the command-line parser shared by the executable and parser tests.
+*
+* @returns Configured command-line parser
+*/
+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 +144,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",
@@ -148,80 +205,37 @@ const PNPM_V11_REMOVED_SETTINGS = [
 	"useNodeVersion"
 ];
 //#endregion
-//#region src/options.ts
+//#region src/utils/fs.ts
 /**
-* Default values for migration options.
+* Modulus that isolates Unix permission bits from a stat mode.
 */
-const DEFAULT_OPTIONS = {
-	cleanNpmrc: true,
-	cleanPackageJson: true,
-	compatibility: "auto",
-	cwd: process.cwd(),
-	newlineBetween: true,
-	replaceDeprecated: false,
-	showChanges: true,
-	sortKeys: false,
-	strategy: "merge",
-	yarnResolutions: true
-};
-const VALID_STRATEGIES = [
-	"discard",
-	"merge",
-	"overwrite"
-];
-const VALID_COMPATIBILITIES = [
-	"auto",
-	"v10",
-	"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(", ")}`);
-}
+const FILE_PERMISSION_MODULUS = 512;
 /**
-* Resolve and normalize migration options with defaults.
-*
-* This function takes partial options and returns a complete options object
-* with all properties set to either the provided value or the default value.
+* Resolve a filesystem path to a string suitable for a sibling temp file.
 *
-* @param options - Partial migration options
+* @param path - Filesystem path to normalize
 *
-* @returns Complete options object with all required properties
+* @returns String path suitable for path manipulation
+*/
+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.
 *
-* @example
-* ```ts
-* // Use all defaults
-* const opts = resolveOptions()
-* // { cleanNpmrc: true, cleanPackageJson: true, cwd: '/current/dir', ... }
+* @param path - Filesystem path to inspect
 *
-* // Override specific options
-* const opts = resolveOptions({ sortKeys: true, cleanNpmrc: false })
-* // { cleanNpmrc: false, cleanPackageJson: true, sortKeys: true, ... }
-* ```
+* @returns Unix permission bits, or `undefined` when the file does not exist
 */
-function resolveOptions(options = {}) {
-	return {
-		cleanNpmrc: options.cleanNpmrc ?? DEFAULT_OPTIONS.cleanNpmrc,
-		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,
-		cleanPackageJson: options.cleanPackageJson ?? DEFAULT_OPTIONS.cleanPackageJson,
-		replaceDeprecated: options.replaceDeprecated ?? DEFAULT_OPTIONS.replaceDeprecated
-	};
+async function resolveExistingMode(path) {
+	try {
+		return (await stat(path)).mode % FILE_PERMISSION_MODULUS;
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
 }
-//#endregion
-//#region src/utils/fs.ts
 /**
 * Check whether a filesystem path exists.
 *
@@ -261,52 +275,208 @@ 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.
+*
+* @param text - Text or number to style
+*
+* @returns ANSI-styled string
 */
 const dim = getColor("dim");
 /**
 * Apply green terminal styling to a value.
+*
+* @param text - Text or number to style
+*
+* @returns ANSI-styled string
 */
 const green = getColor("green");
 /**
 * Apply red terminal styling to a value.
+*
+* @param text - Text or number to style
+*
+* @returns ANSI-styled string
 */
 const red = getColor("red");
 /**
 * Apply bold terminal styling to a value.
+*
+* @param text - Text or number to style
+*
+* @returns ANSI-styled string
 */
 const bold = getColor("bold");
 /**
 * Apply magenta terminal styling to a value.
+*
+* @param text - Text or number to style
+*
+* @returns ANSI-styled string
 */
 const magenta = getColor("magenta");
 //#endregion
-//#region src/utils/compatibility.ts
+//#region src/utils/deprecated-settings.ts
 /**
-* Legacy build settings that can be replaced for pnpm v10.
+* Replace deprecated audit fields with the structured `audit` setting.
+*
+* @param settings - Workspace settings to normalize in place
 */
-const PNPM_REPLACEABLE_IN_V10_SETTINGS = [
-	"allowNonAppliedPatches",
-	"ignoredBuiltDependencies",
-	"neverBuiltDependencies",
-	"onlyBuiltDependencies",
-	"onlyBuiltDependenciesFile"
-];
+function normalizeAuditSettings(settings) {
+	const level = settings.audit?.level ?? settings.auditLevel;
+	const ignore = settings.audit?.ignore ?? settings.auditConfig?.ignoreGhsas;
+	if (level !== void 0 || ignore !== void 0) settings.audit = {
+		...settings.audit,
+		...level === void 0 ? {} : { level },
+		...ignore === void 0 ? {} : { ignore }
+	};
+	Reflect.deleteProperty(settings, "auditConfig");
+	Reflect.deleteProperty(settings, "auditLevel");
+}
+/**
+* Replace deprecated update fields with the structured `update` setting.
+*
+* @param settings - Workspace settings to normalize in place
+*/
+function normalizeUpdateSettings(settings) {
+	const { updateConfig } = settings;
+	if (!updateConfig) return;
+	settings.update = {
+		...updateConfig.ignoreDependencies === void 0 ? {} : { ignoreDeps: updateConfig.ignoreDependencies },
+		...updateConfig.changeset === void 0 ? {} : { changeset: updateConfig.changeset },
+		...updateConfig.githubActions === void 0 ? {} : { githubActions: updateConfig.githubActions },
+		...updateConfig.githubActionsServer === void 0 ? {} : { githubActionsServer: updateConfig.githubActionsServer },
+		...settings.update
+	};
+	Reflect.deleteProperty(settings, "updateConfig");
+}
+/**
+* Replace former scalar aliases with their canonical v11+ settings.
+*
+* @param settings - Workspace settings to normalize in place
+*/
+function normalizeScalarAliases(settings) {
+	if (settings.cleanupUnusedCatalogs !== void 0) {
+		settings.catalogPrune ??= settings.cleanupUnusedCatalogs;
+		Reflect.deleteProperty(settings, "cleanupUnusedCatalogs");
+	}
+	if (settings.enableGlobalVirtualStore !== void 0) {
+		settings.virtualStoreType ??= settings.enableGlobalVirtualStore ? "global" : "project";
+		Reflect.deleteProperty(settings, "enableGlobalVirtualStore");
+	}
+}
+/**
+* Replace the older side-effects cache spellings with one structured value.
+*
+* @param settings - Workspace settings to normalize in place
+*/
+function normalizeSideEffectsCache(settings) {
+	const declared = settings.sideEffectsCache;
+	const readonly = settings.sideEffectsCacheReadonly;
+	const remote = settings.remoteSideEffectsCache;
+	if (readonly === void 0 && remote === void 0) return;
+	const structured = typeof declared === "object" && declared !== null ? declared : void 0;
+	const shorthand = typeof declared === "boolean" ? declared : void 0;
+	settings.sideEffectsCache = {
+		...shorthand === void 0 ? {} : {
+			read: readonly === true ? true : shorthand,
+			write: readonly === true ? false : shorthand
+		},
+		...readonly === void 0 || shorthand !== void 0 ? {} : {
+			read: readonly,
+			...readonly ? { write: false } : {}
+		},
+		...remote === void 0 ? {} : { remote },
+		...structured
+	};
+	Reflect.deleteProperty(settings, "remoteSideEffectsCache");
+	Reflect.deleteProperty(settings, "sideEffectsCacheReadonly");
+}
+function addRegistryScope(declarations, url, scope) {
+	declarations[url] ??= {};
+	const declaration = declarations[url];
+	declaration.scopes = [.../* @__PURE__ */ new Set([...declaration.scopes ?? [], scope])];
+}
+/**
+* Replace `namedRegistries` with URL-keyed registry declarations.
+*
+* A URL can expose only one canonical prefix. Conflicting legacy aliases are
+* therefore retained for manual resolution instead of being discarded.
+*
+* @param settings - Workspace settings to normalize in place
+* @param warnings - Collection that receives unresolved conflict warnings
+*/
+function normalizeNamedRegistries(settings, warnings) {
+	const { namedRegistries } = settings;
+	if (!namedRegistries) return;
+	const prefixesByUrl = /* @__PURE__ */ new Map();
+	for (const [prefix, url] of Object.entries(namedRegistries)) {
+		const prefixes = prefixesByUrl.get(url) ?? [];
+		prefixes.push(prefix);
+		prefixesByUrl.set(url, prefixes);
+	}
+	const conflicts = [...prefixesByUrl.entries()].filter(([, prefixes]) => prefixes.length > 1);
+	if (conflicts.length) {
+		warnings.push(`namedRegistries was kept because the new registries format supports one prefix per URL: ${conflicts.map(([url, prefixes]) => `${url} (${prefixes.join(", ")})`).join("; ")}.`);
+		return;
+	}
+	const declarations = {};
+	for (const [key, value] of Object.entries(settings.registries ?? {})) if (typeof value === "string") addRegistryScope(declarations, value, key === "default" ? "@" : key);
+	else declarations[key] = { ...value };
+	for (const [url, [prefix]] of prefixesByUrl) {
+		declarations[url] ??= {};
+		const declaration = declarations[url];
+		if (declaration.prefix && declaration.prefix !== prefix) {
+			warnings.push(`namedRegistries was kept because ${url} already declares prefix ${declaration.prefix}.`);
+			return;
+		}
+		declaration.prefix = prefix;
+	}
+	settings.registries = declarations;
+	Reflect.deleteProperty(settings, "namedRegistries");
+}
+/**
+* Replace aliases that remain accepted but are no longer canonical.
+*
+* @param settings - Workspace settings to normalize in place
+* @param warnings - Collection that receives unresolved conflict warnings
+*
+* @returns Nothing; settings and warnings are updated in place
+*/
+function normalizeCurrentAliases(settings, warnings) {
+	normalizeAuditSettings(settings);
+	normalizeUpdateSettings(settings);
+	normalizeScalarAliases(settings);
+	normalizeSideEffectsCache(settings);
+	normalizeNamedRegistries(settings, warnings);
+}
+//#endregion
+//#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`
+* @param cwd - Workspace root directory
+* @param file - Path declared by the legacy setting
 *
-* @returns Package names read from the referenced JSON file
+* @returns Validated package names, or an empty list when no file is declared
 *
-* @throws {TypeError} When the referenced JSON value is not a string array
-* @throws {SyntaxError} When the referenced file contains invalid JSON
+* @throws {TypeError} When the file does not contain an array of package names
 */
 async function readOnlyBuiltDependenciesFile(cwd, file) {
 	if (!file) return [];
@@ -316,21 +486,56 @@ 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.
+*
+* @param settings - Workspace settings containing the legacy list
+* @param key - Legacy setting name to read
+*
+* @returns Validated package names, or an empty list when the setting is absent
+*
+* @throws {TypeError} When the setting is not an array of package names
+*/
+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
+* @param incomingSettings - Legacy settings to read and normalize
+* @param cwd - Workspace root used to resolve dependency list files
 *
-* @returns Package-to-permission map, or `undefined` when no entries exist
+* @returns Package permissions, or `undefined` when no legacy values 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.
 *
@@ -407,6 +612,7 @@ async function normalizeIncomingSettings(incomingSettings, options) {
 	const pmOnFail = resolvePmOnFail(incomingSettings);
 	if (pmOnFail) incomingSettings.pmOnFail = pmOnFail;
 	normalizeAuditConfig(incomingSettings, warnings);
+	if (replaceDeprecated) normalizeCurrentAliases(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.");
@@ -466,6 +672,28 @@ const PNPM_V11_MAJOR = 11;
 */
 const PNPM_V12_MAJOR = 12;
 /**
+* Resolve a pnpm major from a package manager declaration.
+*
+* @param hint - Package manager declaration to inspect
+*
+* @returns Detected pnpm major, or `undefined` when the hint does not match
+*/
+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.
+*
+* @param value - Optional single or multiple package manager declarations
+*
+* @returns Package manager declarations normalized to an array
+*/
+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 +704,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
@@ -557,6 +786,380 @@ function mergeByStrategy(existing, incoming, strategy) {
 	}
 }
 //#endregion
+//#region src/settings-fields.ts
+/**
+* Settings that a project-level `pnpm-workspace.yaml` must never control.
+*
+* @see https://github.com/pnpm/pnpm/blob/main/pnpm11/config/reader/src/index.ts
+* @see https://github.com/pnpm/pnpm/blob/v12.2.1/pnpm/crates/config/src/refused_keys.rs
+*/
+const PNPM_PROJECT_REFUSED_SETTINGS = [
+	"allProjects",
+	"allProjectsGraph",
+	"authConfig",
+	"bin",
+	"cliOptions",
+	"configByUri",
+	"configDir",
+	"explicitlySetKeys",
+	"finders",
+	"globalBinDir",
+	"globalDir",
+	"globalPkgDir",
+	"hooks",
+	"npmrcAuthFile",
+	"packageManager",
+	"packageManagerNetworkConfig",
+	"packageManagerRegistries",
+	"pnpmHomeDir",
+	"prodAllProjectsGraph",
+	"prodOnlySelectedProjectDirs",
+	"rootProjectManifest",
+	"rootProjectManifestDir",
+	"scope",
+	"selectedProjectsGraph",
+	"stateDir",
+	"userConfig",
+	"userconfig",
+	"wantedPackageManager",
+	"workspaceDir"
+];
+/**
+* Settings added to, or recognized by, pnpm's v11 workspace config schema.
+* Combined with the v10 settings below to form the complete v11 allowlist.
+*
+* @see https://github.com/pnpm/pnpm/blob/main/pnpm11/config/reader/src/types.ts
+* @see https://github.com/pnpm/pnpm/blob/main/pnpm11/config/reader/src/unknownSettings.ts
+*/
+const PNPM_V11_ADDITIONAL_WORKSPACE_SETTINGS_FIELDS = [
+	"access",
+	"aggregateOutput",
+	"allowNew",
+	"allowSameVersion",
+	"audit",
+	"auditIgnorePrune",
+	"autoConfirmAllPrompts",
+	"bail",
+	"binLinks",
+	"catalog",
+	"catalogPrune",
+	"catalogs",
+	"changedFilesIgnorePattern",
+	"commitHooks",
+	"confirmModulesPurge",
+	"cpu",
+	"dedupePeers",
+	"depth",
+	"description",
+	"dev",
+	"dryRun",
+	"embedReadme",
+	"enablePnp",
+	"excludeLinksFromLockfile",
+	"extraBinPaths",
+	"extraEnv",
+	"fetchingConcurrency",
+	"filter",
+	"filterProd",
+	"force",
+	"frozenStore",
+	"git",
+	"gitTagVersion",
+	"global",
+	"globalPath",
+	"globalPrefix",
+	"hoistingLimits",
+	"ignoreCurrentSpecifiers",
+	"ignoreWorkspace",
+	"initAuthorEmail",
+	"initAuthorName",
+	"initAuthorUrl",
+	"initLicense",
+	"initPackageManager",
+	"initType",
+	"initVersion",
+	"json",
+	"legacyDirFiltering",
+	"libc",
+	"lockfileOnly",
+	"long",
+	"maxSockets",
+	"message",
+	"minimumReleaseAgeExcludePrune",
+	"minimumReleaseAgeIgnoreMissingTime",
+	"minimumReleaseAgeStrict",
+	"namedRegistries",
+	"nodeDownloadMirrors",
+	"nodeExperimentalPackageMap",
+	"nodePackageMapType",
+	"offline",
+	"only",
+	"os",
+	"packDestination",
+	"packGzipLevel",
+	"packageConfigs",
+	"packageLock",
+	"packages",
+	"parseable",
+	"patchesDir",
+	"pending",
+	"pmOnFail",
+	"pnpmExecPath",
+	"pnprServer",
+	"preferOffline",
+	"preserveAbsolutePaths",
+	"progress",
+	"provenance",
+	"publishBranch",
+	"recursive",
+	"registries",
+	"registriesByPrefix",
+	"registriesByScope",
+	"registry",
+	"registryOptionsByUrl",
+	"remoteSideEffectsCache",
+	"reporter",
+	"reporterHidePrefix",
+	"reverse",
+	"runtime",
+	"runtimeOnFail",
+	"save",
+	"saveCatalogName",
+	"saveDev",
+	"saveOptional",
+	"savePeer",
+	"saveProd",
+	"scriptsPrependNodePath",
+	"sideEffectsCacheRead",
+	"sideEffectsCacheWrite",
+	"signGitTag",
+	"skipManifestObfuscation",
+	"sort",
+	"stream",
+	"tasks",
+	"testPattern",
+	"trustLockfile",
+	"tryLoadDefaultPnpmfile",
+	"umask",
+	"update",
+	"useGitBranchLockfile",
+	"useLockfile",
+	"userAgent",
+	"version",
+	"versioning",
+	"virtualStoreOnly",
+	"virtualStoreType",
+	"workspacePackagePatterns",
+	"workspacePackages",
+	"workspacePrefix",
+	"workspaceRoot",
+	"yes"
+];
+const refusedProjectSettings = new Set(PNPM_PROJECT_REFUSED_SETTINGS);
+/**
+* Settings accepted by a pnpm v11 project workspace manifest.
+*/
+const PNPM_V11_WORKSPACE_SETTINGS_FIELDS = [.../* @__PURE__ */ new Set([...PNPM_V10_NPMRC_SETTINGS_FIELDS, ...PNPM_V11_ADDITIONAL_WORKSPACE_SETTINGS_FIELDS])].filter((field) => !refusedProjectSettings.has(field));
+/**
+* Settings that are supported by v11 but not by pnpm v12.
+*/
+const PNPM_V11_ONLY_WORKSPACE_SETTINGS = ["confirmModulesPurge", "packageConfigs"];
+/**
+* Settings introduced by pnpm v12.
+*/
+const PNPM_V12_ONLY_WORKSPACE_SETTINGS = [
+	"autoInstallPeersFromHighestMatch",
+	"externalDependencies",
+	"globalShims"
+];
+const v11OnlyWorkspaceSettings = new Set(PNPM_V11_ONLY_WORKSPACE_SETTINGS);
+/**
+* Settings accepted by a pnpm v12 project workspace manifest.
+*/
+const PNPM_V12_WORKSPACE_SETTINGS_FIELDS = [...PNPM_V11_WORKSPACE_SETTINGS_FIELDS.filter((field) => !v11OnlyWorkspaceSettings.has(field)), ...PNPM_V12_ONLY_WORKSPACE_SETTINGS];
+/**
+* Fields pnpm v11 accepts inside a `packageConfigs` entry.
+*/
+const PNPM_V11_PACKAGE_CONFIG_FIELDS = [
+	"hoist",
+	"modulesDir",
+	"overrides",
+	"saveExact",
+	"savePrefix"
+];
+//#endregion
+//#region src/utils/settings-schema.ts
+const PNPM_V10_WORKSPACE_SETTINGS_FIELDS = [
+	...PNPM_V10_NPMRC_SETTINGS_FIELDS,
+	"catalog",
+	"catalogs",
+	"packages"
+];
+const PROJECT_REFUSED_SETTINGS = new Set(PNPM_PROJECT_REFUSED_SETTINGS);
+const PNPM_V11_ONLY_SETTINGS = new Set(PNPM_V11_ONLY_WORKSPACE_SETTINGS);
+const PNPM_V11_SETTINGS = new Set(PNPM_V11_WORKSPACE_SETTINGS_FIELDS);
+const PNPM_V12_ONLY_SETTINGS = new Set(PNPM_V12_ONLY_WORKSPACE_SETTINGS);
+const PNPM_V12_SETTINGS = new Set(PNPM_V12_WORKSPACE_SETTINGS_FIELDS);
+const PNPM_V10_SETTINGS = new Set(PNPM_V10_WORKSPACE_SETTINGS_FIELDS);
+const REGISTRY_SETTINGS = /* @__PURE__ */ new Set([
+	"namedRegistries",
+	"registries",
+	"registriesByPrefix",
+	"registriesByScope",
+	"registry",
+	"registryOptionsByUrl"
+]);
+const REGISTRY_CREDENTIAL_KEYS = /* @__PURE__ */ new Set([
+	"auth",
+	"authtoken",
+	"password",
+	"token",
+	"tokenhelper",
+	"username"
+]);
+const WORKSPACE_SCHEMA_DIRECTIVE = "$schema";
+/**
+* Create an empty collection of schema selection issues.
+*
+* @returns Empty issue lists for every supported issue category
+*/
+function createSettingsIssues() {
+	return {
+		incompatible: [],
+		nonCamelCase: [],
+		refused: [],
+		unsafe: [],
+		unknown: [],
+		unsupported: []
+	};
+}
+function hasUrlCredentials(value) {
+	try {
+		const url = new URL(value);
+		return Boolean(url.username || url.password);
+	} catch {
+		return false;
+	}
+}
+function isRegistryCredentialKey(key) {
+	return REGISTRY_CREDENTIAL_KEYS.has(key.replaceAll("-", "").replaceAll("_", "").toLowerCase());
+}
+function isUnsafeRegistryUrl(value) {
+	return value.includes("${") || hasUrlCredentials(value);
+}
+function containsUnsafeRegistryValue(value, checkCredentialKeys = false) {
+	if (typeof value === "string") return isUnsafeRegistryUrl(value);
+	if (!value || typeof value !== "object") return false;
+	return Object.entries(value).some(([key, entryValue]) => checkCredentialKeys && isRegistryCredentialKey(key) || isUnsafeRegistryUrl(key) || containsUnsafeRegistryValue(entryValue, true));
+}
+function resolveCamelCaseKey(key) {
+	return Object.keys(camelcaseKeys({ [key]: true }))[0] ?? key;
+}
+function resolveTargetSettings(compatibility) {
+	switch (compatibility) {
+		case "v10": return PNPM_V10_SETTINGS;
+		case "v11": return PNPM_V11_SETTINGS;
+		case "v12": return PNPM_V12_SETTINGS;
+		default: throw new TypeError(`Unsupported compatibility target: ${compatibility}`);
+	}
+}
+function isSettingFromAnotherMajor(key, compatibility) {
+	if (compatibility === "v11") return PNPM_V12_ONLY_SETTINGS.has(key);
+	if (compatibility === "v12") return PNPM_V11_ONLY_SETTINGS.has(key);
+	return PNPM_V11_SETTINGS.has(key) || PNPM_V12_SETTINGS.has(key);
+}
+function resolveSettingIssue({ allowedFields, compatibility, key, npmrc, targetSettings, value }) {
+	if (!npmrc && key !== resolveCamelCaseKey(key)) return "nonCamelCase";
+	if (compatibility !== "v10" && PROJECT_REFUSED_SETTINGS.has(key)) return "refused";
+	if (REGISTRY_SETTINGS.has(key) && containsUnsafeRegistryValue(value)) return "unsafe";
+	if (!targetSettings.has(key)) return isSettingFromAnotherMajor(key, compatibility) ? "incompatible" : "unknown";
+	if (allowedFields && !allowedFields.has(key)) return "unsupported";
+}
+/**
+* Select settings that are valid for a concrete pnpm workspace schema.
+*
+* Unrecognized, refused, incompatible, and destination-specific unsupported
+* settings are reported but never returned for migration.
+*
+* @param rawSettings - Settings read from a legacy configuration source
+* @param compatibility - Concrete pnpm compatibility target
+* @param options - Source spelling and destination field restrictions
+*
+* @returns Selected settings, original source keys, and rejected field groups
+*/
+function selectPnpmSettings(rawSettings, compatibility, options = {}) {
+	const issues = createSettingsIssues();
+	const keys = [];
+	const settings = {};
+	const targetSettings = resolveTargetSettings(compatibility);
+	const allowedFields = options.allowedFields ? new Set(options.allowedFields) : void 0;
+	for (const [originalKey, value] of Object.entries(rawSettings)) {
+		const key = options.npmrc ? resolveCamelCaseKey(originalKey) : originalKey;
+		const issue = resolveSettingIssue({
+			allowedFields,
+			compatibility,
+			key,
+			npmrc: Boolean(options.npmrc),
+			targetSettings,
+			value
+		});
+		if (issue) issues[issue].push(originalKey);
+		else {
+			keys.push(originalKey);
+			settings[key] = value;
+		}
+	}
+	return {
+		issues,
+		keys,
+		settings
+	};
+}
+function assertPackageConfigFields(settings) {
+	const { packageConfigs } = settings;
+	if (packageConfigs === void 0) return;
+	const allowedFields = new Set(PNPM_V11_PACKAGE_CONFIG_FIELDS);
+	const entries = Array.isArray(packageConfigs) ? packageConfigs.flatMap((entry, index) => {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new TypeError(`packageConfigs[${index}] must be an object with a match array.`);
+		const { match, ...config } = entry;
+		if (!Array.isArray(match) || !match.every((projectName) => typeof projectName === "string")) throw new TypeError(`packageConfigs[${index}].match must be an array of package names.`);
+		return [[`packageConfigs[${index}]`, config]];
+	}) : Object.entries(packageConfigs);
+	for (const [name, config] of entries) {
+		if (!config || typeof config !== "object" || Array.isArray(config)) throw new TypeError(`${name} must contain a project settings object.`);
+		const unsupported = Object.keys(config).filter((key) => !allowedFields.has(key));
+		if (unsupported.length) throw new TypeError(`${name} contains unsupported project settings: ${unsupported.map((key) => JSON.stringify(key)).join(", ")}.`);
+	}
+}
+function formatIssueList(keys) {
+	return keys.map((key) => JSON.stringify(key)).join(", ");
+}
+/**
+* Assert that an existing workspace manifest matches the selected pnpm major.
+*
+* The migrator refuses to rewrite a manifest containing ignored settings so a
+* migration cannot silently preserve invalid output.
+*
+* @param settings - Existing workspace settings to validate
+* @param compatibility - Concrete pnpm compatibility target
+*
+* @returns Nothing when all settings match the target schema
+*
+* @throws {TypeError} When the manifest contains incompatible settings
+*/
+function assertCompatibleWorkspaceSettings(settings, compatibility) {
+	if (compatibility === "v10") return;
+	const { issues } = selectPnpmSettings(Object.fromEntries(Object.entries(settings).filter(([key]) => key !== WORKSPACE_SCHEMA_DIRECTIVE)), compatibility);
+	const problems = [];
+	if (issues.refused.length) problems.push(`refused: ${formatIssueList(issues.refused)}`);
+	if (issues.incompatible.length) problems.push(`other pnpm major: ${formatIssueList(issues.incompatible)}`);
+	if (issues.nonCamelCase.length) problems.push(`not camelCase: ${formatIssueList(issues.nonCamelCase)}`);
+	if (issues.unknown.length) problems.push(`unrecognized: ${formatIssueList(issues.unknown)}`);
+	if (issues.unsafe.length) problems.push(`unsafe registry URL: ${formatIssueList(issues.unsafe)}`);
+	if (problems.length) throw new TypeError(`pnpm-workspace.yaml is incompatible with pnpm ${compatibility.slice(1)} (${problems.join("; ")}).`);
+	if (compatibility === "v11") assertPackageConfigFields(settings);
+}
+//#endregion
 //#region src/utils/npmrc.ts
 /**
 * Authentication and registry keys that must remain in `.npmrc`.
@@ -581,6 +1184,9 @@ const NPMRC_AUTH_OR_REGISTRY_KEYS = [
 * Pattern for pnpm's channel-specific Node.js mirror keys.
 */
 const NODE_MIRROR_KEY_PATTERN = /^node-mirror:(?<channel>.+)$/iu;
+function mergeSettingsIssues(target, source, sourceKeys) {
+	for (const reason of Object.keys(target)) if (source[reason].length) target[reason].push(...sourceKeys ?? source[reason]);
+}
 /**
 * Normalize `.npmrc` key for case-insensitive matching.
 *
@@ -622,9 +1228,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 +1241,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);
@@ -658,44 +1261,271 @@ async function pruneNpmrc(path, compatibility = "v10", migratedKeys = []) {
 * Read `.npmrc` and return settings that should be migrated into workspace config.
 *
 * - `v10`: returns settings from the legacy whitelist.
-* - `v11+`: excludes auth/registry keys because pnpm still reads them from
-*   `.npmrc`.
+* - `v11+`: selects target-schema settings and retains auth, registry,
+*   refused, incompatible, and unknown keys.
 *
 * @param path - Absolute path to the `.npmrc` file
 * @param compatibility - Concrete pnpm compatibility target
+* @param options - Optional destination-specific field restrictions
 *
 * @returns Migratable settings and their original `.npmrc` keys
 *
 * @throws {Error} When file reading or INI parsing fails
 */
-async function readMigratableNpmrc(path, compatibility) {
+async function readMigratableNpmrc(path, compatibility, options = {}) {
 	const raw = await readIniFile(path);
+	const issues = createSettingsIssues();
 	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)
+			issues,
+			keys,
+			settings: camelcaseKeys(migratable)
 		};
 	}
 	const migratable = {};
 	const keys = [];
 	const nodeDownloadMirrors = {};
+	const nodeDownloadMirrorKeys = [];
 	for (const [key, value] of Object.entries(raw)) if (!isNpmrcAuthOrRegistryKey(key)) {
-		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;
-	}
+		if (nodeMirrorMatch?.groups?.channel) {
+			nodeDownloadMirrorKeys.push(key);
+			nodeDownloadMirrors[nodeMirrorMatch.groups.channel] = String(value);
+		} else {
+			const selected = selectPnpmSettings({ [key]: value }, compatibility, {
+				allowedFields: options.allowedFields,
+				npmrc: true
+			});
+			keys.push(...selected.keys);
+			Object.assign(migratable, selected.settings);
+			mergeSettingsIssues(issues, selected.issues);
+		}
+	}
 	const settings = camelcaseKeys(migratable);
-	if (Object.keys(nodeDownloadMirrors).length) settings.nodeDownloadMirrors = nodeDownloadMirrors;
+	if (Object.keys(nodeDownloadMirrors).length) {
+		const selected = selectPnpmSettings({ nodeDownloadMirrors }, compatibility, { allowedFields: options.allowedFields });
+		if (selected.keys.length) {
+			keys.push(...nodeDownloadMirrorKeys);
+			settings.nodeDownloadMirrors = nodeDownloadMirrors;
+		} else mergeSettingsIssues(issues, selected.issues, nodeDownloadMirrorKeys);
+	}
 	return {
+		issues,
 		keys,
 		settings
 	};
 }
 //#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 {
+		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: parsedValue ?? {}
+	};
+}
+/**
+* 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
+* @param compatibility - Concrete pnpm compatibility target
+*
+* @returns Selected workspace settings and source cleanup metadata
+*/
+function resolvePackageJsonSettings(packageJson, yarnResolutions, compatibility) {
+	const selected = selectPnpmSettings(Object.fromEntries(Object.entries(packageJson.pnpm ?? {})), compatibility);
+	const migrateYarnResolutions = Boolean(yarnResolutions && packageJson.resolutions);
+	const pnpmSettings = migrateYarnResolutions ? {
+		...selected.settings,
+		overrides: defu(selected.settings.overrides, packageJson.resolutions)
+	} : { ...selected.settings };
+	if (pnpmSettings.overrides && !Object.keys(pnpmSettings.overrides).length) delete pnpmSettings.overrides;
+	return {
+		issues: selected.issues,
+		keys: selected.keys,
+		settings: pnpmSettings,
+		yarnResolutions: migrateYarnResolutions
+	};
+}
+//#endregion
+//#region src/utils/project-npmrc.ts
+function resolvePackageJsonPatterns(patterns) {
+	return patterns.map((pattern) => {
+		const negated = pattern.startsWith("!");
+		const workspacePattern = (negated ? pattern.slice(1) : pattern).replace(/\/+$/u, "");
+		const packageJsonPattern = workspacePattern === "." ? PACKAGE_JSON : `${workspacePattern}/${PACKAGE_JSON}`;
+		return negated ? `!${packageJsonPattern}` : packageJsonPattern;
+	});
+}
+/**
+* Collect unique workspace package patterns from multiple settings sources.
+*
+* @param settingsSources - Workspace settings that may declare package patterns
+*
+* @returns Unique package patterns in source order
+*/
+function collectWorkspacePackagePatterns(...settingsSources) {
+	return [...new Set(settingsSources.flatMap((settings) => Array.isArray(settings.packages) ? settings.packages : []))];
+}
+async function readProjectManifestCandidates(cwd, patterns) {
+	if (!patterns.some((pattern) => !pattern.startsWith("!"))) return {
+		candidates: [],
+		warnings: []
+	};
+	const rootPackageJsonPath = resolve(cwd, PACKAGE_JSON);
+	const packageJsonPaths = await glob(resolvePackageJsonPatterns(patterns), {
+		absolute: true,
+		cwd,
+		dot: true,
+		ignore: ["**/node_modules/**"],
+		onlyFiles: true
+	});
+	const candidateResults = await Promise.all([...new Set(packageJsonPaths)].sort().filter((packageJsonPath) => resolve(packageJsonPath) !== rootPackageJsonPath).map(async (packageJsonPath) => {
+		const projectDir = dirname(packageJsonPath);
+		const npmrcPath = resolve(projectDir, NPMRC);
+		if (!await fsExists(npmrcPath)) return {};
+		const packageJson = await readPackageJson(packageJsonPath, true);
+		if (!packageJson.value.name) return { warning: `${relative(cwd, npmrcPath)} was kept because its package.json has no name for packageConfigs matching.` };
+		return { candidate: {
+			npmrcPath,
+			packageJsonPath,
+			projectName: packageJson.value.name
+		} };
+	}));
+	const candidates = [];
+	const warnings = [];
+	for (const result of candidateResults) {
+		if (result.candidate) candidates.push(result.candidate);
+		if (result.warning) warnings.push(result.warning);
+	}
+	return {
+		candidates,
+		warnings
+	};
+}
+/**
+* Collect supported settings from subproject `.npmrc` files.
+*
+* pnpm v11 accepts five fields in `packageConfigs`. pnpm v12 does not support
+* `packageConfigs`, so its subproject settings are only reported and retained.
+*
+* @param cwd - Workspace root directory
+* @param patterns - Workspace package patterns used to discover subprojects
+* @param compatibility - Concrete pnpm compatibility target
+*
+* @returns Migratable project settings, source metadata, and warnings
+*/
+async function readProjectNpmrcMigrations(cwd, patterns, compatibility) {
+	if (compatibility === "v10") return {
+		packageConfigs: {},
+		projects: [],
+		warnings: []
+	};
+	const { candidates, warnings } = await readProjectManifestCandidates(cwd, patterns);
+	const candidatesByName = /* @__PURE__ */ new Map();
+	for (const candidate of candidates) {
+		const namedCandidates = candidatesByName.get(candidate.projectName) ?? [];
+		namedCandidates.push(candidate);
+		candidatesByName.set(candidate.projectName, namedCandidates);
+	}
+	const packageConfigs = {};
+	const projects = [];
+	const allowedFields = compatibility === "v11" ? PNPM_V11_PACKAGE_CONFIG_FIELDS : [];
+	const migrationResults = await Promise.all([...candidatesByName].map(async ([projectName, namedCandidates]) => {
+		if (namedCandidates.length > 1) return { warning: `Subproject .npmrc files for duplicate package name ${JSON.stringify(projectName)} were kept: ${namedCandidates.map((candidate) => relative(cwd, candidate.packageJsonPath)).join(", ")}.` };
+		const [candidate] = namedCandidates;
+		return { project: {
+			migratable: await readMigratableNpmrc(candidate.npmrcPath, compatibility, { allowedFields }),
+			npmrcPath: candidate.npmrcPath,
+			projectName
+		} };
+	}));
+	for (const result of migrationResults) {
+		if (result.warning) warnings.push(result.warning);
+		if (result.project) {
+			projects.push(result.project);
+			if (result.project.migratable.keys.length) packageConfigs[result.project.projectName] = result.project.migratable.settings;
+		}
+	}
+	return {
+		packageConfigs,
+		projects,
+		warnings
+	};
+}
+//#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 +1544,43 @@ 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.
+*
+* @param beforeLines - YAML lines before migration
+* @param afterLines - YAML lines after migration
+*
+* @returns Classified diff lines in display order
+*/
+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 +1589,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 +1644,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 +1662,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,78 +1684,312 @@ function reportSettingsChanges(changes) {
 	}
 }
 //#endregion
-//#region src/utils/config.ts
+//#region src/utils/settings-issue-report.ts
+function formatIssueKeys(keys) {
+	return keys.map((key) => JSON.stringify(key)).join(", ");
+}
 /**
-* Resolve the indentation width for a YAML document.
+* Report settings that were intentionally left in their source.
 *
-* @param content - Raw YAML content
+* @param options - Retained settings and destination context
 *
-* @returns Detected indentation width or the project default
+* @returns Nothing; warnings are written through consola
 */
-function resolveYamlIndent(content) {
-	const detectedIndent = detectIndent(content).amount;
-	return detectedIndent > 0 ? detectedIndent : 2;
+function reportSettingsIssues(options) {
+	const { compatibility, issues, projectConfig = false, source } = options;
+	if (issues.refused.length) consola$1.warn(`Kept project-refused settings in ${source}: ${formatIssueKeys(issues.refused)}. Configure machine settings globally and current-run paths on the command line.`);
+	if (issues.incompatible.length) consola$1.warn(`Kept settings in ${source} that are incompatible with pnpm ${compatibility.slice(1)}: ${formatIssueKeys(issues.incompatible)}.`);
+	if (issues.nonCamelCase.length) consola$1.warn(`Kept non-camelCase settings in ${source}: ${formatIssueKeys(issues.nonCamelCase)}. Workspace manifest keys must use camelCase.`);
+	if (issues.unknown.length) consola$1.warn(`Kept settings in ${source} that pnpm ${compatibility.slice(1)} does not recognize: ${formatIssueKeys(issues.unknown)}.`);
+	if (issues.unsupported.length) {
+		const destination = projectConfig && compatibility === "v12" ? "pnpm v12 does not support packageConfigs" : "packageConfigs only accepts hoist, modulesDir, overrides, saveExact, and savePrefix";
+		consola$1.warn(`Kept subproject settings in ${source}: ${formatIssueKeys(issues.unsupported)}; ${destination}.`);
+	}
+	if (issues.unsafe.length) consola$1.warn(`Kept unsafe registry settings in ${source}: ${formatIssueKeys(issues.unsafe)}. Remove credentials and dynamic URL interpolation before migrating them.`);
 }
+//#endregion
+//#region src/utils/yaml-document.ts
 /**
-* Read and parse a package manifest when it exists.
+* Sort every mapping in a YAML node without replacing its comments or anchors.
 *
-* @param path - Absolute path to `package.json`
-* @param exists - Whether the package manifest exists
+* @param node - YAML node whose nested mappings should be sorted
+*/
+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.
 *
-* @returns Parsed package manifest and detected indentation
+* @param document - Parsed YAML document to update in place
+* @param options - Before/after settings and sorting preference
 *
-* @throws {SyntaxError} When the package manifest contains invalid JSON
+* @returns Nothing; the document is updated in place
 */
-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)
-	};
+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);
 }
 /**
-* Read and parse a pnpm workspace manifest when it exists.
+* Normalize blank lines immediately before root mapping keys.
 *
-* @param path - Absolute path to `pnpm-workspace.yaml`
-* @param exists - Whether the workspace manifest exists
+* @param content - Serialized workspace YAML
+* @param newlineBetween - Whether root keys should be separated by blank lines
 *
-* @returns Parsed workspace settings and detected indentation
+* @returns YAML with normalized root-key spacing
+*/
+function formatRootSpacing(content, newlineBetween) {
+	return content.replace(/\n+(?=[^\s#][^:\n]*:)/gu, newlineBetween ? "\n\n" : "\n");
+}
+//#endregion
+//#region src/migration-persistence.ts
+const SETTINGS_WITHOUT_REPLACEMENT = /* @__PURE__ */ new Set(["ignoreDepScripts", "ignorePatchFailures"]);
+const REPLACEMENT_SETTING_KEYS = {
+	allowNonAppliedPatches: "allowUnusedPatches",
+	auditConfig: "audit",
+	auditLevel: "audit",
+	cleanupUnusedCatalogs: "catalogPrune",
+	enableGlobalVirtualStore: "virtualStoreType",
+	ignoredBuiltDependencies: "allowBuilds",
+	managePackageManagerVersions: "pmOnFail",
+	namedRegistries: "registries",
+	neverBuiltDependencies: "allowBuilds",
+	onlyBuiltDependencies: "allowBuilds",
+	onlyBuiltDependenciesFile: "allowBuilds",
+	packageManagerStrict: "pmOnFail",
+	packageManagerStrictVersion: "pmOnFail",
+	remoteSideEffectsCache: "sideEffectsCache",
+	sideEffectsCacheReadonly: "sideEffectsCache",
+	updateConfig: "update"
+};
+function cleanPackageJsonSettings({ migratedKeys, packageJson, settings, yarnResolutionsApplied }) {
+	let changed = false;
+	if (packageJson.value.pnpm) {
+		for (const key of migratedKeys) {
+			Reflect.deleteProperty(packageJson.value.pnpm, key);
+			changed = true;
+		}
+		if (!Object.keys(packageJson.value.pnpm).length) delete packageJson.value.pnpm;
+	}
+	if (settings.yarnResolutions && yarnResolutionsApplied) {
+		changed = true;
+		delete packageJson.value.resolutions;
+	}
+	return changed;
+}
+function containsMigratedValue(actual, expected) {
+	if (Array.isArray(actual) && Array.isArray(expected)) return expected.every((expectedItem) => actual.some((actualItem) => containsMigratedValue(actualItem, expectedItem)));
+	if (actual && expected && typeof actual === "object" && typeof expected === "object") return Object.entries(expected).every(([key, expectedValue]) => containsMigratedValue(actual[key], expectedValue));
+	return Object.is(actual, expected);
+}
+function resolveSourceRuntimeVersion(sourceSettings, targetKey) {
+	if (targetKey === "useNodeVersion") return Reflect.get(sourceSettings, "useNodeVersion");
+	const executionEnv = Reflect.get(sourceSettings, "executionEnv");
+	if (!executionEnv || typeof executionEnv !== "object" || Array.isArray(executionEnv)) return;
+	return executionEnv.nodeVersion;
+}
+function resolveReplacementSettingKey(sourceKey, targetKey, npmrc) {
+	if (npmrc && /^node-mirror:/iu.test(sourceKey)) return "nodeDownloadMirrors";
+	return REPLACEMENT_SETTING_KEYS[targetKey];
+}
+function selectAppliedRootKeys({ finalSettings, incomingSettings, keys, npmrc = false, runtimeApplied, runtimeVersion, sourceSettings }) {
+	return keys.filter((sourceKey) => {
+		const targetKey = npmrc ? Object.keys(camelcaseKeys({ [sourceKey]: true }))[0] ?? sourceKey : sourceKey;
+		if (!Object.hasOwn(incomingSettings, targetKey)) {
+			if (targetKey === "executionEnv" || targetKey === "useNodeVersion") {
+				const sourceRuntimeVersion = resolveSourceRuntimeVersion(sourceSettings, targetKey);
+				return runtimeApplied && typeof sourceRuntimeVersion === "string" && sourceRuntimeVersion === runtimeVersion;
+			}
+			if (SETTINGS_WITHOUT_REPLACEMENT.has(targetKey)) return false;
+			const replacementKey = resolveReplacementSettingKey(sourceKey, targetKey, npmrc);
+			if (!replacementKey || !Object.hasOwn(incomingSettings, replacementKey)) return true;
+			return containsMigratedValue(Reflect.get(finalSettings, replacementKey), Reflect.get(incomingSettings, replacementKey));
+		}
+		return containsMigratedValue(Reflect.get(finalSettings, targetKey), Reflect.get(incomingSettings, targetKey));
+	});
+}
+function resolveProjectConfig(settings, projectName) {
+	const { packageConfigs } = settings;
+	if (!packageConfigs || typeof packageConfigs !== "object" || Array.isArray(packageConfigs)) return;
+	const projectConfig = packageConfigs[projectName];
+	return projectConfig && typeof projectConfig === "object" && !Array.isArray(projectConfig) ? projectConfig : void 0;
+}
+function selectAppliedProjectKeys(project, finalSettings) {
+	const finalProjectConfig = resolveProjectConfig(finalSettings, project.projectName);
+	if (!finalProjectConfig) return [];
+	return project.migratable.keys.filter((sourceKey) => {
+		const targetKey = Object.keys(camelcaseKeys({ [sourceKey]: true }))[0] ?? sourceKey;
+		return containsMigratedValue(finalProjectConfig[targetKey], project.migratable.settings[targetKey]);
+	});
+}
+/**
+* Persist destinations before pruning any legacy source file.
 *
-* @throws {Error} When the workspace manifest contains invalid YAML
+* @param options - Destination files, selected sources, and cleanup policy
+*
+* @returns A promise that resolves after destinations and sources are persisted
 */
-async function readPnpmWorkspace(path, exists) {
-	if (!exists) return {
-		indent: 2,
-		value: {}
+async function persistMigration(options) {
+	const { cleanNpmrc, cleanPackageJson, compatibility, finalSettings, incomingSettings, npmrc, npmrcExists, npmrcPath, packageJson, packageJsonExists, packageJsonPath, packageJsonRuntimeChanged, packageJsonSettings, pnpmWorkspaceContent, pnpmWorkspacePath, projectNpmrcs, runtimeVersion } = options;
+	const appliedPackageJsonKeys = selectAppliedRootKeys({
+		finalSettings,
+		incomingSettings,
+		keys: packageJsonSettings.keys,
+		runtimeApplied: packageJsonRuntimeChanged,
+		runtimeVersion,
+		sourceSettings: packageJsonSettings.settings
+	});
+	const appliedNpmrcKeys = selectAppliedRootKeys({
+		finalSettings,
+		incomingSettings,
+		keys: npmrc.keys,
+		npmrc: true,
+		runtimeApplied: packageJsonRuntimeChanged,
+		runtimeVersion,
+		sourceSettings: npmrc.settings
+	});
+	const yarnResolutionsApplied = packageJsonSettings.yarnResolutions && containsMigratedValue(finalSettings.overrides, incomingSettings.overrides);
+	const packageJsonSettingsChanged = packageJsonExists && cleanPackageJson ? cleanPackageJsonSettings({
+		migratedKeys: appliedPackageJsonKeys,
+		packageJson,
+		settings: packageJsonSettings,
+		yarnResolutionsApplied
+	}) : false;
+	await fsWriteFile(pnpmWorkspacePath, pnpmWorkspaceContent);
+	if (packageJsonExists && (packageJsonRuntimeChanged || packageJsonSettingsChanged)) await fsWriteFile(packageJsonPath, JSON.stringify(packageJson.value, null, packageJson.indent));
+	if (!cleanNpmrc) return;
+	const pruneTasks = projectNpmrcs.projects.flatMap((project) => {
+		const appliedKeys = selectAppliedProjectKeys(project, finalSettings);
+		return appliedKeys.length ? [pruneNpmrc(project.npmrcPath, compatibility, appliedKeys)] : [];
+	});
+	if (npmrcExists && appliedNpmrcKeys.length) pruneTasks.push(pruneNpmrc(npmrcPath, compatibility, appliedNpmrcKeys));
+	await Promise.all(pruneTasks);
+}
+//#endregion
+//#region src/migration-sources.ts
+/**
+* Read, schema-filter, report, and merge all legacy settings sources.
+*
+* @param options - Migration target and source configuration
+*
+* @returns Resolved source metadata and merged incoming settings
+*/
+async function resolveMigrationSources(options) {
+	const { compatibility, cwd, npmrcExists, npmrcPath, packageJson, pnpmWorkspace, strategy, yarnResolutions } = options;
+	const npmrc = npmrcExists ? await readMigratableNpmrc(npmrcPath, compatibility) : {
+		issues: createSettingsIssues(),
+		keys: [],
+		settings: {}
 	};
-	const content = await fsReadFile(path);
+	reportSettingsIssues({
+		compatibility,
+		issues: npmrc.issues,
+		source: NPMRC
+	});
+	const packageJsonSettings = resolvePackageJsonSettings(packageJson, yarnResolutions, compatibility);
+	reportSettingsIssues({
+		compatibility,
+		issues: packageJsonSettings.issues,
+		source: `${PACKAGE_JSON}#pnpm`
+	});
+	const projectNpmrcs = await readProjectNpmrcMigrations(cwd, collectWorkspacePackagePatterns(mergeByStrategy(pnpmWorkspace, mergeByStrategy(packageJsonSettings.settings, npmrc.settings, "merge"), strategy)), compatibility);
+	for (const warning of projectNpmrcs.warnings) consola$1.warn(warning);
+	for (const project of projectNpmrcs.projects) reportSettingsIssues({
+		compatibility,
+		issues: project.migratable.issues,
+		projectConfig: true,
+		source: relative(cwd, project.npmrcPath)
+	});
+	const npmrcSettings = mergeByStrategy(npmrc.settings, Object.keys(projectNpmrcs.packageConfigs).length ? { packageConfigs: projectNpmrcs.packageConfigs } : {}, "merge");
 	return {
-		indent: resolveYamlIndent(content),
-		value: parse(content) ?? {}
+		incomingSettings: mergeByStrategy(packageJsonSettings.settings, npmrcSettings, "merge"),
+		npmrc,
+		packageJson: packageJsonSettings,
+		projectNpmrcs
 	};
 }
+//#endregion
+//#region src/options.ts
 /**
-* Resolve migratable pnpm settings from a package manifest.
+* Default values for migration options.
+*/
+const DEFAULT_OPTIONS = {
+	cleanNpmrc: true,
+	cleanPackageJson: true,
+	compatibility: "auto",
+	newlineBetween: true,
+	replaceDeprecated: false,
+	showChanges: true,
+	sortKeys: false,
+	strategy: "merge",
+	yarnResolutions: true
+};
+const VALID_STRATEGIES = [
+	"discard",
+	"merge",
+	"overwrite"
+];
+const VALID_COMPATIBILITIES = [
+	"auto",
+	"v10",
+	"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.
 *
-* Yarn resolutions are merged into pnpm overrides when enabled. Empty
-* overrides are removed from the result.
+* This function takes partial options and returns a complete options object
+* with all properties set to either the provided value or the default value.
 *
-* @param packageJson - Parsed package manifest
-* @param yarnResolutions - Whether to convert Yarn resolutions to pnpm overrides
+* @param options - Partial migration options
+*
+* @returns Complete options object with all required properties
 *
-* @returns Pnpm workspace settings resolved from the package manifest
+* @example
+* ```ts
+* // Use all defaults
+* const opts = resolveOptions()
+* // { cleanNpmrc: true, cleanPackageJson: true, cwd: '/current/dir', ... }
+*
+* // Override specific options
+* const opts = resolveOptions({ sortKeys: true, cleanNpmrc: false })
+* // { cleanNpmrc: false, cleanPackageJson: true, sortKeys: true, ... }
+* ```
 */
-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;
+function resolveOptions(options = {}) {
+	return {
+		cleanNpmrc: options.cleanNpmrc ?? DEFAULT_OPTIONS.cleanNpmrc,
+		compatibility: resolveCompatibility(options.compatibility),
+		cwd: options.cwd ?? process.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,
+		cleanPackageJson: options.cleanPackageJson ?? DEFAULT_OPTIONS.cleanPackageJson,
+		replaceDeprecated: options.replaceDeprecated ?? DEFAULT_OPTIONS.replaceDeprecated
+	};
 }
 //#endregion
 //#region src/core.ts
@@ -885,8 +2001,8 @@ function hasSettingsSources(npmrcExists, packageJsonExists, pnpmWorkspaceExists)
 	return false;
 }
 function hasMigratableSettings(sources) {
-	const { existingSettingsChanged, packageJson, pnpmSettingsInNpmrc, yarnResolutions } = sources;
-	return Boolean(existingSettingsChanged || packageJson.pnpm || yarnResolutions && packageJson.resolutions || Object.keys(pnpmSettingsInNpmrc).length);
+	const { existingSettingsChanged, npmrcKeys, packageJsonKeys, projectNpmrcKeys, yarnResolutions } = sources;
+	return Boolean(existingSettingsChanged || npmrcKeys.length || packageJsonKeys.length || projectNpmrcKeys.length || yarnResolutions);
 }
 function assertCanMigrateRuntime(runtimeVersion, packageJsonExists) {
 	if (runtimeVersion && !packageJsonExists) throw new Error("Cannot migrate the removed Node.js runtime setting without a package.json file.");
@@ -909,10 +2025,13 @@ function reportMigrationChanges(showChanges, before = {}, after = {}) {
 * @param rawOptions.cwd - Current working directory (default: process.cwd())
 * @param rawOptions.cleanNpmrc - Whether to remove pnpm settings from `.npmrc` (default: true)
 * @param rawOptions.cleanPackageJson - Whether to remove pnpm field from `package.json` (default: true)
+* @param rawOptions.compatibility - Target pnpm major, or automatic detection (default: auto)
 * @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.replaceDeprecated - Whether to replace deprecated settings (default: false)
 * @param rawOptions.showChanges - Show settings changes after migration (default: true)
+* @param rawOptions.strategy - Conflict handling strategy (default: merge)
 *
 * @returns A promise that resolves when migration is complete
 *
@@ -949,16 +2068,18 @@ async function migratePnpmSettings(rawOptions = {}) {
 		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 pnpmSettingsInPackageJson = resolvePackageJsonSettings(packageJson.value, options.yarnResolutions);
-		const incomingSettings = {
-			...pnpmSettingsInNpmrc,
-			...pnpmSettingsInPackageJson
-		};
+		assertCompatibleWorkspaceSettings(pnpmWorkspace.value, compatibility);
+		const sources = await resolveMigrationSources({
+			compatibility,
+			cwd: options.cwd,
+			npmrcExists,
+			npmrcPath,
+			packageJson: packageJson.value,
+			pnpmWorkspace: pnpmWorkspace.value,
+			strategy: options.strategy,
+			yarnResolutions: options.yarnResolutions
+		});
+		const { incomingSettings } = sources;
 		const [existingNormalization, incomingNormalization] = await Promise.all([normalizeIncomingSettings(pnpmWorkspace.value, {
 			compatibility,
 			cwd: options.cwd,
@@ -975,35 +2096,41 @@ async function migratePnpmSettings(rawOptions = {}) {
 		if (runtimeMigration.warning) consola$1.warn(runtimeMigration.warning);
 		if (!hasMigratableSettings({
 			existingSettingsChanged: existingNormalization.changed,
-			packageJson: packageJson.value,
-			pnpmSettingsInNpmrc,
-			yarnResolutions: options.yarnResolutions
+			npmrcKeys: sources.npmrc.keys,
+			packageJsonKeys: sources.packageJson.keys,
+			projectNpmrcKeys: sources.projectNpmrcs.projects.flatMap((project) => project.migratable.keys),
+			yarnResolutions: sources.packageJson.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({
-				key,
-				value
-			});
+		updateYamlDocument(pnpmWorkspace.document, {
+			after: pnpmWorkspaceResult,
+			before: pnpmWorkspaceBefore,
+			sortKeys: options.sortKeys
+		});
+		const finalYamlContent = formatRootSpacing(pnpmWorkspace.document.toString({ indent: pnpmWorkspace.indent }), options.newlineBetween);
+		await persistMigration({
+			cleanNpmrc: options.cleanNpmrc,
+			cleanPackageJson: options.cleanPackageJson,
+			compatibility,
+			finalSettings: pnpmWorkspaceResult,
+			incomingSettings,
+			npmrc: sources.npmrc,
+			npmrcExists,
+			npmrcPath,
+			packageJson,
+			packageJsonExists,
+			packageJsonPath,
+			packageJsonRuntimeChanged: runtimeMigration.changed,
+			packageJsonSettings: sources.packageJson,
+			pnpmWorkspaceContent: finalYamlContent,
+			pnpmWorkspacePath: pnpmWorkspaceYamlPath,
+			projectNpmrcs: sources.projectNpmrcs,
+			runtimeVersion
 		});
-		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);
-		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);
@@ -1012,9 +2139,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"));