dev-disk-doctor 0.0.0-stage → 0.1.1

package/dist/src/detectors/projects.js

@@ -0,0 +1,133 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { sizeOf } from '../core/size.js';
+import { daysAgo, pathExists } from '../core/util.js';
+import { removeAction } from './helpers.js';
+const SKIP = new Set(['.git', 'Library', '.Trash', '.cache', 'vendor', '__pycache__', '.gradle']);
+/** Hidden folders worth entering because AI tools park worktrees there. */
+const HIDDEN_OK = new Set(['.claude', '.codex', '.cursor', '.worktrees', '.conductor']);
+const MAX_DEPTH = 7;
+const MAX_DIRS = 400_000;
+async function artifactKind(dir, name) {
+    const sib = (f) => pathExists(path.join(dir, f));
+    switch (name) {
+        case 'node_modules':
+            return { kind: 'node_modules', why: 'Installed JavaScript dependencies.', rebuild: 'npm/pnpm/yarn install' };
+        case '.next':
+        case '.nuxt':
+        case '.svelte-kit':
+        case '.turbo':
+        case '.expo':
+            if (await sib('package.json'))
+                return { kind: name, why: 'Framework build output and cache.', rebuild: 'the next dev/build run' };
+            return undefined;
+        case 'target':
+            if (await sib('Cargo.toml'))
+                return { kind: 'Rust target', why: 'Cargo build output.', rebuild: 'cargo build' };
+            return undefined;
+        case 'Pods':
+            if (await sib('Podfile'))
+                return { kind: 'CocoaPods Pods', why: 'Installed iOS dependencies.', rebuild: 'pod install' };
+            return undefined;
+        case '.venv':
+        case 'venv':
+            if (await pathExists(path.join(dir, name, 'pyvenv.cfg')))
+                return { kind: 'Python venv', why: 'A virtual environment.', rebuild: 'recreate the venv and reinstall requirements' };
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+async function newestMtime(paths) {
+    let best;
+    for (const p of paths) {
+        try {
+            const st = await fs.stat(p);
+            if (best === undefined || st.mtimeMs > best)
+                best = st.mtimeMs;
+        }
+        catch {
+            /* missing */
+        }
+    }
+    return best;
+}
+async function findArtifacts(roots) {
+    const out = [];
+    let visited = 0;
+    const seen = new Set();
+    async function walk(dir, depth) {
+        if (depth > MAX_DEPTH || visited++ > MAX_DIRS)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (!e.isDirectory())
+                continue;
+            const full = path.join(dir, e.name);
+            const a = await artifactKind(dir, e.name);
+            if (a) {
+                if (!seen.has(full)) {
+                    seen.add(full);
+                    out.push({ dir: full, ...a });
+                }
+                continue; // never descend into an artifact
+            }
+            if (SKIP.has(e.name))
+                continue;
+            if (e.name.startsWith('.') && !HIDDEN_OK.has(e.name))
+                continue;
+            await walk(full, depth + 1);
+        }
+    }
+    await Promise.all(roots.map((r) => walk(r, 0)));
+    return out;
+}
+export const projects = {
+    id: 'projects',
+    title: 'Dependencies and build output in your projects',
+    async run(opts) {
+        const artifacts = await findArtifacts(opts.roots);
+        const findings = [];
+        const now = Date.now();
+        await Promise.all(artifacts.map(async (a) => {
+            const bytes = await sizeOf(a.dir, opts.detectorTimeoutMs);
+            if (bytes === undefined || bytes < opts.minBytes)
+                return;
+            const project = path.dirname(a.dir);
+            const activity = (await newestMtime([
+                path.join(project, 'package.json'),
+                path.join(project, 'package-lock.json'),
+                path.join(project, 'pnpm-lock.yaml'),
+                path.join(project, 'yarn.lock'),
+                path.join(project, 'Cargo.lock'),
+                path.join(project, 'Podfile.lock'),
+                path.join(project, '.git/HEAD'),
+                path.join(project, '.git/index'),
+            ])) ?? (await newestMtime([a.dir]));
+            const idle = activity === undefined ? undefined : daysAgo(activity, now);
+            const stale = idle !== undefined && idle >= opts.staleDays;
+            const id = `projects:${a.dir}`;
+            const risk = stale ? 'safe' : 'review';
+            findings.push({
+                id,
+                detector: 'projects',
+                category: 'projects',
+                title: `${a.kind} in ${project.replace(opts.home, '~')}${idle !== undefined ? ` (idle ${idle}d)` : ''}`,
+                path: a.dir,
+                bytes,
+                risk,
+                regenerable: true,
+                why: `${a.why} Rebuilt with ${a.rebuild}.${stale ? ' The project has not been touched recently.' : ' The project was active recently, so you will likely need this soon.'}`,
+                actions: [removeAction(id, a.dir, risk, bytes, stale ? undefined : 'Active project: the next run will need to reinstall or rebuild.')],
+                meta: { project, idleDays: idle, stale },
+            });
+        }));
+        return findings;
+    },
+};

package/dist/src/detectors/system.js

@@ -0,0 +1,102 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { run } from '../core/exec.js';
+import { sizeOf } from '../core/size.js';
+import { daysAgo, listDir } from '../core/util.js';
+import { manualAction, pathFinding, removeAction } from './helpers.js';
+export const system = {
+    id: 'system',
+    title: 'Trash, Downloads, logs, backups, snapshots',
+    async run(opts) {
+        const h = opts.home;
+        const findings = [];
+        const trash = await pathFinding({
+            detector: 'system',
+            key: 'trash',
+            category: 'system',
+            title: 'Trash',
+            path: path.join(h, '.Trash'),
+            risk: 'review',
+            regenerable: false,
+            why: 'Deleted files still occupy disk until the Trash is emptied.',
+            actions: (id) => [manualAction(id, 'empty', 'Empty the Trash in Finder', 'Finder → Empty Trash', 'review', 'Permanent. Look through it first.')],
+        }, opts);
+        if (trash)
+            findings.push(trash);
+        const logs = await pathFinding({
+            detector: 'system',
+            key: 'logs',
+            category: 'system',
+            title: 'User logs (~/Library/Logs)',
+            path: path.join(h, 'Library/Logs'),
+            risk: 'safe',
+            regenerable: true,
+            why: 'Application and crash logs. Apps recreate them.',
+        }, opts);
+        if (logs)
+            findings.push(logs);
+        const backups = await pathFinding({
+            detector: 'system',
+            key: 'ios-backups',
+            category: 'system',
+            title: 'iPhone and iPad backups',
+            path: path.join(h, 'Library/Application Support/MobileSync/Backup'),
+            risk: 'danger',
+            regenerable: false,
+            why: 'Local device backups made by Finder. They may be the only copy of data from an old device.',
+            actions: (id) => [manualAction(id, 'manage', 'Manage backups in Finder', 'Finder → device → Manage Backups…', 'danger', 'Deleting a backup is permanent.')],
+        }, opts);
+        if (backups)
+            findings.push(backups);
+        // Large files in Downloads.
+        const downloads = path.join(h, 'Downloads');
+        const bigFloor = Math.max(opts.minBytes, 500 * 1024 * 1024);
+        for (const name of await listDir(downloads)) {
+            const p = path.join(downloads, name);
+            let st;
+            try {
+                st = await fs.lstat(p);
+            }
+            catch {
+                continue;
+            }
+            const bytes = (await sizeOf(p, opts.detectorTimeoutMs)) ?? 0;
+            if (bytes < bigFloor)
+                continue;
+            const id = `system:download:${name}`;
+            findings.push({
+                id,
+                detector: 'system',
+                category: 'system',
+                title: `Large download: ${name}`,
+                path: p,
+                bytes,
+                risk: 'review',
+                regenerable: false,
+                why: `Sits in Downloads, last modified ${daysAgo(st.mtimeMs)} days ago. Installers and disk images are usually safe to delete once installed.`,
+                actions: [removeAction(id, p, 'review', bytes, 'This is a personal file, not a cache. Check what it is first.', 'Delete this download')],
+            });
+        }
+        if (opts.platform === 'darwin') {
+            const snap = await run('tmutil', ['listlocalsnapshots', '/'], { timeoutMs: 15_000 });
+            const count = snap.ok ? snap.stdout.split('\n').filter((l) => l.includes('com.apple.TimeMachine')).length : 0;
+            if (count > 0) {
+                const id = 'system:tm-snapshots';
+                findings.push({
+                    id,
+                    detector: 'system',
+                    category: 'system',
+                    title: `Time Machine local snapshots (${count})`,
+                    bytes: 0,
+                    risk: 'review',
+                    regenerable: true,
+                    why: 'macOS keeps local snapshots on this disk and normally frees them when space runs low, but they can inflate "used" space. Their size is not reported by du.',
+                    actions: [
+                        manualAction(id, 'thin', 'Thin local snapshots', 'sudo tmutil thinlocalsnapshots / 50000000000 4', 'review', 'Needs sudo. Snapshots are only a local convenience; your real backup is on the backup disk.'),
+                    ],
+                });
+            }
+        }
+        return findings;
+    },
+};

package/dist/src/detectors/xcode.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { execAction, manualAction, pathFindings } from './helpers.js';
+import { sizeOf } from '../core/size.js';
+export const xcode = {
+    id: 'xcode',
+    title: 'Xcode and iOS Simulator',
+    async run(opts) {
+        if (opts.platform !== 'darwin')
+            return [];
+        const dev = path.join(opts.home, 'Library/Developer');
+        const findings = await pathFindings([
+            {
+                detector: 'xcode',
+                key: 'derived-data',
+                category: 'mobile',
+                title: 'Xcode DerivedData',
+                path: path.join(dev, 'Xcode/DerivedData'),
+                risk: 'safe',
+                regenerable: true,
+                why: 'Build products and indexes. Xcode rebuilds them; the next build is just slower.',
+                warning: 'Quit Xcode first.',
+            },
+            {
+                detector: 'xcode',
+                key: 'device-support',
+                category: 'mobile',
+                title: 'Xcode iOS DeviceSupport',
+                path: path.join(dev, 'Xcode/iOS DeviceSupport'),
+                risk: 'safe',
+                regenerable: true,
+                why: 'Debug symbols copied from every iPhone or iPad you ever plugged in, one folder per iOS version. Recreated the next time that device connects.',
+            },
+            {
+                detector: 'xcode',
+                key: 'archives',
+                category: 'mobile',
+                title: 'Xcode Archives',
+                path: path.join(dev, 'Xcode/Archives'),
+                risk: 'review',
+                regenerable: false,
+                why: 'Past app builds, including the dSYMs needed to symbolicate crash reports for released versions.',
+                removable: false,
+            },
+            {
+                detector: 'xcode',
+                key: 'simulator-caches',
+                category: 'mobile',
+                title: 'CoreSimulator caches',
+                path: path.join(dev, 'CoreSimulator/Caches'),
+                risk: 'safe',
+                regenerable: true,
+                why: 'Simulator dyld and runtime caches. Rebuilt on the next simulator boot.',
+            },
+        ], opts);
+        const sims = path.join(dev, 'CoreSimulator/Devices');
+        const simBytes = await sizeOf(sims, opts.detectorTimeoutMs);
+        if (simBytes !== undefined && simBytes >= opts.minBytes) {
+            const id = 'xcode:simulators';
+            findings.push({
+                id,
+                detector: 'xcode',
+                category: 'mobile',
+                title: 'iOS Simulator devices and their data',
+                path: sims,
+                bytes: simBytes,
+                risk: 'review',
+                regenerable: false,
+                why: 'Every simulator keeps its own installed apps and data. Simulators for runtimes you no longer have are dead weight.',
+                actions: [
+                    execAction(id, 'delete-unavailable', 'Delete simulators whose runtime is gone', 'xcrun', ['simctl', 'delete', 'unavailable'], 'safe'),
+                    manualAction(id, 'list', 'See which simulators exist', 'xcrun simctl list devices', 'safe'),
+                ],
+            });
+        }
+        return findings;
+    },
+};

package/dist/src/mcp.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { applyAction } from './core/fix.js';
+import { buildOptions, scan } from './core/scan.js';
+import { fmtBytes } from './core/util.js';
+import { version } from './core/version.js';
+import { auditWorktrees } from './worktrees/audit.js';
+import { auditToFindings } from './worktrees/detector.js';
+const text = (summary, data) => ({
+    content: [
+        { type: 'text', text: summary },
+        { type: 'text', text: JSON.stringify(data) },
+    ],
+});
+const scanShape = {
+    roots: z.array(z.string()).optional().describe('Workspace folders to search for projects and repos. Default: ~/dev, ~/code, ~/src, ~/projects, ~/work… whichever exist.'),
+    min_size_mb: z.number().optional().describe('Ignore items smaller than this. Default 100.'),
+    stale_days: z.number().optional().describe('Days idle before a project or worktree is stale. Default 30.'),
+};
+export async function startMcp() {
+    const server = new McpServer({ name: 'dev-disk-doctor', version: version() });
+    server.registerTool('disk_scan', {
+        title: 'Scan for disk space hogs',
+        description: 'Read-only scan of a developer machine for what is using disk space: Docker, Android SDK/emulators, Xcode, package caches, test browsers, AI models, node_modules and build output, git worktrees, Trash and Downloads. Returns ranked findings, each with a plain-English explanation, a risk level (safe/review/danger) and the actions available. Present the findings to the user and let them choose. Never apply an action without the user agreeing to that specific item.',
+        inputSchema: {
+            ...scanShape,
+            only: z.array(z.string()).optional().describe('Restrict to detectors: docker, android, xcode, pkgcaches, browsers, models, projects, worktrees, system, biggest.'),
+            deep: z.boolean().optional().describe('Also sweep the whole home folder for unknown hogs. Slow (minutes).'),
+            limit: z.number().optional().describe('Return only the N largest findings. Default 25.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (a) => {
+        const opts = await buildOptions({
+            roots: a.roots,
+            minBytes: a.min_size_mb !== undefined ? a.min_size_mb * 1024 * 1024 : undefined,
+            staleDays: a.stale_days,
+            deep: a.deep,
+            only: a.only,
+        });
+        const result = await scan(opts);
+        const limit = a.limit ?? 25;
+        const shown = { ...result, findings: result.findings.slice(0, limit) };
+        const free = result.disk ? `${fmtBytes(result.disk.freeBytes)} free of ${fmtBytes(result.disk.totalBytes)}. ` : '';
+        return text(`${free}Found ${fmtBytes(result.totals.bytes)} in ${result.totals.findings} items; ${fmtBytes(result.totals.reclaimableBytes)} reclaimable with actions the tool can run. Showing ${shown.findings.length}.`, shown);
+    });
+    server.registerTool('worktree_audit', {
+        title: 'Audit git worktrees across all repos',
+        description: 'Read-only. Finds every git repo under the workspace roots and every linked worktree (including ones created by Claude Code, Codex, Cursor and Conductor), and classifies each as active, stale, dangling, locked, or at-risk (uncommitted or unpushed work). Also finds orphaned worktree folders whose repo no longer knows them. Use this to answer "how many worktrees do I have and which are leftovers?".',
+        inputSchema: scanShape,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (a) => {
+        const opts = await buildOptions({
+            roots: a.roots,
+            minBytes: a.min_size_mb !== undefined ? a.min_size_mb * 1024 * 1024 : undefined,
+            staleDays: a.stale_days,
+        });
+        const audit = await auditWorktrees(opts);
+        const t = audit.totals;
+        return text(`${t.repos} repos, ${t.linkedWorktrees} linked worktrees in ${t.reposWithLinkedWorktrees} repos (${t.byStatus.stale} stale, ${t.byStatus['at-risk']} at risk, ${t.byStatus.prunable} dangling, ${t.orphans} orphaned folders), ${fmtBytes(t.bytes)} total.`, { audit, findings: auditToFindings(audit, opts) });
+    });
+    server.registerTool('explain_finding', {
+        title: 'Explain one finding and its actions',
+        description: 'Re-checks a single finding by id (from disk_scan) and returns its current size, explanation, risks and actions. Read-only.',
+        inputSchema: { finding_id: z.string().describe('e.g. "docker:images" or "android:image:android-34/android-tv/arm64-v8a"'), ...scanShape },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (a) => {
+        const detector = a.finding_id.split(':')[0];
+        const opts = await buildOptions({ roots: a.roots, only: [detector], minBytes: 0 });
+        const result = await scan(opts);
+        const f = result.findings.find((x) => x.id === a.finding_id);
+        return f ? text(`${f.title}: ${fmtBytes(f.bytes)}, risk ${f.risk}.`, f) : text(`No finding "${a.finding_id}" right now. It may already be gone.`, null);
+    });
+    server.registerTool('apply_action', {
+        title: 'Apply one cleanup action',
+        description: 'Runs ONE allowlisted action from a finding. Dry run by default: it returns the exact command and warning without changing anything. Only set confirm=true after the user has explicitly agreed to this specific action, and read the action\'s warning to them first. Actions with risk "danger" and manual actions are always refused. State is re-checked before running, so a stale id fails safely.',
+        inputSchema: {
+            action_id: z.string().describe('The action id from a finding, e.g. "docker:build-cache#prune".'),
+            confirm: z.boolean().optional().describe('true = actually run it. Omit for a dry run.'),
+            roots: scanShape.roots,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    }, async (a) => {
+        const opts = await buildOptions({ roots: a.roots });
+        const res = await applyAction(opts, a.action_id, a.confirm === true);
+        return text(res.message, res);
+    });
+    await server.connect(new StdioServerTransport());
+}
+// Run directly as `dev-disk-doctor-mcp`.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+    startMcp().catch((e) => {
+        console.error(e);
+        process.exit(1);
+    });
+}

package/dist/src/report/text.js

@@ -0,0 +1,83 @@
+import { fmtBytes } from '../core/util.js';
+function paint(style) {
+    const c = (code) => (s) => (style.color ? `\u001b[${code}m${s}\u001b[0m` : s);
+    return { bold: c('1'), dim: c('2'), red: c('31'), yellow: c('33'), green: c('32'), cyan: c('36') };
+}
+const RISK_LABEL = { safe: 'SAFE', review: 'REVIEW', danger: 'CAREFUL' };
+export function renderScan(r, style, opts = {}) {
+    const p = paint(style);
+    const riskTag = (risk) => (risk === 'safe' ? p.green : risk === 'review' ? p.yellow : p.red)(`[${RISK_LABEL[risk]}]`);
+    const out = [];
+    out.push(p.bold('dev-disk-doctor'));
+    if (r.disk) {
+        const used = r.disk.totalBytes - r.disk.freeBytes;
+        out.push(`Disk: ${fmtBytes(r.disk.totalBytes)} total, ${fmtBytes(used)} used, ${p.bold(fmtBytes(r.disk.freeBytes))} free`);
+    }
+    out.push(`Found ${p.bold(fmtBytes(r.totals.bytes))} across ${r.totals.findings} items; ` +
+        `${p.bold(fmtBytes(r.totals.reclaimableBytes))} could be reclaimed with actions this tool can run ` +
+        `(${fmtBytes(r.totals.bytesByRisk.safe)} safe, ${fmtBytes(r.totals.bytesByRisk.review)} needs a look, ${fmtBytes(r.totals.bytesByRisk.danger)} careful).`);
+    out.push(p.dim(`Searched for projects in: ${r.options.roots.map((x) => x.replace(r.host.home, '~')).join(', ') || 'no workspace folders found (use --root <dir>)'}`));
+    out.push('');
+    const limit = opts.limit ?? 25;
+    const shown = r.findings.slice(0, limit);
+    shown.forEach((f, i) => out.push(renderFinding(f, i + 1, p, riskTag)));
+    if (r.findings.length > shown.length)
+        out.push(p.dim(`… ${r.findings.length - shown.length} smaller items hidden. Use --all to see everything.`));
+    if (r.skipped.length) {
+        out.push('');
+        for (const s of r.skipped)
+            out.push(p.dim(`Skipped ${s.detector}: ${s.reason}`));
+    }
+    out.push('');
+    out.push(p.dim('Nothing was changed. To act on an item: dev-disk-doctor fix "<action id>" (dry run), then add --yes.'));
+    return out.join('\n');
+}
+function renderFinding(f, n, p, tag) {
+    const lines = [];
+    lines.push(`${String(n).padStart(2)}. ${p.bold(fmtBytes(f.bytes).padStart(8))}  ${tag(f.risk)} ${f.title}`);
+    lines.push(`    ${p.dim(f.why)}`);
+    if (f.path)
+        lines.push(`    ${p.dim(f.path)}`);
+    for (const a of f.actions) {
+        const mark = a.kind.type === 'manual' ? 'manual' : a.risk === 'safe' ? 'can run' : 'asks first';
+        lines.push(`    ${p.cyan('→')} ${a.label} ${p.dim(`(${mark})`)}`);
+        lines.push(`      ${p.dim('$')} ${a.display}`);
+        if (a.warning)
+            lines.push(`      ${p.yellow('! ' + a.warning)}`);
+        lines.push(`      ${p.dim('id: ' + a.id)}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+const STATUS_ORDER = { 'at-risk': 0, stale: 1, prunable: 2, locked: 3, active: 4 };
+export function renderWorktrees(a, style, home) {
+    const p = paint(style);
+    const short = (s) => s.replace(home, '~');
+    const t = a.totals;
+    const out = [];
+    out.push(p.bold('Git worktree audit'));
+    out.push(`${t.repos} repos found; ${p.bold(String(t.linkedWorktrees))} linked worktrees across ${t.reposWithLinkedWorktrees} of them, using ${fmtBytes(t.bytes)}.`);
+    out.push(`${t.byStatus.active} active · ${p.yellow(String(t.byStatus.stale))} stale · ${p.red(String(t.byStatus['at-risk']))} at risk · ${t.byStatus.prunable} dangling records · ${t.byStatus.locked} locked · ${t.orphans} orphaned folders`);
+    out.push(p.dim(`Searched: ${a.rootsScanned.map(short).join(', ') || '(no workspace roots found; pass --root)'}`));
+    out.push('');
+    for (const repo of a.repos.filter((r) => r.worktrees.some((w) => !w.isMain))) {
+        const linked = repo.worktrees.filter((w) => !w.isMain).sort((x, y) => STATUS_ORDER[x.status] - STATUS_ORDER[y.status] || (y.bytes ?? 0) - (x.bytes ?? 0));
+        out.push(p.bold(`${short(repo.repo)}  (${linked.length} linked)`));
+        for (const w of linked)
+            out.push(worktreeLine(w, p, short));
+        out.push('');
+    }
+    if (a.orphans.length) {
+        out.push(p.bold('Orphaned folders (no repository owns them any more)'));
+        for (const o of a.orphans)
+            out.push(`  ${p.yellow('orphan')}  ${fmtBytes(o.bytes ?? 0).padStart(8)}  ${short(o.path)}${o.idleDays !== undefined ? `  idle ${o.idleDays}d` : ''}`);
+        out.push('');
+    }
+    return out.join('\n');
+}
+function worktreeLine(w, p, short) {
+    const color = w.status === 'at-risk' ? p.red : w.status === 'stale' ? p.yellow : w.status === 'active' ? p.green : p.dim;
+    const who = w.toolOwned ? ` ${p.dim('(' + w.toolOwned + ')')}` : '';
+    const br = w.branch ?? (w.detached ? 'detached' : '?');
+    return `  ${color(w.status.padEnd(8))} ${fmtBytes(w.bytes ?? 0).padStart(8)}  ${short(w.path)} [${br}]${who}\n           ${p.dim(w.reason)}`;
+}