pnpm-settings-migrator 0.15.0 → 0.17.0

package/README.md

@@ -217,6 +217,52 @@ the lockfile. Existing linker strings and boolean `lockfile` values still work.
 it from workspace configuration. Unsupported or invalid nested settings stay
 intact in their source; the migrator does not add pnpm's defaults.
 
+For pnpm 12.11.0 and later stable v12 releases, `permissions` maps dependency
+names or package IDs to `build` and `skills` decisions. Boolean `build`
+decisions override matching `allowBuilds` entries; strings are undecided prompts
+and null leaves a capability unset. Both settings are preserved for pnpm to
+apply its precedence. Unknown capabilities or invalid nested values keep the
+entire source object intact.
+
+`skills.dirs` accepts an array of workspace-relative agent skill directories;
+an empty array disables linking. Workspace `provenance` also requires 12.11.0
+for v12 targets and accepts boolean or null values. Its v11 support is unchanged.
+For example, targeting 12.11.0 migrates
+`{ "pnpm": { "permissions": { "example": { "build": false, "skills": true } }, "skills": { "dirs": [".agents/skills"] } } }`
+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.
+
+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>
@@ -253,6 +299,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
@@ -277,10 +326,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.
@@ -291,16 +346,17 @@ 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.10.0, including 11.28.0,
+- Compatibility checks cover pnpm 11.28.5 and 12.12.1, 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, and 12.9.1. Earlier regressions remain at 11.25.0,
+  12.9.0, 12.9.1, 12.10.0, 12.10.1, 12.11.0, 12.11.1, 12.11.2, and 12.12.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-06](docs/research/pnpm-settings-bump-2026-10-06.md),
-  npm `latest` is 12.9.1; the highest confirmed stable release is 12.10.0 on
+  As [audited on 2026-10-13](docs/research/pnpm-settings-bump-2026-10-13.md),
+  npm `latest` is 12.11.2; the highest confirmed stable release is 12.12.1 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.9.1. These checks verify the documented
+  11.28.2. The project is pinned to 12.11.2. 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.
 
@@ -373,7 +429,7 @@ Strategy to handle conflicts when merging settings with existing `pnpm-workspace
 `packageConfigs` matcher arrays preserve order and repeated entries because the
 last matching entry wins. With `merge`, incoming matchers follow existing ones;
 an overlapping end/start sequence is reused to keep repeated migrations stable.
-`filter` and `filterProd` use the same ordered merging: a repeated inclusion can
+For v11 targets, `filter` and `filterProd` use the same ordered merging: a repeated inclusion can
 restore projects removed by an earlier exclusion. Cleanup verifies the combined
 selector sequence. If package cleanup is disabled, later `.npmrc` selectors are
 retained when needed to keep repeated migrations stable.

package/dist/cli.mjs

@@ -502,7 +502,12 @@ const PNPM_V11_WORKSPACE_SETTINGS_FIELDS = unique([...PNPM_V10_NPMRC_SETTINGS_FI
 /**
 * Settings that are supported by v11 but not by pnpm v12.
 */
-const PNPM_V11_ONLY_WORKSPACE_SETTINGS = ["confirmModulesPurge", "packageConfigs"];
+const PNPM_V11_ONLY_WORKSPACE_SETTINGS = [
+	"confirmModulesPurge",
+	"filter",
+	"filterProd",
+	"packageConfigs"
+];
 /**
 * Fields pnpm v11 accepts inside a `packageConfigs` entry.
 */
@@ -614,6 +619,38 @@ const PNPM_V12_10_MINIMUM_VERSION = [
 	0
 ];
 /**
+* Release introducing package permissions, agent skills, and workspace provenance.
+*/
+const PNPM_V12_11_MINIMUM_VERSION = [
+	12,
+	11,
+	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
+];
+/**
+* Workspace settings first consumed by pnpm v12 in 12.11.0.
+*/
+const PNPM_V12_11_WORKSPACE_SETTINGS = [
+	"permissions",
+	"skills",
+	"provenance"
+];
+/**
 * Workspace settings first consumed by pnpm v12 in 12.10.0.
 */
 const PNPM_V12_10_WORKSPACE_SETTINGS = ["failIfNoMatch"];
@@ -631,6 +668,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_12_MINIMUM_VERSION,
+		workspaceFields: ["addMissingPeerTypes", "remoteCache"],
+		taskFields: []
+	},
+	{
+		minimumVersion: PNPM_V12_11_MINIMUM_VERSION,
+		workspaceFields: PNPM_V12_11_WORKSPACE_SETTINGS,
+		taskFields: []
+	},
 	{
 		minimumVersion: PNPM_V11_28_MINIMUM_VERSION,
 		workspaceFields: ["forceIgnoresPlatform"],
@@ -707,9 +754,82 @@ const PNPM_V12_ONLY_WORKSPACE_SETTINGS = [
 	"globalShims"
 ];
 /**
+* Legacy fields absent from pnpm v12's workspace reader through 12.12.1.
+* Removed aliases with explicit migration replacements are kept separately.
+*
+* @see https://github.com/pnpm/pnpm/blob/v12.12.1/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.
 */
@@ -725,7 +845,7 @@ const PNPM_V12_REGISTRY_DECLARATION_FIELDS = [
 /**
 * 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_6_WORKSPACE_SETTINGS.includes(field) && !PNPM_V12_7_WORKSPACE_SETTINGS.includes(field) && !PNPM_V12_10_WORKSPACE_SETTINGS.includes(field)), ...PNPM_V12_ONLY_WORKSPACE_SETTINGS];
+const PNPM_V12_WORKSPACE_SETTINGS_FIELDS = [...PNPM_V11_WORKSPACE_SETTINGS_FIELDS.filter((field) => !v11OnlyWorkspaceSettings.has(field) && !PNPM_V12_6_WORKSPACE_SETTINGS.includes(field) && !PNPM_V12_7_WORKSPACE_SETTINGS.includes(field) && !PNPM_V12_10_WORKSPACE_SETTINGS.includes(field) && !PNPM_V12_11_WORKSPACE_SETTINGS.includes(field)), ...PNPM_V12_ONLY_WORKSPACE_SETTINGS];
 //#endregion
 //#region src/constants/settings-schema.ts
 /**
@@ -744,7 +864,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.
 */
@@ -1093,6 +1213,63 @@ 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.
+*
+* @param value - Untrusted per-package permission entry
+*
+* @returns Whether pnpm cannot consume every capability in the entry
+*/
+function hasInvalidPackagePermissions(value) {
+	if (value === null) return false;
+	if (!value || typeof value !== "object" || isArray(value)) return true;
+	return Object.entries(value).some(([capability, decision]) => !["build", "skills"].includes(capability) || decision !== null && !isBoolean(decision) && !isString(decision));
+}
+/**
+* Validate permissions and skill directories introduced in pnpm 12.11.
+* Preserve an entire object when a nested value is invalid or ignored upstream.
+*
+* @param key - Canonical workspace setting name
+* @param value - Untrusted source or existing workspace value
+*
+* @returns Whether the setting contains unsupported nested values
+*/
+function hasInvalidPermissionSettings(key, value) {
+	if (!["permissions", "skills"].includes(key) || value === null) return false;
+	if (!value || typeof value !== "object" || isArray(value)) return true;
+	if (key === "permissions") return Object.values(value).some(hasInvalidPackagePermissions);
+	if (Object.keys(value).some((field) => field !== "dirs")) return true;
+	const dirs = Reflect.get(value, "dirs");
+	return Object.hasOwn(value, "dirs") && dirs !== null && (!isArray(dirs) || !dirs.every(isString));
+}
+//#endregion
 //#region src/features/settings/pnpm-v12-values.ts
 /**
 * Check a loaded linker object without discarding unsupported options.
@@ -1206,6 +1383,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.
@@ -1254,6 +1447,7 @@ function hasInvalidScalarValue(key, value, target) {
 			"ndjson",
 			"silent"
 		].includes(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("${") && ![
@@ -1283,6 +1477,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.
@@ -1294,7 +1499,7 @@ function hasInvalidReleaseValue(key, value, target) {
 * @returns Whether the value uses a shape unsupported by the selected release
 */
 function hasIncompatibleSettingValue(key, value, target) {
-	if (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;
@@ -1312,19 +1517,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
@@ -1429,8 +1657,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";
 }
@@ -1839,8 +2067,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
@@ -1867,7 +2104,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
 *
@@ -1880,18 +2117,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.
@@ -2321,6 +2565,7 @@ function resolveReplacementSettingKey(sourceKey, targetKey, npmrc) {
 * @returns Original source keys that can be pruned
 */
 function selectAppliedRootKeys({ appliedOrderedFilterKeys, finalSettings, normalizedSettings, keys, npmrc = false, runtimeApplied, runtimeVersion, sourceSettings }) {
+	const hasUnappliedSkillsDisable = normalizedSettings.skills?.dirs?.length === 0 && finalSettings.skills?.dirs?.length !== 0;
 	return keys.filter((sourceKey) => {
 		const targetKey = npmrc ? Object.keys(camelcaseKeys({ [sourceKey]: true }))[0] ?? sourceKey : sourceKey;
 		if (!Object.hasOwn(normalizedSettings, targetKey)) {
@@ -2343,6 +2588,7 @@ function selectAppliedRootKeys({ appliedOrderedFilterKeys, finalSettings, normal
 			const expected = Reflect.get(normalizedSettings, targetKey);
 			return appliedOrderedFilterKeys.has(targetKey) && containsOrderedFilterValue(actual, expected);
 		}
+		if (targetKey === "skills" && hasUnappliedSkillsDisable) return false;
 		return containsMigratedValue(Reflect.get(finalSettings, targetKey), Reflect.get(normalizedSettings, targetKey));
 	});
 }
@@ -2428,10 +2674,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;
@@ -2527,9 +2773,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.
@@ -2558,9 +2804,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));
@@ -2575,17 +2821,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");
 }
 /**
@@ -3147,7 +3393,7 @@ const bold = getColor("bold");
 //#endregion
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.15.0";
+var version = "0.17.0";
 //#endregion
 //#region src/cli/options.ts
 /**

package/dist/index.d.mts

@@ -230,10 +230,52 @@ interface PnpmLockfileSettings {
    */
   includeResolutionSettings?: boolean | null;
 }
+/**
+ * Dependency capabilities introduced in pnpm 12.11.0. Strings are undecided
+ * prompts; null leaves a capability unset.
+ */
+interface PnpmPackagePermissions {
+  /**
+   * Lifecycle script decision, taking precedence over the matching allowBuilds
+   * entry when boolean. An undecided string leaves that entry effective.
+   */
+  build?: boolean | string | null;
+  /**
+   * Whether pnpm may link the agent skills shipped by the dependency.
+   */
+  skills?: boolean | string | null;
+}
+/**
+ * Agent skill linking configuration introduced in pnpm 12.11.0.
+ */
+interface PnpmSkillsSettings {
+  /**
+   * Workspace-relative agent skill directories, replacing detected directories.
+   * An empty list disables linking; null leaves directory detection enabled.
+   */
+  dirs?: string[] | null;
+}
 /**
  * Settings supported by pnpm v12, subject to the resolved version capabilities.
  */
 interface PnpmSettingsV12 {
+  /**
+   * 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+).
+   */
+  permissions?: Record<string, PnpmPackagePermissions | null> | null;
+  /**
+   * Agent skill linking options (pnpm 12.11+).
+   */
+  skills?: PnpmSkillsSettings | null;
   /**
    * Dependency linking mode. Loaded linking and its options require pnpm 12.10+.
    */
@@ -320,6 +362,16 @@ interface PnpmSettingsV12 {
    */
   tasks?: Record<string, PnpmTaskSettings>;
 }
+/**
+ * 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
 /**
@@ -440,6 +492,11 @@ interface PnpmSettingsDeprecated {
  * Settings introduced in pnpm v11.
  */
 interface PnpmSettingsV11 {
+  /**
+   * Publish provenance preference. Consumed from workspace configuration by
+   * pnpm v11 and pnpm v12 starting with 12.11. Null leaves it unset.
+   */
+  provenance?: boolean | null;
   /**
    * Fail when no workspace project matches a filter. Accepted by pnpm v11 and
    * consumed from workspace configuration by pnpm v12 starting with 12.10.
@@ -484,7 +541,7 @@ interface PnpmSettingsV11 {
 /**
  * `pnpm-workspace.yaml` types.
  */
-type PnpmWorkspace = Omit<PnpmSettings, 'lockfile' | 'nodeLinker' | 'registries' | 'supportedArchitectures' | 'tasks'> & PnpmSettingsDeprecated & PnpmSettingsV11 & PnpmSettingsV12 & PnpmWorkspaceLegacy;
+type PnpmWorkspace = Omit<PnpmSettings, 'lockfile' | 'nodeLinker' | 'provenance' | 'registries' | 'supportedArchitectures' | 'tasks'> & PnpmSettingsDeprecated & PnpmSettingsV11 & PnpmSettingsV12 & PnpmWorkspaceLegacy;
 //#endregion
 //#region src/types/package-json.d.ts
 /**
@@ -692,4 +749,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, PnpmPythonSettings, PnpmRegistryDeclaration, PnpmSettingsDeprecated, PnpmSettingsV11, PnpmSettingsV12, PnpmTaskSettings, PnpmWorkspace, PnpmWorkspaceLegacy, ResolvedOptions, RuntimeEngine, SettingsChange };
+export type { CompatibilityTarget, GlobalShimPolicy, MergeStrategy, MigrationResult, NpmRC, Options, PackageJson, PackageManagerEngine, PnpmCargoSettings, PnpmLoadedNodeLinkerSettings, PnpmLockfileSettings, PnpmPackagePermissions, PnpmPythonSettings, PnpmRegistryDeclaration, PnpmRemoteCacheSettings, PnpmSettingsDeprecated, PnpmSettingsV11, PnpmSettingsV12, PnpmSkillsSettings, PnpmTaskSettings, PnpmWorkspace, PnpmWorkspaceLegacy, ResolvedOptions, RuntimeEngine, SettingsChange };

package/dist/index.mjs

@@ -500,7 +500,12 @@ const PNPM_V11_WORKSPACE_SETTINGS_FIELDS = unique([...PNPM_V10_NPMRC_SETTINGS_FI
 /**
 * Settings that are supported by v11 but not by pnpm v12.
 */
-const PNPM_V11_ONLY_WORKSPACE_SETTINGS = ["confirmModulesPurge", "packageConfigs"];
+const PNPM_V11_ONLY_WORKSPACE_SETTINGS = [
+	"confirmModulesPurge",
+	"filter",
+	"filterProd",
+	"packageConfigs"
+];
 /**
 * Fields pnpm v11 accepts inside a `packageConfigs` entry.
 */
@@ -612,6 +617,38 @@ const PNPM_V12_10_MINIMUM_VERSION = [
 	0
 ];
 /**
+* Release introducing package permissions, agent skills, and workspace provenance.
+*/
+const PNPM_V12_11_MINIMUM_VERSION = [
+	12,
+	11,
+	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
+];
+/**
+* Workspace settings first consumed by pnpm v12 in 12.11.0.
+*/
+const PNPM_V12_11_WORKSPACE_SETTINGS = [
+	"permissions",
+	"skills",
+	"provenance"
+];
+/**
 * Workspace settings first consumed by pnpm v12 in 12.10.0.
 */
 const PNPM_V12_10_WORKSPACE_SETTINGS = ["failIfNoMatch"];
@@ -629,6 +666,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_12_MINIMUM_VERSION,
+		workspaceFields: ["addMissingPeerTypes", "remoteCache"],
+		taskFields: []
+	},
+	{
+		minimumVersion: PNPM_V12_11_MINIMUM_VERSION,
+		workspaceFields: PNPM_V12_11_WORKSPACE_SETTINGS,
+		taskFields: []
+	},
 	{
 		minimumVersion: PNPM_V11_28_MINIMUM_VERSION,
 		workspaceFields: ["forceIgnoresPlatform"],
@@ -705,9 +752,82 @@ const PNPM_V12_ONLY_WORKSPACE_SETTINGS = [
 	"globalShims"
 ];
 /**
+* Legacy fields absent from pnpm v12's workspace reader through 12.12.1.
+* Removed aliases with explicit migration replacements are kept separately.
+*
+* @see https://github.com/pnpm/pnpm/blob/v12.12.1/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.
 */
@@ -723,7 +843,7 @@ const PNPM_V12_REGISTRY_DECLARATION_FIELDS = [
 /**
 * 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_6_WORKSPACE_SETTINGS.includes(field) && !PNPM_V12_7_WORKSPACE_SETTINGS.includes(field) && !PNPM_V12_10_WORKSPACE_SETTINGS.includes(field)), ...PNPM_V12_ONLY_WORKSPACE_SETTINGS];
+const PNPM_V12_WORKSPACE_SETTINGS_FIELDS = [...PNPM_V11_WORKSPACE_SETTINGS_FIELDS.filter((field) => !v11OnlyWorkspaceSettings.has(field) && !PNPM_V12_6_WORKSPACE_SETTINGS.includes(field) && !PNPM_V12_7_WORKSPACE_SETTINGS.includes(field) && !PNPM_V12_10_WORKSPACE_SETTINGS.includes(field) && !PNPM_V12_11_WORKSPACE_SETTINGS.includes(field)), ...PNPM_V12_ONLY_WORKSPACE_SETTINGS];
 //#endregion
 //#region src/constants/settings-schema.ts
 /**
@@ -742,7 +862,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.
 */
@@ -1086,6 +1206,63 @@ 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.
+*
+* @param value - Untrusted per-package permission entry
+*
+* @returns Whether pnpm cannot consume every capability in the entry
+*/
+function hasInvalidPackagePermissions(value) {
+	if (value === null) return false;
+	if (!value || typeof value !== "object" || isArray(value)) return true;
+	return Object.entries(value).some(([capability, decision]) => !["build", "skills"].includes(capability) || decision !== null && !isBoolean(decision) && !isString(decision));
+}
+/**
+* Validate permissions and skill directories introduced in pnpm 12.11.
+* Preserve an entire object when a nested value is invalid or ignored upstream.
+*
+* @param key - Canonical workspace setting name
+* @param value - Untrusted source or existing workspace value
+*
+* @returns Whether the setting contains unsupported nested values
+*/
+function hasInvalidPermissionSettings(key, value) {
+	if (!["permissions", "skills"].includes(key) || value === null) return false;
+	if (!value || typeof value !== "object" || isArray(value)) return true;
+	if (key === "permissions") return Object.values(value).some(hasInvalidPackagePermissions);
+	if (Object.keys(value).some((field) => field !== "dirs")) return true;
+	const dirs = Reflect.get(value, "dirs");
+	return Object.hasOwn(value, "dirs") && dirs !== null && (!isArray(dirs) || !dirs.every(isString));
+}
+//#endregion
 //#region src/features/settings/pnpm-v12-values.ts
 /**
 * Check a loaded linker object without discarding unsupported options.
@@ -1199,6 +1376,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.
@@ -1247,6 +1440,7 @@ function hasInvalidScalarValue(key, value, target) {
 			"ndjson",
 			"silent"
 		].includes(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("${") && ![
@@ -1276,6 +1470,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.
@@ -1287,7 +1492,7 @@ function hasInvalidReleaseValue(key, value, target) {
 * @returns Whether the value uses a shape unsupported by the selected release
 */
 function hasIncompatibleSettingValue(key, value, target) {
-	if (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;
@@ -1305,19 +1510,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
@@ -1422,8 +1650,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";
 }
@@ -1832,8 +2060,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
@@ -1860,7 +2097,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
 *
@@ -1873,18 +2110,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.
@@ -2314,6 +2558,7 @@ function resolveReplacementSettingKey(sourceKey, targetKey, npmrc) {
 * @returns Original source keys that can be pruned
 */
 function selectAppliedRootKeys({ appliedOrderedFilterKeys, finalSettings, normalizedSettings, keys, npmrc = false, runtimeApplied, runtimeVersion, sourceSettings }) {
+	const hasUnappliedSkillsDisable = normalizedSettings.skills?.dirs?.length === 0 && finalSettings.skills?.dirs?.length !== 0;
 	return keys.filter((sourceKey) => {
 		const targetKey = npmrc ? Object.keys(camelcaseKeys({ [sourceKey]: true }))[0] ?? sourceKey : sourceKey;
 		if (!Object.hasOwn(normalizedSettings, targetKey)) {
@@ -2336,6 +2581,7 @@ function selectAppliedRootKeys({ appliedOrderedFilterKeys, finalSettings, normal
 			const expected = Reflect.get(normalizedSettings, targetKey);
 			return appliedOrderedFilterKeys.has(targetKey) && containsOrderedFilterValue(actual, expected);
 		}
+		if (targetKey === "skills" && hasUnappliedSkillsDisable) return false;
 		return containsMigratedValue(Reflect.get(finalSettings, targetKey), Reflect.get(normalizedSettings, targetKey));
 	});
 }
@@ -2421,10 +2667,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;
@@ -2520,9 +2766,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.
@@ -2551,9 +2797,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));
@@ -2568,17 +2814,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.15.0",
+  "version": "0.17.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",