dev-disk-doctor 0.0.0-stage → 0.1.1

package/dist/src/worktrees/audit.js

@@ -0,0 +1,231 @@
+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, isDir, pathExists } from '../core/util.js';
+import { discover, realpathSafe, repoFromGitdir, toolWorktreeRoots, parseGitFile } from './discover.js';
+export function parseWorktreeList(porcelain) {
+    const out = [];
+    for (const block of porcelain.split(/\n\s*\n/)) {
+        const lines = block.split('\n').filter(Boolean);
+        if (!lines.length)
+            continue;
+        const w = { path: '', detached: false, locked: false, prunable: false, bare: false };
+        for (const line of lines) {
+            const [key, ...rest] = line.split(' ');
+            const val = rest.join(' ');
+            if (key === 'worktree')
+                w.path = val;
+            else if (key === 'HEAD')
+                w.head = val;
+            else if (key === 'branch')
+                w.branch = val.replace(/^refs\/heads\//, '');
+            else if (key === 'detached')
+                w.detached = true;
+            else if (key === 'bare')
+                w.bare = true;
+            else if (key === 'locked') {
+                w.locked = true;
+                w.lockReason = val || undefined;
+            }
+            else if (key === 'prunable')
+                w.prunable = true;
+        }
+        if (w.path)
+            out.push(w);
+    }
+    return out;
+}
+function toolOwner(p) {
+    const s = p.split(path.sep).join('/');
+    if (s.includes('/.claude/worktrees/'))
+        return 'claude';
+    if (s.includes('/.codex/worktrees/'))
+        return 'codex';
+    if (s.includes('/.cursor/worktrees/'))
+        return 'cursor';
+    if (s.includes('/conductor/'))
+        return 'conductor';
+    if (s.includes('/.worktrees/'))
+        return 'worktrees-dir';
+    return undefined;
+}
+async function git(cwd, args, timeoutMs = 20_000) {
+    return run('git', ['-C', cwd, ...args], { timeoutMs });
+}
+async function defaultRef(repo) {
+    const head = await git(repo, ['symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD']);
+    if (head.ok && head.stdout.trim())
+        return head.stdout.trim();
+    for (const ref of ['origin/main', 'origin/master', 'main', 'master']) {
+        const r = await git(repo, ['rev-parse', '--verify', '-q', ref]);
+        if (r.ok)
+            return ref;
+    }
+    return undefined;
+}
+async function mtimeMs(p) {
+    try {
+        return (await fs.stat(p)).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function inspectLinked(l, repo, defRef, opts) {
+    const info = {
+        repo,
+        path: l.path,
+        isMain: false,
+        branch: l.branch,
+        head: l.head,
+        detached: l.detached,
+        locked: l.locked,
+        lockReason: l.lockReason,
+        exists: await isDir(l.path),
+        prunable: l.prunable,
+        toolOwned: toolOwner(l.path),
+        status: 'active',
+        reason: '',
+    };
+    if (!info.exists || info.prunable) {
+        info.status = 'prunable';
+        info.reason = 'The folder is gone but git still has a record of it.';
+        return info;
+    }
+    const [status, unpushed, merged, commitTime, size] = await Promise.all([
+        git(l.path, ['status', '--porcelain']),
+        git(l.path, ['rev-list', '--count', 'HEAD', '--not', '--remotes']),
+        defRef ? git(l.path, ['merge-base', '--is-ancestor', 'HEAD', defRef]) : Promise.resolve(undefined),
+        git(l.path, ['log', '-1', '--format=%ct']),
+        sizeOf(l.path, opts.detectorTimeoutMs),
+    ]);
+    info.dirty = status.ok ? status.stdout.trim().length > 0 : undefined;
+    info.unpushed = unpushed.ok ? Number(unpushed.stdout.trim()) : undefined;
+    info.merged = merged ? merged.ok : undefined;
+    info.bytes = size;
+    const gitdir = await parseGitFile(l.path);
+    const times = [
+        commitTime.ok ? Number(commitTime.stdout.trim()) * 1000 : undefined,
+        gitdir ? await mtimeMs(path.join(gitdir, 'index')) : undefined,
+        gitdir ? await mtimeMs(path.join(gitdir, 'HEAD')) : undefined,
+        await mtimeMs(l.path),
+    ].filter((t) => t !== undefined && Number.isFinite(t));
+    if (times.length) {
+        info.lastActivityMs = Math.max(...times);
+        info.idleDays = daysAgo(info.lastActivityMs);
+    }
+    Object.assign(info, classify(info, opts.staleDays));
+    return info;
+}
+export function classify(w, staleDays) {
+    if (w.locked)
+        return { status: 'locked', reason: `Locked${w.lockReason ? ` (${w.lockReason})` : ''}; git will not remove it.` };
+    if (w.dirty === undefined || w.unpushed === undefined) {
+        return { status: 'at-risk', reason: 'Could not read its git state, so it is not safe to assume it is disposable.' };
+    }
+    const problems = [];
+    if (w.dirty)
+        problems.push('has uncommitted or untracked changes');
+    if (w.unpushed > 0 && !w.merged)
+        problems.push(`has ${w.unpushed} commit${w.unpushed === 1 ? '' : 's'} no remote has`);
+    if (problems.length)
+        return { status: 'at-risk', reason: `Work would be lost: it ${problems.join(' and ')}.` };
+    const idle = w.idleDays ?? 0;
+    if (idle >= staleDays) {
+        return {
+            status: 'stale',
+            reason: `Clean, ${w.merged ? 'merged into the default branch' : 'fully pushed'}, and idle for ${idle} days.`,
+        };
+    }
+    return { status: 'active', reason: `Touched ${idle} day${idle === 1 ? '' : 's'} ago.` };
+}
+async function pool(items, size, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(size, items.length) }, async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    }));
+    return out;
+}
+export async function auditWorktrees(opts) {
+    const roots = [...new Set([...opts.roots, ...toolWorktreeRoots(opts.home)])];
+    const found = await discover(roots);
+    // Repos come from two places: the walk, and the repos that stray worktrees point back to.
+    const repoSet = new Map(); // realpath → path
+    for (const r of found.repos)
+        repoSet.set(await realpathSafe(r), r);
+    for (const l of found.linked) {
+        const repo = repoFromGitdir(l.gitdir);
+        if (repo && (await pathExists(path.join(repo, '.git'))))
+            repoSet.set(await realpathSafe(repo), repo);
+    }
+    const known = new Set();
+    const audits = [];
+    await pool([...repoSet.values()], 4, async (repo) => {
+        const list = await git(repo, ['worktree', 'list', '--porcelain']);
+        if (!list.ok)
+            return;
+        const listed = parseWorktreeList(list.stdout).filter((w) => !w.bare);
+        const defRef = await defaultRef(repo);
+        const repoReal = await realpathSafe(repo);
+        const worktrees = [];
+        const linked = [];
+        for (const w of listed) {
+            known.add(await realpathSafe(w.path));
+            if ((await realpathSafe(w.path)) === repoReal) {
+                worktrees.push({
+                    repo, path: w.path, isMain: true, branch: w.branch, head: w.head, detached: w.detached, locked: false,
+                    exists: true, prunable: false, status: 'active', reason: 'Main working copy.',
+                });
+            }
+            else
+                linked.push(w);
+        }
+        worktrees.push(...(await pool(linked, 6, (w) => inspectLinked(w, repo, defRef, opts))));
+        audits.push({ repo, defaultBranch: defRef, worktrees });
+    });
+    // Folders carrying a worktree `.git` file that no repository lists any more.
+    const orphans = [];
+    for (const l of found.linked) {
+        if (known.has(await realpathSafe(l.dir)))
+            continue;
+        const gitdirExists = await pathExists(l.gitdir);
+        if (gitdirExists)
+            continue; // still registered somewhere we did not list; leave it alone
+        const bytes = await sizeOf(l.dir, opts.detectorTimeoutMs);
+        const mt = await mtimeMs(l.dir);
+        orphans.push({
+            path: l.dir,
+            gitdir: l.gitdir,
+            bytes,
+            idleDays: mt ? daysAgo(mt) : undefined,
+            reason: 'Its repository no longer knows about it (the repo was moved, deleted, or the worktree record was pruned). Git can no longer tell you if it holds unsaved work.',
+        });
+    }
+    audits.sort((a, b) => a.repo.localeCompare(b.repo));
+    const byStatus = { active: 0, stale: 0, prunable: 0, 'at-risk': 0, locked: 0 };
+    let linkedCount = 0;
+    let reposWith = 0;
+    let bytes = 0;
+    for (const a of audits) {
+        const l = a.worktrees.filter((w) => !w.isMain);
+        if (l.length)
+            reposWith++;
+        linkedCount += l.length;
+        for (const w of l) {
+            byStatus[w.status]++;
+            bytes += w.bytes ?? 0;
+        }
+    }
+    bytes += orphans.reduce((s, o) => s + (o.bytes ?? 0), 0);
+    return {
+        rootsScanned: roots,
+        repos: audits,
+        orphans,
+        totals: { repos: audits.length, reposWithLinkedWorktrees: reposWith, linkedWorktrees: linkedCount, byStatus, orphans: orphans.length, bytes },
+    };
+}

package/dist/src/worktrees/detector.js

@@ -0,0 +1,93 @@
+import { execAction, manualAction, removeAction } from '../detectors/helpers.js';
+import { auditWorktrees } from './audit.js';
+/** Turn an audit into findings. Active worktrees are not findings; they only show in the audit. */
+export function auditToFindings(audit, opts) {
+    const findings = [];
+    const short = (p) => p.replace(opts.home, '~');
+    for (const a of audit.repos) {
+        const prunable = a.worktrees.filter((w) => w.status === 'prunable');
+        if (prunable.length) {
+            const id = `worktrees:prune:${a.repo}`;
+            findings.push({
+                id,
+                detector: 'worktrees',
+                category: 'worktrees',
+                title: `${prunable.length} dangling worktree record${prunable.length === 1 ? '' : 's'} in ${short(a.repo)}`,
+                path: a.repo,
+                bytes: 0,
+                risk: 'safe',
+                regenerable: true,
+                why: `Git still lists worktrees whose folders were deleted: ${prunable.map((w) => short(w.path)).join(', ')}. Pruning removes only the stale records.`,
+                actions: [execAction(id, 'prune', 'Run git worktree prune', 'git', ['worktree', 'prune'], 'safe', { cwd: a.repo })],
+            });
+        }
+        for (const w of a.worktrees) {
+            if (w.isMain || (w.status !== 'stale' && w.status !== 'at-risk' && w.status !== 'locked'))
+                continue;
+            const id = `worktrees:wt:${w.path}`;
+            const label = `${short(w.path)}${w.branch ? ` [${w.branch}]` : w.detached ? ' [detached]' : ''}${w.toolOwned ? ` (${w.toolOwned})` : ''}`;
+            if (w.status === 'stale') {
+                findings.push({
+                    id,
+                    detector: 'worktrees',
+                    category: 'worktrees',
+                    title: `Stale worktree ${label} of ${short(a.repo)}`,
+                    path: w.path,
+                    bytes: w.bytes ?? 0,
+                    risk: 'review',
+                    regenerable: false,
+                    why: w.reason,
+                    actions: [
+                        execAction(id, 'remove', 'Remove this worktree (git worktree remove)', 'git', ['worktree', 'remove', w.path], 'review', {
+                            bytes: w.bytes,
+                            cwd: a.repo,
+                            warning: w.branch ? `The branch "${w.branch}" is kept; only the checkout folder is removed. Git refuses if anything changed since the scan.` : 'Git refuses if anything changed since the scan.',
+                        }),
+                    ],
+                    meta: { repo: a.repo, branch: w.branch, idleDays: w.idleDays, toolOwned: w.toolOwned },
+                });
+            }
+            else {
+                findings.push({
+                    id,
+                    detector: 'worktrees',
+                    category: 'worktrees',
+                    title: `${w.status === 'locked' ? 'Locked' : 'At-risk'} worktree ${label} of ${short(a.repo)}`,
+                    path: w.path,
+                    bytes: w.bytes ?? 0,
+                    risk: 'danger',
+                    regenerable: false,
+                    why: w.reason,
+                    actions: [
+                        manualAction(id, 'inspect', 'Look before deleting', `git -C ${JSON.stringify(w.path)} status && git -C ${JSON.stringify(w.path)} log --branches --not --remotes --oneline`, 'danger', 'This worktree may hold work that exists nowhere else. Commit and push it, or decide to discard it yourself.'),
+                    ],
+                    meta: { repo: a.repo, branch: w.branch, idleDays: w.idleDays, dirty: w.dirty, unpushed: w.unpushed, toolOwned: w.toolOwned },
+                });
+            }
+        }
+    }
+    for (const o of audit.orphans) {
+        const id = `worktrees:orphan:${o.path}`;
+        findings.push({
+            id,
+            detector: 'worktrees',
+            category: 'worktrees',
+            title: `Orphaned worktree folder ${short(o.path)}`,
+            path: o.path,
+            bytes: o.bytes ?? 0,
+            risk: 'review',
+            regenerable: false,
+            why: o.reason,
+            actions: [removeAction(id, o.path, 'review', o.bytes ?? 0, 'Open the folder first: files here are no longer tracked by git and cannot be recovered after deletion.')],
+        });
+    }
+    return findings;
+}
+export const worktrees = {
+    id: 'worktrees',
+    title: 'Git worktrees across all your repos',
+    async run(opts) {
+        const audit = await auditWorktrees(opts);
+        return auditToFindings(audit, opts);
+    },
+};

package/dist/src/worktrees/discover.js

@@ -0,0 +1,81 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { isDir, readText } from '../core/util.js';
+const SKIP = new Set([
+    'node_modules', '.git', 'Library', '.Trash', 'vendor', 'Pods', 'target', 'build', 'dist',
+    '.next', 'venv', '.venv', '__pycache__', '.gradle', '.cache', '.npm', '.cargo', '.rustup',
+]);
+const HIDDEN_OK = new Set(['.claude', '.codex', '.cursor', '.worktrees', '.conductor']);
+const MAX_DEPTH = 7;
+const MAX_DIRS = 400_000;
+export async function realpathSafe(p) {
+    try {
+        return await fs.realpath(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** Where AI coding tools tend to park worktrees. Included automatically when present. */
+export function toolWorktreeRoots(home) {
+    return [
+        path.join(home, '.codex/worktrees'),
+        path.join(home, '.cursor/worktrees'),
+        path.join(home, '.claude/worktrees'),
+        path.join(home, 'conductor'),
+    ];
+}
+export async function parseGitFile(dir) {
+    const text = await readText(path.join(dir, '.git'));
+    const m = text && /^gitdir:\s*(.+)$/m.exec(text);
+    if (!m)
+        return undefined;
+    const raw = m[1].trim();
+    return path.isAbsolute(raw) ? raw : path.resolve(dir, raw);
+}
+/** `<repo>/.git/worktrees/<name>` → `<repo>`; anything else (submodules etc.) → undefined. */
+export function repoFromGitdir(gitdir) {
+    const parent = path.dirname(gitdir);
+    if (path.basename(parent) !== 'worktrees')
+        return undefined;
+    const dotGit = path.dirname(parent);
+    if (path.basename(dotGit) !== '.git')
+        return undefined;
+    return path.dirname(dotGit);
+}
+export async function discover(roots) {
+    const repos = new Set();
+    const linked = new Map();
+    let visited = 0;
+    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;
+        }
+        const dotGit = entries.find((e) => e.name === '.git');
+        if (dotGit?.isDirectory())
+            repos.add(dir);
+        else if (dotGit?.isFile()) {
+            const gitdir = await parseGitFile(dir);
+            if (gitdir && gitdir.includes(`${path.sep}worktrees${path.sep}`))
+                linked.set(dir, gitdir);
+            return; // a linked worktree is a leaf; its content belongs to that worktree
+        }
+        for (const e of entries) {
+            if (!e.isDirectory() || SKIP.has(e.name))
+                continue;
+            if (e.name.startsWith('.') && !HIDDEN_OK.has(e.name))
+                continue;
+            await walk(path.join(dir, e.name), depth + 1);
+        }
+    }
+    for (const r of roots)
+        if (await isDir(r))
+            await walk(r, 0);
+    return { repos: [...repos], linked: [...linked].map(([dir, gitdir]) => ({ dir, gitdir })) };
+}

package/dist/src/worktrees/types.js

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

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "dev-disk-doctor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Why is my disk full? A read-only disk and git-worktree doctor for developer machines (Docker, Xcode, Android, node_modules, caches). CLI + MCP server for AI agents.",
+  "license": "MIT",
+  "author": "Prageeth Silva",
+  "type": "module",
+  "bin": {
+    "dev-disk-doctor": "dist/src/cli.js",
+    "dev-disk-doctor-mcp": "dist/src/mcp.js"
+  },
+  "files": [
+    "dist/src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm test",
+    "test": "npm run build && node --test dist/test/*.test.js",
+    "scan": "npm run build && node dist/src/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pureartisan/dev-disk-doctor.git"
+  },
+  "homepage": "https://github.com/pureartisan/dev-disk-doctor#readme",
+  "bugs": {
+    "url": "https://github.com/pureartisan/dev-disk-doctor/issues"
+  },
+  "keywords": [
+    "disk-space",
+    "disk-usage",
+    "cleanup",
+    "macos",
+    "storage",
+    "docker",
+    "xcode",
+    "android-sdk",
+    "node_modules",
+    "git-worktree",
+    "mcp",
+    "mcp-server",
+    "developer-tools",
+    "cli"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2"
+  }
+}

package/skills/dev-disk-doctor/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: dev-disk-doctor
+description: Diagnose why a developer machine's disk is full and clean it up safely. Use when the user says their disk or Mac storage is full, "Documents" is huge, Docker/Android/Xcode/node_modules are eating space, or they want to find leftover git worktrees from Claude Code, Codex or Cursor.
+---
+
+# dev-disk-doctor playbook
+
+Goal: find what is using disk space, explain it in plain words, and let the user choose what to clean. Never delete anything the user has not agreed to, item by item.
+
+## 1. Scan (read-only)
+
+Prefer the MCP tools if the `dev-disk-doctor` server is connected: `disk_scan`, `worktree_audit`, `explain_finding`, `apply_action`.
+
+Otherwise use the CLI:
+
+```bash
+npx -y dev-disk-doctor scan --json          # takes about a minute
+npx -y dev-disk-doctor worktrees --json     # git worktree audit
+npx -y dev-disk-doctor scan --deep --json   # also sweeps the whole home folder (slow, ask first)
+```
+
+Add `--root <dir>` if the user keeps projects somewhere unusual.
+
+## 2. Present options
+
+Summarise: free space, total found, and how much is reclaimable. Then list the biggest items grouped by risk:
+
+- **SAFE**: regenerates automatically (caches, build output). Offer these first.
+- **REVIEW**: probably fine but check (old Docker images, AI models, stale worktrees, active-project build folders). Say what is lost and how to get it back.
+- **CAREFUL** (`danger`): could lose data (Docker volumes, dirty worktrees, backups, emulator images in use). Explain; the tool will not run these.
+
+For each item say: what it is, how big, what deleting it costs, and the exact command. Lead with the biggest wins. Do not read out the whole list.
+
+## 3. Apply only with explicit consent
+
+For each item the user approves:
+
+1. Dry run first: `apply_action` without `confirm`, or `npx -y dev-disk-doctor fix "<action id>"`.
+2. Read the action's warning to the user (for example "quit Chrome first", "images that only exist locally are lost").
+3. Run for real only after they say yes to that item: `confirm: true`, or `--yes`.
+
+One approval covers one action, not a batch and not later items.
+
+## Rules
+
+- Never `rm -rf` anything yourself that the tool did not offer.
+- Never remove a worktree that is `at-risk` (uncommitted changes or unpushed commits). Show the user `git status` and the unpushed log, and let them decide.
+- For orphaned worktree folders, ask the user to look inside first: git can no longer say whether they hold unsaved work.
+- Docker's `Docker.raw` never shrinks after pruning on its own. After pruning, tell the user to compact it in Docker Desktop → Settings → Resources.
+- Android emulator images used by an AVD are flagged and must stay.
+- After cleanup, run the scan again and report the free-space change.