Workspace Cleanup Orchestrator

A Node-based utility that removes selected dependencies, prunes extraneous installs, and rebuilds the remaining tree to keep a project consistent after package changes.

Capabilities

Remove requested dependencies

• Given a project with dependencies alpha and beta, removing only alpha updates the manifest and lock data accordingly while keeping beta installed. @test
• When asked to remove a package that is not in the manifest, the tool leaves manifests unchanged and reports no removals. @test

Prune extraneous modules

• If node_modules contains a folder not declared in the manifest (for example, unused-lib), running the cleanup process deletes that extraneous module while preserving declared dependencies. @test

Rebuild remaining installs

• After removals and pruning, the cleanup process rebuilds installed modules (or a provided subset) so native components are recompiled and ready to run. @test

Implementation

@generates

API

export interface CleanupOptions {
  /**
   * Project directory containing package metadata and node_modules.
   */
  cwd?: string;
  /**
   * Package names to remove from dependencies and devDependencies.
   */
  remove: string[];
  /**
   * Whether to remove matching entries from devDependencies as well.
   * Defaults to true.
   */
  includeDev?: boolean;
  /**
   * Controls rebuild behavior:
   * - true: rebuild all installed modules
   * - string[]: rebuild only the specified modules
   * - false/undefined: skip rebuild
   */
  rebuild?: boolean | string[];
}

export interface CleanupResult {
  removed: string[];
  pruned: boolean;
  rebuilt: string[];
}

/**
 * Orchestrates dependency removal, pruning of extraneous installs, and rebuilds.
 * Executes the three stages in order: remove -> prune -> rebuild.
 */
export function cleanupProject(options: CleanupOptions): Promise<CleanupResult>;

Dependencies { .dependencies }

npm CLI { .dependency }

Provides uninstall, pruning, and rebuild capabilities for project dependencies.

@satisfied-by