fix(@angular/cli): abort and guide manual mitigation when updating catalog packages

When packages to be updated are configured to use catalogs (e.g. '@angular/core': 'catalog:'), ng update cannot modify the shared catalog configuration files directly without potentially breaking other monorepo projects.

Detect catalog updates early in resolveUserUpdatePlan, resolve the target versions from the registry, and abort with a detailed step-by-step instruction on how to manually update their catalog config file, run package manager install, and execute migration schematics via 'ng update --migrate-only --from <installed-version>'.

Author: clydin

packages/angular/cli/src/commands/update/update-resolver.ts

@@ -759,6 +759,73 @@ function isPkgFromRegistry(name: string, specifier: string): boolean {
   return !!result.registry;
 }
 
+async function checkCatalogUpdates(
+  normalizedPackages: string[],
+  packageJsonContent: PackageManifest,
+  registryClient: RegistryClient,
+  workspaceRoot: string,
+  options: UpdateResolverOptions,
+): Promise<void> {
+  const catalogUpdates: { name: string; current: string; target: string; specifier: string }[] = [];
+
+  for (const requestedPkg of normalizedPackages) {
+    const specifier =
+      packageJsonContent.dependencies?.[requestedPkg] ||
+      packageJsonContent.devDependencies?.[requestedPkg] ||
+      packageJsonContent.peerDependencies?.[requestedPkg];
+
+    if (specifier?.startsWith('catalog:')) {
+      const current = getInstalledVersion(requestedPkg, workspaceRoot) ?? 'unknown';
+      let target = 'latest';
+      try {
+        const metadata = await registryClient.getMetadata(requestedPkg);
+        if (metadata) {
+          const resolved = await resolvePackageVersion(
+            registryClient,
+            metadata,
+            options.next ? 'next' : 'latest',
+            !!options.next,
+          );
+          target = resolved ?? 'latest';
+        }
+      } catch {
+        // Fallback to 'latest' tag
+      }
+
+      catalogUpdates.push({ name: requestedPkg, current, target, specifier });
+    }
+  }
+
+  if (catalogUpdates.length > 0) {
+    const packageManagerName = options.packageManager ?? 'your package manager';
+    const installCmd = packageManagerName === 'yarn' ? 'yarn install' : 'pnpm install';
+
+    const updatesList = catalogUpdates
+      .map((pkg) => `  - ${pkg.name} (${pkg.specifier}) -> Target version: ${pkg.target}`)
+      .join('\n');
+
+    const migrationCommands = catalogUpdates
+      .map((pkg) => {
+        const fromVer = pkg.current === 'unknown' ? '<current-version>' : pkg.current;
+
+        return `  ng update ${pkg.name} --migrate-only --from ${fromVer}`;
+      })
+      .join('\n');
+
+    throw new Error(
+      `The following packages to update are configured to use catalogs:\n` +
+        `${updatesList}\n\n` +
+        `Because catalogs are shared across the monorepo, 'ng update' cannot modify them directly.\n` +
+        `Please perform the following steps to update:\n` +
+        `  1. Manually update the versions for these packages in your catalog configuration file ` +
+        `(e.g., pnpm-workspace.yaml or .yarnrc.yml).\n` +
+        `  2. Run '${installCmd}' to install the updated versions.\n` +
+        `  3. Run the following command(s) to execute the migration schematics:\n` +
+        `${migrationCommands}`,
+    );
+  }
+}
+
 export async function resolveUserUpdatePlan(
   options: UpdateResolverOptions,
   packageManager: PackageManager,
@@ -810,10 +877,19 @@ export async function resolveUserUpdatePlan(
   options.to = _formatVersion(options.to);
   const usingYarn = options.packageManager === 'yarn';
 
-  const packages = _buildPackageList(options, npmDeps, logger);
   const minReleaseAge = await packageManager.getMinimumReleaseAge();
   const registryClient = new RegistryClient(packageManager, logger, minReleaseAge);
 
+  await checkCatalogUpdates(
+    normalizedPackages,
+    packageJsonContent,
+    registryClient,
+    workspaceRoot,
+    options,
+  );
+
+  const packages = _buildPackageList(options, npmDeps, logger);
+
   const getOrFetchPackageMetadata = async (
     packageName: string,
   ): Promise<PackageMetadata | null> => {

packages/angular/cli/src/commands/update/update-resolver_spec.ts

@@ -474,6 +474,40 @@ describe('UpdateResolver', () => {
     expect(plan.packagesToUpdate.get('@angular-devkit-tests/common-bug')).toBe('13.2.0');
     expect(plan.packagesToUpdate.get('@angular-devkit-tests/cdk-bug')).toBe('13.2.0');
   });
+
+  it('rejects updates for catalog packages and guides on manual migration steps', async () => {
+    createMockWorkspace(
+      {
+        name: 'blah',
+        dependencies: {
+          '@angular/core': 'catalog:',
+        },
+      },
+      {
+        '@angular/core': { version: '5.1.0' },
+      },
+    );
+
+    const expectedError = [
+      `The following packages to update are configured to use catalogs:`,
+      `\\s+- @angular/core \\(catalog:\\) -> Target version: 6\\.0\\.0`,
+      ``,
+      `Because catalogs are shared across the monorepo, 'ng update' cannot modify them directly\\.`,
+      `Please perform the following steps to update:`,
+      `\\s+1\\. Manually update the versions for these packages in your catalog configuration file ` +
+        `\\(e\\.g\\., pnpm-workspace\\.yaml or \\.yarnrc\\.yml\\)\\.`,
+      `\\s+2\\. Run 'pnpm install' to install the updated versions\\.`,
+      `\\s+3\\. Run the following command\\(s\\) to execute the migration schematics:`,
+      `\\s+ng update @angular/core --migrate-only --from 5\\.1\\.0`,
+    ].join('\\n');
+
+    await expectAsync(
+      resolvePlan({
+        packages: ['@angular/core'],
+        workspaceRoot: tempRoot,
+      }),
+    ).toBeRejectedWithError(new RegExp(expectedError));
+  });
 });
 
 describe('RegistryClient', () => {