Use AsyncRecycler for autoinstaller cleanup

Author: kevin-y-ang

common/changes/@microsoft/rush/autoinstaller-move-node-modules-to-recycler_2026-04-07-18-05.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Move stale autoinstaller node_modules folders into Rush's recycler before deleting them, instead of clearing them in place.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

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

@@ -0,0 +1,101 @@
+// 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 './mockRushCommandLineParser';
+
+import { FileSystem } from '@rushstack/node-core-library';
+
+import { Autoinstaller } from '../../logic/Autoinstaller';
+import { InstallHelpers } from '../../logic/installManager/InstallHelpers';
+import { RushConstants } from '../../logic/RushConstants';
+import { Utilities } from '../../utilities/Utilities';
+import {
+  getCommandLineParserInstanceAsync,
+  isolateEnvironmentConfigurationForTests,
+  type IEnvironmentConfigIsolation
+} from './TestUtils';
+
+describe('Autoinstaller', () => {
+  let _envIsolation: IEnvironmentConfigIsolation;
+
+  beforeEach(() => {
+    _envIsolation = isolateEnvironmentConfigurationForTests();
+  });
+
+  afterEach(() => {
+    _envIsolation.restore();
+    jest.restoreAllMocks();
+  });
+
+  it('moves an existing node_modules folder into the Rush recycler before reinstalling', async () => {
+    const { parser, repoPath, spawnMock } = await getCommandLineParserInstanceAsync(
+      'pluginWithBuildCommandRepo',
+      'update'
+    );
+    const autoinstallerPath: string = path.join(repoPath, 'common/autoinstallers/plugins');
+    const nodeModulesFolder: string = path.join(autoinstallerPath, RushConstants.nodeModulesFolderName);
+    const staleFilePath: string = path.join(nodeModulesFolder, 'stale-package/index.js');
+    const recyclerFolder: string = path.join(
+      parser.rushConfiguration.commonTempFolder,
+      RushConstants.rushRecyclerFolderName
+    );
+
+    FileSystem.writeFile(staleFilePath, 'stale', {
+      ensureFolderExists: true
+    });
+
+    const recyclerEntriesBefore: Set<string> = FileSystem.exists(recyclerFolder)
+      ? new Set(FileSystem.readFolderItemNames(recyclerFolder))
+      : new Set();
+
+    jest.spyOn(InstallHelpers, 'ensureLocalPackageManagerAsync').mockResolvedValue(undefined);
+    jest.spyOn(Utilities, 'syncNpmrc').mockImplementation(() => undefined);
+    jest
+      .spyOn(Utilities, 'executeCommandAsync')
+      .mockImplementation(async (options: Parameters<typeof Utilities.executeCommandAsync>[0]) => {
+        FileSystem.ensureFolder(path.join(options.workingDirectory, RushConstants.nodeModulesFolderName));
+      });
+
+    const autoinstaller: Autoinstaller = new Autoinstaller({
+      autoinstallerName: 'plugins',
+      rushConfiguration: parser.rushConfiguration,
+      rushGlobalFolder: parser.rushGlobalFolder
+    });
+
+    await autoinstaller.prepareAsync();
+
+    const recyclerEntriesAfter: string[] = FileSystem.readFolderItemNames(recyclerFolder).filter(
+      (entry: string) => !recyclerEntriesBefore.has(entry)
+    );
+
+    expect(recyclerEntriesAfter).toHaveLength(1);
+    expect(
+      FileSystem.exists(path.join(recyclerFolder, recyclerEntriesAfter[0], 'stale-package/index.js'))
+    ).toBe(true);
+    expect(FileSystem.exists(staleFilePath)).toBe(false);
+    expect(FileSystem.exists(path.join(nodeModulesFolder, 'rush-autoinstaller.flag'))).toBe(true);
+
+    if (process.platform === 'win32') {
+      expect(spawnMock).toHaveBeenCalledWith(
+        'cmd.exe',
+        expect.arrayContaining(['/c']),
+        expect.objectContaining({
+          detached: true,
+          stdio: 'ignore',
+          windowsVerbatimArguments: true
+        })
+      );
+    } else {
+      expect(spawnMock).toHaveBeenCalledWith(
+        'rm',
+        expect.arrayContaining(['-rf']),
+        expect.objectContaining({
+          detached: true,
+          stdio: 'ignore'
+        })
+      );
+    }
+  });
+});

libraries/rush-lib/src/logic/Autoinstaller.ts

@@ -1,13 +1,21 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import colors from 'colors/safe';
-import * as path from 'path';
-
-import { FileSystem, type IPackageJson, JsonFile, LockFile, NewlineKind } from '@rushstack/node-core-library';
+import * as path from 'node:path';
+
+import {
+  FileSystem,
+  type IPackageJson,
+  JsonFile,
+  LockFile,
+  NewlineKind,
+  PackageName,
+  type IParsedPackageNameOrError
+} from '@rushstack/node-core-library';
+import { Colorize } from '@rushstack/terminal';
+
+import { AsyncRecycler } from '../utilities/AsyncRecycler';
 import { Utilities } from '../utilities/Utilities';
-
-import { PackageName, type IParsedPackageNameOrError } from '@rushstack/node-core-library';
 import type { RushConfiguration } from '../api/RushConfiguration';
 import { PackageJsonEditor } from '../api/PackageJsonEditor';
 import { InstallHelpers } from './installManager/InstallHelpers';
@@ -17,7 +25,7 @@ import { LastInstallFlag } from '../api/LastInstallFlag';
 import { RushCommandLineParser } from '../cli/RushCommandLineParser';
 import type { PnpmPackageManager } from '../api/packageManager/PnpmPackageManager';
 
-interface IAutoinstallerOptions {
+export interface IAutoinstallerOptions {
   autoinstallerName: string;
   rushConfiguration: RushConfiguration;
   rushGlobalFolder: RushGlobalFolder;
@@ -79,7 +87,7 @@ export class Autoinstaller {
       );
     }
 
-    await InstallHelpers.ensureLocalPackageManager(
+    await InstallHelpers.ensureLocalPackageManagerAsync(
       this._rushConfiguration,
       this._rushGlobalFolder,
       RushConstants.defaultMaxInstallAttempts,
@@ -94,7 +102,7 @@ export class Autoinstaller {
 
     this._logIfConsoleOutputIsNotRestricted(`Acquiring lock for "${relativePathForLogs}" folder...`);
 
-    const lock: LockFile = await LockFile.acquire(autoinstallerFullPath, 'autoinstaller');
+    const lock: LockFile = await LockFile.acquireAsync(autoinstallerFullPath, 'autoinstaller');
 
     try {
       // Example: .../common/autoinstallers/my-task/.rush/temp
@@ -118,30 +126,39 @@ export class Autoinstaller {
       // Example: ../common/autoinstallers/my-task/node_modules
       const nodeModulesFolder: string = `${autoinstallerFullPath}/${RushConstants.nodeModulesFolderName}`;
       const flagPath: string = `${nodeModulesFolder}/rush-autoinstaller.flag`;
-      const isLastInstallFlagDirty: boolean = !lastInstallFlag.isValid() || !FileSystem.exists(flagPath);
+      const isLastInstallFlagDirty: boolean =
+        !(await lastInstallFlag.isValidAsync()) || !FileSystem.exists(flagPath);
 
       if (isLastInstallFlagDirty || lock.dirtyWhenAcquired) {
         if (FileSystem.exists(nodeModulesFolder)) {
           this._logIfConsoleOutputIsNotRestricted('Deleting old files from ' + nodeModulesFolder);
-          FileSystem.ensureEmptyFolder(nodeModulesFolder);
+          const recycler = new AsyncRecycler(
+            path.join(this._rushConfiguration.commonTempFolder, RushConstants.rushRecyclerFolderName)
+          );
+          recycler.moveFolder(nodeModulesFolder);
+          await recycler.startDeleteAllAsync();
         }
 
         // Copy: .../common/autoinstallers/my-task/.npmrc
-        Utilities.syncNpmrc(this._rushConfiguration.commonRushConfigFolder, autoinstallerFullPath);
+        Utilities.syncNpmrc({
+          sourceNpmrcFolder: this._rushConfiguration.commonRushConfigFolder,
+          targetNpmrcFolder: autoinstallerFullPath,
+          supportEnvVarFallbackSyntax: this._rushConfiguration.isPnpm
+        });
 
         this._logIfConsoleOutputIsNotRestricted(
           `Installing dependencies under ${autoinstallerFullPath}...\n`
         );
 
-        Utilities.executeCommand({
+        await Utilities.executeCommandAsync({
           command: this._rushConfiguration.packageManagerToolFilename,
           args: ['install', '--frozen-lockfile'],
           workingDirectory: autoinstallerFullPath,
           keepEnvironment: true
         });
 
         // Create file: ../common/autoinstallers/my-task/.rush/temp/last-install.flag
-        lastInstallFlag.create();
+        await lastInstallFlag.createAsync();
 
         FileSystem.writeFile(
           flagPath,
@@ -159,7 +176,7 @@ export class Autoinstaller {
   }
 
   public async updateAsync(): Promise<void> {
-    await InstallHelpers.ensureLocalPackageManager(
+    await InstallHelpers.ensureLocalPackageManagerAsync(
       this._rushConfiguration,
       this._rushGlobalFolder,
       RushConstants.defaultMaxInstallAttempts,
@@ -182,7 +199,7 @@ export class Autoinstaller {
       oldFileContents = FileSystem.readFile(this.shrinkwrapFilePath, { convertLineEndings: NewlineKind.Lf });
       this._logIfConsoleOutputIsNotRestricted('Deleting ' + this.shrinkwrapFilePath);
       await FileSystem.deleteFileAsync(this.shrinkwrapFilePath);
-      if (this._rushConfiguration.packageManager === 'pnpm') {
+      if (this._rushConfiguration.isPnpm) {
         // Workaround for https://github.com/pnpm/pnpm/issues/1890
         //
         // When "rush update-autoinstaller" is run, Rush deletes "common/autoinstallers/my-task/pnpm-lock.yaml"
@@ -198,7 +215,7 @@ export class Autoinstaller {
     }
 
     // Detect a common mistake where PNPM prints "Already up-to-date" without creating a shrinkwrap file
-    const packageJsonEditor: PackageJsonEditor = PackageJsonEditor.load(this.packageJsonPath);
+    const packageJsonEditor: PackageJsonEditor = await PackageJsonEditor.loadAsync(this.packageJsonPath);
     if (packageJsonEditor.dependencyList.length === 0) {
       throw new Error(
         'You must add at least one dependency to the autoinstaller package' +
@@ -209,9 +226,13 @@ export class Autoinstaller {
 
     this._logIfConsoleOutputIsNotRestricted();
 
-    Utilities.syncNpmrc(this._rushConfiguration.commonRushConfigFolder, this.folderFullPath);
+    Utilities.syncNpmrc({
+      sourceNpmrcFolder: this._rushConfiguration.commonRushConfigFolder,
+      targetNpmrcFolder: this.folderFullPath,
+      supportEnvVarFallbackSyntax: this._rushConfiguration.isPnpm
+    });
 
-    Utilities.executeCommand({
+    await Utilities.executeCommandAsync({
       command: this._rushConfiguration.packageManagerToolFilename,
       args: ['install'],
       workingDirectory: this.folderFullPath,
@@ -221,8 +242,8 @@ export class Autoinstaller {
     this._logIfConsoleOutputIsNotRestricted();
 
     if (this._rushConfiguration.packageManager === 'npm') {
-      this._logIfConsoleOutputIsNotRestricted(colors.bold('Running "npm shrinkwrap"...'));
-      Utilities.executeCommand({
+      this._logIfConsoleOutputIsNotRestricted(Colorize.bold('Running "npm shrinkwrap"...'));
+      await Utilities.executeCommandAsync({
         command: this._rushConfiguration.packageManagerToolFilename,
         args: ['shrinkwrap'],
         workingDirectory: this.folderFullPath,
@@ -243,11 +264,11 @@ export class Autoinstaller {
     });
     if (oldFileContents !== newFileContents) {
       this._logIfConsoleOutputIsNotRestricted(
-        colors.green('The shrinkwrap file has been updated.') + '  Please commit the updated file:'
+        Colorize.green('The shrinkwrap file has been updated.') + '  Please commit the updated file:'
       );
       this._logIfConsoleOutputIsNotRestricted(`\n  ${this.shrinkwrapFilePath}`);
     } else {
-      this._logIfConsoleOutputIsNotRestricted(colors.green('Already up to date.'));
+      this._logIfConsoleOutputIsNotRestricted(Colorize.green('Already up to date.'));
     }
   }