pnpm-settings-migrator 0.16.0 → 0.17.0

package/README.md

@@ -232,11 +232,37 @@ 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.
+
 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 +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
@@ -297,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.
@@ -311,17 +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.11.2, 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, 12.9.1, 12.10.0, 12.10.1, 12.11.0, and 12.11.1.
+  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-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
+  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.10.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.
 

package/dist/cli.mjs

@@ -627,6 +627,22 @@ 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
+];
+/**
 * Workspace settings first consumed by pnpm v12 in 12.11.0.
 */
 const PNPM_V12_11_WORKSPACE_SETTINGS = [
@@ -652,6 +668,11 @@ 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,
@@ -733,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.
 */
@@ -770,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.
 */
@@ -1119,6 +1213,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.
@@ -1263,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.
@@ -1311,7 +1447,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 +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.
@@ -1352,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 (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 +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
@@ -1487,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";
 }
@@ -1897,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
@@ -1925,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
 *
@@ -1938,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.
@@ -2488,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;
@@ -2587,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.
@@ -2618,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));
@@ -2635,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");
 }
 /**
@@ -3207,7 +3393,7 @@ const bold = getColor("bold");
 //#endregion
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.16.0";
+var version = "0.17.0";
 //#endregion
 //#region src/cli/options.ts
 /**

package/dist/index.d.mts

@@ -259,6 +259,15 @@ interface PnpmSkillsSettings {
  * 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+).
    */
@@ -353,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
 /**
@@ -730,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, 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, PnpmPackagePermissions, PnpmPythonSettings, PnpmRegistryDeclaration, PnpmRemoteCacheSettings, PnpmSettingsDeprecated, PnpmSettingsV11, PnpmSettingsV12, PnpmSkillsSettings, PnpmTaskSettings, PnpmWorkspace, PnpmWorkspaceLegacy, ResolvedOptions, RuntimeEngine, SettingsChange };

package/dist/index.mjs

@@ -625,6 +625,22 @@ 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
+];
+/**
 * Workspace settings first consumed by pnpm v12 in 12.11.0.
 */
 const PNPM_V12_11_WORKSPACE_SETTINGS = [
@@ -650,6 +666,11 @@ 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,
@@ -731,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.
 */
@@ -768,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.
 */
@@ -1112,6 +1206,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.
@@ -1256,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.
@@ -1304,7 +1440,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 +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.
@@ -1345,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 (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 +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
@@ -1480,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";
 }
@@ -1890,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
@@ -1918,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
 *
@@ -1931,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.
@@ -2481,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;
@@ -2580,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.
@@ -2611,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));
@@ -2628,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.16.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",