Cache Maintenance Utility

A small helper that reports and cleans package manager caches for installed modules and the bundled command runner. It should lean on the dependency's built-in cache tooling rather than reimplementing cache semantics.

Capabilities

Discover cache locations

• Resolves npm and command-runner cache paths to absolute locations using package configuration, honoring an optional cacheRoot override. @test

Inspect caches

• Returns path, total size in bytes, entry count, and an integrity flag for npm cache contents, optionally including the command-runner cache. Validation should use the dependency's cache inspection rather than manual file walks. @test

Purge caches selectively

• Removes cached artifacts for a chosen target (npm, command-runner, or both) and reports bytes and entries removed. The command-runner cache may be cleared without touching the npm cache when requested. @test

Dry-run preview

• With dry-run enabled, produces the same removal plan and metrics without deleting any cache files. @test

Implementation

@generates

API

export type CacheTarget = "npm" | "npx" | "all";

export interface CachePaths {
  npm: string;
  npx: string;
}

export interface CacheDetails {
  path: string;
  sizeBytes: number;
  entries: number;
  verified: boolean;
}

export interface InspectOptions {
  cacheRoot?: string;
  includeNpx?: boolean;
}

export interface PurgeOptions {
  cacheRoot?: string;
  target?: CacheTarget;
  dryRun?: boolean;
}

export function locateCaches(opts?: { cacheRoot?: string }): CachePaths;

export function inspectCaches(opts?: InspectOptions): Promise<{
  npm: CacheDetails;
  npx?: CacheDetails;
}>;

export function purgeCaches(opts?: PurgeOptions): Promise<{
  target: CacheTarget;
  removedBytes: number;
  removedEntries: number;
  dryRun: boolean;
}>;

Dependencies { .dependencies }

npm { .dependency }

Provides commands for discovering, verifying, and cleaning cache directories used by the package manager and bundled command runner.