dev-disk-doctor 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prageeth Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# dev-disk-doctor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Why is my disk full?** A read-only disk and git-worktree doctor for developer machines. It finds the space hogs (Docker, Android emulators, Xcode, `node_modules`, package caches, AI models, orphaned git worktrees), explains each one, and gives you a ready-to-run fix with a warning when one is needed.
+
+Works as a CLI and as an **MCP server**, so an AI agent (Claude Code, Cursor, Codex…) can run it, show you the options, and ask before touching anything.
+
+```bash
+npx dev-disk-doctor            # scan, read-only
+npx dev-disk-doctor worktrees  # how many git worktrees do I have, and which are leftovers?
+```
+
+## Getting started
+
+You need [Node.js](https://nodejs.org) 18 or newer. Nothing else to install.
+
+1. **Scan** (read-only, about a minute on a big disk):
+   ```bash
+   npx dev-disk-doctor
+   ```
+   You get a ranked list. Each item says what it is, how big it is, how risky deleting it is, and the exact command to fix it.
+2. **Check the git worktrees** (also read-only):
+   ```bash
+   npx dev-disk-doctor worktrees
+   ```
+3. **Fix one item at a time.** Copy the `id:` shown under an action. This shows what would happen and changes nothing:
+   ```bash
+   npx dev-disk-doctor fix "docker:build-cache#prune"
+   ```
+   Add `--yes` to actually run it.
+4. **Or let an AI agent drive it**; see [Use it with an AI agent](#use-it-with-an-ai-agent-mcp) below.
+
+To install it globally instead of using `npx`: `npm install -g dev-disk-doctor`, then run `dev-disk-doctor`.
+
+## Where it looks for your projects
+
+Projects, `node_modules` and git worktrees are searched in your *workspace folders*. You don't have to configure them:
+
+- Common names directly under your home folder are always used if they exist: `dev`, `code`, `src`, `projects`, `work`, `workspace`, `workspaces`, `Developer`, `repos`, `git`, `Sites`.
+- **Any other visible folder directly under your home that contains a git repo or project** within three levels is picked up too. So a company folder such as `~/acme` is found automatically, even though it has an arbitrary name.
+- Also checked automatically, for worktrees: the places AI coding tools park them (`~/.codex/worktrees`, `~/.cursor/worktrees`, `~/.claude/worktrees`, `~/conductor`), and `.claude/worktrees` inside any repo.
+- Never searched by default: `~/Documents`, `~/Desktop`, `~/Downloads`, `~/Library`, `~/Applications`, hidden folders, and cloud-sync folders (Dropbox, OneDrive, Google Drive, iCloud…), because they are slow and can trigger permission prompts.
+
+See what it will use:
+
+```bash
+npx dev-disk-doctor roots
+```
+
+Override it when your code lives somewhere else (for example `~/Documents/GitHub` or an external drive):
+
+```bash
+npx dev-disk-doctor --root ~/Documents/GitHub --root /Volumes/Work/code
+# or, for every run:
+export DEV_DISK_DOCTOR_ROOTS="$HOME/Documents/GitHub:/Volumes/Work/code"
+```
+
+When you pass `--root` or set `DEV_DISK_DOCTOR_ROOTS`, auto-discovery is turned off and only those folders are searched.
+
+## What it checks
+
+| Area | Examples |
+|---|---|
+| Containers | Docker Desktop disk image (`Docker.raw`), unused images, build cache, stopped containers, volumes |
+| Mobile | Android emulator system images (never one an AVD uses), AVD data, NDKs, Xcode DerivedData, DeviceSupport, simulators |
+| Package caches | npm, pnpm (old store versions too), Yarn, Bun, pip, uv, conda, Homebrew, Cargo, Gradle, Maven, CocoaPods, Go |
+| Test browsers | Playwright, Puppeteer, Cypress downloads |
+| AI models | Hugging Face, Ollama, LM Studio, PyTorch hub, DiffusionBee |
+| Projects | `node_modules`, `.next`, Rust `target/`, `Pods/`, Python venvs in your workspaces, with how long the project has been idle |
+| **Git worktrees** | Every linked worktree in every repo under your workspaces, including those made by Claude Code, Codex, Cursor and Conductor: active, stale, dangling, locked, at-risk, or orphaned |
+| System | Trash, big Downloads, logs, iOS backups, Time Machine local snapshots |
+| Everything else | `--deep` sweeps your home folder for hogs nobody else recognises |
+
+## Safe by design
+
+- **Scanning never changes anything.** No network, no telemetry.
+- Every finding has a risk level: `SAFE` (regenerates on its own), `REVIEW` (probably fine, check first) or `CAREFUL` (could lose data, never run by the tool).
+- `fix <action-id>` is a **dry run** unless you add `--yes`. Actions come from a fixed allowlist built by the scanners; the tool never executes free-form commands.
+- Worktrees are offered for removal only when they are clean, unlocked, and merged or fully pushed. Dirty worktrees, unpushed commits and Docker volumes are reported with a warning and no apply path.
+- It will not delete anything outside your home folder, your home folder itself, or `Documents`, `Desktop`, `Library` and other top-level folders.
+
+## Use it with an AI agent (MCP)
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "dev-disk-doctor": { "command": "npx", "args": ["-y", "dev-disk-doctor", "mcp"] }
+  }
+}
+```
+
+Claude Code: `claude mcp add dev-disk-doctor -- npx -y dev-disk-doctor mcp`
+
+| Tool | What it does |
+|---|---|
+| `disk_scan` | Ranked findings with explanations, risk and available actions |
+| `worktree_audit` | All repos, all worktrees, which are stale, dangling, orphaned or at risk |
+| `explain_finding` | Re-checks one finding |
+| `apply_action` | Runs one allowlisted action. Dry run unless `confirm: true`. Refuses anything risky |
+
+No MCP? Give your agent the playbook in [`skills/dev-disk-doctor/SKILL.md`](skills/dev-disk-doctor/SKILL.md) and it can drive the CLI with `--json`.
+
+## CLI
+
+```text
+dev-disk-doctor [scan]            Scan for space hogs (read-only)
+dev-disk-doctor worktrees         Audit git worktrees across all your repos
+dev-disk-doctor fix <action-id>   Show what an action does; add --yes to run it
+dev-disk-doctor roots             Show which workspace folders will be searched
+dev-disk-doctor mcp               Start the MCP server on stdio
+
+--json  --root <dir>  --min-size <MB>  --stale-days <n>  --only <detector>  --deep  --all  --yes
+```
+
+## Why does macOS say "Documents" is 230 GB?
+
+macOS Storage settings has a category called **Documents** that is not your `~/Documents` folder. It is everything macOS cannot file under Apps, Photos, Mail or System, which for a developer means `~/Library` (Docker's disk image, Android SDK images, app data), `~/.cache`, `~/.npm`, model downloads and your code. Run `npx dev-disk-doctor` to see what is actually in there.
+
+## Common questions
+
+- **How do I shrink `Docker.raw`?** Prune inside Docker (`docker image prune -a`, `docker builder prune -a`), then compact the disk image in Docker Desktop → Settings → Resources. The tool reports what is reclaimable and warns about volumes.
+- **How do I delete old Android system images?** The scan lists every image under `~/Library/Android/sdk/system-images`, marks the ones your emulators use, and gives a removal command for the rest.
+- **How do I find stale git worktrees?** `npx dev-disk-doctor worktrees` lists every linked worktree across your repos with its state and size. AI coding tools create many; some get orphaned.
+- **Is the pnpm store safe to delete?** It is a cache. Old store versions (`v3`, `v10`) that your installed pnpm does not use can go; the active one is pruned rather than deleted.
+
+## Platform support
+
+macOS is the primary target and is tested. Linux works for the cross-platform checks (Docker, package caches, models, projects, worktrees). Windows is not supported yet.
+
+## Development
+
+```bash
+npm install
+npm test        # builds, then runs the node:test suite
+npm run scan    # build and run against your machine
+```
+
+The scanner core is in `src/core`, one file per area in `src/detectors`, the worktree audit in `src/worktrees`, and the MCP server in `src/mcp.ts`. See [PLAN.md](PLAN.md) for the design.
+
+## Releasing (maintainers)
+
+Pushing a `v*` tag publishes to npm through GitHub Actions. Setup, the release steps, how to verify a release and troubleshooting are in [docs/RELEASING.md](docs/RELEASING.md).
+
+## License
+
+MIT

package/dist/src/cli.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { applyAction } from './core/fix.js';
+import { buildOptions, scan } from './core/scan.js';
+import { version } from './core/version.js';
+import { expandHome } from './core/util.js';
+import { renderScan, renderWorktrees } from './report/text.js';
+import { auditWorktrees } from './worktrees/audit.js';
+const HELP = `dev-disk-doctor: find out why your developer machine's disk is full
+
+Usage
+  dev-disk-doctor [scan]            Scan for space hogs (read-only)
+  dev-disk-doctor worktrees         Audit git worktrees across all your repos (read-only)
+  dev-disk-doctor fix <action-id>   Show what an action would do; add --yes to run it
+  dev-disk-doctor roots             Show which workspace folders will be searched
+  dev-disk-doctor mcp               Start the MCP server on stdio (for AI agents)
+
+Options
+  --json                 Machine-readable output (stable schema)
+  --root <dir>           Workspace folder to search for projects and repos (repeatable).
+                         Default: ~/dev ~/code ~/src ... plus any other folder directly under
+                         your home that contains a git repo (e.g. ~/acme). Also settable with
+                         DEV_DISK_DOCTOR_ROOTS=/path/a:/path/b. Run "roots" to see the result.
+  --min-size <MB>        Ignore items smaller than this (default 100)
+  --stale-days <n>       Days idle before a project or worktree counts as stale (default 30)
+  --only <detector>      Run one detector (docker, android, xcode, pkgcaches, browsers,
+                         models, projects, worktrees, system, biggest). Repeatable.
+  --deep                 Also sweep your whole home folder for unknown space hogs (slow)
+  --all                  Show every finding instead of the top 25
+  --yes                  With "fix": actually run the action
+  --no-color             Plain output
+  -v, --version          Print the version
+
+Nothing is deleted unless you run "fix <id> --yes". Actions marked CAREFUL are never run by the tool.`;
+function parse(argv) {
+    const p = { command: 'scan', positional: [], json: false, roots: [], only: [], deep: false, all: false, yes: false, color: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR };
+    const args = [...argv];
+    const need = (flag) => {
+        const v = args.shift();
+        if (v === undefined)
+            throw new Error(`${flag} needs a value`);
+        return v;
+    };
+    let first = true;
+    while (args.length) {
+        const a = args.shift();
+        if (a === '--json')
+            p.json = true;
+        else if (a === '--root')
+            p.roots.push(need(a));
+        else if (a === '--min-size')
+            p.minMb = Number(need(a));
+        else if (a === '--stale-days')
+            p.staleDays = Number(need(a));
+        else if (a === '--only')
+            p.only.push(need(a));
+        else if (a === '--deep')
+            p.deep = true;
+        else if (a === '--all')
+            p.all = true;
+        else if (a === '--yes' || a === '-y')
+            p.yes = true;
+        else if (a === '--no-color')
+            p.color = false;
+        else if (a === '-h' || a === '--help' || a === 'help')
+            p.command = 'help';
+        else if (a === '-v' || a === '--version')
+            p.command = 'version';
+        else if (a.startsWith('-'))
+            throw new Error(`Unknown option ${a}. Try --help.`);
+        else if (first)
+            p.command = a;
+        else
+            p.positional.push(a);
+        first = false;
+    }
+    return p;
+}
+async function options(p) {
+    const home = process.env.HOME ?? '';
+    return buildOptions({
+        roots: p.roots.map((r) => path.resolve(expandHome(r, home))),
+        minBytes: p.minMb !== undefined ? p.minMb * 1024 * 1024 : undefined,
+        staleDays: p.staleDays,
+        deep: p.deep,
+        only: p.only.length ? p.only : undefined,
+    });
+}
+async function main() {
+    const p = parse(process.argv.slice(2));
+    switch (p.command) {
+        case 'help':
+            console.log(HELP);
+            return;
+        case 'version':
+            console.log(version());
+            return;
+        case 'mcp': {
+            const { startMcp } = await import('./mcp.js');
+            await startMcp();
+            return;
+        }
+        case 'roots': {
+            const opts = await options(p);
+            if (p.json)
+                console.log(JSON.stringify({ roots: opts.roots }, null, 2));
+            else if (opts.roots.length)
+                console.log(opts.roots.join('\n'));
+            else
+                console.log('No workspace folders found under your home. Pass --root <dir> or set DEV_DISK_DOCTOR_ROOTS.');
+            return;
+        }
+        case 'scan': {
+            const opts = await options(p);
+            if (!p.json)
+                console.error('Scanning (read-only)… this can take a minute on a big disk.');
+            const result = await scan(opts);
+            console.log(p.json ? JSON.stringify(result, null, 2) : renderScan(result, { color: p.color }, { limit: p.all ? Infinity : 25 }));
+            return;
+        }
+        case 'worktrees': {
+            const opts = await options(p);
+            if (!p.json)
+                console.error('Auditing worktrees (read-only)…');
+            const audit = await auditWorktrees(opts);
+            console.log(p.json ? JSON.stringify(audit, null, 2) : renderWorktrees(audit, { color: p.color }, opts.home));
+            return;
+        }
+        case 'fix': {
+            const id = p.positional[0];
+            if (!id)
+                throw new Error('fix needs an action id, e.g. dev-disk-doctor fix "docker:build-cache#prune"');
+            const opts = await options(p);
+            const res = await applyAction(opts, id, p.yes);
+            if (p.json)
+                console.log(JSON.stringify(res, null, 2));
+            else {
+                console.log(res.message);
+                if (res.command)
+                    console.log(`$ ${res.command}`);
+                if (res.warning)
+                    console.log(`! ${res.warning}`);
+                if (res.output)
+                    console.log(res.output);
+                if (res.freedBytes !== undefined && !res.dryRun)
+                    console.log(`Free space changed by ${(res.freedBytes / 1024 ** 3).toFixed(2)} GB.`);
+            }
+            if (!res.ok)
+                process.exitCode = 1;
+            return;
+        }
+        default:
+            throw new Error(`Unknown command "${p.command}". Try --help.`);
+    }
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exitCode = 1;
+});

package/dist/src/core/exec.js

@@ -0,0 +1,28 @@
+import { execFile } from 'node:child_process';
+/** Run a program without a shell. Never throws. */
+export function run(file, args, opts = {}) {
+    return new Promise((resolve) => {
+        execFile(file, args, {
+            cwd: opts.cwd,
+            timeout: opts.timeoutMs ?? 30_000,
+            maxBuffer: opts.maxBuffer ?? 16 * 1024 * 1024,
+            encoding: 'utf8',
+            env: { ...process.env, LC_ALL: 'C', GIT_TERMINAL_PROMPT: '0' },
+        }, (err, stdout, stderr) => {
+            if (!err)
+                return resolve({ ok: true, code: 0, stdout, stderr, timedOut: false });
+            const e = err;
+            resolve({
+                ok: false,
+                code: typeof e.code === 'number' ? e.code : null,
+                stdout: stdout ?? '',
+                stderr: stderr || e.message,
+                timedOut: Boolean(e.killed),
+            });
+        });
+    });
+}
+export async function commandExists(file) {
+    const r = await run(process.platform === 'win32' ? 'where' : 'which', [file], { timeoutMs: 5000 });
+    return r.ok;
+}

package/dist/src/core/fix.js

@@ -0,0 +1,74 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { run } from './exec.js';
+import { diskInfo, scan } from './scan.js';
+import { isInside } from './util.js';
+const PROTECTED_HOME_CHILDREN = new Set(['Documents', 'Desktop', 'Pictures', 'Movies', 'Music', 'Public', 'Applications', 'Library', 'Downloads']);
+/** Defence in depth: detectors only ever produce safe paths, but never trust that blindly. */
+export function assertSafeToRemove(target, opts) {
+    if (!path.isAbsolute(target))
+        throw new Error('Refusing to delete a relative path.');
+    const normalized = path.resolve(target);
+    if (normalized !== target.replace(/\/+$/, '') && normalized !== target)
+        throw new Error('Refusing to delete a non-normalised path.');
+    if (!isInside(normalized, opts.home) || normalized === opts.home)
+        throw new Error('Refusing to delete anything outside your home folder.');
+    const rel = path.relative(opts.home, normalized);
+    if (PROTECTED_HOME_CHILDREN.has(rel))
+        throw new Error(`Refusing to delete ~/${rel} itself.`);
+    if (opts.roots.some((r) => path.resolve(r) === normalized))
+        throw new Error('Refusing to delete a workspace root.');
+}
+export function findAction(findings, actionId) {
+    for (const finding of findings) {
+        const action = finding.actions.find((a) => a.id === actionId);
+        if (action)
+            return { finding, action };
+    }
+    return undefined;
+}
+/**
+ * Re-scans just the owning detector (so state is fresh), then runs one allowlisted action.
+ * Dry run unless `confirm` is true.
+ */
+export async function applyAction(opts, actionId, confirm = false) {
+    const hash = actionId.lastIndexOf('#');
+    const findingId = hash > 0 ? actionId.slice(0, hash) : actionId;
+    const detector = findingId.split(':')[0];
+    const base = { dryRun: !confirm, findingId, actionId };
+    if (detector === 'biggest')
+        return { ...base, ok: false, dryRun: true, message: 'Findings from the whole-home sweep have no automatic actions.' };
+    const result = await scan({ ...opts, only: [detector], minBytes: 0 });
+    const hit = findAction(result.findings, actionId);
+    if (!hit) {
+        return { ...base, ok: false, dryRun: true, message: `No action "${actionId}" exists any more. It may already be done, or the state changed. Run a new scan.` };
+    }
+    const { finding, action } = hit;
+    const common = { command: action.display, warning: action.warning };
+    if (action.kind.type === 'manual')
+        return { ...base, ...common, ok: false, dryRun: true, message: 'This one is instructions only; the tool never applies it. Run it yourself if you decide to.' };
+    if (action.risk === 'danger' || finding.risk === 'danger')
+        return { ...base, ...common, ok: false, dryRun: true, message: 'Refused: this could lose data that cannot be recovered.' };
+    if (!confirm)
+        return { ...base, ...common, ok: true, dryRun: true, message: `Dry run. Would run: ${action.display}. Re-run with --yes (CLI) or confirm: true (MCP) to apply.` };
+    const before = await diskInfo(opts.home);
+    try {
+        let output = '';
+        if (action.kind.type === 'remove-path') {
+            assertSafeToRemove(action.kind.path, opts);
+            await fs.rm(action.kind.path, { recursive: true, force: true, maxRetries: 2 });
+        }
+        else {
+            const r = await run(action.kind.file, action.kind.args, { cwd: action.kind.cwd, timeoutMs: 15 * 60_000 });
+            output = (r.stdout + r.stderr).trim().slice(-4000);
+            if (!r.ok)
+                return { ...base, ...common, ok: false, dryRun: false, message: `Command failed${r.timedOut ? ' (timed out)' : ''}.`, output };
+        }
+        const after = await diskInfo(opts.home);
+        const freed = before && after ? Math.max(0, after.freeBytes - before.freeBytes) : undefined;
+        return { ...base, ...common, ok: true, dryRun: false, message: 'Done.', output: output || undefined, freedBytes: freed };
+    }
+    catch (e) {
+        return { ...base, ...common, ok: false, dryRun: false, message: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/src/core/roots.js

@@ -0,0 +1,81 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { expandHome, isDir } from './util.js';
+/** Folder names people commonly keep code in. Always included when present. */
+const KNOWN = ['dev', 'code', 'src', 'projects', 'work', 'workspace', 'workspaces', 'Developer', 'repos', 'git', 'Sites'];
+/** Top-level folders that are never workspaces: macOS standard folders and cloud-sync mounts (slow, may prompt). */
+const NEVER = new Set([
+    'Applications', 'Library', 'Documents', 'Desktop', 'Downloads', 'Movies', 'Music', 'Pictures', 'Public',
+    'node_modules', 'miniconda3', 'anaconda3', 'miniforge3', 'mambaforge', 'go', 'snap',
+]);
+const CLOUD = /^(Dropbox|OneDrive|Box|Google Drive|iCloud|Creative Cloud Files|pCloud|MEGA|Sync)/i;
+const MARKERS = new Set(['.git', 'package.json', 'Cargo.toml', 'pyproject.toml', 'go.mod', 'pom.xml', 'build.gradle', 'composer.json', 'Gemfile', 'Package.swift']);
+/** Does this folder hold a git repo or project within a few levels? Bounded so it stays cheap. */
+async function looksLikeWorkspace(dir) {
+    let budget = 3000;
+    async function walk(d, depth) {
+        if (budget-- <= 0)
+            return false;
+        let entries;
+        try {
+            entries = await fs.readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        if (entries.some((e) => MARKERS.has(e.name)))
+            return true;
+        if (depth >= 3)
+            return false;
+        for (const e of entries) {
+            if (!e.isDirectory() || e.name.startsWith('.') || e.name === 'node_modules')
+                continue;
+            if (await walk(path.join(d, e.name), depth + 1))
+                return true;
+        }
+        return false;
+    }
+    return walk(dir, 0);
+}
+/**
+ * Where to look for projects and git repos.
+ *
+ * 1. `DEV_DISK_DOCTOR_ROOTS` (colon-separated) replaces everything below.
+ * 2. Otherwise: common names (`~/dev`, `~/code`, `~/src`…) plus every other visible folder directly
+ *    under your home that contains a git repo or project within three levels. That is how a company
+ *    folder such as `~/acme` is found without configuration.
+ *
+ * `~/Documents`, `~/Desktop` and cloud-sync folders are never searched unless you pass them with `--root`.
+ */
+export async function defaultRoots(home, env = process.env) {
+    const fromEnv = env.DEV_DISK_DOCTOR_ROOTS?.split(':').map((s) => s.trim()).filter(Boolean);
+    if (fromEnv?.length) {
+        const resolved = fromEnv.map((r) => path.resolve(expandHome(r, home)));
+        const existing = [];
+        for (const r of resolved)
+            if (await isDir(r))
+                existing.push(r);
+        return existing;
+    }
+    const roots = [];
+    let names = [];
+    try {
+        names = await fs.readdir(home);
+    }
+    catch {
+        return roots;
+    }
+    const candidates = names.filter((n) => !n.startsWith('.') && !NEVER.has(n) && !CLOUD.test(n));
+    const results = await Promise.all(candidates.map(async (n) => {
+        const p = path.join(home, n);
+        if (!(await isDir(p)))
+            return undefined;
+        if (KNOWN.includes(n) || (await looksLikeWorkspace(p)))
+            return p;
+        return undefined;
+    }));
+    for (const r of results)
+        if (r)
+            roots.push(r);
+    return roots.sort();
+}

package/dist/src/core/scan.js

@@ -0,0 +1,99 @@
+import os from 'node:os';
+import { detectors } from '../detectors/index.js';
+import { run } from './exec.js';
+import { defaultRoots } from './roots.js';
+import { isInside } from './util.js';
+export async function buildOptions(partial = {}) {
+    const home = partial.home ?? os.homedir();
+    return {
+        home,
+        platform: partial.platform ?? process.platform,
+        roots: partial.roots?.length ? partial.roots : await defaultRoots(home),
+        minBytes: partial.minBytes ?? 100 * 1024 * 1024,
+        staleDays: partial.staleDays ?? 30,
+        deep: partial.deep ?? false,
+        only: partial.only,
+        detectorTimeoutMs: partial.detectorTimeoutMs ?? 120_000,
+    };
+}
+export async function diskInfo(home) {
+    const r = await run('df', ['-k', home], { timeoutMs: 10_000 });
+    const line = r.stdout.trim().split('\n')[1];
+    if (!line)
+        return undefined;
+    const cols = line.trim().split(/\s+/);
+    const total = Number(cols[1]) * 1024;
+    const free = Number(cols[3]) * 1024;
+    return Number.isFinite(total) && Number.isFinite(free) ? { totalBytes: total, freeBytes: free } : undefined;
+}
+/** Drop findings that live inside another finding's folder so nothing is counted twice. */
+function outermost(findings) {
+    const withPath = findings.filter((f) => f.path);
+    return findings.filter((f) => {
+        if (!f.path)
+            return true;
+        return !withPath.some((g) => g !== f && g.path !== f.path && isInside(f.path, g.path));
+    });
+}
+export function computeTotals(findings) {
+    // A container such as Docker's disk image holds the other Docker findings; count it only when it stands alone.
+    const counted = outermost(findings).filter((f) => !(f.meta?.envelope && findings.some((g) => g !== f && g.detector === f.detector && !g.meta?.envelope && g.bytes > 0)));
+    const bytesByRisk = { safe: 0, review: 0, danger: 0 };
+    let bytes = 0;
+    let reclaimable = 0;
+    for (const f of counted) {
+        bytes += f.bytes;
+        bytesByRisk[f.risk] += f.bytes;
+        if (f.risk !== 'danger') {
+            // Only count what an action says it frees; "delete unavailable simulators" etc. do not free the whole folder.
+            const runnable = f.actions.filter((a) => a.kind.type !== 'manual' && a.risk !== 'danger');
+            reclaimable += Math.max(0, ...runnable.map((a) => a.reclaimBytes ?? 0));
+        }
+    }
+    return { findings: findings.length, bytes, reclaimableBytes: reclaimable, bytesByRisk };
+}
+function withTimeout(p, ms, label) {
+    let timer;
+    const t = new Promise((_, rej) => {
+        timer = setTimeout(() => rej(new Error(`${label} exceeded ${Math.round(ms / 1000)}s`)), ms);
+    });
+    return Promise.race([p, t]).finally(() => clearTimeout(timer));
+}
+export async function scan(opts) {
+    const findings = [];
+    const skipped = [];
+    const timings = {};
+    const selected = detectors.filter((d) => (opts.only ? opts.only.includes(d.id) : true));
+    const runOne = async (d) => {
+        const t0 = Date.now();
+        try {
+            const res = await withTimeout(d.run(opts, () => findings), opts.detectorTimeoutMs * 4, d.id);
+            findings.push(...res.filter((f) => f.bytes >= opts.minBytes || f.bytes === 0 || f.detector === 'worktrees'));
+        }
+        catch (e) {
+            skipped.push({ detector: d.id, reason: e instanceof Error ? e.message : String(e) });
+        }
+        finally {
+            timings[d.id] = Date.now() - t0;
+        }
+    };
+    const quick = selected.filter((d) => !d.deepOnly);
+    const deep = selected.filter((d) => d.deepOnly);
+    await Promise.all(quick.map(runOne));
+    if (opts.deep || (opts.only && deep.length))
+        await Promise.all(deep.map(runOne));
+    else if (deep.length)
+        skipped.push(...deep.map((d) => ({ detector: d.id, reason: 'Only runs with --deep (slow whole-home sweep).' })));
+    findings.sort((a, b) => b.bytes - a.bytes);
+    return {
+        schema: 1,
+        generatedAt: new Date().toISOString(),
+        host: { platform: opts.platform, home: opts.home },
+        disk: await diskInfo(opts.home),
+        options: { roots: opts.roots, minBytes: opts.minBytes, staleDays: opts.staleDays, deep: opts.deep },
+        totals: computeTotals(findings),
+        findings,
+        skipped,
+        timingsMs: timings,
+    };
+}

package/dist/src/core/size.js

@@ -0,0 +1,34 @@
+import { run } from './exec.js';
+import { pathExists } from './util.js';
+const MAX_PARALLEL = 4;
+let active = 0;
+const waiting = [];
+async function slot(fn) {
+    if (active >= MAX_PARALLEL)
+        await new Promise((r) => waiting.push(r));
+    active++;
+    try {
+        return await fn();
+    }
+    finally {
+        active--;
+        waiting.shift()?.();
+    }
+}
+/**
+ * Allocated size in bytes (what the disk actually spends, so sparse files such as
+ * Docker.raw report their real footprint). Returns undefined if missing or too slow.
+ */
+export async function sizeOf(p, timeoutMs = 120_000) {
+    if (!(await pathExists(p)))
+        return undefined;
+    return slot(async () => {
+        // -k: 1024-byte blocks, -s: summary, -x: stay on one filesystem. Exit code can be
+        // non-zero on unreadable subfolders while stdout is still the right total.
+        const r = await run('du', ['-skx', p], { timeoutMs });
+        if (r.timedOut)
+            return undefined;
+        const kb = Number(r.stdout.split(/\s/, 1)[0]);
+        return Number.isFinite(kb) ? kb * 1024 : undefined;
+    });
+}

package/dist/src/core/types.js

@@ -0,0 +1 @@
+export {};