dev-disk-doctor 0.0.0-stage → 0.1.0

package/dist/src/core/util.js

@@ -0,0 +1,74 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+export async function pathExists(p) {
+    try {
+        await fs.lstat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function isDir(p) {
+    try {
+        return (await fs.stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function listDir(p) {
+    try {
+        return await fs.readdir(p);
+    }
+    catch {
+        return [];
+    }
+}
+export async function readText(p) {
+    try {
+        return await fs.readFile(p, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+export function fmtBytes(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let i = 0;
+    let v = n;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v >= 100 || i === 0 ? v.toFixed(0) : v.toFixed(1)} ${units[i]}`;
+}
+/** Parse sizes printed by Docker ("196.2GB", "58.38MB", "0B"). Docker uses decimal units. */
+export function parseDockerSize(s) {
+    const m = /^\s*(-?[\d.]+)\s*([kKmMgGtT]?)B/.exec(s);
+    if (!m)
+        return 0;
+    const n = Number(m[1]);
+    const mult = { '': 1, k: 1e3, m: 1e6, g: 1e9, t: 1e12 };
+    return Math.max(0, Math.round(n * (mult[m[2].toLowerCase()] ?? 1)));
+}
+export function expandHome(p, home) {
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/'))
+        return path.join(home, p.slice(2));
+    return p;
+}
+/** True when `child` is `parent` or lives inside it. */
+export function isInside(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+export function shellQuote(s) {
+    return /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+export function daysAgo(ms, now = Date.now()) {
+    return Math.floor((now - ms) / 86_400_000);
+}

package/dist/src/core/version.js

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The published package version, read from package.json next to the compiled files. */
+export function version() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    for (const rel of ['../../package.json', '../../../package.json']) {
+        try {
+            return JSON.parse(readFileSync(path.join(here, rel), 'utf8')).version;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return 'unknown';
+}

package/dist/src/detectors/android.js

@@ -0,0 +1,94 @@
+import path from 'node:path';
+import { sizeOf } from '../core/size.js';
+import { isDir, listDir, readText } from '../core/util.js';
+import { pathFinding, removeAction } from './helpers.js';
+function sdkRoots(home) {
+    const roots = [process.env.ANDROID_SDK_ROOT, process.env.ANDROID_HOME].filter((v) => Boolean(v));
+    roots.push(path.join(home, 'Library/Android/sdk'), path.join(home, 'Android/Sdk'));
+    return [...new Set(roots)];
+}
+/** Image folders referenced by AVDs, as `android-36/google_apis_playstore/arm64-v8a`. */
+async function imagesInUse(home) {
+    const used = new Set();
+    const avdDir = process.env.ANDROID_AVD_HOME ?? path.join(home, '.android/avd');
+    for (const entry of await listDir(avdDir)) {
+        if (!entry.endsWith('.avd'))
+            continue;
+        const cfg = await readText(path.join(avdDir, entry, 'config.ini'));
+        const m = cfg && /^image\.sysdir\.1\s*=\s*(.+)$/m.exec(cfg);
+        if (m)
+            used.add(m[1].trim().replace(/^system-images\//, '').replace(/\/+$/, ''));
+    }
+    return used;
+}
+export const android = {
+    id: 'android',
+    title: 'Android SDK and emulators',
+    async run(opts) {
+        const findings = [];
+        const used = await imagesInUse(opts.home);
+        for (const sdk of sdkRoots(opts.home)) {
+            const imagesRoot = path.join(sdk, 'system-images');
+            if (!(await isDir(imagesRoot)))
+                continue;
+            for (const api of await listDir(imagesRoot)) {
+                for (const tag of await listDir(path.join(imagesRoot, api))) {
+                    for (const abi of await listDir(path.join(imagesRoot, api, tag))) {
+                        const dir = path.join(imagesRoot, api, tag, abi);
+                        if (!(await isDir(dir)))
+                            continue;
+                        const key = `${api}/${tag}/${abi}`;
+                        const bytes = await sizeOf(dir, opts.detectorTimeoutMs);
+                        if (bytes === undefined || bytes < opts.minBytes)
+                            continue;
+                        const id = `android:image:${key}`;
+                        const inUse = used.has(key);
+                        findings.push({
+                            id,
+                            detector: 'android',
+                            category: 'mobile',
+                            title: `Android emulator image ${key}${inUse ? ' (used by an AVD)' : ''}`,
+                            path: dir,
+                            bytes,
+                            risk: inUse ? 'danger' : 'review',
+                            regenerable: true,
+                            why: inUse
+                                ? 'An existing virtual device boots from this image. Removing it breaks that emulator.'
+                                : 'System image no virtual device uses. Re-downloadable from the SDK Manager.',
+                            actions: inUse ? [] : [removeAction(id, dir, 'review', bytes, 'You will need to re-download it if you create an emulator for this API level later.')],
+                            meta: { inUse },
+                        });
+                    }
+                }
+            }
+            const extras = await Promise.all([
+                pathFinding({
+                    detector: 'android',
+                    key: 'ndk',
+                    category: 'mobile',
+                    title: 'Android NDK versions',
+                    path: path.join(sdk, 'ndk'),
+                    risk: 'review',
+                    regenerable: true,
+                    why: 'Native toolchains. Several versions pile up as projects pin different ones; keep the ones your projects use.',
+                    removable: false,
+                }, opts),
+            ]);
+            findings.push(...extras.filter((f) => f !== undefined));
+        }
+        const avds = await pathFinding({
+            detector: 'android',
+            key: 'avd',
+            category: 'mobile',
+            title: 'Android virtual devices (AVD data)',
+            path: process.env.ANDROID_AVD_HOME ?? path.join(opts.home, '.android/avd'),
+            risk: 'review',
+            regenerable: false,
+            why: 'Disk images and snapshots for your emulators, including any app data installed on them. Wipe a device in Android Studio rather than deleting the folder.',
+            removable: false,
+        }, opts);
+        if (avds)
+            findings.push(avds);
+        return findings;
+    },
+};

package/dist/src/detectors/biggest.js

@@ -0,0 +1,67 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { sizeOf } from '../core/size.js';
+import { isInside } from '../core/util.js';
+import { manualAction } from './helpers.js';
+/** Folders we look inside of, instead of reporting as one opaque lump. */
+function expandable(home) {
+    const lib = path.join(home, 'Library');
+    return new Set(['Containers', 'Application Support', 'Caches', 'Group Containers', 'Android'].map((n) => path.join(lib, n)).concat(lib));
+}
+async function children(dir) {
+    try {
+        return (await fs.readdir(dir)).map((n) => path.join(dir, n));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Sweep for space the specific detectors do not know about. Reports each top-level
+ * folder's *uncovered remainder* (its size minus what other findings already explain).
+ */
+export const biggest = {
+    id: 'biggest',
+    title: 'Everything else: unknown space hogs',
+    deepOnly: true,
+    async run(opts, covered) {
+        const expand = expandable(opts.home);
+        const queue = await children(opts.home);
+        const entries = [];
+        while (queue.length) {
+            const p = queue.pop();
+            if (expand.has(p))
+                queue.push(...(await children(p)));
+            else
+                entries.push(p);
+        }
+        const known = covered().filter((f) => f.path && f.bytes > 0);
+        const findings = [];
+        await Promise.all(entries.map(async (p) => {
+            const total = await sizeOf(p, opts.detectorTimeoutMs * 2);
+            if (total === undefined)
+                return;
+            const inside = known.filter((f) => isInside(f.path, p));
+            // Findings that are themselves nested only count once.
+            const outer = inside.filter((f) => !inside.some((g) => g !== f && g.path !== f.path && isInside(f.path, g.path)));
+            const explained = outer.reduce((s, f) => s + f.bytes, 0);
+            const remainder = total - explained;
+            if (remainder < opts.minBytes)
+                return;
+            const id = `biggest:${p}`;
+            findings.push({
+                id,
+                detector: 'biggest',
+                category: 'unknown',
+                title: `${p.replace(opts.home, '~')}${explained > 0 ? ` (excluding ${outer.length} item${outer.length === 1 ? '' : 's'} listed above)` : ''}`,
+                path: p,
+                bytes: remainder,
+                risk: 'review',
+                regenerable: false,
+                why: 'Not recognised by any specific check. Look inside before deleting; an app\'s own settings, or its in-app "clear cache" option, is usually the safe route.',
+                actions: [manualAction(id, 'inspect', 'See what is inside', `du -sh ${JSON.stringify(p)}/* | sort -rh | head -20`, 'safe')],
+            });
+        }));
+        return findings;
+    },
+};

package/dist/src/detectors/browsers-models.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { pathFindings } from './helpers.js';
+export const browsers = {
+    id: 'browsers',
+    title: 'Test browsers (Playwright, Puppeteer, Cypress)',
+    async run(opts) {
+        const h = opts.home;
+        const mac = opts.platform === 'darwin';
+        const why = 'Browser binaries downloaded for automated testing, one set per tool version, so old versions pile up. Re-downloaded by the tool when needed (e.g. `npx playwright install`).';
+        const specs = [
+            { detector: 'browsers', key: 'playwright', category: 'browsers', title: 'Playwright browsers', path: mac ? path.join(h, 'Library/Caches/ms-playwright') : path.join(h, '.cache/ms-playwright'), risk: 'safe', regenerable: true, why },
+            { detector: 'browsers', key: 'puppeteer', category: 'browsers', title: 'Puppeteer browsers', path: path.join(h, '.cache/puppeteer'), risk: 'safe', regenerable: true, why },
+            { detector: 'browsers', key: 'cypress', category: 'browsers', title: 'Cypress binaries', path: mac ? path.join(h, 'Library/Caches/Cypress') : path.join(h, '.cache/Cypress'), risk: 'safe', regenerable: true, why },
+        ];
+        return pathFindings(specs, opts);
+    },
+};
+export const models = {
+    id: 'models',
+    title: 'AI and ML model caches',
+    async run(opts) {
+        const h = opts.home;
+        const why = (what) => `${what} Model files are large and can take hours to download again, so only delete what you no longer use.`;
+        const specs = [
+            { detector: 'models', key: 'huggingface', category: 'ai-models', title: 'Hugging Face model cache', path: path.join(h, '.cache/huggingface'), risk: 'review', regenerable: true, why: why('Models and datasets downloaded by transformers, diffusers and similar libraries.') },
+            { detector: 'models', key: 'ollama', category: 'ai-models', title: 'Ollama models', path: path.join(h, '.ollama/models'), risk: 'review', regenerable: true, why: why('Local LLMs pulled with `ollama pull`.'), warning: 'Prefer `ollama rm <model>` to remove individual models.' },
+            { detector: 'models', key: 'lmstudio', category: 'ai-models', title: 'LM Studio models', path: path.join(h, '.lmstudio/models'), risk: 'review', regenerable: true, why: why('Models downloaded through LM Studio.') },
+            { detector: 'models', key: 'torch', category: 'ai-models', title: 'PyTorch hub cache', path: path.join(h, '.cache/torch'), risk: 'review', regenerable: true, why: why('Pretrained weights fetched by torch and torchvision.') },
+            { detector: 'models', key: 'diffusionbee', category: 'ai-models', title: 'DiffusionBee model assets', path: path.join(h, '.diffusionbee/downloaded_assets'), risk: 'review', regenerable: true, why: why('Stable Diffusion weights downloaded by the DiffusionBee app.') },
+        ];
+        return pathFindings(specs, opts);
+    },
+};

package/dist/src/detectors/docker.js

@@ -0,0 +1,140 @@
+import path from 'node:path';
+import { run } from '../core/exec.js';
+import { sizeOf } from '../core/size.js';
+import { parseDockerSize, pathExists } from '../core/util.js';
+import { execAction, manualAction } from './helpers.js';
+function parseDf(stdout) {
+    const rows = [];
+    for (const line of stdout.split('\n')) {
+        if (!line.trim().startsWith('{'))
+            continue;
+        try {
+            rows.push(JSON.parse(line));
+        }
+        catch {
+            /* ignore partial lines */
+        }
+    }
+    return rows;
+}
+export const docker = {
+    id: 'docker',
+    title: 'Docker',
+    async run(opts) {
+        const findings = [];
+        const candidates = [
+            path.join(opts.home, 'Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw'),
+            path.join(opts.home, 'Library/Containers/com.docker.docker/Data/vms/0/data/Docker.qcow2'),
+            path.join(opts.home, '.docker/desktop/vms/0/data/Docker.raw'),
+        ];
+        let diskImage;
+        let diskBytes = 0;
+        for (const c of candidates) {
+            if (!(await pathExists(c)))
+                continue;
+            const b = (await sizeOf(c, opts.detectorTimeoutMs)) ?? 0;
+            if (b > diskBytes) {
+                diskBytes = b;
+                diskImage = c;
+            }
+        }
+        const df = await run('docker', ['system', 'df', '--format', '{{json .}}'], { timeoutMs: 20_000 });
+        const rows = df.ok ? parseDf(df.stdout) : [];
+        if (diskImage && diskBytes >= opts.minBytes) {
+            const id = 'docker:disk-image';
+            findings.push({
+                id,
+                detector: 'docker',
+                category: 'containers',
+                title: 'Docker Desktop disk image',
+                path: diskImage,
+                bytes: diskBytes,
+                risk: 'danger',
+                regenerable: false,
+                meta: { envelope: true },
+                why: rows.length
+                    ? 'All images, containers, volumes and build cache live inside this one file. It grows but never shrinks on its own, so pruning inside Docker may not give the space back until Docker Desktop compacts it.'
+                    : 'All images, containers, volumes and build cache live inside this one file. Docker is not running, so the contents could not be inspected: start Docker Desktop and scan again.',
+                actions: [
+                    manualAction(id, 'shrink', 'Prune inside Docker first, then compact the image', 'Docker Desktop → Settings → Resources → Disk image size (or Troubleshoot → Clean / Purge data)', 'danger', 'Never delete this file by hand and "Clean / Purge data" removes every image, container and volume, including databases.'),
+                ],
+            });
+        }
+        for (const row of rows) {
+            const reclaim = parseDockerSize(row.Reclaimable.split(' ')[0] ?? '');
+            if (reclaim < opts.minBytes)
+                continue;
+            if (row.Type === 'Images') {
+                const id = 'docker:images';
+                findings.push({
+                    id,
+                    detector: 'docker',
+                    category: 'containers',
+                    title: `Unused Docker images (${row.TotalCount} total, ${row.Active} in use)`,
+                    bytes: reclaim,
+                    risk: 'review',
+                    regenerable: true,
+                    why: 'Images no container uses. Anything pulled from a registry can be pulled again; images you built locally and never pushed must be rebuilt.',
+                    actions: [
+                        execAction(id, 'prune', 'Remove all images not used by any container', 'docker', ['image', 'prune', '-a', '-f'], 'review', {
+                            bytes: reclaim,
+                            warning: 'Images that exist only on this machine (local builds, unpushed tags) are lost.',
+                        }),
+                    ],
+                });
+            }
+            else if (row.Type === 'Build Cache') {
+                const id = 'docker:build-cache';
+                findings.push({
+                    id,
+                    detector: 'docker',
+                    category: 'containers',
+                    title: 'Docker build cache',
+                    bytes: reclaim,
+                    risk: 'safe',
+                    regenerable: true,
+                    why: 'Layers cached from previous builds. Deleting them only makes the next build slower.',
+                    actions: [
+                        execAction(id, 'prune', 'Clear the build cache', 'docker', ['builder', 'prune', '-a', '-f'], 'safe', { bytes: reclaim }),
+                    ],
+                });
+            }
+            else if (row.Type === 'Containers') {
+                const id = 'docker:containers';
+                findings.push({
+                    id,
+                    detector: 'docker',
+                    category: 'containers',
+                    title: 'Stopped Docker containers',
+                    bytes: reclaim,
+                    risk: 'review',
+                    regenerable: false,
+                    why: 'Stopped containers keep their writable layer. Data written inside a container (not in a volume) is lost when it is removed.',
+                    actions: [
+                        execAction(id, 'prune', 'Remove all stopped containers', 'docker', ['container', 'prune', '-f'], 'review', {
+                            bytes: reclaim,
+                            warning: 'Check that nothing you care about lives in a stopped container.',
+                        }),
+                    ],
+                });
+            }
+            else if (row.Type === 'Local Volumes') {
+                const id = 'docker:volumes';
+                findings.push({
+                    id,
+                    detector: 'docker',
+                    category: 'containers',
+                    title: 'Unused Docker volumes',
+                    bytes: reclaim,
+                    risk: 'danger',
+                    regenerable: false,
+                    why: 'Volumes hold persistent data such as local databases. "Unused" means no container is attached right now, not that the data is disposable.',
+                    actions: [
+                        manualAction(id, 'prune', 'Review volumes, then prune', 'docker volume ls   # inspect first, then: docker volume rm <name>', 'danger', 'Deleted volumes cannot be recovered. The tool will not run this for you.'),
+                    ],
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/src/detectors/helpers.js

@@ -0,0 +1,56 @@
+import { sizeOf } from '../core/size.js';
+import { shellQuote } from '../core/util.js';
+export function removeAction(findingId, p, risk, bytes, warning, label = 'Delete this folder') {
+    return {
+        id: `${findingId}#remove`,
+        label,
+        display: `rm -rf ${shellQuote(p)}`,
+        risk,
+        kind: { type: 'remove-path', path: p },
+        reclaimBytes: bytes,
+        warning,
+    };
+}
+export function execAction(findingId, name, label, file, args, risk, extra = {}) {
+    return {
+        id: `${findingId}#${name}`,
+        label,
+        display: [file, ...args].map(shellQuote).join(' '),
+        risk,
+        kind: { type: 'exec', file, args, cwd: extra.cwd },
+        reclaimBytes: extra.bytes,
+        warning: extra.warning,
+    };
+}
+export function manualAction(findingId, name, label, display, risk, warning) {
+    return { id: `${findingId}#${name}`, label, display, risk, kind: { type: 'manual' }, warning };
+}
+/** Build a finding for one directory or file, or undefined if absent or below the size floor. */
+export async function pathFinding(spec, opts) {
+    const bytes = await sizeOf(spec.path, opts.detectorTimeoutMs);
+    if (bytes === undefined || bytes < opts.minBytes)
+        return undefined;
+    const id = `${spec.detector}:${spec.key}`;
+    const actions = spec.actions
+        ? spec.actions(id, bytes)
+        : spec.removable === false
+            ? []
+            : [removeAction(id, spec.path, spec.risk, bytes, spec.warning)];
+    return {
+        id,
+        detector: spec.detector,
+        category: spec.category,
+        title: spec.title,
+        path: spec.path,
+        bytes,
+        risk: spec.risk,
+        regenerable: spec.regenerable,
+        why: spec.why,
+        actions,
+        meta: spec.meta,
+    };
+}
+export async function pathFindings(specs, opts) {
+    const out = await Promise.all(specs.map((s) => pathFinding(s, opts)));
+    return out.filter((f) => f !== undefined);
+}

package/dist/src/detectors/index.js

@@ -0,0 +1,11 @@
+import { android } from './android.js';
+import { biggest } from './biggest.js';
+import { browsers, models } from './browsers-models.js';
+import { docker } from './docker.js';
+import { pkgcaches } from './pkgcaches.js';
+import { projects } from './projects.js';
+import { system } from './system.js';
+import { xcode } from './xcode.js';
+import { worktrees } from '../worktrees/detector.js';
+/** `biggest` must stay last: it subtracts what the others already explain. */
+export const detectors = [docker, android, xcode, pkgcaches, browsers, models, projects, worktrees, system, biggest];

package/dist/src/detectors/pkgcaches.js

@@ -0,0 +1,99 @@
+import path from 'node:path';
+import { run } from '../core/exec.js';
+import { listDir } from '../core/util.js';
+import { execAction, pathFinding, pathFindings } from './helpers.js';
+const REGEN = 'A cache: deleting it only means packages are downloaded again on the next install.';
+async function pnpmFindings(opts) {
+    const out = [];
+    const active = await run('pnpm', ['store', 'path'], { timeoutMs: 15_000 });
+    const activePath = active.ok ? active.stdout.trim() : undefined;
+    const storeRoots = [path.join(opts.home, 'Library/pnpm/store'), path.join(opts.home, '.local/share/pnpm/store')];
+    for (const root of storeRoots) {
+        for (const v of await listDir(root)) {
+            const dir = path.join(root, v);
+            const isActive = activePath === dir;
+            const f = await pathFinding({
+                detector: 'pkgcaches',
+                key: `pnpm-store:${v}`,
+                category: 'package-caches',
+                title: `pnpm store ${v}${isActive ? ' (active for your installed pnpm)' : ''}`,
+                path: dir,
+                risk: 'safe',
+                regenerable: true,
+                why: isActive
+                    ? 'Content-addressable package store shared by every pnpm project. Pruning removes only packages no project links to anymore.'
+                    : 'Store from an older (or newer) pnpm major version that your installed pnpm does not use. Projects keep working: node_modules hard-link copies are independent of the store.',
+                actions: (id, bytes) => isActive
+                    ? [execAction(id, 'prune', 'Prune unreferenced packages', 'pnpm', ['store', 'prune'], 'safe')]
+                    : [
+                        {
+                            id: `${id}#remove`,
+                            label: 'Delete this store',
+                            display: `rm -rf '${dir}'`,
+                            risk: 'safe',
+                            kind: { type: 'remove-path', path: dir },
+                            reclaimBytes: bytes,
+                            warning: 'Next install with that pnpm version re-downloads packages.',
+                        },
+                    ],
+            }, opts);
+            if (f)
+                out.push(f);
+        }
+    }
+    return out;
+}
+export const pkgcaches = {
+    id: 'pkgcaches',
+    title: 'Package manager and toolchain caches',
+    async run(opts) {
+        const h = opts.home;
+        const mac = opts.platform === 'darwin';
+        const lib = (p) => path.join(h, 'Library/Caches', p);
+        const specs = [
+            {
+                detector: 'pkgcaches',
+                key: 'npm',
+                category: 'package-caches',
+                title: 'npm cache (~/.npm)',
+                path: path.join(h, '.npm'),
+                risk: 'safe',
+                regenerable: true,
+                why: 'Downloaded tarballs plus the npx cache. Only speeds up installs.',
+                actions: (id, bytes) => [execAction(id, 'clean', 'Clear the npm cache', 'npm', ['cache', 'clean', '--force'], 'safe', { bytes })],
+            },
+            { detector: 'pkgcaches', key: 'pnpm-meta', category: 'package-caches', title: 'pnpm metadata cache', path: lib('pnpm'), risk: 'safe', regenerable: true, why: REGEN },
+            { detector: 'pkgcaches', key: 'yarn', category: 'package-caches', title: 'Yarn cache', path: lib('Yarn'), risk: 'safe', regenerable: true, why: REGEN },
+            { detector: 'pkgcaches', key: 'yarn-berry', category: 'package-caches', title: 'Yarn Berry global cache', path: path.join(h, '.yarn/berry/cache'), risk: 'safe', regenerable: true, why: REGEN },
+            { detector: 'pkgcaches', key: 'bun', category: 'package-caches', title: 'Bun install cache', path: path.join(h, '.bun/install/cache'), risk: 'safe', regenerable: true, why: REGEN },
+            { detector: 'pkgcaches', key: 'pip', category: 'package-caches', title: 'pip cache', path: mac ? lib('pip') : path.join(h, '.cache/pip'), risk: 'safe', regenerable: true, why: REGEN },
+            { detector: 'pkgcaches', key: 'uv', category: 'package-caches', title: 'uv cache', path: path.join(h, '.cache/uv'), risk: 'safe', regenerable: true, why: REGEN },
+            { detector: 'pkgcaches', key: 'homebrew', category: 'package-caches', title: 'Homebrew downloads cache', path: mac ? lib('Homebrew') : path.join(h, '.cache/Homebrew'), risk: 'safe', regenerable: true, why: 'Old bottles and downloads Homebrew keeps after installing.', actions: (id, bytes) => [execAction(id, 'cleanup', 'Run brew cleanup', 'brew', ['cleanup', '--prune=all', '-s'], 'safe', { bytes })] },
+            { detector: 'pkgcaches', key: 'cargo-registry', category: 'package-caches', title: 'Cargo registry cache', path: path.join(h, '.cargo/registry'), risk: 'safe', regenerable: true, why: REGEN },
+            { detector: 'pkgcaches', key: 'cargo-git', category: 'package-caches', title: 'Cargo git checkouts', path: path.join(h, '.cargo/git'), risk: 'safe', regenerable: true, why: REGEN },
+            { detector: 'pkgcaches', key: 'gradle-caches', category: 'package-caches', title: 'Gradle caches', path: path.join(h, '.gradle/caches'), risk: 'safe', regenerable: true, why: 'Dependency and build caches. The next Gradle build re-downloads what it needs, which can take a while.', warning: 'Stop Gradle daemons first (`./gradlew --stop`).' },
+            { detector: 'pkgcaches', key: 'gradle-wrapper', category: 'package-caches', title: 'Gradle wrapper distributions', path: path.join(h, '.gradle/wrapper/dists'), risk: 'safe', regenerable: true, why: 'One Gradle install per version your projects asked for. Re-downloaded on demand.' },
+            { detector: 'pkgcaches', key: 'maven', category: 'package-caches', title: 'Maven local repository', path: path.join(h, '.m2/repository'), risk: 'review', regenerable: true, why: 'Maven artifacts, including any you installed locally from your own builds, which cannot be downloaded again.' },
+            { detector: 'pkgcaches', key: 'cocoapods', category: 'package-caches', title: 'CocoaPods cache', path: lib('CocoaPods'), risk: 'safe', regenerable: true, why: REGEN },
+            { detector: 'pkgcaches', key: 'go-build', category: 'package-caches', title: 'Go build cache', path: mac ? lib('go-build') : path.join(h, '.cache/go-build'), risk: 'safe', regenerable: true, why: 'Compiled package cache. Rebuilt on the next build.' },
+            { detector: 'pkgcaches', key: 'jetbrains', category: 'package-caches', title: 'JetBrains IDE caches', path: lib('JetBrains'), risk: 'safe', regenerable: true, why: 'Indexes and caches for IntelliJ, WebStorm, Android Studio and friends. Rebuilt when you reopen projects.', warning: 'Quit the IDE first.' },
+            { detector: 'pkgcaches', key: 'chrome-cache', category: 'package-caches', title: 'Google Chrome cache', path: lib('Google'), risk: 'safe', regenerable: true, why: 'Browser cache. Chrome refills it as you browse.', warning: 'Quit Chrome first.' },
+        ];
+        const conda = ['miniconda3', 'anaconda3', 'miniforge3', 'mambaforge'].map((d) => path.join(h, d));
+        for (const base of conda) {
+            specs.push({
+                detector: 'pkgcaches',
+                key: `conda-pkgs:${path.basename(base)}`,
+                category: 'package-caches',
+                title: `Conda package cache (${path.basename(base)})`,
+                path: path.join(base, 'pkgs'),
+                risk: 'safe',
+                regenerable: true,
+                why: 'Downloaded conda packages and extracted copies. `conda clean` removes the ones no environment uses.',
+                actions: (id, bytes) => [execAction(id, 'clean', 'Run conda clean --all', path.join(base, 'bin/conda'), ['clean', '--all', '--yes'], 'safe', { bytes })],
+            });
+        }
+        const found = await pathFindings(specs, opts);
+        return [...found, ...(await pnpmFindings(opts))];
+    },
+};