Add 'rush-pnpm up' support for catalogs

common/changes/@microsoft/rush/main_2026-01-31-22-28.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Add catalog support to `rush-pnpm update`.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/reviews/api/rush-lib.api.md

@@ -1183,7 +1183,8 @@ export class PnpmOptionsConfiguration extends PackageManagerOptionsConfiguration
     readonly resolutionMode: PnpmResolutionMode | undefined;
     readonly strictPeerDependencies: boolean;
     readonly unsupportedPackageJsonSettings: unknown | undefined;
-    updateGlobalOnlyBuiltDependencies(onlyBuiltDependencies: string[] | undefined): void;
+    updateGlobalCatalogsAsync(catalogs: Record<string, Record<string, string>> | undefined): Promise<void>;
+    updateGlobalOnlyBuiltDependenciesAsync(onlyBuiltDependencies: string[] | undefined): Promise<void>;
     updateGlobalPatchedDependencies(patchedDependencies: Record<string, string> | undefined): void;
     readonly useWorkspaces: boolean;
 }

libraries/rush-lib/config/heft.json

@@ -30,7 +30,7 @@
                 {
                   "sourcePath": "src/cli/test",
                   "destinationFolders": ["lib-intermediate-commonjs/cli/test"],
-                  "fileExtensions": [".js"]
+                  "fileExtensions": [".js", ".yaml"]
                 },
                 {
                   "sourcePath": "src/logic/pnpm/test",

libraries/rush-lib/src/cli/RushPnpmCommandLineParser.ts

@@ -32,6 +32,7 @@ import type { IInstallManagerOptions } from '../logic/base/BaseInstallManagerTyp
 import { Utilities } from '../utilities/Utilities';
 import type { Subspace } from '../api/Subspace';
 import type { PnpmOptionsConfiguration } from '../logic/pnpm/PnpmOptionsConfiguration';
+import { PnpmWorkspaceFile } from '../logic/pnpm/PnpmWorkspaceFile';
 import { EnvironmentVariableNames } from '../api/EnvironmentConfiguration';
 import { initializeDotEnv } from '../logic/dotenv';
 
@@ -583,7 +584,7 @@ export class RushPnpmCommandLineParser {
 
         if (!Objects.areDeepEqual(currentGlobalOnlyBuiltDependencies, newGlobalOnlyBuiltDependencies)) {
           // Update onlyBuiltDependencies to pnpm configuration file
-          pnpmOptions?.updateGlobalOnlyBuiltDependencies(newGlobalOnlyBuiltDependencies);
+          await pnpmOptions?.updateGlobalOnlyBuiltDependenciesAsync(newGlobalOnlyBuiltDependencies);
 
           // Rerun installation to update
           await this._doRushUpdateAsync();
@@ -595,6 +596,29 @@ export class RushPnpmCommandLineParser {
         }
         break;
       }
+      case 'up':
+      case 'update': {
+        const pnpmOptions: PnpmOptionsConfiguration | undefined = this._subspace.getPnpmOptions();
+        if (pnpmOptions === undefined) {
+          break;
+        }
+
+        const workspaceYamlFilename: string = path.join(subspaceTempFolder, 'pnpm-workspace.yaml');
+        const newCatalogs: Record<string, Record<string, string>> | undefined =
+          await PnpmWorkspaceFile.loadCatalogsFromFileAsync(workspaceYamlFilename);
+        const currentCatalogs: Record<string, Record<string, string>> | undefined =
+          pnpmOptions.globalCatalogs;
+
+        if (!Objects.areDeepEqual(currentCatalogs, newCatalogs)) {
+          await pnpmOptions.updateGlobalCatalogsAsync(newCatalogs);
+
+          this._terminal.writeWarningLine(
+            `Rush refreshed the ${RushConstants.pnpmConfigFilename} with updated catalog definitions.\n` +
+              `  Run "rush update --recheck" to update the lockfile, then commit these changes to Git.`
+          );
+        }
+        break;
+      }
     }
   }
 

libraries/rush-lib/src/cli/test/RushPnpmCommandLineParser.test.ts

@@ -0,0 +1,123 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as path from 'node:path';
+import { FileSystem, JsonFile } from '@rushstack/node-core-library';
+import { TestUtilities } from '@rushstack/heft-config-file';
+import { RushConfiguration } from '../../api/RushConfiguration';
+import { PnpmWorkspaceFile } from '../../logic/pnpm/PnpmWorkspaceFile';
+
+const PACKAGE_ROOT: string = path.resolve(__dirname, '../../..');
+const CATALOG_SYNC_REPO_PATH: string = `${__dirname}/catalogSyncTestRepo`;
+
+describe('RushPnpmCommandLineParser', () => {
+  describe('catalog syncing', () => {
+    const testRepoPath: string = `${PACKAGE_ROOT}/temp/catalog-sync-test-repo`;
+    const pnpmConfigPath: string = `${testRepoPath}/common/config/rush/pnpm-config.json`;
+    const pnpmWorkspacePath: string = `${testRepoPath}/common/temp/pnpm-workspace.yaml`;
+
+    beforeEach(async () => {
+      await FileSystem.copyFilesAsync({ sourcePath: CATALOG_SYNC_REPO_PATH, destinationPath: testRepoPath });
+    });
+
+    afterEach(async () => {
+      await FileSystem.deleteFolderAsync(testRepoPath);
+    });
+
+    it('syncs updated catalogs from pnpm-workspace.yaml to pnpm-config.json', async () => {
+      const updatedWorkspaceYaml = `packages:
+  - '../../apps/*'
+catalogs:
+  default:
+    react: ^18.2.0
+    react-dom: ^18.2.0
+    typescript: ~5.3.0
+  frontend:
+    vue: ^3.4.0
+`;
+      await FileSystem.writeFileAsync(pnpmWorkspacePath, updatedWorkspaceYaml);
+
+      const rushConfiguration: RushConfiguration = RushConfiguration.loadFromConfigurationFile(
+        `${testRepoPath}/rush.json`
+      );
+
+      const subspace = rushConfiguration.getSubspace('default');
+      const pnpmOptions = subspace.getPnpmOptions();
+
+      expect(TestUtilities.stripAnnotations(pnpmOptions?.globalCatalogs)).toEqual({
+        default: {
+          react: '^18.0.0',
+          'react-dom': '^18.0.0'
+        }
+      });
+
+      const newCatalogs = await PnpmWorkspaceFile.loadCatalogsFromFileAsync(pnpmWorkspacePath);
+
+      await pnpmOptions?.updateGlobalCatalogsAsync(newCatalogs);
+
+      const updatedRushConfiguration: RushConfiguration = RushConfiguration.loadFromConfigurationFile(
+        `${testRepoPath}/rush.json`
+      );
+      const updatedSubspace = updatedRushConfiguration.getSubspace('default');
+      const updatedPnpmOptions = updatedSubspace.getPnpmOptions();
+
+      expect(TestUtilities.stripAnnotations(updatedPnpmOptions?.globalCatalogs)).toEqual({
+        default: {
+          react: '^18.2.0',
+          'react-dom': '^18.2.0',
+          typescript: '~5.3.0'
+        },
+        frontend: {
+          vue: '^3.4.0'
+        }
+      });
+    });
+
+    it('does not update pnpm-config.json when catalogs are unchanged', async () => {
+      const newCatalogs = await PnpmWorkspaceFile.loadCatalogsFromFileAsync(pnpmWorkspacePath);
+
+      const rushConfiguration: RushConfiguration = RushConfiguration.loadFromConfigurationFile(
+        `${testRepoPath}/rush.json`
+      );
+      const subspace = rushConfiguration.getSubspace('default');
+      const pnpmOptions = subspace.getPnpmOptions();
+
+      await pnpmOptions?.updateGlobalCatalogsAsync(newCatalogs);
+
+      const savedConfig = JsonFile.load(pnpmConfigPath);
+      expect(savedConfig.globalCatalogs).toEqual({
+        default: {
+          react: '^18.0.0',
+          'react-dom': '^18.0.0'
+        }
+      });
+    });
+
+    it('removes catalogs when pnpm-workspace.yaml has no catalogs', async () => {
+      const workspaceWithoutCatalogs = `packages:
+  - '../../apps/*'
+`;
+      await FileSystem.writeFileAsync(pnpmWorkspacePath, workspaceWithoutCatalogs);
+
+      const newCatalogs = await PnpmWorkspaceFile.loadCatalogsFromFileAsync(pnpmWorkspacePath);
+
+      expect(newCatalogs).toBeUndefined();
+
+      const rushConfiguration: RushConfiguration = RushConfiguration.loadFromConfigurationFile(
+        `${testRepoPath}/rush.json`
+      );
+      const subspace = rushConfiguration.getSubspace('default');
+      const pnpmOptions = subspace.getPnpmOptions();
+
+      await pnpmOptions?.updateGlobalCatalogsAsync(newCatalogs);
+
+      const updatedRushConfiguration: RushConfiguration = RushConfiguration.loadFromConfigurationFile(
+        `${testRepoPath}/rush.json`
+      );
+      const updatedSubspace = updatedRushConfiguration.getSubspace('default');
+      const updatedPnpmOptions = updatedSubspace.getPnpmOptions();
+
+      expect(updatedPnpmOptions?.globalCatalogs).toBeUndefined();
+    });
+  });
+});

libraries/rush-lib/src/cli/test/catalogSyncTestRepo/common/.gitignore

@@ -0,0 +1 @@
+!temp

libraries/rush-lib/src/cli/test/catalogSyncTestRepo/common/config/rush/pnpm-config.json

@@ -0,0 +1,8 @@
+{
+  "globalCatalogs": {
+    "default": {
+      "react": "^18.0.0",
+      "react-dom": "^18.0.0"
+    }
+  }
+}

libraries/rush-lib/src/cli/test/catalogSyncTestRepo/common/temp/pnpm-workspace.yaml

@@ -0,0 +1,6 @@
+packages:
+  - '../../apps/*'
+catalogs:
+  default:
+    react: ^18.0.0
+    react-dom: ^18.0.0

libraries/rush-lib/src/cli/test/catalogSyncTestRepo/rush.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush.schema.json",
+  "rushVersion": "5.166.0",
+  "pnpmVersion": "10.28.1",
+  "nodeSupportedVersionRange": ">=18.0.0",
+  "projects": []
+}

libraries/rush-lib/src/logic/pnpm/PnpmOptionsConfiguration.ts

@@ -535,18 +535,32 @@ export class PnpmOptionsConfiguration extends PackageManagerOptionsConfiguration
   public updateGlobalPatchedDependencies(patchedDependencies: Record<string, string> | undefined): void {
     this._globalPatchedDependencies = patchedDependencies;
     this._json.globalPatchedDependencies = patchedDependencies;
-    if (this.jsonFilename) {
-      JsonFile.save(this._json, this.jsonFilename, { updateExistingFile: true });
-    }
+    JsonFile.save(this._json, this.jsonFilename as string, { updateExistingFile: true });
   }
 
   /**
    * Updates globalOnlyBuiltDependencies field of the PNPM options in the common/config/rush/pnpm-config.json file.
    */
-  public updateGlobalOnlyBuiltDependencies(onlyBuiltDependencies: string[] | undefined): void {
+  public async updateGlobalOnlyBuiltDependenciesAsync(
+    onlyBuiltDependencies: string[] | undefined
+  ): Promise<void> {
     this._json.globalOnlyBuiltDependencies = onlyBuiltDependencies;
-    if (this.jsonFilename) {
-      JsonFile.save(this._json, this.jsonFilename, { updateExistingFile: true });
-    }
+    await JsonFile.saveAsync(this._json, this.jsonFilename as string, {
+      updateExistingFile: true,
+      ignoreUndefinedValues: true
+    });
+  }
+
+  /**
+   * Updates globalCatalogs field of the PNPM options in the common/config/rush/pnpm-config.json file.
+   */
+  public async updateGlobalCatalogsAsync(
+    catalogs: Record<string, Record<string, string>> | undefined
+  ): Promise<void> {
+    this._json.globalCatalogs = catalogs;
+    await JsonFile.saveAsync(this._json, this.jsonFilename as string, {
+      updateExistingFile: true,
+      ignoreUndefinedValues: true
+    });
   }
 }

libraries/rush-lib/src/logic/pnpm/PnpmWorkspaceFile.ts

@@ -3,7 +3,7 @@
 
 import * as path from 'node:path';
 
-import { Sort, Import, Path } from '@rushstack/node-core-library';
+import { FileSystem, Sort, Import, Path } from '@rushstack/node-core-library';
 
 import { BaseWorkspaceFile } from '../base/BaseWorkspaceFile';
 import { PNPM_SHRINKWRAP_YAML_FORMAT } from './PnpmYamlCommon';
@@ -29,7 +29,7 @@ const globEscape: (unescaped: string) => string = require('glob-escape'); // No
 interface IPnpmWorkspaceYaml {
   /** The list of local package directories */
   packages: string[];
-  /** Catalog definitions for centralized version management */
+  /** Named catalog definitions for centralized version management */
   catalogs?: Record<string, Record<string, string>>;
 }
 
@@ -56,6 +56,33 @@ export class PnpmWorkspaceFile extends BaseWorkspaceFile {
     this._catalogs = undefined;
   }
 
+  /**
+   * Loads and returns the catalogs section from an existing pnpm-workspace.yaml file.
+   * This method handles both the singular 'catalog' field (for the default catalog) and
+   * the plural 'catalogs' field (for named catalogs), merging them into a single object.
+   *
+   * @param workspaceYamlFilename - The path to the pnpm-workspace.yaml file
+   * @returns The catalogs object, or undefined if the file doesn't exist or has no catalogs
+   */
+  public static async loadCatalogsFromFileAsync(
+    workspaceYamlFilename: string
+  ): Promise<Record<string, Record<string, string>> | undefined> {
+    let content: string;
+    try {
+      content = await FileSystem.readFileAsync(workspaceYamlFilename);
+    } catch (error) {
+      if (FileSystem.isNotExistError(error)) {
+        return undefined;
+      } else {
+        throw error;
+      }
+    }
+
+    const parsed: IPnpmWorkspaceYaml | undefined = yamlModule.load(content) as IPnpmWorkspaceYaml | undefined;
+
+    return parsed?.catalogs;
+  }
+
   /**
    * Sets the catalog definitions for the workspace.
    * @param catalogs - A map of catalog name to package versions