pnpm-settings-migrator 0.11.0 → 0.12.0

package/README.md

@@ -132,6 +132,24 @@ For pnpm 12.4.0 and later stable v12 releases, the migrator additionally accepts
 `cargoTargetDir`. On older or unconfirmed targets, a `tasks` object containing
 these fields stays in its source as a whole.
 
+For pnpm 12.5.0 and later stable v12 releases, the migrator also accepts
+`concurrencyGroups`, task `concurrencyGroup`, platform lists in
+`supportedArchitectures`, Python `versions` / `overrides` / `constraints`, and
+`registries` declarations with `ecosystem`. Python registry `packages` routes
+require 12.5.1. Unsupported nested settings stay in their source as a whole.
+The legacy OS/CPU/libc architecture mapping continues to work.
+
+pnpm 12.5 removes `python.indexUrl` and `cargo.indexUrl`. Settings containing
+these fields are retained with an incompatibility warning; existing workspaces
+containing them fail validation before any files are written. Replace them with
+URL-keyed `registries` entries using `ecosystem: pypi` or `ecosystem: cargo`.
+The registry prefix `pkg` is reserved from 12.5 onward. Tool download mirrors
+under `tools` belong in global `config.yaml` or `PNPM_CONFIG_TOOLS` and are
+never migrated into the project workspace.
+
+On the v11 line, `trustPolicyExcludePrune` requires a confirmed stable version
+from 11.27.0 onward; v12 support still starts at 12.4.0.
+
 Automated v10 to v11 conversions include:
 
 - `managePackageManagerVersions`, `packageManagerStrict`, and
@@ -151,6 +169,9 @@ Notes:
 - `.npmrc` migration is aligned with the target pnpm workspace schema. Unknown
   keys and settings supported only by a different pnpm version stay in `.npmrc`
   with a warning.
+- Scalar list settings such as `public-hoist-pattern=*eslint*` become YAML
+  arrays (`publicHoistPattern: ['*eslint*']`). Existing arrays and patterns
+  containing commas are preserved without splitting their values.
 - In `v11` and `v12`, auth/registry keys and project-refused machine settings
   such as `globalDir`, `stateDir`, `configDir`, and `scope` stay in `.npmrc`.
 - Registry declarations containing embedded credentials or dynamic `${...}`
@@ -177,6 +198,8 @@ Notes:
   resolutions remain in their original source.
   Unrecognized, refused, incompatible, or otherwise unsupported
   `package.json#pnpm` child keys remain in `package.json`.
+  INI sections in `.npmrc` are retained conservatively; their child names are
+  never treated as root keys during cleanup.
 - Runtime migration writes `devEngines.runtime` before removing a workspace
   runtime declaration. A failed write preserves source settings for retry.
   If an existing runtime declaration conflicts with a workspace runtime, migration
@@ -191,9 +214,10 @@ Notes:
 - The migrator does not update the `packageManager` version, CI environment variables,
   shell setup, or pnpm commands in scripts. When `packageManager` still pins pnpm 10,
   pass `--compatibility v11` explicitly and update the pin separately.
-- Compatibility checks cover pnpm 11.26.0, 12.3.4, and 12.4.0, retaining
-  11.25.0 and 12.2.1 regressions. As audited on 2026-09-10, 12.3.4 is npm
-  `latest` and 12.4.0 is on `next-12`; the project stays pinned to 12.3.4. Its removed `pnpm install --resolution-only` CLI
+- Compatibility checks cover pnpm 11.27.1 and 12.5.1, retaining 11.25.0,
+  11.26.0, 12.2.1, 12.3.4, 12.4.0, 12.4.2, and 12.5.0 regressions.
+  As audited on 2026-09-22, npm `latest` is 12.5.1 and `latest-11` is 11.27.1;
+  the project is pinned to 12.5.1. Its removed `pnpm install --resolution-only` CLI
   flag is outside this settings migrator's scope; replace it with
   `pnpm peers check` in scripts before upgrading.
 

package/dist/cli.mjs

@@ -110,6 +110,30 @@ 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;
+/**
+* List settings accepting a single string in legacy `.npmrc` files.
+* Workspace YAML requires these values to be arrays.
+* Legacy build permission lists keep their explicit array validation.
+*/
+const NPMRC_STRING_ARRAY_SETTINGS = [
+	"changedFilesIgnorePattern",
+	"externalDependencies",
+	"extraBinPaths",
+	"filter",
+	"filterProd",
+	"gitShallowHosts",
+	"hoistPattern",
+	"ignoredOptionalDependencies",
+	"mergeGitBranchLockfilesBranchPattern",
+	"minimumReleaseAgeExclude",
+	"packages",
+	"publicHoistPattern",
+	"requiredScripts",
+	"syncInjectedDepsAfterScripts",
+	"testPattern",
+	"trustPolicyExclude",
+	"workspacePackagePatterns"
+];
 //#endregion
 //#region src/constants/pnpm-v10.ts
 /**
@@ -298,6 +322,7 @@ const PNPM_PROJECT_REFUSED_SETTINGS = [
 	"scope",
 	"selectedProjectsGraph",
 	"stateDir",
+	"tools",
 	"userConfig",
 	"userconfig",
 	"wantedPackageManager",
@@ -586,32 +611,64 @@ const PNPM_WORKSPACE_YAML = "pnpm-workspace.yaml";
 //#endregion
 //#region src/constants/pnpm-capabilities.ts
 /**
+* Release introducing platform lists, registry ecosystems, and Python options.
+*/
+const PNPM_V12_5_MINIMUM_VERSION = [
+	12,
+	5,
+	0
+];
+/**
+* Release introducing package routes in Python registry declarations.
+*/
+const PNPM_V12_5_1_MINIMUM_VERSION = [
+	12,
+	5,
+	1
+];
+/**
 * Version-gated settings. Add a release entry only when supported fields change.
 *
 * @see https://github.com/pnpm/pnpm/blob/v12.4.0/pnpm/crates/config/src/workspace_yaml.rs
 */
-const PNPM_SETTINGS_CAPABILITIES = [{
-	minimumVersion: [
-		12,
-		4,
-		0
-	],
-	workspaceFields: [
-		"cargo",
-		"packageConfigs",
-		"pipelineBase",
-		"pipelines",
-		"python",
-		"trustPolicyExcludePrune"
-	],
-	taskFields: [
-		"cache",
-		"cargoTargetDir",
-		"env",
-		"inputs",
-		"outputs"
-	]
-}];
+const PNPM_SETTINGS_CAPABILITIES = [
+	{
+		minimumVersion: [
+			11,
+			27,
+			0
+		],
+		workspaceFields: ["trustPolicyExcludePrune"],
+		taskFields: []
+	},
+	{
+		minimumVersion: [
+			12,
+			4,
+			0
+		],
+		workspaceFields: [
+			"cargo",
+			"packageConfigs",
+			"pipelineBase",
+			"pipelines",
+			"python",
+			"trustPolicyExcludePrune"
+		],
+		taskFields: [
+			"cache",
+			"cargoTargetDir",
+			"env",
+			"inputs",
+			"outputs"
+		]
+	},
+	{
+		minimumVersion: PNPM_V12_5_MINIMUM_VERSION,
+		workspaceFields: ["concurrencyGroups"],
+		taskFields: ["concurrencyGroup"]
+	}
+];
 /**
 * Known workspace fields that require a confirmed version.
 */
@@ -761,8 +818,13 @@ function resolveOptions(options = {}) {
 function discardMerge(priority, fallback) {
 	const result = { ...priority };
 	for (const [key, fallbackValue] of Object.entries(fallback)) {
-		const priorityValue = result[key];
-		if (isUndefined(priorityValue)) result[key] = fallbackValue;
+		const priorityValue = Object.hasOwn(result, key) ? result[key] : void 0;
+		if (isUndefined(priorityValue)) Object.defineProperty(result, key, {
+			configurable: true,
+			enumerable: true,
+			value: fallbackValue,
+			writable: true
+		});
 		else if (isPlainObject(priorityValue) && isPlainObject(fallbackValue)) result[key] = discardMerge(priorityValue, fallbackValue);
 	}
 	return result;
@@ -782,8 +844,13 @@ function discardMerge(priority, fallback) {
 function mergeWithArrayDedupe(existing, incoming) {
 	const result = { ...existing };
 	for (const [key, incomingValue] of Object.entries(incoming)) {
-		const existingValue = result[key];
-		if (isUndefined(existingValue)) result[key] = incomingValue;
+		const existingValue = Object.hasOwn(result, key) ? result[key] : void 0;
+		if (isUndefined(existingValue)) Object.defineProperty(result, key, {
+			configurable: true,
+			enumerable: true,
+			value: incomingValue,
+			writable: true
+		});
 		else if (Array.isArray(existingValue) && Array.isArray(incomingValue)) {
 			const items = Array.from(/* @__PURE__ */ new Set([...existingValue, ...incomingValue]));
 			result[key] = items.filter((item, index) => !item || typeof item !== "object" || !items.slice(0, index).some((previous) => isDeepStrictEqual(previous, item)));
@@ -863,6 +930,41 @@ function formatSettingsIssues(options) {
 	return warnings;
 }
 //#endregion
+//#region src/features/settings/versioned-values.ts
+/**
+* Check value shapes that changed within a pnpm major release.
+*
+* Reject the whole setting so cleanup cannot discard unsupported nested values.
+*
+* @param key - Canonical workspace setting name
+* @param value - Incoming or existing setting value
+* @param target - Confirmed target version and major schema
+*
+* @returns Whether the value uses a shape unsupported by the selected release
+*/
+function hasIncompatibleSettingValue(key, value, target) {
+	const supportsV12_5 = supportsMinimumVersion(target.version, PNPM_V12_5_MINIMUM_VERSION);
+	if (key === "supportedArchitectures" && Array.isArray(value)) return !supportsV12_5;
+	if (!value || typeof value !== "object") return false;
+	if (key === "python" || key === "cargo") {
+		if (supportsV12_5 && Object.hasOwn(value, "indexUrl")) return true;
+		if (key === "python" && !supportsV12_5) return [
+			"versions",
+			"overrides",
+			"constraints"
+		].some((field) => Object.hasOwn(value, field));
+	}
+	if (key === "namedRegistries" && supportsV12_5) return Object.keys(value).some((prefix) => prefix.toLowerCase() === "pkg");
+	if (key === "registries") return Object.values(value).some((entry) => {
+		if (!entry || typeof entry !== "object") return false;
+		if (Object.hasOwn(entry, "ecosystem") && !supportsV12_5) return true;
+		if (Object.hasOwn(entry, "packages") && !supportsMinimumVersion(target.version, PNPM_V12_5_1_MINIMUM_VERSION)) return true;
+		const prefix = Reflect.get(entry, "prefix");
+		return supportsV12_5 && typeof prefix === "string" && prefix.toLowerCase() === "pkg";
+	});
+	return false;
+}
+//#endregion
 //#region src/features/settings/schema.ts
 /**
 * Create an empty collection of schema selection issues.
@@ -969,6 +1071,7 @@ function resolveSettingIssue({ allowedFields, target, key, npmrc, value }) {
 	if (compatibility !== "v10" && PROJECT_REFUSED_SETTINGS.has(key)) return "refused";
 	if (REGISTRY_SETTINGS.has(key) && containsUnsafeRegistryValue(value)) return "unsafe";
 	if (PROXY_SETTINGS.has(key) && typeof value === "string" && value.includes("${")) return "unsafe";
+	if (hasIncompatibleSettingValue(key, value, target)) return "incompatible";
 	if (key === "tasks" && value && typeof value === "object" && Object.values(value).some((task) => task && typeof task === "object" && Object.keys(task).some((field) => !taskSettings.has(field)))) return "incompatible";
 	if (!workspaceSettings.has(key)) return isSettingFromAnotherVersion(key, compatibility) ? "incompatible" : "unknown";
 	if (allowedFields && !allowedFields.has(key)) return "unsupported";
@@ -1351,6 +1454,17 @@ function normalizeNpmrcKey(key) {
 	return key.trim().replace(/\[\]$/u, "").toLowerCase();
 }
 /**
+* Convert scalar list settings to the array representation required by YAML.
+*
+* @param settings - Selected `.npmrc` settings with camelCase keys
+*
+* @returns Settings with each scalar list value preserved as one array item
+*/
+function normalizeNpmrcSettings(settings) {
+	for (const key of NPMRC_STRING_ARRAY_SETTINGS) if (typeof settings[key] === "string") settings[key] = [settings[key]];
+	return settings;
+}
+/**
 * Extract key name from a raw `.npmrc` line.
 *
 * @param line - Raw line from an `.npmrc` file
@@ -1382,7 +1496,8 @@ function isNpmrcAuthOrRegistryKey(key) {
 * Remove pnpm-related settings from `.npmrc` file.
 *
 * This function reads the `.npmrc` file, removes lines whose exact normalized
-* keys were migrated, and writes the cleaned content back to the file.
+* root keys were migrated, and writes the cleaned content back to the file.
+* INI sections are retained because their child keys are not root settings.
 *
 * @param path - Absolute path to the `.npmrc` file
 * @param compatibility - Concrete pnpm compatibility target
@@ -1399,7 +1514,11 @@ function isNpmrcAuthOrRegistryKey(key) {
 */
 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 content = await fsReadFile(path);
+	let inSection = false;
+	const updatedContent = content.split(/\r?\n/u).filter((line) => {
+		if (/^\[[^\]]*\]\s*$/u.test(line.replace(/^\uFEFF/u, ""))) inSection = true;
+		if (inSection) return true;
 		const key = getNpmrcLineKey(line);
 		if (!key) return true;
 		return !migratedKeySet.has(key);
@@ -1443,7 +1562,7 @@ async function readMigratableNpmrc(path, target, options = {}) {
 		return {
 			issues,
 			keys,
-			settings: camelcaseKeys(migratable)
+			settings: normalizeNpmrcSettings(camelcaseKeys(migratable))
 		};
 	}
 	const migratable = {};
@@ -1465,7 +1584,7 @@ async function readMigratableNpmrc(path, target, options = {}) {
 			mergeSettingsIssues(issues, selected.issues);
 		}
 	}
-	const settings = camelcaseKeys(migratable);
+	const settings = normalizeNpmrcSettings(camelcaseKeys(migratable));
 	if (Object.keys(nodeDownloadMirrors).length) {
 		const selected = selectPnpmSettings({ nodeDownloadMirrors }, target, { allowedFields: options.allowedFields });
 		if (selected.keys.length) {
@@ -2554,7 +2673,7 @@ const bold = getColor("bold");
 //#endregion
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.11.0";
+var version = "0.12.0";
 //#endregion
 //#region src/cli/options.ts
 /**

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Document } from "yaml";
-import { PnpmSettings } from "@pnpm/types";
+import { PnpmSettings, RegistryDeclaration } from "@pnpm/types";
 //#region src/types/options.d.ts
 /**
  * Compatibility target used by the migrator.
@@ -93,15 +93,19 @@ type ResolvedOptions = Required<Omit<Options, 'targetVersion'>> & Pick<Options,
  */
 type GlobalShimPolicy = boolean | 'always' | 'auto' | 'prompt';
 /**
- * Pipeline task configuration supported by pnpm 12.4.0.
+ * Task configuration, including pnpm 12.4 caching and 12.5 concurrency groups.
  *
- * @see https://github.com/pnpm/pnpm/blob/v12.4.0/pnpm/crates/config/src/workspace_yaml.rs
+ * @see https://github.com/pnpm/pnpm/blob/v12.5.1/pnpm/crates/config/src/workspace_yaml/sections.rs
  */
 interface PnpmTaskSettings {
   /**
    * Maximum concurrent executions of this task.
    */
   concurrency?: number;
+  /**
+   * Machine-wide concurrency group to count this task against (pnpm 12.5+).
+   */
+  concurrencyGroup?: string;
   /**
    * Prerequisite tasks; a caret prefix refers to workspace dependencies.
    */
@@ -140,7 +144,8 @@ interface PnpmPythonSettings {
    */
   executable?: string;
   /**
-   * Python package index URL.
+   * Python package index URL accepted by pnpm 12.4.
+   * @deprecated pnpm 12.5+ uses a registries entry with ecosystem: pypi.
    */
   indexUrl?: string;
   /**
@@ -151,6 +156,18 @@ interface PnpmPythonSettings {
    * Python dependency groups to install.
    */
   groups?: string[];
+  /**
+   * Python versions to resolve the lockfile for (pnpm 12.5+).
+   */
+  versions?: string[];
+  /**
+   * Python requirements that override dependency versions (pnpm 12.5+).
+   */
+  overrides?: string[];
+  /**
+   * Additional constraints on Python dependency versions (pnpm 12.5+).
+   */
+  constraints?: string[];
 }
 /**
  * Cargo dependency management configuration introduced in pnpm 12.4.0.
@@ -161,14 +178,41 @@ interface PnpmCargoSettings {
    */
   enabled?: boolean;
   /**
-   * Cargo registry index URL.
+   * Cargo registry index URL accepted by pnpm 12.4.
+   * @deprecated pnpm 12.5+ uses a registries entry with ecosystem: cargo.
    */
   indexUrl?: string;
 }
+/**
+ * URL-keyed registry declaration with pnpm 12.5 ecosystem support.
+ */
+interface PnpmRegistryDeclaration extends RegistryDeclaration {
+  /**
+   * Package ecosystem served by the registry; omitted means npm (pnpm 12.5+).
+   */
+  ecosystem?: 'cargo' | 'npm' | 'pypi';
+  /**
+   * Python package names or trailing-prefix patterns; * selects the default
+   * index (pnpm 12.5.1+).
+   */
+  packages?: string[];
+}
 /**
  * Settings supported by pnpm v12, subject to the resolved version capabilities.
  */
 interface PnpmSettingsV12 {
+  /**
+   * Machine-wide limits shared by tasks in each group (pnpm 12.5+).
+   */
+  concurrencyGroups?: Record<string, number>;
+  /**
+   * Legacy OS/CPU/libc axes, or platform names and Rust triples (pnpm 12.5+).
+   */
+  supportedArchitectures?: PnpmSettings['supportedArchitectures'] | string[];
+  /**
+   * Legacy scope routes or URL-keyed declarations with ecosystem settings.
+   */
+  registries?: Record<string, PnpmRegistryDeclaration | string>;
   /**
    * Peer auto-installation policy accepted only by the v12 target.
    */
@@ -360,7 +404,7 @@ interface PnpmSettingsV11 {
 /**
  * `pnpm-workspace.yaml` types.
  */
-type PnpmWorkspace = Omit<PnpmSettings, 'tasks'> & PnpmSettingsDeprecated & PnpmSettingsV11 & PnpmSettingsV12 & PnpmWorkspaceLegacy;
+type PnpmWorkspace = Omit<PnpmSettings, 'registries' | 'supportedArchitectures' | 'tasks'> & PnpmSettingsDeprecated & PnpmSettingsV11 & PnpmSettingsV12 & PnpmWorkspaceLegacy;
 //#endregion
 //#region src/types/package-json.d.ts
 /**
@@ -568,4 +612,4 @@ export declare function migratePnpmSettings(rawOptions?: Options): Promise<Migra
  */
 export declare function resolveOptions(options?: Options): ResolvedOptions;
 //#endregion
-export type { CompatibilityTarget, GlobalShimPolicy, MergeStrategy, MigrationResult, NpmRC, Options, PackageJson, PackageManagerEngine, PnpmCargoSettings, PnpmPythonSettings, PnpmSettingsDeprecated, PnpmSettingsV11, PnpmSettingsV12, PnpmTaskSettings, PnpmWorkspace, PnpmWorkspaceLegacy, ResolvedOptions, RuntimeEngine, SettingsChange };
+export type { CompatibilityTarget, GlobalShimPolicy, MergeStrategy, MigrationResult, NpmRC, Options, PackageJson, PackageManagerEngine, PnpmCargoSettings, PnpmPythonSettings, PnpmRegistryDeclaration, PnpmSettingsDeprecated, PnpmSettingsV11, PnpmSettingsV12, PnpmTaskSettings, PnpmWorkspace, PnpmWorkspaceLegacy, ResolvedOptions, RuntimeEngine, SettingsChange };

package/dist/index.mjs

@@ -108,6 +108,30 @@ 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;
+/**
+* List settings accepting a single string in legacy `.npmrc` files.
+* Workspace YAML requires these values to be arrays.
+* Legacy build permission lists keep their explicit array validation.
+*/
+const NPMRC_STRING_ARRAY_SETTINGS = [
+	"changedFilesIgnorePattern",
+	"externalDependencies",
+	"extraBinPaths",
+	"filter",
+	"filterProd",
+	"gitShallowHosts",
+	"hoistPattern",
+	"ignoredOptionalDependencies",
+	"mergeGitBranchLockfilesBranchPattern",
+	"minimumReleaseAgeExclude",
+	"packages",
+	"publicHoistPattern",
+	"requiredScripts",
+	"syncInjectedDepsAfterScripts",
+	"testPattern",
+	"trustPolicyExclude",
+	"workspacePackagePatterns"
+];
 //#endregion
 //#region src/constants/pnpm-v10.ts
 /**
@@ -296,6 +320,7 @@ const PNPM_PROJECT_REFUSED_SETTINGS = [
 	"scope",
 	"selectedProjectsGraph",
 	"stateDir",
+	"tools",
 	"userConfig",
 	"userconfig",
 	"wantedPackageManager",
@@ -579,32 +604,64 @@ const PNPM_WORKSPACE_YAML = "pnpm-workspace.yaml";
 //#endregion
 //#region src/constants/pnpm-capabilities.ts
 /**
+* Release introducing platform lists, registry ecosystems, and Python options.
+*/
+const PNPM_V12_5_MINIMUM_VERSION = [
+	12,
+	5,
+	0
+];
+/**
+* Release introducing package routes in Python registry declarations.
+*/
+const PNPM_V12_5_1_MINIMUM_VERSION = [
+	12,
+	5,
+	1
+];
+/**
 * Version-gated settings. Add a release entry only when supported fields change.
 *
 * @see https://github.com/pnpm/pnpm/blob/v12.4.0/pnpm/crates/config/src/workspace_yaml.rs
 */
-const PNPM_SETTINGS_CAPABILITIES = [{
-	minimumVersion: [
-		12,
-		4,
-		0
-	],
-	workspaceFields: [
-		"cargo",
-		"packageConfigs",
-		"pipelineBase",
-		"pipelines",
-		"python",
-		"trustPolicyExcludePrune"
-	],
-	taskFields: [
-		"cache",
-		"cargoTargetDir",
-		"env",
-		"inputs",
-		"outputs"
-	]
-}];
+const PNPM_SETTINGS_CAPABILITIES = [
+	{
+		minimumVersion: [
+			11,
+			27,
+			0
+		],
+		workspaceFields: ["trustPolicyExcludePrune"],
+		taskFields: []
+	},
+	{
+		minimumVersion: [
+			12,
+			4,
+			0
+		],
+		workspaceFields: [
+			"cargo",
+			"packageConfigs",
+			"pipelineBase",
+			"pipelines",
+			"python",
+			"trustPolicyExcludePrune"
+		],
+		taskFields: [
+			"cache",
+			"cargoTargetDir",
+			"env",
+			"inputs",
+			"outputs"
+		]
+	},
+	{
+		minimumVersion: PNPM_V12_5_MINIMUM_VERSION,
+		workspaceFields: ["concurrencyGroups"],
+		taskFields: ["concurrencyGroup"]
+	}
+];
 /**
 * Known workspace fields that require a confirmed version.
 */
@@ -754,8 +811,13 @@ function resolveOptions(options = {}) {
 function discardMerge(priority, fallback) {
 	const result = { ...priority };
 	for (const [key, fallbackValue] of Object.entries(fallback)) {
-		const priorityValue = result[key];
-		if (isUndefined(priorityValue)) result[key] = fallbackValue;
+		const priorityValue = Object.hasOwn(result, key) ? result[key] : void 0;
+		if (isUndefined(priorityValue)) Object.defineProperty(result, key, {
+			configurable: true,
+			enumerable: true,
+			value: fallbackValue,
+			writable: true
+		});
 		else if (isPlainObject(priorityValue) && isPlainObject(fallbackValue)) result[key] = discardMerge(priorityValue, fallbackValue);
 	}
 	return result;
@@ -775,8 +837,13 @@ function discardMerge(priority, fallback) {
 function mergeWithArrayDedupe(existing, incoming) {
 	const result = { ...existing };
 	for (const [key, incomingValue] of Object.entries(incoming)) {
-		const existingValue = result[key];
-		if (isUndefined(existingValue)) result[key] = incomingValue;
+		const existingValue = Object.hasOwn(result, key) ? result[key] : void 0;
+		if (isUndefined(existingValue)) Object.defineProperty(result, key, {
+			configurable: true,
+			enumerable: true,
+			value: incomingValue,
+			writable: true
+		});
 		else if (Array.isArray(existingValue) && Array.isArray(incomingValue)) {
 			const items = Array.from(/* @__PURE__ */ new Set([...existingValue, ...incomingValue]));
 			result[key] = items.filter((item, index) => !item || typeof item !== "object" || !items.slice(0, index).some((previous) => isDeepStrictEqual(previous, item)));
@@ -856,6 +923,41 @@ function formatSettingsIssues(options) {
 	return warnings;
 }
 //#endregion
+//#region src/features/settings/versioned-values.ts
+/**
+* Check value shapes that changed within a pnpm major release.
+*
+* Reject the whole setting so cleanup cannot discard unsupported nested values.
+*
+* @param key - Canonical workspace setting name
+* @param value - Incoming or existing setting value
+* @param target - Confirmed target version and major schema
+*
+* @returns Whether the value uses a shape unsupported by the selected release
+*/
+function hasIncompatibleSettingValue(key, value, target) {
+	const supportsV12_5 = supportsMinimumVersion(target.version, PNPM_V12_5_MINIMUM_VERSION);
+	if (key === "supportedArchitectures" && Array.isArray(value)) return !supportsV12_5;
+	if (!value || typeof value !== "object") return false;
+	if (key === "python" || key === "cargo") {
+		if (supportsV12_5 && Object.hasOwn(value, "indexUrl")) return true;
+		if (key === "python" && !supportsV12_5) return [
+			"versions",
+			"overrides",
+			"constraints"
+		].some((field) => Object.hasOwn(value, field));
+	}
+	if (key === "namedRegistries" && supportsV12_5) return Object.keys(value).some((prefix) => prefix.toLowerCase() === "pkg");
+	if (key === "registries") return Object.values(value).some((entry) => {
+		if (!entry || typeof entry !== "object") return false;
+		if (Object.hasOwn(entry, "ecosystem") && !supportsV12_5) return true;
+		if (Object.hasOwn(entry, "packages") && !supportsMinimumVersion(target.version, PNPM_V12_5_1_MINIMUM_VERSION)) return true;
+		const prefix = Reflect.get(entry, "prefix");
+		return supportsV12_5 && typeof prefix === "string" && prefix.toLowerCase() === "pkg";
+	});
+	return false;
+}
+//#endregion
 //#region src/features/settings/schema.ts
 /**
 * Create an empty collection of schema selection issues.
@@ -962,6 +1064,7 @@ function resolveSettingIssue({ allowedFields, target, key, npmrc, value }) {
 	if (compatibility !== "v10" && PROJECT_REFUSED_SETTINGS.has(key)) return "refused";
 	if (REGISTRY_SETTINGS.has(key) && containsUnsafeRegistryValue(value)) return "unsafe";
 	if (PROXY_SETTINGS.has(key) && typeof value === "string" && value.includes("${")) return "unsafe";
+	if (hasIncompatibleSettingValue(key, value, target)) return "incompatible";
 	if (key === "tasks" && value && typeof value === "object" && Object.values(value).some((task) => task && typeof task === "object" && Object.keys(task).some((field) => !taskSettings.has(field)))) return "incompatible";
 	if (!workspaceSettings.has(key)) return isSettingFromAnotherVersion(key, compatibility) ? "incompatible" : "unknown";
 	if (allowedFields && !allowedFields.has(key)) return "unsupported";
@@ -1344,6 +1447,17 @@ function normalizeNpmrcKey(key) {
 	return key.trim().replace(/\[\]$/u, "").toLowerCase();
 }
 /**
+* Convert scalar list settings to the array representation required by YAML.
+*
+* @param settings - Selected `.npmrc` settings with camelCase keys
+*
+* @returns Settings with each scalar list value preserved as one array item
+*/
+function normalizeNpmrcSettings(settings) {
+	for (const key of NPMRC_STRING_ARRAY_SETTINGS) if (typeof settings[key] === "string") settings[key] = [settings[key]];
+	return settings;
+}
+/**
 * Extract key name from a raw `.npmrc` line.
 *
 * @param line - Raw line from an `.npmrc` file
@@ -1375,7 +1489,8 @@ function isNpmrcAuthOrRegistryKey(key) {
 * Remove pnpm-related settings from `.npmrc` file.
 *
 * This function reads the `.npmrc` file, removes lines whose exact normalized
-* keys were migrated, and writes the cleaned content back to the file.
+* root keys were migrated, and writes the cleaned content back to the file.
+* INI sections are retained because their child keys are not root settings.
 *
 * @param path - Absolute path to the `.npmrc` file
 * @param compatibility - Concrete pnpm compatibility target
@@ -1392,7 +1507,11 @@ function isNpmrcAuthOrRegistryKey(key) {
 */
 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 content = await fsReadFile(path);
+	let inSection = false;
+	const updatedContent = content.split(/\r?\n/u).filter((line) => {
+		if (/^\[[^\]]*\]\s*$/u.test(line.replace(/^\uFEFF/u, ""))) inSection = true;
+		if (inSection) return true;
 		const key = getNpmrcLineKey(line);
 		if (!key) return true;
 		return !migratedKeySet.has(key);
@@ -1436,7 +1555,7 @@ async function readMigratableNpmrc(path, target, options = {}) {
 		return {
 			issues,
 			keys,
-			settings: camelcaseKeys(migratable)
+			settings: normalizeNpmrcSettings(camelcaseKeys(migratable))
 		};
 	}
 	const migratable = {};
@@ -1458,7 +1577,7 @@ async function readMigratableNpmrc(path, target, options = {}) {
 			mergeSettingsIssues(issues, selected.issues);
 		}
 	}
-	const settings = camelcaseKeys(migratable);
+	const settings = normalizeNpmrcSettings(camelcaseKeys(migratable));
 	if (Object.keys(nodeDownloadMirrors).length) {
 		const selected = selectPnpmSettings({ nodeDownloadMirrors }, target, { allowedFields: options.allowedFields });
 		if (selected.keys.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pnpm-settings-migrator",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Move pnpm settings from `pnpm` field in `package.json` and `.npmrc` file to `pnpm-workspace.yaml`",
   "keywords": [
     "migrator",
@@ -42,10 +42,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@ntnyq/utils": "^0.22.0",
+    "@ntnyq/utils": "^0.23.0",
     "@pnpm/types": "^1102.1.0",
     "cac": "^7.0.0",
-    "camelcase-keys": "^10.0.2",
+    "camelcase-keys": "^10.0.3",
     "consola": "^3.4.2",
     "defu": "^6.1.7",
     "detect-indent": "^7.0.2",
@@ -56,16 +56,17 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.2",
     "bumpp": "^12.3.0",
     "husky": "^9.1.7",
     "nano-staged": "^1.0.2",
     "npm-run-all2": "^9.0.3",
-    "oxfmt": "^0.67.0",
-    "oxlint": "^1.82.0",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0",
     "tsdown": "^0.23.0",
+    "tsx": "^4.23.15",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "nano-staged": {
     "*.{js,ts,mjs,tsx}": "oxlint --fix",
@@ -84,7 +85,7 @@
     "release:check": "run-s lint format:check typecheck test",
     "release:version": "bumpp",
     "test": "vitest",
-    "test:compatibility": "node scripts/verify-pnpm-compatibility.mjs",
+    "test:compatibility": "tsx scripts/verify-pnpm-compatibility.ts",
     "typecheck": "tsc --noEmit"
   }
 }