refactor(@angular/cli): introduce new package manager abstraction

Introduces a new abstraction layer for interacting with JavaScript package managers.
This change centralizes all package-manager-specific logic into a single, reliable,
and extensible interface. The primary motivation is to standardize package manager
interactions for commands like `ng add` and `ng update`.

The new system is designed to be highly testable. All side-effectful operations
(file system access, command execution) are abstracted behind a `Host` interface,
allowing for comprehensive and reliable unit testing in complete isolation.

Key features include:
- A high-level API to install, add, and query packages from a registry.
- Methods to fetch full package metadata and specific version manifests.
- An `acquireTempPackage` method to support temporary, isolated package installations.

This abstraction paves the way for the eventual removal of several direct package
dependencies, including `ini`, `@yarnpkg/lockfile`, and `pacote`.

Author: clydin

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

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+/**
+ * @fileoverview This file contains the logic for discovering the package manager
+ * used in a project by searching for lockfiles. It is designed to be efficient
+ * and to correctly handle monorepo structures.
+ */
+
+import { dirname, join } from 'node:path';
+import { Host } from './host';
+import { Logger } from './logger';
+import {
+  PACKAGE_MANAGER_PRECEDENCE,
+  PackageManagerName,
+  SUPPORTED_PACKAGE_MANAGERS,
+} from './package-manager-descriptor';
+
+/**
+ * A map from lockfile names to their corresponding package manager.
+ * This is a performance optimization to avoid iterating over all possible
+ * lockfiles in every directory.
+ */
+const LOCKFILE_TO_PACKAGE_MANAGER = new Map<string, PackageManagerName>();
+for (const [name, descriptor] of Object.entries(SUPPORTED_PACKAGE_MANAGERS)) {
+  for (const lockfile of descriptor.lockfiles) {
+    LOCKFILE_TO_PACKAGE_MANAGER.set(lockfile, name as PackageManagerName);
+  }
+}
+
+/**
+ * Searches a directory for lockfiles and returns a set of package managers that correspond to them.
+ * @param host A `Host` instance for interacting with the file system.
+ * @param directory The directory to search.
+ * @param logger An optional logger instance.
+ * @returns A promise that resolves to a set of package manager names.
+ */
+async function findLockfiles(
+  host: Host,
+  directory: string,
+  logger?: Logger,
+): Promise<Set<PackageManagerName>> {
+  logger?.debug(`Searching for lockfiles in '${directory}'...`);
+
+  try {
+    const files = await host.readdir(directory);
+    const foundPackageManagers = new Set<PackageManagerName>();
+
+    for (const file of files) {
+      const packageManager = LOCKFILE_TO_PACKAGE_MANAGER.get(file);
+      if (packageManager) {
+        logger?.debug(`  Found '${file}'.`);
+        foundPackageManagers.add(packageManager);
+      }
+    }
+
+    return foundPackageManagers;
+  } catch (e) {
+    logger?.debug(`  Failed to read directory: ${e}`);
+
+    // Ignore directories that don't exist or can't be read.
+    return new Set();
+  }
+}
+
+/**
+ * Checks if a given path is a directory.
+ * @param host A `Host` instance for interacting with the file system.
+ * @param path The path to check.
+ * @returns A promise that resolves to true if the path is a directory, false otherwise.
+ */
+async function isDirectory(host: Host, path: string): Promise<boolean> {
+  try {
+    return (await host.stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Discovers the package manager used in a project by searching for lockfiles.
+ *
+ * This function searches for lockfiles in the given directory and its ancestors.
+ * If multiple lockfiles are found, it uses the precedence array to determine
+ * which package manager to use. The search is bounded by the git repository root.
+ *
+ * @param host A `Host` instance for interacting with the file system.
+ * @param startDir The directory to start the search from.
+ * @param logger An optional logger instance.
+ * @returns A promise that resolves to the name of the discovered package manager, or null if none is found.
+ */
+export async function discover(
+  host: Host,
+  startDir: string,
+  logger?: Logger,
+): Promise<PackageManagerName | null> {
+  logger?.debug(`Starting package manager discovery in '${startDir}'...`);
+  let currentDir = startDir;
+
+  while (true) {
+    const found = await findLockfiles(host, currentDir, logger);
+
+    if (found.size > 0) {
+      logger?.debug(`Found lockfile(s): [${[...found].join(', ')}]. Applying precedence...`);
+      for (const packageManager of PACKAGE_MANAGER_PRECEDENCE) {
+        if (found.has(packageManager)) {
+          logger?.debug(`Selected '${packageManager}' based on precedence.`);
+
+          return packageManager;
+        }
+      }
+    }
+
+    // Stop searching if we reach the git repository root.
+    if (await isDirectory(host, join(currentDir, '.git'))) {
+      logger?.debug(`Reached repository root at '${currentDir}'. Stopping search.`);
+
+      return null;
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      // We have reached the filesystem root.
+      logger?.debug('Reached filesystem root. No lockfile found.');
+
+      return null;
+    }
+
+    currentDir = parentDir;
+  }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { discover } from './discovery';
+import { MockHost } from './testing/mock-host';
+
+describe('discover', () => {
+  it('should find a lockfile in the starting directory', async () => {
+    const host = new MockHost({
+      '/project': ['package-lock.json'],
+    });
+    const result = await discover(host, '/project');
+    expect(result).toBe('npm');
+  });
+
+  it('should find a lockfile in a parent directory', async () => {
+    const host = new MockHost({
+      '/project': ['yarn.lock'],
+      '/project/subdir': [],
+    });
+    const result = await discover(host, '/project/subdir');
+    expect(result).toBe('yarn');
+  });
+
+  it('should return null if no lockfile is found up to the root', async () => {
+    const host = new MockHost({
+      '/': [],
+      '/project': [],
+      '/project/subdir': [],
+    });
+    const result = await discover(host, '/project/subdir');
+    expect(result).toBeNull();
+  });
+
+  it('should apply precedence when multiple lockfiles are found', async () => {
+    const host = new MockHost({
+      '/project': ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'],
+    });
+    // pnpm should have the highest precedence according to the descriptor.
+    const result = await discover(host, '/project');
+    expect(result).toBe('pnpm');
+  });
+
+  it('should stop searching at a .git boundary', async () => {
+    const host = new MockHost({
+      '/': ['yarn.lock'],
+      '/project': ['.git'], // .git is mocked as a directory.
+      '/project/subdir': [],
+    });
+    const result = await discover(host, '/project/subdir');
+    expect(result).toBeNull();
+  });
+
+  it('should stop searching at the filesystem root', async () => {
+    const host = new MockHost({
+      '/': [],
+    });
+    const result = await discover(host, '/');
+    expect(result).toBeNull();
+  });
+
+  it('should handle file system errors during readdir gracefully', async () => {
+    const host = new MockHost({});
+    host.readdir = () => Promise.reject(new Error('Permission denied'));
+
+    const result = await discover(host, '/project');
+    expect(result).toBeNull();
+  });
+
+  it('should handle file system errors during stat gracefully', async () => {
+    const host = new MockHost({ '/project': ['.git'] });
+    host.stat = () => Promise.reject(new Error('Permission denied'));
+
+    // The error on stat should prevent it from finding the .git dir and thus it will continue to the root.
+    const result = await discover(host, '/project');
+    expect(result).toBeNull();
+  });
+});

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

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+/**
+ * @fileoverview This file defines a custom error class for the package manager
+ * abstraction. This allows for structured error handling and provides consumers
+ * with detailed information about the process failure.
+ */
+
+/**
+ * A custom error class for package manager-related errors.
+ *
+ * This error class provides structured data about the failed process,
+ * including stdout, stderr, and the exit code.
+ */
+export class PackageManagerError extends Error {
+  /**
+   * Creates a new `PackageManagerError` instance.
+   * @param message The error message.
+   * @param stdout The standard output of the failed process.
+   * @param stderr The standard error of the failed process.
+   * @param exitCode The exit code of the failed process.
+   */
+  constructor(
+    message: string,
+    public readonly stdout: string,
+    public readonly stderr: string,
+    public readonly exitCode: number | null,
+  ) {
+    super(message);
+  }
+}

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

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { major } from 'semver';
+import { discover } from './discovery';
+import { Host, NodeJS_HOST } from './host';
+import { Logger } from './logger';
+import { PackageManager } from './package-manager';
+import { PackageManagerName, SUPPORTED_PACKAGE_MANAGERS } from './package-manager-descriptor';
+import { getYarnVersion, isPackageManagerInstalled } from './verification';
+
+/**
+ * Determines the package manager to use for a given project.
+ *
+ * This function will determine the package manager by checking for a configured
+ * package manager, discovering the package manager from lockfiles, or falling
+ * back to a default. It also handles differentiation between yarn classic and modern.
+ *
+ * @param host A `Host` instance for interacting with the file system and running commands.
+ * @param cwd The directory to start the search from.
+ * @param configured An optional, explicitly configured package manager.
+ * @param logger An optional logger instance.
+ * @returns A promise that resolves to an object containing the name and source of the package manager.
+ */
+async function determinePackageManager(
+  host: Host,
+  cwd: string,
+  configured?: PackageManagerName,
+  logger?: Logger,
+): Promise<{ name: PackageManagerName; source: 'configured' | 'discovered' | 'default' }> {
+  let name: PackageManagerName;
+  let source: 'configured' | 'discovered' | 'default';
+
+  if (configured) {
+    name = configured;
+    source = 'configured';
+    logger?.debug(`Using configured package manager: '${name}'.`);
+  } else {
+    const discovered = await discover(host, cwd, logger);
+    if (discovered) {
+      name = discovered;
+      source = 'discovered';
+      logger?.debug(`Discovered package manager: '${name}'.`);
+    } else {
+      name = 'npm';
+      source = 'default';
+      logger?.debug(`No lockfile found. Using default package manager: 'npm'.`);
+    }
+  }
+
+  if (name === 'yarn') {
+    const version = await getYarnVersion(host, logger);
+    if (version && major(version) < 2) {
+      name = 'yarn-legacy';
+      logger?.debug(`Detected yarn classic. Using 'yarn-legacy'.`);
+    }
+  }
+
+  return { name, source };
+}
+
+/**
+ * Creates a new `PackageManager` instance for a given project.
+ *
+ * This function is the main entry point for the package manager abstraction.
+ * It will determine, verify, and instantiate the correct package manager.
+ *
+ * @param options An object containing the options for creating the package manager.
+ * @returns A promise that resolves to a new `PackageManager` instance.
+ */
+export async function createPackageManager(options: {
+  cwd: string;
+  configuredPackageManager?: PackageManagerName;
+  logger?: Logger;
+  dryRun?: boolean;
+}): Promise<PackageManager> {
+  const { cwd, configuredPackageManager, logger, dryRun } = options;
+  const host = NodeJS_HOST;
+
+  const { name, source } = await determinePackageManager(
+    host,
+    cwd,
+    configuredPackageManager,
+    logger,
+  );
+
+  if (!SUPPORTED_PACKAGE_MANAGERS[name]) {
+    throw new Error(`Unsupported package manager: "${name}"`);
+  }
+
+  // Do not verify if the package manager is installed during a dry run.
+  if (!dryRun) {
+    const isInstalled = await isPackageManagerInstalled(host, name, logger);
+    if (!isInstalled) {
+      if (source === 'default') {
+        throw new Error(
+          `'npm' was selected as the default package manager, but it is not installed or` +
+            ` cannot be found in the PATH. Please install 'npm' to continue.`,
+        );
+      } else {
+        throw new Error(
+          `The project is configured to use '${name}', but it is not installed or cannot be` +
+            ` found in the PATH. Please install '${name}' to continue.`,
+        );
+      }
+    }
+  }
+
+  logger?.debug(`Successfully created PackageManager for '${name}'.`);
+  const descriptor = SUPPORTED_PACKAGE_MANAGERS[name];
+
+  return new PackageManager(host, cwd, descriptor, { dryRun, logger });
+}