pnpm-settings-migrator 0.15.0 → 0.16.0

package/README.md

@@ -217,6 +217,26 @@ 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.
+
+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.
+
 </details>
 
 <details>
@@ -291,14 +311,15 @@ 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.11.2, including 11.28.0,
   11.28.1, 11.28.2, 11.28.3, 11.28.4, 12.7.0, 12.8.0, 12.8.1, 12.8.2,
-  12.9.0, 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, and 12.11.1.
+  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-10](docs/research/pnpm-settings-bump-2026-10-10.md),
+  npm `latest` is 12.10.1; the highest confirmed stable release is 12.11.2 on
   `next-12`. The v11 target is 11.28.5 on `next-11`, while `latest-11` is
-  11.28.2. The project is pinned to 12.9.1. These checks verify the documented
+  11.28.2. The project is pinned to 12.10.1. 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.
   The removed `pnpm install --resolution-only` CLI flag is outside this settings
@@ -373,7 +394,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,22 @@ 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
+];
+/**
+* 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 +652,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_11_MINIMUM_VERSION,
+		workspaceFields: PNPM_V12_11_WORKSPACE_SETTINGS,
+		taskFields: []
+	},
 	{
 		minimumVersion: PNPM_V11_28_MINIMUM_VERSION,
 		workspaceFields: ["forceIgnoresPlatform"],
@@ -725,7 +751,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
 /**
@@ -1093,6 +1119,37 @@ function formatSettingsIssues(options) {
 	return warnings;
 }
 //#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.
@@ -1254,6 +1311,7 @@ function hasInvalidScalarValue(key, value, target) {
 			"ndjson",
 			"silent"
 		].includes(value);
+		if (key === "provenance") 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("${") && ![
@@ -1294,7 +1352,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) || 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;
@@ -2321,6 +2379,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 +2402,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));
 	});
 }
@@ -3147,7 +3207,7 @@ const bold = getColor("bold");
 //#endregion
 //#region package.json
 var name = "pnpm-settings-migrator";
-var version = "0.15.0";
+var version = "0.16.0";
 //#endregion
 //#region src/cli/options.ts
 /**

package/dist/index.d.mts

@@ -230,10 +230,43 @@ 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 {
+  /**
+   * 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+.
    */
@@ -440,6 +473,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 +522,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 +730,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, 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,22 @@ 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
+];
+/**
+* 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 +650,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_11_MINIMUM_VERSION,
+		workspaceFields: PNPM_V12_11_WORKSPACE_SETTINGS,
+		taskFields: []
+	},
 	{
 		minimumVersion: PNPM_V11_28_MINIMUM_VERSION,
 		workspaceFields: ["forceIgnoresPlatform"],
@@ -723,7 +749,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
 /**
@@ -1086,6 +1112,37 @@ function formatSettingsIssues(options) {
 	return warnings;
 }
 //#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.
@@ -1247,6 +1304,7 @@ function hasInvalidScalarValue(key, value, target) {
 			"ndjson",
 			"silent"
 		].includes(value);
+		if (key === "provenance") 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("${") && ![
@@ -1287,7 +1345,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) || 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;
@@ -2314,6 +2372,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 +2395,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));
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pnpm-settings-migrator",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Move pnpm settings from `pnpm` field in `package.json` and `.npmrc` file to `pnpm-workspace.yaml`",
   "keywords": [
     "migrator",