refactor(@angular/cli): implement structured error handling in package manager API

This commit introduces a structured error handling system into the package manager abstraction. Previously, the system treated most command failures generically, often assuming a package was simply "not found." This could mask the true root cause of issues such as network failures, registry authentication errors, or unexpected changes in a package manager's output.

The new implementation enhances diagnostics and provides clearer, more actionable error messages by:
- Introducing a standardized `ErrorInfo` interface to represent parsed error details.
- Adding dedicated parsers to extract structured error information (JSON or text-based) from the stderr of npm, yarn, pnpm, and bun.
- Making the core execution logic stricter. It now re-throws the original `PackageManagerError` if a command fails for an unknown reason, preventing silent failures.
- Abstracting the "package not found" check into the `PackageManagerDescriptor`, removing hardcoded logic from the execution layer.
- Improving the `yarn-classic` parser to use verbose logs, allowing it to accurately detect and report specific HTTP status codes (e.g., 401, 403, 404, 500).

Author: clydin

packages/angular/cli/src/package-managers/error.ts

@@ -35,3 +35,18 @@ export class PackageManagerError extends Error {
     super(message);
   }
 }
+
+/**
+ * Represents structured information about an error returned by a package manager command.
+ * This is a data interface, not an `Error` subclass.
+ */
+export interface ErrorInfo {
+  /** A specific error code (e.g. 'E404', 'EACCES'). */
+  readonly code: string;
+
+  /** A short, human-readable summary of the error. */
+  readonly summary: string;
+
+  /** An optional, detailed description of the error. */
+  readonly detail?: string;
+}

packages/angular/cli/src/package-managers/package-manager-descriptor.ts

@@ -12,14 +12,17 @@
  * package-manager-specific commands, flags, and output parsing.
  */
 
+import { ErrorInfo } from './error';
 import { Logger } from './logger';
 import { PackageManifest, PackageMetadata } from './package-metadata';
 import { InstalledPackage } from './package-tree';
 import {
   parseNpmLikeDependencies,
+  parseNpmLikeError,
   parseNpmLikeManifest,
   parseNpmLikeMetadata,
   parseYarnClassicDependencies,
+  parseYarnClassicError,
   parseYarnLegacyManifest,
   parseYarnModernDependencies,
 } from './parsers';
@@ -86,12 +89,30 @@ export interface PackageManagerDescriptor {
 
     /** A function to parse the output of `getManifestCommand` for the full package metadata. */
     getRegistryMetadata: (stdout: string, logger?: Logger) => PackageMetadata | null;
+
+    /** A function to parse the output of stderr when a command fails. */
+    getError?: (stderr: string, logger?: Logger) => ErrorInfo | null;
   };
+
+  /** A function that checks if a structured error represents a "package not found" error. */
+  readonly isNotFound: (error: ErrorInfo) => boolean;
 }
 
 /** A type that represents the name of a supported package manager. */
 export type PackageManagerName = keyof typeof SUPPORTED_PACKAGE_MANAGERS;
 
+/** A set of error codes that are known to indicate a "package not found" error. */
+const NOT_FOUND_ERROR_CODES = new Set(['E404']);
+
+/**
+ * A shared function to check if a structured error represents a "package not found" error.
+ * @param error The structured error to check.
+ * @returns True if the error code is a known "not found" code, false otherwise.
+ */
+function isKnownNotFound(error: ErrorInfo): boolean {
+  return NOT_FOUND_ERROR_CODES.has(error.code);
+}
+
 /**
  * A map of supported package managers to their descriptors.
  * This is the single source of truth for all package-manager-specific
@@ -124,7 +145,9 @@ export const SUPPORTED_PACKAGE_MANAGERS = {
       listDependencies: parseNpmLikeDependencies,
       getRegistryManifest: parseNpmLikeManifest,
       getRegistryMetadata: parseNpmLikeMetadata,
+      getError: parseNpmLikeError,
     },
+    isNotFound: isKnownNotFound,
   },
   yarn: {
     binary: 'yarn',
@@ -146,7 +169,9 @@ export const SUPPORTED_PACKAGE_MANAGERS = {
       listDependencies: parseYarnModernDependencies,
       getRegistryManifest: parseNpmLikeManifest,
       getRegistryMetadata: parseNpmLikeMetadata,
+      getError: parseNpmLikeError,
     },
+    isNotFound: isKnownNotFound,
   },
   'yarn-classic': {
     binary: 'yarn',
@@ -165,12 +190,14 @@ export const SUPPORTED_PACKAGE_MANAGERS = {
     getRegistryOptions: (registry: string) => ({ args: ['--registry', registry] }),
     versionCommand: ['--version'],
     listDependenciesCommand: ['list', '--depth=0', '--json'],
-    getManifestCommand: ['info', '--json'],
+    getManifestCommand: ['info', '--json', '--verbose'],
     outputParsers: {
       listDependencies: parseYarnClassicDependencies,
       getRegistryManifest: parseYarnLegacyManifest,
       getRegistryMetadata: parseNpmLikeMetadata,
+      getError: parseYarnClassicError,
     },
+    isNotFound: isKnownNotFound,
   },
   pnpm: {
     binary: 'pnpm',
@@ -192,7 +219,9 @@ export const SUPPORTED_PACKAGE_MANAGERS = {
       listDependencies: parseNpmLikeDependencies,
       getRegistryManifest: parseNpmLikeManifest,
       getRegistryMetadata: parseNpmLikeMetadata,
+      getError: parseNpmLikeError,
     },
+    isNotFound: isKnownNotFound,
   },
   bun: {
     binary: 'bun',
@@ -214,7 +243,9 @@ export const SUPPORTED_PACKAGE_MANAGERS = {
       listDependencies: parseNpmLikeDependencies,
       getRegistryManifest: parseNpmLikeManifest,
       getRegistryMetadata: parseNpmLikeMetadata,
+      getError: parseNpmLikeError,
     },
+    isNotFound: isKnownNotFound,
   },
 } satisfies Record<string, PackageManagerDescriptor>;
 

packages/angular/cli/src/package-managers/package-manager.ts

@@ -14,7 +14,7 @@
 
 import { join } from 'node:path';
 import npa from 'npm-package-arg';
-import { PackageManagerError } from './error';
+import { ErrorInfo, PackageManagerError } from './error';
 import { Host } from './host';
 import { Logger } from './logger';
 import { PackageManagerDescriptor } from './package-manager-descriptor';
@@ -191,17 +191,45 @@ export class PackageManager {
 
     let stdout;
     let stderr;
+    let exitCode: number | null = null;
+    let parsedError: ErrorInfo | null = null;
+
     try {
       ({ stdout, stderr } = await this.#run(args, runOptions));
     } catch (e) {
-      if (e instanceof PackageManagerError && typeof e.exitCode === 'number' && e.exitCode !== 0) {
-        // Some package managers exit with a non-zero code when the package is not found.
-        if (cache && cacheKey) {
-          cache.set(cacheKey, null);
-        }
+      if (!(e instanceof PackageManagerError && typeof e.exitCode === 'number')) {
+        throw e;
+      }
+
+      exitCode = e.exitCode;
+      stdout = e.stdout;
+      stderr = e.stderr;
+
+      // Only try to parse errors if exit code is non-zero.
+      if (exitCode !== 0) {
+        parsedError = this.descriptor.outputParsers.getError?.(stderr, this.options.logger) ?? null;
+      }
 
-        return null;
+      if (parsedError) {
+        this.options.logger?.debug(
+          `[${this.descriptor.binary}] Structured error (code: ${parsedError.code}): ${parsedError.summary}`,
+        );
+
+        // Special case for 'not found' errors (e.g., E404). Return null for these.
+        if (this.descriptor.isNotFound(parsedError)) {
+          if (cache && cacheKey) {
+            cache.set(cacheKey, null);
+          }
+
+          return null;
+        } else {
+          // For all other structured errors, re-throw a more informative error.
+          throw new PackageManagerError(parsedError.summary, stdout, stderr, exitCode);
+        }
       }
+
+      // If no structured error was parsed, rethrow the original PackageManagerError
+      // (this also covers cases where exitCode is 0 but runCommand still threw for other reasons).
       throw e;
     }
 
@@ -216,7 +244,7 @@ export class PackageManager {
       const message = `Failed to parse package manager output: ${
         e instanceof Error ? e.message : ''
       }`;
-      throw new PackageManagerError(message, stdout, stderr, 0);
+      throw new PackageManagerError(message, stdout, stderr, exitCode);
     }
   }
 

packages/angular/cli/src/package-managers/parsers.ts

@@ -12,6 +12,7 @@
  * into their own file improves modularity and allows for focused testing.
  */
 
+import { ErrorInfo } from './error';
 import { Logger } from './logger';
 import { PackageManifest, PackageMetadata } from './package-metadata';
 import { InstalledPackage } from './package-tree';
@@ -106,7 +107,7 @@ export function parseNpmLikeDependencies(
  * Parses the output of `yarn list` (classic).
  *
  * The expected output is a JSON stream (JSONL), where each line is a JSON object.
- * The relevant object has a `type` of `'tree'`.
+ * The relevant object has a `type` of `'tree'` with a `data` property.
  * Yarn classic does not provide a path, so the `path` property will be `undefined`.
  *
  * ```json
@@ -289,3 +290,162 @@ export function parseYarnLegacyManifest(stdout: string, logger?: Logger): Packag
   // Yarn classic wraps the manifest in a `data` property.
   return data.data ?? data;
 }
+
+/**
+ * Parses the stderr output of npm, pnpm, modern yarn, or bun to extract structured error information.
+ *
+ * This parser uses a multi-stage approach. It first attempts to parse the entire `stderr` as a
+ * single JSON object, which is the standard for modern tools like pnpm, yarn, and bun. If JSON
+ * parsing fails, it falls back to a line-by-line regex-based approach to handle the plain
+ * text output from older versions of npm.
+ *
+ * Example JSON output (pnpm):
+ * ```json
+ * {
+ *   "code": "E404",
+ *   "summary": "Not Found - GET https://registry.npmjs.org/@angular%2fnon-existent - Not found",
+ *   "detail": "The requested resource '@angular/non-existent@*' could not be found or you do not have permission to access it."
+ * }
+ * ```
+ *
+ * Example text output (npm):
+ * ```
+ * npm error code E404
+ * npm error 404 Not Found - GET https://registry.npmjs.org/@angular%2fnon-existent - Not found
+ * ```
+ *
+ * @param stderr The standard error output of the command.
+ * @param logger An optional logger instance.
+ * @returns An `ErrorInfo` object if parsing is successful, otherwise `null`.
+ */
+export function parseNpmLikeError(stderr: string, logger?: Logger): ErrorInfo | null {
+  logger?.debug(`Parsing npm-like error output...`);
+  logStdout(stderr, logger); // Log stderr for debugging purposes
+
+  if (!stderr) {
+    logger?.debug('  stderr is empty. No error found.');
+
+    return null;
+  }
+
+  // Attempt to parse as JSON first (common for pnpm, modern yarn, bun)
+  try {
+    const jsonError = JSON.parse(stderr);
+    if (
+      jsonError &&
+      typeof jsonError.code === 'string' &&
+      (typeof jsonError.summary === 'string' || typeof jsonError.message === 'string')
+    ) {
+      const summary = jsonError.summary || jsonError.message;
+      logger?.debug(`  Successfully parsed JSON error with code '${jsonError.code}'.`);
+
+      return {
+        code: jsonError.code,
+        summary: summary,
+        detail: jsonError.detail,
+      };
+    }
+  } catch (e) {
+    logger?.debug(`  Failed to parse stderr as JSON: ${e}. Attempting regex fallback.`);
+    // Fallback to regex for plain text errors (common for npm)
+  }
+
+  // Regex for npm-like error codes (e.g., `npm ERR! code E404` or `npm error code E404`)
+  const errorCodeMatch = stderr.match(/npm (ERR!|error) code (E\d{3}|[A-Z_]+)/);
+  if (errorCodeMatch) {
+    const code = errorCodeMatch[2]; // Capture group 2 is the actual error code
+    let summary: string | undefined;
+
+    // Find the most descriptive summary line (the line after `npm ERR! code ...` or `npm error code ...`).
+    for (const line of stderr.split('\n')) {
+      if (line.startsWith('npm ERR!') && !line.includes(' code ')) {
+        summary = line.replace('npm ERR! ', '').trim();
+        break;
+      } else if (line.startsWith('npm error') && !line.includes(' code ')) {
+        summary = line.replace('npm error ', '').trim();
+        break;
+      }
+    }
+
+    logger?.debug(`  Successfully parsed text error with code '${code}'.`);
+
+    return {
+      code,
+      summary: summary || `Package manager error: ${code}`,
+    };
+  }
+
+  logger?.debug('  Failed to parse npm-like error. No structured error found.');
+
+  return null;
+}
+
+/**
+ * Parses the stderr output of yarn classic to extract structured error information.
+ *
+ * This parser first attempts to find an HTTP status code (e.g., 404, 401) in the verbose output.
+ * If found, it returns a standardized error code (`E${statusCode}`).
+ * If no HTTP status code is found, it falls back to parsing generic JSON error lines.
+ *
+ * Example verbose output (with HTTP status code):
+ * ```json
+ * {"type":"verbose","data":"Request \"https://registry.npmjs.org/@angular%2fnon-existent\" finished with status code 404."}
+ * ```
+ *
+ * Example generic JSON error output:
+ * ```json
+ * {"type":"error","data":"Received invalid response from npm."}
+ * ```
+ *
+ * @param stderr The standard error output of the command.
+ * @param logger An optional logger instance.
+ * @returns An `ErrorInfo` object if parsing is successful, otherwise `null`.
+ */
+export function parseYarnClassicError(stderr: string, logger?: Logger): ErrorInfo | null {
+  logger?.debug(`Parsing yarn classic error output...`);
+  logStdout(stderr, logger); // Log stderr for debugging purposes
+
+  if (!stderr) {
+    logger?.debug('  stderr is empty. No error found.');
+
+    return null;
+  }
+
+  // First, check for any HTTP status code in the verbose output.
+  const statusCodeMatch = stderr.match(/finished with status code (\d{3})/);
+  if (statusCodeMatch) {
+    const statusCode = statusCodeMatch[1];
+    logger?.debug(`  Detected HTTP status code '${statusCode}' in verbose output.`);
+
+    return {
+      code: `E${statusCode}`,
+      summary: `Request failed with status code ${statusCode}.`,
+    };
+  }
+
+  // Fallback to the JSON error type if no HTTP status code is present.
+  for (const line of stderr.split('\n')) {
+    if (!line) {
+      continue;
+    }
+    try {
+      const json = JSON.parse(line);
+      if (json.type === 'error' && typeof json.data === 'string') {
+        const message = json.data;
+        logger?.debug(`  Successfully parsed generic yarn classic error.`);
+
+        return {
+          code: 'UNKNOWN_ERROR',
+          summary: message,
+        };
+      }
+    } catch (e) {
+      // Ignore lines that are not valid JSON or not error types
+      logger?.debug(`  Ignoring non-JSON or non-error line: ${e}`);
+    }
+  }
+
+  logger?.debug('  Failed to parse yarn classic error. No structured error found.');
+
+  return null;
+}