pnpm-settings-migrator 0.16.0 → 0.18.0

package/README.md

@@ -202,7 +202,8 @@ From 11.28.3, non-null `allowBuilds` values must be maps of booleans or strings.
 From 11.28.4, non-null `allowUnusedPatches` must be boolean, and non-null
 `ignoredOptionalDependencies` / `requiredScripts` must be string arrays.
 From 11.28.5, `httpProxy` and `httpsProxy` must be strings, including when empty;
-null is incompatible. Invalid values remain in their sources with diagnostics.
+null is incompatible in 11.28.5. From 11.28.6, null is accepted again and leaves
+the proxy unset. Invalid values remain in their sources with diagnostics.
 
 For pnpm 12.9.0 and later stable v12 releases, URL-keyed `registries` entries
 can set `networkConcurrency` to a positive safe integer, or null to leave it
@@ -232,11 +233,54 @@ For example, targeting 12.11.0 migrates
 to equivalent workspace YAML. Targeting 12.10.1 retains these settings with
 diagnostics.
 
+For pnpm 12.12.0 and later stable v12 releases, `addMissingPeerTypes` accepts
+boolean or null values and `remoteCache` accepts the project organization:
+`{ org: 'acme' }`. Empty and null remote-cache sections are preserved. Server,
+team, signing, and publication fields belong in trusted global configuration
+or environment variables. Objects containing those fields, unknown fields,
+or invalid values remain intact in their source with diagnostics; existing
+incompatible workspace values block migration before writes.
+
+`remoteCache` and legacy `sideEffectsCache.remote` are kept independently so
+pnpm applies its field-level precedence. The migrator does not insert defaults
+or rewrite `allowBuilds`: pnpm 12.12 itself now honors explicit build denials
+when `dangerouslyAllowAllBuilds` is true.
+
+From 12.12.1, the registry prefix `tool` is reserved. Both `namedRegistries`
+and URL-keyed `registries` using that exact prefix remain in their sources;
+existing workspace declarations block migration. This restriction is
+case-sensitive (`ToOl` remains valid), unlike the existing `pkg` restriction.
+
+For pnpm 12.13.0 and later stable v12 releases, `nodePackageMap` accepts
+`mode: off | write-only | load` and `type: standard | loose`. The section and
+its fields may be null to leave them unset. New and legacy
+`nodeExperimentalPackageMap` / `nodePackageMapType` values are preserved so pnpm
+applies the new section's field-level precedence. `storeIndexFormat` accepts
+`sqlite`, `files`, or null; `files` supports stores shared over network filesystems.
+Enum values may use environment placeholders, which are preserved without expansion.
+Older or unconfirmed targets retain these settings in their source.
+
+For pnpm 12.14.0 and later stable v12 releases, `sideEffectsCache.exclude`
+accepts package patterns such as `['java', '@native/*', 'example@1']`, an empty
+array, or null. Excluded builds are neither restored nor saved in local or remote
+caches. Cache `read` and `write` values may also use preserved environment
+placeholders. On older targets, the complete cache section stays in its source.
+Invalid nested values and unknown fields also preserve the complete source
+section; existing incompatible workspace values block writes.
+
 pnpm v12 reads `filter` and `filterProd` from CLI arguments or `updateConfig`
 hooks, not workspace YAML. These settings remain in their source with
 diagnostics for v12 targets; existing YAML containing them blocks migration.
 The 12.11.2 hook fix does not add workspace support.
 
+Other legacy fields ignored by the v12 workspace reader also stay in their
+sources with diagnostics. These include `production`, `dev`, `recursive`,
+`lockfileOnly`, `force`, `depth`, `saveDev`, `fetchingConcurrency`,
+`requiredScripts`, `extraBinPaths`, `extraEnv`, and `workspacePackagePatterns`.
+Existing YAML containing ignored fields blocks migration before writes.
+For example, `production=true` cannot be moved into v12 YAML; use
+`pnpm install --prod` to select production dependencies.
+
 </details>
 
 <details>
@@ -273,6 +317,9 @@ Notes:
   such as `globalDir`, `stateDir`, `configDir`, and `scope` stay in `.npmrc`.
 - Registry declarations containing embedded credentials or dynamic `${...}`
   URLs stay in their source with a warning.
+- Invalid registry locations, including relative paths and object property names
+  such as `__proto__`, remain in their sources with diagnostics. Registry
+  conversion never uses inherited object properties as declarations.
 - Dynamic `${...}` values in `httpProxy`, `httpsProxy`, `noProxy`, `proxy`, and
   `noproxy` stay in their source for every target. Project YAML does not expand
   these placeholders; configure them globally in trusted configuration or use
@@ -297,10 +344,16 @@ Notes:
   `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.
+  Bare boolean flags such as `save-exact` and quoted keys such as
+  `"save-exact"=true` are cleaned when migrated. Retained sections alone do not
+  cause repeated cleanup reports or rewrites.
 - 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
   stops before writing any files. An identical Node.js declaration is reused.
+- An `executionEnv` object containing fields besides `nodeVersion` remains
+  intact in its source with a warning. Existing workspace declarations with
+  such fields block migration before writes, so unmigrated values cannot be lost.
 - YAML aliases remain when their anchors are unchanged and precede them.
   If replacement, removal, or sorting would invalidate an alias, its original
   value is written explicitly so unrelated settings keep their values.
@@ -311,17 +364,18 @@ 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.28.5 and 12.11.2, including 11.28.0,
-  11.28.1, 11.28.2, 11.28.3, 11.28.4, 12.7.0, 12.8.0, 12.8.1, 12.8.2,
-  12.9.0, 12.9.1, 12.10.0, 12.10.1, 12.11.0, and 12.11.1.
+- Compatibility checks cover pnpm 11.28.6 and 12.14.0, including 11.28.0,
+  11.28.1, 11.28.2, 11.28.3, 11.28.4, 11.28.5, 12.7.0, 12.8.0, 12.8.1,
+  12.8.2, 12.9.0, 12.9.1, 12.10.0, 12.10.1, 12.11.0, 12.11.1, 12.11.2,
+  12.12.0, 12.12.1, and 12.13.0.
   Earlier regressions remain at 11.25.0,
   11.26.0, 11.27.1, 12.2.1, 12.3.4, 12.4.0, 12.4.2, 12.5.0, 12.5.1, and 12.6.0.
-  As [audited on 2026-10-10](docs/research/pnpm-settings-bump-2026-10-10.md),
-  npm `latest` is 12.10.1; the highest confirmed stable release is 12.11.2 on
-  `next-12`. The v11 target is 11.28.5 on `next-11`, while `latest-11` is
-  11.28.2. The project is pinned to 12.10.1. These checks verify the documented
+  As [audited on 2026-10-17](docs/research/pnpm-settings-bump-2026-10-17.md),
+  npm `latest` and the highest confirmed stable release are 12.14.0, also on
+  `latest-12` and `next-12`. The v11 target is 11.28.6 on both `latest-11` and
+  `next-11`. The project is pinned to 12.14.0. These checks verify the documented
   fixtures, not every setting in every release. v10 has unit regressions and
-  source review through 10.34.6; real v10 consumption remains unverified.
+  source review through 10.34.7; real v10 consumption remains unverified.
   The 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

@@ -587,6 +587,14 @@ const PNPM_V11_28_5_MINIMUM_VERSION = [
 	5
 ];
 /**
+* Release restoring null proxy values as unset configuration.
+*/
+const PNPM_V11_28_6_MINIMUM_VERSION = [
+	11,
+	28,
+	6
+];
+/**
 * Release adding force, publishing, and reporter settings.
 */
 const PNPM_V12_7_MINIMUM_VERSION = [
@@ -627,6 +635,38 @@ const PNPM_V12_11_MINIMUM_VERSION = [
 	0
 ];
 /**
+* Release introducing remote cache configuration and missing peer types.
+*/
+const PNPM_V12_12_MINIMUM_VERSION = [
+	12,
+	12,
+	0
+];
+/**
+* Release reserving the tool registry prefix.
+*/
+const PNPM_V12_12_1_MINIMUM_VERSION = [
+	12,
+	12,
+	1
+];
+/**
+* Release introducing package map options and file-based store indexes.
+*/
+const PNPM_V12_13_MINIMUM_VERSION = [
+	12,
+	13,
+	0
+];
+/**
+* Release introducing side-effects cache exclusions.
+*/
+const PNPM_V12_14_MINIMUM_VERSION = [
+	12,
+	14,
+	0
+];
+/**
 * Workspace settings first consumed by pnpm v12 in 12.11.0.
 */
 const PNPM_V12_11_WORKSPACE_SETTINGS = [
@@ -652,6 +692,16 @@ const PNPM_V12_7_WORKSPACE_SETTINGS = [
 * @see https://github.com/pnpm/pnpm/blob/v12.4.0/pnpm/crates/config/src/workspace_yaml.rs
 */
 const PNPM_SETTINGS_CAPABILITIES = [
+	{
+		minimumVersion: PNPM_V12_13_MINIMUM_VERSION,
+		workspaceFields: ["nodePackageMap", "storeIndexFormat"],
+		taskFields: []
+	},
+	{
+		minimumVersion: PNPM_V12_12_MINIMUM_VERSION,
+		workspaceFields: ["addMissingPeerTypes", "remoteCache"],
+		taskFields: []
+	},
 	{
 		minimumVersion: PNPM_V12_11_MINIMUM_VERSION,
 		workspaceFields: PNPM_V12_11_WORKSPACE_SETTINGS,
@@ -733,9 +783,82 @@ const PNPM_V12_ONLY_WORKSPACE_SETTINGS = [
 	"globalShims"
 ];
 /**
+* Legacy fields absent from pnpm v12's workspace reader through 12.14.0.
+* Removed aliases with explicit migration replacements are kept separately.
+*
+* @see https://github.com/pnpm/pnpm/blob/v12.14.0/pnpm/crates/config/src/workspace_yaml/settings.rs
+*/
+const PNPM_V12_IGNORED_WORKSPACE_SETTINGS = [
+	"access",
+	"allowNew",
+	"allowSameVersion",
+	"auditIgnorePrune",
+	"autoConfirmAllPrompts",
+	"binLinks",
+	"commitHooks",
+	"cpu",
+	"depth",
+	"description",
+	"dev",
+	"dryRun",
+	"enablePnp",
+	"extraBinPaths",
+	"extraEnv",
+	"fetchingConcurrency",
+	"force",
+	"git",
+	"gitTagVersion",
+	"global",
+	"globalPath",
+	"globalPrefix",
+	"ignoreCurrentSpecifiers",
+	"json",
+	"libc",
+	"localAddress",
+	"lockfileOnly",
+	"long",
+	"message",
+	"npmPath",
+	"only",
+	"os",
+	"packDestination",
+	"packGzipLevel",
+	"parseable",
+	"pnpmExecPath",
+	"preserveAbsolutePaths",
+	"production",
+	"publishBranch",
+	"recursive",
+	"registriesByPrefix",
+	"registriesByScope",
+	"registryOptionsByUrl",
+	"requiredScripts",
+	"runtime",
+	"save",
+	"saveDev",
+	"saveOptional",
+	"saveProd",
+	"sideEffectsCacheRead",
+	"sideEffectsCacheWrite",
+	"signGitTag",
+	"strictSsl",
+	"tag",
+	"tryLoadDefaultPnpmfile",
+	"umask",
+	"useGitBranchLockfile",
+	"useLockfile",
+	"useRunningStoreServer",
+	"version",
+	"workspacePackagePatterns",
+	"workspacePackages",
+	"workspacePrefix",
+	"workspaceRoot",
+	"yes"
+];
+/**
 * Lookup used to remove v11-only fields from the v12 workspace allowlist.
 */
-const v11OnlyWorkspaceSettings = new Set(PNPM_V11_ONLY_WORKSPACE_SETTINGS);
+const v11OnlyWorkspaceSettings = /* @__PURE__ */ new Set([...PNPM_V11_ONLY_WORKSPACE_SETTINGS, ...PNPM_V12_IGNORED_WORKSPACE_SETTINGS]);
 /**
 * Fields accepted by registry declarations with pnpm 12.9 concurrency limits.
 */
@@ -770,7 +893,7 @@ const PROJECT_REFUSED_SETTINGS = new Set(PNPM_PROJECT_REFUSED_SETTINGS);
 /**
 * Fields reported as incompatible when selecting settings for v12.
 */
-const PNPM_V11_ONLY_SETTINGS = new Set(PNPM_V11_ONLY_WORKSPACE_SETTINGS);
+const PNPM_V11_ONLY_SETTINGS = /* @__PURE__ */ new Set([...PNPM_V11_ONLY_WORKSPACE_SETTINGS, ...PNPM_V12_IGNORED_WORKSPACE_SETTINGS]);
 /**
 * Allowed workspace fields for the v11 target.
 */
@@ -1119,6 +1242,32 @@ function formatSettingsIssues(options) {
 	return warnings;
 }
 //#endregion
+//#region src/features/settings/registries.ts
+/**
+* Check that a registry location is a URL rather than an object property name.
+*
+* @param value - Untrusted registry location
+*
+* @returns Whether the location is an absolute or scheme-relative URL
+*/
+function isRegistryUrl(value) {
+	return isString(value) && URL.canParse(value.startsWith("//") ? `https:${value}` : value);
+}
+/**
+* Validate locations in legacy registry maps and URL-keyed declarations.
+*
+* @param key - Canonical workspace setting name
+* @param value - Untrusted registry configuration
+*
+* @returns Whether the complete setting must be retained in its source
+*/
+function hasInvalidRegistryLocations(key, value) {
+	if (!["namedRegistries", "registries"].includes(key) || value === null) return false;
+	if (!isPlainObject(value)) return true;
+	if (key === "namedRegistries") return Object.values(value).some((url) => !isRegistryUrl(url));
+	return Object.entries(value).some(([url, entry]) => isString(entry) ? !isRegistryUrl(entry) : !isRegistryUrl(url));
+}
+//#endregion
 //#region src/features/settings/permissions.ts
 /**
 * Validate a dependency's capability map without dropping unknown permissions.
@@ -1152,6 +1301,65 @@ function hasInvalidPermissionSettings(key, value) {
 //#endregion
 //#region src/features/settings/pnpm-v12-values.ts
 /**
+* Validate the package-map section without dropping future or misspelled keys.
+*
+* @param value - Untrusted package-map value
+*
+* @returns Whether the section is outside the pnpm 12.13 schema
+*/
+function hasInvalidNodePackageMap(value) {
+	if (value === null) return false;
+	if (!value || typeof value !== "object" || isArray(value)) return true;
+	return Object.entries(value).some(([field, entry]) => {
+		let values = [];
+		if (field === "mode") values = [
+			"off",
+			"write-only",
+			"load"
+		];
+		else if (field === "type") values = ["standard", "loose"];
+		return values.length === 0 || entry !== null && (!isString(entry) || !entry.includes("${") && !values.includes(entry));
+	});
+}
+/**
+* Validate cache exclusions and retain their whole section on older targets.
+*
+* @param value - Untrusted cache section
+* @param target - Confirmed release controlling exclusion support
+*
+* @returns Whether a section containing exclusions cannot migrate
+*/
+function hasInvalidCacheExclusions(value, target) {
+	if (!Object.hasOwn(value, "exclude")) return false;
+	if (!supportsMinimumVersion(target.version, PNPM_V12_14_MINIMUM_VERSION)) return true;
+	return Object.entries(value).some(([field, entry]) => {
+		if (field === "exclude") return entry !== null && (!isArray(entry) || !entry.every(isString));
+		if (field === "read" || field === "write") return entry !== null && !isBoolean(entry) && !(isString(entry) && entry.includes("${"));
+		if (field !== "remote") return true;
+		if (entry === null) return false;
+		if (!entry || typeof entry !== "object" || isArray(entry)) return true;
+		return Object.entries(entry).some(([key, setting]) => {
+			if (key === "org" || key === "organization") return !isString(setting);
+			return key !== "packages" || !isArray(setting) || !setting.every(isString);
+		});
+	});
+}
+/**
+* Check the value expansions introduced by pnpm 12.13 and 12.14.
+*
+* @param key - Canonical setting name
+* @param value - Untrusted setting value
+* @param target - Confirmed target release
+*
+* @returns Whether a package-map, store-index, or cache value is incompatible
+*/
+function hasIncompatiblePackageMapOrCache(key, value, target) {
+	if (key === "nodePackageMap") return !supportsMinimumVersion(target.version, PNPM_V12_13_MINIMUM_VERSION) || hasInvalidNodePackageMap(value);
+	if (key === "storeIndexFormat") return !supportsMinimumVersion(target.version, PNPM_V12_13_MINIMUM_VERSION) || value !== null && (!isString(value) || !value.includes("${") && !["sqlite", "files"].includes(value));
+	if (key === "sideEffectsCache" && value && typeof value === "object") return hasInvalidCacheExclusions(value, target);
+	return false;
+}
+/**
 * Check a loaded linker object without discarding unsupported options.
 *
 * @param value - Untrusted nodeLinker object
@@ -1241,6 +1449,7 @@ function hasInvalidLinkerOrLockfileScalarValue(key, value) {
 * @returns Whether the setting cannot be used by the target release
 */
 function hasIncompatibleV12SettingValue(key, value, target) {
+	if (hasIncompatiblePackageMapOrCache(key, value, target)) return true;
 	const supportsV12_10 = supportsMinimumVersion(target.version, PNPM_V12_10_MINIMUM_VERSION);
 	if (key === "nodeLinker" && value === "loaded") return !supportsV12_10;
 	if (key === "failIfNoMatch" && target.compatibility === "v12") return value !== null && !isBoolean(value);
@@ -1263,6 +1472,22 @@ function hasIncompatibleV12SettingValue(key, value, target) {
 	return false;
 }
 //#endregion
+//#region src/features/settings/remote-cache.ts
+/**
+* Accept only the project-owned remote cache organization.
+* Keep machine configuration and unknown fields intact in their source.
+*
+* @param key - Canonical workspace setting name
+* @param value - Untrusted incoming or existing workspace value
+*
+* @returns Whether the remote cache setting cannot migrate to project YAML
+*/
+function hasInvalidRemoteCacheValue(key, value) {
+	if (key !== "remoteCache" || value === null) return false;
+	if (!value || typeof value !== "object" || isArray(value)) return true;
+	return Object.entries(value).some(([field, entry]) => field !== "org" || entry !== null && !isString(entry));
+}
+//#endregion
 //#region src/features/settings/versioned-values.ts
 /**
 * Bounds of the signed 32-bit integer used by pnpm's task priority.
@@ -1279,7 +1504,10 @@ const MAX_TASK_PRIORITY = 2147483647;
 * @returns Whether pnpm rejects the value after migration
 */
 function hasInvalidV11PatchValue(key, value, target) {
-	if (["httpProxy", "httpsProxy"].includes(key) && supportsMinimumVersion(target.version, PNPM_V11_28_5_MINIMUM_VERSION)) return !isString(value);
+	if (["httpProxy", "httpsProxy"].includes(key) && supportsMinimumVersion(target.version, PNPM_V11_28_5_MINIMUM_VERSION)) {
+		if (value === null && supportsMinimumVersion(target.version, PNPM_V11_28_6_MINIMUM_VERSION)) return false;
+		return !isString(value);
+	}
 	if (value === null || value === void 0) return false;
 	if (key === "allowBuilds" && supportsMinimumVersion(target.version, PNPM_V11_28_3_MINIMUM_VERSION)) return typeof value !== "object" || isArray(value) || Object.values(value).some((entry) => !isBoolean(entry) && !isString(entry));
 	if (supportsMinimumVersion(target.version, PNPM_V11_28_4_MINIMUM_VERSION)) {
@@ -1311,7 +1539,7 @@ function hasInvalidScalarValue(key, value, target) {
 			"ndjson",
 			"silent"
 		].includes(value);
-		if (key === "provenance") return value !== null && !isBoolean(value);
+		if (key === "provenance" || key === "addMissingPeerTypes") return value !== null && !isBoolean(value);
 		if (key === "progress") return !isBoolean(value);
 		if (key === "tagVersionPrefix") return !isString(value);
 		if (key === "loglevel") return !isString(value) || !value.includes("${") && ![
@@ -1341,6 +1569,17 @@ function hasInvalidReleaseValue(key, value, target) {
 	return false;
 }
 /**
+* Check release-specific reserved aliases without broadening case sensitivity.
+*
+* @param prefix - Registry alias as declared
+* @param target - Confirmed target version
+*
+* @returns Whether the alias shadows a protocol introduced by these releases
+*/
+function isReservedRegistryPrefix(prefix, target) {
+	return prefix.toLowerCase() === "pkg" && supportsMinimumVersion(target.version, PNPM_V12_5_MINIMUM_VERSION) || prefix === "tool" && supportsMinimumVersion(target.version, PNPM_V12_12_1_MINIMUM_VERSION);
+}
+/**
 * Check value shapes that changed within a pnpm major release.
 *
 * Reject the whole setting so cleanup cannot discard unsupported nested values.
@@ -1352,7 +1591,7 @@ function hasInvalidReleaseValue(key, value, target) {
 * @returns Whether the value uses a shape unsupported by the selected release
 */
 function hasIncompatibleSettingValue(key, value, target) {
-	if (hasInvalidPermissionSettings(key, value) || hasInvalidReleaseValue(key, value, target) || hasInvalidV11PatchValue(key, value, target) || hasIncompatibleV12SettingValue(key, value, target)) return true;
+	if (hasInvalidPermissionSettings(key, value) || hasInvalidRemoteCacheValue(key, value) || hasInvalidReleaseValue(key, value, target) || hasInvalidV11PatchValue(key, value, target) || hasIncompatibleV12SettingValue(key, value, target)) return true;
 	if (hasInvalidScalarValue(key, value, target)) return true;
 	const supportsV12_5 = supportsMinimumVersion(target.version, PNPM_V12_5_MINIMUM_VERSION);
 	if (key === "supportedArchitectures" && isArray(value)) return !supportsV12_5;
@@ -1370,19 +1609,42 @@ function hasIncompatibleSettingValue(key, value, target) {
 			"constraints"
 		].some((field) => Object.hasOwn(value, field));
 	}
-	if (key === "namedRegistries" && supportsV12_5) return Object.keys(value).some((prefix) => prefix.toLowerCase() === "pkg");
+	if (key === "namedRegistries") return Object.keys(value).some((prefix) => isReservedRegistryPrefix(prefix, target));
 	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 && isString(prefix) && prefix.toLowerCase() === "pkg";
+		return isString(prefix) && isReservedRegistryPrefix(prefix, target);
 	});
 	return false;
 }
 //#endregion
 //#region src/features/settings/schema.ts
 /**
+* Detect legacy runtime fields without a destination in pnpm v11 and newer.
+*
+* @param key - Canonical setting name
+* @param value - Untrusted legacy runtime declaration
+* @param compatibility - Target major controlling runtime conversion
+*
+* @returns Whether converting the runtime would discard sibling fields
+*/
+function hasUnmigratableRuntimeFields(key, value, compatibility) {
+	return Boolean(key === "executionEnv" && compatibility !== "v10" && value && typeof value === "object" && Object.keys(value).some((field) => field !== "nodeVersion"));
+}
+/**
+* Check task declarations against the fields consumed by the target release.
+*
+* @param value - Untrusted task declarations
+* @param taskSettings - Supported task field names
+*
+* @returns Whether any declared task field is unsupported
+*/
+function hasUnsupportedTaskFields(value, taskSettings) {
+	return Boolean(value && typeof value === "object" && Object.values(value).some((task) => task && typeof task === "object" && Object.keys(task).some((field) => !taskSettings.has(field))));
+}
+/**
 * Create an empty collection of schema selection issues.
 *
 * @returns Empty issue lists for every supported issue category
@@ -1487,8 +1749,8 @@ 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) && isString(value) && 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 (hasInvalidRegistryLocations(key, value) || hasUnmigratableRuntimeFields(key, value, compatibility) || hasIncompatibleSettingValue(key, value, target)) return "incompatible";
+	if (key === "tasks" && hasUnsupportedTaskFields(value, taskSettings)) return "incompatible";
 	if (!workspaceSettings.has(key)) return isSettingFromAnotherVersion(key, compatibility) ? "incompatible" : "unknown";
 	if (allowedFields && !allowedFields.has(key)) return "unsupported";
 }
@@ -1897,8 +2159,17 @@ function getNpmrcLineKey(line) {
 	const trimmed = line.trim();
 	if (!trimmed || trimmed.startsWith(";") || trimmed.startsWith("#")) return;
 	const index = trimmed.indexOf("=");
-	if (index <= 0) return;
-	return normalizeNpmrcKey(trimmed.slice(0, index));
+	if (index === 0) return;
+	let key = (index < 0 ? trimmed : trimmed.slice(0, index)).trim();
+	if (key.startsWith("\"") && key.endsWith("\"") || key.startsWith("'") && key.endsWith("'")) {
+		if (key.startsWith("'")) key = key.slice(1, -1);
+		try {
+			const parsed = JSON.parse(key);
+			if (!isString(parsed)) return;
+			key = parsed;
+		} catch {}
+	} else key = key.replace(/\\(?<escaped>[\\;#])|[;#].*$/gu, (_, escaped) => escaped ?? "");
+	return normalizeNpmrcKey(key);
 }
 /**
 * Check whether a `.npmrc` key is auth/registry-related and should stay in
@@ -1925,7 +2196,7 @@ function isNpmrcAuthOrRegistryKey(key) {
 * @param compatibility - Concrete pnpm compatibility target
 * @param migratedKeys - Original `.npmrc` keys that were migrated
 *
-* @returns A promise that resolves when the file has been pruned
+* @returns Whether the file was changed or removed
 *
 * @throws {Error} When file read/write operations fail
 *
@@ -1938,18 +2209,25 @@ async function pruneNpmrc(path, compatibility, migratedKeys) {
 	const migratedKeySet = new Set(migratedKeys.map(normalizeNpmrcKey));
 	const content = await fsReadFile(path);
 	let inSection = false;
-	const updatedContent = content.split(/\r\n|[\r\n]/u).filter((line) => {
+	let removed = false;
+	const lines = content.split(/\r\n|[\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);
-	}).join("\n").trimEnd();
+		if (migratedKeySet.has(key)) {
+			removed = true;
+			return false;
+		}
+		return true;
+	});
+	if (!removed) return false;
+	const updatedContent = lines.join("\n").trimEnd();
 	if (compatibility !== "v10" && !updatedContent.trim()) {
 		await fsRemoveFile(path);
-		return;
+		return true;
 	}
-	await fsWriteFile(path, updatedContent);
+	return fsWriteFileIfChanged(path, updatedContent);
 }
 /**
 * Read `.npmrc` and return settings that should be migrated into workspace config.
@@ -2488,10 +2766,10 @@ async function persistMigration(options) {
 	if (!cleanNpmrc) return result;
 	const pruneTasks = projectNpmrcs.projects.flatMap((project) => {
 		const appliedKeys = selectAppliedProjectKeys(project, finalSettings);
-		return appliedKeys.length ? [pruneNpmrc(project.npmrcPath, compatibility, appliedKeys).then(() => project.npmrcPath)] : [];
+		return appliedKeys.length ? [pruneNpmrc(project.npmrcPath, compatibility, appliedKeys).then((changed) => changed ? project.npmrcPath : void 0)] : [];
 	});
-	if (npmrcExists && appliedNpmrcKeys.length) pruneTasks.push(pruneNpmrc(npmrcPath, compatibility, appliedNpmrcKeys).then(() => npmrcPath));
-	const cleanedNpmrcPaths = await Promise.all(pruneTasks);
+	if (npmrcExists && appliedNpmrcKeys.length) pruneTasks.push(pruneNpmrc(npmrcPath, compatibility, appliedNpmrcKeys).then((changed) => changed ? npmrcPath : void 0));
+	const cleanedNpmrcPaths = (await Promise.all(pruneTasks)).filter(isString);
 	result.changedFiles.push(...cleanedNpmrcPaths);
 	result.sourceSettingsCleaned ||= cleanedNpmrcPaths.length > 0;
 	return result;
@@ -2587,9 +2865,9 @@ function normalizeSideEffectsCache(settings) {
 * @returns Nothing; the URL's declaration is created or updated in place
 */
 function addRegistryScope(declarations, url, scope) {
-	declarations[url] ??= {};
-	const declaration = declarations[url];
+	const declaration = declarations.get(url) ?? {};
 	declaration.scopes = unique([...declaration.scopes ?? [], scope]);
+	declarations.set(url, declaration);
 }
 /**
 * Find source URLs with multiple active aliases across the merged settings.
@@ -2618,9 +2896,9 @@ function findRegistryAliasConflicts(prefixesByUrl, namedRegistries, canonicalPre
 function normalizeNamedRegistries(settings, warnings, canonicalSettings) {
 	const { namedRegistries } = settings;
 	if (!namedRegistries) return;
-	const declarations = {};
+	const declarations = /* @__PURE__ */ new Map();
 	for (const [key, value] of Object.entries(settings.registries ?? {})) if (isString(value)) addRegistryScope(declarations, value, key === "default" ? "@" : key);
-	else declarations[key] = { ...value };
+	else declarations.set(key, { ...value });
 	const canonicalPrefixes = new Set(Object.values(canonicalSettings.registries ?? {}).flatMap((value) => !isString(value) && isString(value?.prefix) ? [value.prefix] : []));
 	const prefixesByUrl = /* @__PURE__ */ new Map();
 	const registryAliases = Object.entries(namedRegistries).filter(([prefix]) => !canonicalPrefixes.has(prefix));
@@ -2635,17 +2913,17 @@ function normalizeNamedRegistries(settings, warnings, canonicalSettings) {
 		return;
 	}
 	for (const [url, [prefix]] of prefixesByUrl) {
-		declarations[url] ??= {};
-		const declaration = declarations[url];
-		const canonicalDeclaration = canonicalSettings.registries?.[url];
+		const declaration = declarations.get(url) ?? {};
+		const canonicalDeclaration = canonicalSettings.registries && Object.hasOwn(canonicalSettings.registries, url) ? canonicalSettings.registries[url] : void 0;
 		const declaredPrefix = (isString(canonicalDeclaration) ? void 0 : canonicalDeclaration?.prefix) ?? declaration.prefix;
 		if (isString(declaredPrefix) && declaredPrefix !== prefix) {
 			warnings.push(`namedRegistries was kept because ${url} already declares prefix ${declaredPrefix}.`);
 			return;
 		}
 		declaration.prefix = prefix;
+		declarations.set(url, declaration);
 	}
-	settings.registries = declarations;
+	settings.registries = Object.fromEntries(declarations);
 	Reflect.deleteProperty(settings, "namedRegistries");
 }
 /**
@@ -3207,7 +3485,7 @@ const bold = getColor("bold");
 //#endregion
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.16.0";
+var version = "0.18.0";
 //#endregion
 //#region src/cli/options.ts
 /**

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { Document } from "yaml";
-import { PnpmSettings, RegistryDeclaration } from "@pnpm/types";
+import { PnpmSettings, RegistryDeclaration, SideEffectsCacheSettings } from "@pnpm/types";
 //#region src/types/options.d.ts
 /**
  * Compatibility target used by the migrator.
@@ -259,6 +259,27 @@ interface PnpmSkillsSettings {
  * Settings supported by pnpm v12, subject to the resolved version capabilities.
  */
 interface PnpmSettingsV12 {
+  /**
+   * Package-map generation and loading options (pnpm 12.13+).
+   */
+  nodePackageMap?: PnpmNodePackageMapSettings | null;
+  /**
+   * Store package index backend; files supports network shares (pnpm 12.13+).
+   */
+  storeIndexFormat?: 'sqlite' | 'files' | null;
+  /**
+   * Build cache policy, including exclusions from pnpm 12.14 onward.
+   */
+  sideEffectsCache?: boolean | PnpmSideEffectsCacheSettings;
+  /**
+   * Link available companion @types packages as optional peers (pnpm 12.12+).
+   * Null leaves pnpm's default unchanged.
+   */
+  addMissingPeerTypes?: boolean | null;
+  /**
+   * Project-owned remote cache configuration (pnpm 12.12+).
+   */
+  remoteCache?: PnpmRemoteCacheSettings | null;
   /**
    * Per-dependency build and agent skill permissions (pnpm 12.11+).
    */
@@ -353,6 +374,41 @@ interface PnpmSettingsV12 {
    */
   tasks?: Record<string, PnpmTaskSettings>;
 }
+/**
+ * Package-map section introduced in pnpm 12.13. Explicit fields take precedence
+ * over nodeExperimentalPackageMap and nodePackageMapType in the same source.
+ */
+interface PnpmNodePackageMapSettings {
+  /**
+   * Disable the map, write it for tools, or also load it in Node.js scripts.
+   * Null leaves the legacy setting or pnpm's default effective.
+   */
+  mode?: 'off' | 'write-only' | 'load' | null;
+  /**
+   * Map format; null leaves the legacy setting or default effective.
+   */
+  type?: 'standard' | 'loose' | null;
+}
+/**
+ * Structured build cache options with pnpm 12.14 package exclusions.
+ */
+interface PnpmSideEffectsCacheSettings extends SideEffectsCacheSettings {
+  /**
+   * Package name, scope, or name@version patterns whose builds are neither
+   * restored nor saved; null leaves exclusions unset.
+   */
+  exclude?: string[] | null;
+}
+/**
+ * Remote cache options allowed in project YAML. Server and signing settings
+ * belong in trusted global configuration or environment variables.
+ */
+interface PnpmRemoteCacheSettings {
+  /**
+   * Organization owning shared artifacts; null leaves it unset.
+   */
+  org?: string | null;
+}
 //#endregion
 //#region src/types/workspace.d.ts
 /**
@@ -473,6 +529,14 @@ interface PnpmSettingsDeprecated {
  * Settings introduced in pnpm v11.
  */
 interface PnpmSettingsV11 {
+  /**
+   * HTTP proxy; null leaves the proxy unset except in pnpm 11.28.5.
+   */
+  httpProxy?: string | null;
+  /**
+   * HTTPS proxy; null leaves the proxy unset except in pnpm 11.28.5.
+   */
+  httpsProxy?: string | null;
   /**
    * Publish provenance preference. Consumed from workspace configuration by
    * pnpm v11 and pnpm v12 starting with 12.11. Null leaves it unset.
@@ -522,7 +586,7 @@ interface PnpmSettingsV11 {
 /**
  * `pnpm-workspace.yaml` types.
  */
-type PnpmWorkspace = Omit<PnpmSettings, 'lockfile' | 'nodeLinker' | 'provenance' | 'registries' | 'supportedArchitectures' | 'tasks'> & PnpmSettingsDeprecated & PnpmSettingsV11 & PnpmSettingsV12 & PnpmWorkspaceLegacy;
+type PnpmWorkspace = Omit<PnpmSettings, 'httpProxy' | 'httpsProxy' | 'lockfile' | 'nodeLinker' | 'provenance' | 'registries' | 'sideEffectsCache' | 'supportedArchitectures' | 'tasks'> & PnpmSettingsDeprecated & PnpmSettingsV11 & PnpmSettingsV12 & PnpmWorkspaceLegacy;
 //#endregion
 //#region src/types/package-json.d.ts
 /**
@@ -730,4 +794,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, PnpmLoadedNodeLinkerSettings, PnpmLockfileSettings, PnpmPackagePermissions, PnpmPythonSettings, PnpmRegistryDeclaration, PnpmSettingsDeprecated, PnpmSettingsV11, PnpmSettingsV12, PnpmSkillsSettings, PnpmTaskSettings, PnpmWorkspace, PnpmWorkspaceLegacy, ResolvedOptions, RuntimeEngine, SettingsChange };
+export type { CompatibilityTarget, GlobalShimPolicy, MergeStrategy, MigrationResult, NpmRC, Options, PackageJson, PackageManagerEngine, PnpmCargoSettings, PnpmLoadedNodeLinkerSettings, PnpmLockfileSettings, PnpmNodePackageMapSettings, PnpmPackagePermissions, PnpmPythonSettings, PnpmRegistryDeclaration, PnpmRemoteCacheSettings, PnpmSettingsDeprecated, PnpmSettingsV11, PnpmSettingsV12, PnpmSideEffectsCacheSettings, PnpmSkillsSettings, PnpmTaskSettings, PnpmWorkspace, PnpmWorkspaceLegacy, ResolvedOptions, RuntimeEngine, SettingsChange };

package/dist/index.mjs

@@ -585,6 +585,14 @@ const PNPM_V11_28_5_MINIMUM_VERSION = [
 	5
 ];
 /**
+* Release restoring null proxy values as unset configuration.
+*/
+const PNPM_V11_28_6_MINIMUM_VERSION = [
+	11,
+	28,
+	6
+];
+/**
 * Release adding force, publishing, and reporter settings.
 */
 const PNPM_V12_7_MINIMUM_VERSION = [
@@ -625,6 +633,38 @@ const PNPM_V12_11_MINIMUM_VERSION = [
 	0
 ];
 /**
+* Release introducing remote cache configuration and missing peer types.
+*/
+const PNPM_V12_12_MINIMUM_VERSION = [
+	12,
+	12,
+	0
+];
+/**
+* Release reserving the tool registry prefix.
+*/
+const PNPM_V12_12_1_MINIMUM_VERSION = [
+	12,
+	12,
+	1
+];
+/**
+* Release introducing package map options and file-based store indexes.
+*/
+const PNPM_V12_13_MINIMUM_VERSION = [
+	12,
+	13,
+	0
+];
+/**
+* Release introducing side-effects cache exclusions.
+*/
+const PNPM_V12_14_MINIMUM_VERSION = [
+	12,
+	14,
+	0
+];
+/**
 * Workspace settings first consumed by pnpm v12 in 12.11.0.
 */
 const PNPM_V12_11_WORKSPACE_SETTINGS = [
@@ -650,6 +690,16 @@ const PNPM_V12_7_WORKSPACE_SETTINGS = [
 * @see https://github.com/pnpm/pnpm/blob/v12.4.0/pnpm/crates/config/src/workspace_yaml.rs
 */
 const PNPM_SETTINGS_CAPABILITIES = [
+	{
+		minimumVersion: PNPM_V12_13_MINIMUM_VERSION,
+		workspaceFields: ["nodePackageMap", "storeIndexFormat"],
+		taskFields: []
+	},
+	{
+		minimumVersion: PNPM_V12_12_MINIMUM_VERSION,
+		workspaceFields: ["addMissingPeerTypes", "remoteCache"],
+		taskFields: []
+	},
 	{
 		minimumVersion: PNPM_V12_11_MINIMUM_VERSION,
 		workspaceFields: PNPM_V12_11_WORKSPACE_SETTINGS,
@@ -731,9 +781,82 @@ const PNPM_V12_ONLY_WORKSPACE_SETTINGS = [
 	"globalShims"
 ];
 /**
+* Legacy fields absent from pnpm v12's workspace reader through 12.14.0.
+* Removed aliases with explicit migration replacements are kept separately.
+*
+* @see https://github.com/pnpm/pnpm/blob/v12.14.0/pnpm/crates/config/src/workspace_yaml/settings.rs
+*/
+const PNPM_V12_IGNORED_WORKSPACE_SETTINGS = [
+	"access",
+	"allowNew",
+	"allowSameVersion",
+	"auditIgnorePrune",
+	"autoConfirmAllPrompts",
+	"binLinks",
+	"commitHooks",
+	"cpu",
+	"depth",
+	"description",
+	"dev",
+	"dryRun",
+	"enablePnp",
+	"extraBinPaths",
+	"extraEnv",
+	"fetchingConcurrency",
+	"force",
+	"git",
+	"gitTagVersion",
+	"global",
+	"globalPath",
+	"globalPrefix",
+	"ignoreCurrentSpecifiers",
+	"json",
+	"libc",
+	"localAddress",
+	"lockfileOnly",
+	"long",
+	"message",
+	"npmPath",
+	"only",
+	"os",
+	"packDestination",
+	"packGzipLevel",
+	"parseable",
+	"pnpmExecPath",
+	"preserveAbsolutePaths",
+	"production",
+	"publishBranch",
+	"recursive",
+	"registriesByPrefix",
+	"registriesByScope",
+	"registryOptionsByUrl",
+	"requiredScripts",
+	"runtime",
+	"save",
+	"saveDev",
+	"saveOptional",
+	"saveProd",
+	"sideEffectsCacheRead",
+	"sideEffectsCacheWrite",
+	"signGitTag",
+	"strictSsl",
+	"tag",
+	"tryLoadDefaultPnpmfile",
+	"umask",
+	"useGitBranchLockfile",
+	"useLockfile",
+	"useRunningStoreServer",
+	"version",
+	"workspacePackagePatterns",
+	"workspacePackages",
+	"workspacePrefix",
+	"workspaceRoot",
+	"yes"
+];
+/**
 * Lookup used to remove v11-only fields from the v12 workspace allowlist.
 */
-const v11OnlyWorkspaceSettings = new Set(PNPM_V11_ONLY_WORKSPACE_SETTINGS);
+const v11OnlyWorkspaceSettings = /* @__PURE__ */ new Set([...PNPM_V11_ONLY_WORKSPACE_SETTINGS, ...PNPM_V12_IGNORED_WORKSPACE_SETTINGS]);
 /**
 * Fields accepted by registry declarations with pnpm 12.9 concurrency limits.
 */
@@ -768,7 +891,7 @@ const PROJECT_REFUSED_SETTINGS = new Set(PNPM_PROJECT_REFUSED_SETTINGS);
 /**
 * Fields reported as incompatible when selecting settings for v12.
 */
-const PNPM_V11_ONLY_SETTINGS = new Set(PNPM_V11_ONLY_WORKSPACE_SETTINGS);
+const PNPM_V11_ONLY_SETTINGS = /* @__PURE__ */ new Set([...PNPM_V11_ONLY_WORKSPACE_SETTINGS, ...PNPM_V12_IGNORED_WORKSPACE_SETTINGS]);
 /**
 * Allowed workspace fields for the v11 target.
 */
@@ -1112,6 +1235,32 @@ function formatSettingsIssues(options) {
 	return warnings;
 }
 //#endregion
+//#region src/features/settings/registries.ts
+/**
+* Check that a registry location is a URL rather than an object property name.
+*
+* @param value - Untrusted registry location
+*
+* @returns Whether the location is an absolute or scheme-relative URL
+*/
+function isRegistryUrl(value) {
+	return isString(value) && URL.canParse(value.startsWith("//") ? `https:${value}` : value);
+}
+/**
+* Validate locations in legacy registry maps and URL-keyed declarations.
+*
+* @param key - Canonical workspace setting name
+* @param value - Untrusted registry configuration
+*
+* @returns Whether the complete setting must be retained in its source
+*/
+function hasInvalidRegistryLocations(key, value) {
+	if (!["namedRegistries", "registries"].includes(key) || value === null) return false;
+	if (!isPlainObject(value)) return true;
+	if (key === "namedRegistries") return Object.values(value).some((url) => !isRegistryUrl(url));
+	return Object.entries(value).some(([url, entry]) => isString(entry) ? !isRegistryUrl(entry) : !isRegistryUrl(url));
+}
+//#endregion
 //#region src/features/settings/permissions.ts
 /**
 * Validate a dependency's capability map without dropping unknown permissions.
@@ -1145,6 +1294,65 @@ function hasInvalidPermissionSettings(key, value) {
 //#endregion
 //#region src/features/settings/pnpm-v12-values.ts
 /**
+* Validate the package-map section without dropping future or misspelled keys.
+*
+* @param value - Untrusted package-map value
+*
+* @returns Whether the section is outside the pnpm 12.13 schema
+*/
+function hasInvalidNodePackageMap(value) {
+	if (value === null) return false;
+	if (!value || typeof value !== "object" || isArray(value)) return true;
+	return Object.entries(value).some(([field, entry]) => {
+		let values = [];
+		if (field === "mode") values = [
+			"off",
+			"write-only",
+			"load"
+		];
+		else if (field === "type") values = ["standard", "loose"];
+		return values.length === 0 || entry !== null && (!isString(entry) || !entry.includes("${") && !values.includes(entry));
+	});
+}
+/**
+* Validate cache exclusions and retain their whole section on older targets.
+*
+* @param value - Untrusted cache section
+* @param target - Confirmed release controlling exclusion support
+*
+* @returns Whether a section containing exclusions cannot migrate
+*/
+function hasInvalidCacheExclusions(value, target) {
+	if (!Object.hasOwn(value, "exclude")) return false;
+	if (!supportsMinimumVersion(target.version, PNPM_V12_14_MINIMUM_VERSION)) return true;
+	return Object.entries(value).some(([field, entry]) => {
+		if (field === "exclude") return entry !== null && (!isArray(entry) || !entry.every(isString));
+		if (field === "read" || field === "write") return entry !== null && !isBoolean(entry) && !(isString(entry) && entry.includes("${"));
+		if (field !== "remote") return true;
+		if (entry === null) return false;
+		if (!entry || typeof entry !== "object" || isArray(entry)) return true;
+		return Object.entries(entry).some(([key, setting]) => {
+			if (key === "org" || key === "organization") return !isString(setting);
+			return key !== "packages" || !isArray(setting) || !setting.every(isString);
+		});
+	});
+}
+/**
+* Check the value expansions introduced by pnpm 12.13 and 12.14.
+*
+* @param key - Canonical setting name
+* @param value - Untrusted setting value
+* @param target - Confirmed target release
+*
+* @returns Whether a package-map, store-index, or cache value is incompatible
+*/
+function hasIncompatiblePackageMapOrCache(key, value, target) {
+	if (key === "nodePackageMap") return !supportsMinimumVersion(target.version, PNPM_V12_13_MINIMUM_VERSION) || hasInvalidNodePackageMap(value);
+	if (key === "storeIndexFormat") return !supportsMinimumVersion(target.version, PNPM_V12_13_MINIMUM_VERSION) || value !== null && (!isString(value) || !value.includes("${") && !["sqlite", "files"].includes(value));
+	if (key === "sideEffectsCache" && value && typeof value === "object") return hasInvalidCacheExclusions(value, target);
+	return false;
+}
+/**
 * Check a loaded linker object without discarding unsupported options.
 *
 * @param value - Untrusted nodeLinker object
@@ -1234,6 +1442,7 @@ function hasInvalidLinkerOrLockfileScalarValue(key, value) {
 * @returns Whether the setting cannot be used by the target release
 */
 function hasIncompatibleV12SettingValue(key, value, target) {
+	if (hasIncompatiblePackageMapOrCache(key, value, target)) return true;
 	const supportsV12_10 = supportsMinimumVersion(target.version, PNPM_V12_10_MINIMUM_VERSION);
 	if (key === "nodeLinker" && value === "loaded") return !supportsV12_10;
 	if (key === "failIfNoMatch" && target.compatibility === "v12") return value !== null && !isBoolean(value);
@@ -1256,6 +1465,22 @@ function hasIncompatibleV12SettingValue(key, value, target) {
 	return false;
 }
 //#endregion
+//#region src/features/settings/remote-cache.ts
+/**
+* Accept only the project-owned remote cache organization.
+* Keep machine configuration and unknown fields intact in their source.
+*
+* @param key - Canonical workspace setting name
+* @param value - Untrusted incoming or existing workspace value
+*
+* @returns Whether the remote cache setting cannot migrate to project YAML
+*/
+function hasInvalidRemoteCacheValue(key, value) {
+	if (key !== "remoteCache" || value === null) return false;
+	if (!value || typeof value !== "object" || isArray(value)) return true;
+	return Object.entries(value).some(([field, entry]) => field !== "org" || entry !== null && !isString(entry));
+}
+//#endregion
 //#region src/features/settings/versioned-values.ts
 /**
 * Bounds of the signed 32-bit integer used by pnpm's task priority.
@@ -1272,7 +1497,10 @@ const MAX_TASK_PRIORITY = 2147483647;
 * @returns Whether pnpm rejects the value after migration
 */
 function hasInvalidV11PatchValue(key, value, target) {
-	if (["httpProxy", "httpsProxy"].includes(key) && supportsMinimumVersion(target.version, PNPM_V11_28_5_MINIMUM_VERSION)) return !isString(value);
+	if (["httpProxy", "httpsProxy"].includes(key) && supportsMinimumVersion(target.version, PNPM_V11_28_5_MINIMUM_VERSION)) {
+		if (value === null && supportsMinimumVersion(target.version, PNPM_V11_28_6_MINIMUM_VERSION)) return false;
+		return !isString(value);
+	}
 	if (value === null || value === void 0) return false;
 	if (key === "allowBuilds" && supportsMinimumVersion(target.version, PNPM_V11_28_3_MINIMUM_VERSION)) return typeof value !== "object" || isArray(value) || Object.values(value).some((entry) => !isBoolean(entry) && !isString(entry));
 	if (supportsMinimumVersion(target.version, PNPM_V11_28_4_MINIMUM_VERSION)) {
@@ -1304,7 +1532,7 @@ function hasInvalidScalarValue(key, value, target) {
 			"ndjson",
 			"silent"
 		].includes(value);
-		if (key === "provenance") return value !== null && !isBoolean(value);
+		if (key === "provenance" || key === "addMissingPeerTypes") return value !== null && !isBoolean(value);
 		if (key === "progress") return !isBoolean(value);
 		if (key === "tagVersionPrefix") return !isString(value);
 		if (key === "loglevel") return !isString(value) || !value.includes("${") && ![
@@ -1334,6 +1562,17 @@ function hasInvalidReleaseValue(key, value, target) {
 	return false;
 }
 /**
+* Check release-specific reserved aliases without broadening case sensitivity.
+*
+* @param prefix - Registry alias as declared
+* @param target - Confirmed target version
+*
+* @returns Whether the alias shadows a protocol introduced by these releases
+*/
+function isReservedRegistryPrefix(prefix, target) {
+	return prefix.toLowerCase() === "pkg" && supportsMinimumVersion(target.version, PNPM_V12_5_MINIMUM_VERSION) || prefix === "tool" && supportsMinimumVersion(target.version, PNPM_V12_12_1_MINIMUM_VERSION);
+}
+/**
 * Check value shapes that changed within a pnpm major release.
 *
 * Reject the whole setting so cleanup cannot discard unsupported nested values.
@@ -1345,7 +1584,7 @@ function hasInvalidReleaseValue(key, value, target) {
 * @returns Whether the value uses a shape unsupported by the selected release
 */
 function hasIncompatibleSettingValue(key, value, target) {
-	if (hasInvalidPermissionSettings(key, value) || hasInvalidReleaseValue(key, value, target) || hasInvalidV11PatchValue(key, value, target) || hasIncompatibleV12SettingValue(key, value, target)) return true;
+	if (hasInvalidPermissionSettings(key, value) || hasInvalidRemoteCacheValue(key, value) || hasInvalidReleaseValue(key, value, target) || hasInvalidV11PatchValue(key, value, target) || hasIncompatibleV12SettingValue(key, value, target)) return true;
 	if (hasInvalidScalarValue(key, value, target)) return true;
 	const supportsV12_5 = supportsMinimumVersion(target.version, PNPM_V12_5_MINIMUM_VERSION);
 	if (key === "supportedArchitectures" && isArray(value)) return !supportsV12_5;
@@ -1363,19 +1602,42 @@ function hasIncompatibleSettingValue(key, value, target) {
 			"constraints"
 		].some((field) => Object.hasOwn(value, field));
 	}
-	if (key === "namedRegistries" && supportsV12_5) return Object.keys(value).some((prefix) => prefix.toLowerCase() === "pkg");
+	if (key === "namedRegistries") return Object.keys(value).some((prefix) => isReservedRegistryPrefix(prefix, target));
 	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 && isString(prefix) && prefix.toLowerCase() === "pkg";
+		return isString(prefix) && isReservedRegistryPrefix(prefix, target);
 	});
 	return false;
 }
 //#endregion
 //#region src/features/settings/schema.ts
 /**
+* Detect legacy runtime fields without a destination in pnpm v11 and newer.
+*
+* @param key - Canonical setting name
+* @param value - Untrusted legacy runtime declaration
+* @param compatibility - Target major controlling runtime conversion
+*
+* @returns Whether converting the runtime would discard sibling fields
+*/
+function hasUnmigratableRuntimeFields(key, value, compatibility) {
+	return Boolean(key === "executionEnv" && compatibility !== "v10" && value && typeof value === "object" && Object.keys(value).some((field) => field !== "nodeVersion"));
+}
+/**
+* Check task declarations against the fields consumed by the target release.
+*
+* @param value - Untrusted task declarations
+* @param taskSettings - Supported task field names
+*
+* @returns Whether any declared task field is unsupported
+*/
+function hasUnsupportedTaskFields(value, taskSettings) {
+	return Boolean(value && typeof value === "object" && Object.values(value).some((task) => task && typeof task === "object" && Object.keys(task).some((field) => !taskSettings.has(field))));
+}
+/**
 * Create an empty collection of schema selection issues.
 *
 * @returns Empty issue lists for every supported issue category
@@ -1480,8 +1742,8 @@ 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) && isString(value) && 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 (hasInvalidRegistryLocations(key, value) || hasUnmigratableRuntimeFields(key, value, compatibility) || hasIncompatibleSettingValue(key, value, target)) return "incompatible";
+	if (key === "tasks" && hasUnsupportedTaskFields(value, taskSettings)) return "incompatible";
 	if (!workspaceSettings.has(key)) return isSettingFromAnotherVersion(key, compatibility) ? "incompatible" : "unknown";
 	if (allowedFields && !allowedFields.has(key)) return "unsupported";
 }
@@ -1890,8 +2152,17 @@ function getNpmrcLineKey(line) {
 	const trimmed = line.trim();
 	if (!trimmed || trimmed.startsWith(";") || trimmed.startsWith("#")) return;
 	const index = trimmed.indexOf("=");
-	if (index <= 0) return;
-	return normalizeNpmrcKey(trimmed.slice(0, index));
+	if (index === 0) return;
+	let key = (index < 0 ? trimmed : trimmed.slice(0, index)).trim();
+	if (key.startsWith("\"") && key.endsWith("\"") || key.startsWith("'") && key.endsWith("'")) {
+		if (key.startsWith("'")) key = key.slice(1, -1);
+		try {
+			const parsed = JSON.parse(key);
+			if (!isString(parsed)) return;
+			key = parsed;
+		} catch {}
+	} else key = key.replace(/\\(?<escaped>[\\;#])|[;#].*$/gu, (_, escaped) => escaped ?? "");
+	return normalizeNpmrcKey(key);
 }
 /**
 * Check whether a `.npmrc` key is auth/registry-related and should stay in
@@ -1918,7 +2189,7 @@ function isNpmrcAuthOrRegistryKey(key) {
 * @param compatibility - Concrete pnpm compatibility target
 * @param migratedKeys - Original `.npmrc` keys that were migrated
 *
-* @returns A promise that resolves when the file has been pruned
+* @returns Whether the file was changed or removed
 *
 * @throws {Error} When file read/write operations fail
 *
@@ -1931,18 +2202,25 @@ async function pruneNpmrc(path, compatibility, migratedKeys) {
 	const migratedKeySet = new Set(migratedKeys.map(normalizeNpmrcKey));
 	const content = await fsReadFile(path);
 	let inSection = false;
-	const updatedContent = content.split(/\r\n|[\r\n]/u).filter((line) => {
+	let removed = false;
+	const lines = content.split(/\r\n|[\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);
-	}).join("\n").trimEnd();
+		if (migratedKeySet.has(key)) {
+			removed = true;
+			return false;
+		}
+		return true;
+	});
+	if (!removed) return false;
+	const updatedContent = lines.join("\n").trimEnd();
 	if (compatibility !== "v10" && !updatedContent.trim()) {
 		await fsRemoveFile(path);
-		return;
+		return true;
 	}
-	await fsWriteFile(path, updatedContent);
+	return fsWriteFileIfChanged(path, updatedContent);
 }
 /**
 * Read `.npmrc` and return settings that should be migrated into workspace config.
@@ -2481,10 +2759,10 @@ async function persistMigration(options) {
 	if (!cleanNpmrc) return result;
 	const pruneTasks = projectNpmrcs.projects.flatMap((project) => {
 		const appliedKeys = selectAppliedProjectKeys(project, finalSettings);
-		return appliedKeys.length ? [pruneNpmrc(project.npmrcPath, compatibility, appliedKeys).then(() => project.npmrcPath)] : [];
+		return appliedKeys.length ? [pruneNpmrc(project.npmrcPath, compatibility, appliedKeys).then((changed) => changed ? project.npmrcPath : void 0)] : [];
 	});
-	if (npmrcExists && appliedNpmrcKeys.length) pruneTasks.push(pruneNpmrc(npmrcPath, compatibility, appliedNpmrcKeys).then(() => npmrcPath));
-	const cleanedNpmrcPaths = await Promise.all(pruneTasks);
+	if (npmrcExists && appliedNpmrcKeys.length) pruneTasks.push(pruneNpmrc(npmrcPath, compatibility, appliedNpmrcKeys).then((changed) => changed ? npmrcPath : void 0));
+	const cleanedNpmrcPaths = (await Promise.all(pruneTasks)).filter(isString);
 	result.changedFiles.push(...cleanedNpmrcPaths);
 	result.sourceSettingsCleaned ||= cleanedNpmrcPaths.length > 0;
 	return result;
@@ -2580,9 +2858,9 @@ function normalizeSideEffectsCache(settings) {
 * @returns Nothing; the URL's declaration is created or updated in place
 */
 function addRegistryScope(declarations, url, scope) {
-	declarations[url] ??= {};
-	const declaration = declarations[url];
+	const declaration = declarations.get(url) ?? {};
 	declaration.scopes = unique([...declaration.scopes ?? [], scope]);
+	declarations.set(url, declaration);
 }
 /**
 * Find source URLs with multiple active aliases across the merged settings.
@@ -2611,9 +2889,9 @@ function findRegistryAliasConflicts(prefixesByUrl, namedRegistries, canonicalPre
 function normalizeNamedRegistries(settings, warnings, canonicalSettings) {
 	const { namedRegistries } = settings;
 	if (!namedRegistries) return;
-	const declarations = {};
+	const declarations = /* @__PURE__ */ new Map();
 	for (const [key, value] of Object.entries(settings.registries ?? {})) if (isString(value)) addRegistryScope(declarations, value, key === "default" ? "@" : key);
-	else declarations[key] = { ...value };
+	else declarations.set(key, { ...value });
 	const canonicalPrefixes = new Set(Object.values(canonicalSettings.registries ?? {}).flatMap((value) => !isString(value) && isString(value?.prefix) ? [value.prefix] : []));
 	const prefixesByUrl = /* @__PURE__ */ new Map();
 	const registryAliases = Object.entries(namedRegistries).filter(([prefix]) => !canonicalPrefixes.has(prefix));
@@ -2628,17 +2906,17 @@ function normalizeNamedRegistries(settings, warnings, canonicalSettings) {
 		return;
 	}
 	for (const [url, [prefix]] of prefixesByUrl) {
-		declarations[url] ??= {};
-		const declaration = declarations[url];
-		const canonicalDeclaration = canonicalSettings.registries?.[url];
+		const declaration = declarations.get(url) ?? {};
+		const canonicalDeclaration = canonicalSettings.registries && Object.hasOwn(canonicalSettings.registries, url) ? canonicalSettings.registries[url] : void 0;
 		const declaredPrefix = (isString(canonicalDeclaration) ? void 0 : canonicalDeclaration?.prefix) ?? declaration.prefix;
 		if (isString(declaredPrefix) && declaredPrefix !== prefix) {
 			warnings.push(`namedRegistries was kept because ${url} already declares prefix ${declaredPrefix}.`);
 			return;
 		}
 		declaration.prefix = prefix;
+		declarations.set(url, declaration);
 	}
-	settings.registries = declarations;
+	settings.registries = Object.fromEntries(declarations);
 	Reflect.deleteProperty(settings, "namedRegistries");
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pnpm-settings-migrator",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Move pnpm settings from `pnpm` field in `package.json` and `.npmrc` file to `pnpm-workspace.yaml`",
   "keywords": [
     "migrator",
@@ -44,7 +44,7 @@
   "dependencies": {
     "@ntnyq/utils": "^0.23.0",
     "@pnpm/types": "^1102.1.1",
-    "cac": "^7.0.0",
+    "cac": "^7.1.0",
     "camelcase-keys": "^10.0.3",
     "consola": "^3.4.2",
     "defu": "^6.1.7",
@@ -56,17 +56,17 @@
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
     "bumpp": "^12.3.0",
     "husky": "^9.1.7",
     "nano-staged": "^1.0.2",
     "npm-run-all2": "^9.0.3",
-    "oxfmt": "^0.72.0",
-    "oxlint": "^1.87.0",
-    "tsdown": "^0.23.0",
+    "oxfmt": "^0.73.0",
+    "oxlint": "^1.88.0",
+    "tsdown": "^0.23.1",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.4"
   },
   "nano-staged": {
     "*.{js,ts,mjs,tsx}": "oxlint --fix",