@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/unity/disk.js

@@ -0,0 +1,666 @@
+import { execFile } from 'node:child_process';
+import { lstat, readdir, realpath, rm, statfs } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { parseLsofCwd } from "../machine/procs.js";
+import { findProjects, gcApply, gcPlan, human, holdOf } from "./gc.js";
+export const DISK_BELOW_GB = 20;
+export const DISK_DAYS = 2;
+export const TARGET_GC_DAYS = 3;
+export const TARGET_MAX_EDGE_VARIANTS = 3;
+export const WORKTREE_FRESH_MS = 2 * 3600_000;
+export const KINDS = ['worktrees', 'target', 'derived-data', 'unity', 'scratch', 'context'];
+export const APPLY_KINDS = ['worktrees', 'derived-data', 'unity', 'scratch'];
+const alloc = (s) => (typeof s.blocks === 'number' && s.blocks > 0 ? s.blocks * 512 : s.size);
+export async function measure(root, deadline, now = Date.now) {
+    let top;
+    try {
+        top = await lstat(root);
+    }
+    catch (e) {
+        return { bytes: 0, newest: 0, complete: false, error: e.code ?? 'unreadable' };
+    }
+    const out = { bytes: alloc(top), newest: top.mtimeMs, complete: true };
+    if (!top.isDirectory())
+        return out;
+    const seen = new Set();
+    const stack = [root];
+    while (stack.length) {
+        if (now() > deadline) {
+            out.complete = false;
+            break;
+        }
+        const batch = stack.splice(-16);
+        await Promise.all(batch.map(async (dir) => {
+            let names;
+            try {
+                names = await readdir(dir);
+            }
+            catch (e) {
+                out.complete = false;
+                if (dir === root)
+                    out.error = e.code ?? 'unreadable';
+                return;
+            }
+            for (let i = 0; i < names.length; i += 128) {
+                if (now() > deadline) {
+                    out.complete = false;
+                    return;
+                }
+                await Promise.all(names.slice(i, i + 128).map(async (n) => {
+                    const p = join(dir, n);
+                    let s;
+                    try {
+                        s = await lstat(p);
+                    }
+                    catch {
+                        return;
+                    }
+                    if (s.mtimeMs > out.newest)
+                        out.newest = s.mtimeMs;
+                    if (s.isDirectory()) {
+                        out.bytes += alloc(s);
+                        stack.push(p);
+                        return;
+                    }
+                    if (s.nlink > 1) {
+                        const k = `${s.dev}:${s.ino}`;
+                        if (seen.has(k))
+                            return;
+                        seen.add(k);
+                    }
+                    out.bytes += alloc(s);
+                }));
+            }
+        }));
+    }
+    return out;
+}
+class Budget {
+    end;
+    d;
+    constructor(d) { this.d = d; this.end = d.now() + d.budgetMs; }
+    get left() { return this.end - this.d.now(); }
+    async measure(path, capMs = this.d.walkMs) {
+        if (this.left <= 0)
+            return null;
+        return measure(path, this.d.now() + Math.min(capMs, this.left), this.d.now);
+    }
+}
+export const tilde = (p, home) => (p === home ? '~' : p.startsWith(home + sep) ? `~/${relative(home, p)}` : p);
+export function shellPath(p, home) {
+    const t = tilde(p, home);
+    if (/^[\w~./@+,:=-]+$/.test(t))
+        return t;
+    const esc = (x) => x.replace(/(["\\$`])/g, '\\$1');
+    return t.startsWith('~/') ? `"$HOME/${esc(t.slice(2))}"` : `"${esc(t)}"`;
+}
+const inside = (p, root) => p === root || p.startsWith(root.endsWith(sep) ? root : root + sep);
+const names = (args, root) => {
+    let i = args.indexOf(root);
+    while (i >= 0) {
+        const next = args[i + root.length];
+        if (next === undefined || next === '/' || next === ' ' || next === '"' || next === "'")
+            return true;
+        i = args.indexOf(root, i + 1);
+    }
+    return false;
+};
+async function forms(p) {
+    const real = await realpath(p).catch(() => p);
+    return [...new Set([resolve(p), real])];
+}
+const argv0 = (args) => basename(args.split(' ')[0] ?? '');
+const short = (args) => (args.length > 80 ? `${args.slice(0, 77)}…` : args);
+export async function busyIn(root, procs, cwds, self) {
+    const fs = await forms(root);
+    for (const p of procs) {
+        if (p.pid === self)
+            continue;
+        const cwd = cwds?.get(p.pid) ?? p.cwd;
+        if (cwd && fs.some((f) => inside(cwd, f)))
+            return `pid ${p.pid} works in it (${short(p.args)})`;
+        if (fs.some((f) => names(p.args, f)))
+            return `pid ${p.pid} names it (${short(p.args)})`;
+    }
+    for (const [pid, cwd] of cwds ?? [])
+        if (pid !== self && fs.some((f) => inside(cwd, f)))
+            return `pid ${pid} works in it`;
+    return null;
+}
+const CARGO = new Set(['cargo', 'rustc', 'cargo-nextest', 'cargo-clippy', 'clippy-driver', 'rustdoc']);
+export const cargoRuns = (procs) => procs.filter((p) => CARGO.has(argv0(p.args)));
+const XCODEBUILD = (p) => argv0(p.args) === 'xcodebuild';
+const XCODE_ANY = (p) => XCODEBUILD(p) || /\/Xcode[^/]*\.app\/Contents\/MacOS\/Xcode\b/.test(p.args) || argv0(p.args) === 'swift-frontend' || argv0(p.args) === 'swift-build';
+const want = (o, k) => !o.only || o.only.includes(k);
+const sizeText = (b, atLeast) => `${atLeast ? 'at least ' : ''}${human(b)}`;
+const ago = (now, t) => {
+    const h = (now - t) / 3600_000;
+    return h < 1 ? `${Math.max(1, Math.round(h * 60))} min ago` : h < 48 ? `${Math.round(h)} h ago` : `${Math.round(h / 24)} days ago`;
+};
+async function repoOf(d) {
+    const top = await d.git(['rev-parse', '--show-toplevel'], d.cwd);
+    if (top.status !== 0)
+        return null;
+    const common = await d.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], d.cwd);
+    const branch = await d.git(['rev-parse', '--abbrev-ref', 'HEAD'], d.cwd);
+    const t = top.stdout.trim();
+    const c = common.status === 0 ? common.stdout.trim() : join(t, '.git');
+    return { top: t, main: basename(c) === '.git' ? dirname(c) : t, branch: branch.stdout.trim() || 'HEAD' };
+}
+export function parseWorktrees(text) {
+    const out = [];
+    let cur = null;
+    for (const l of text.split('\n')) {
+        if (l.startsWith('worktree ')) {
+            cur = { path: l.slice(9) };
+            out.push(cur);
+            continue;
+        }
+        if (!cur)
+            continue;
+        if (l.startsWith('HEAD '))
+            cur.head = l.slice(5);
+        else if (l.startsWith('branch '))
+            cur.branch = l.slice(7).replace(/^refs\/heads\//, '');
+        else if (l === 'bare')
+            cur.bare = true;
+        else if (l === 'locked' || l.startsWith('locked '))
+            cur.locked = l.slice(7) || 'locked';
+        else if (l === 'prunable' || l.startsWith('prunable '))
+            cur.prunable = true;
+    }
+    return out;
+}
+async function checkWorktree(w, repo, c) {
+    const { d } = c;
+    if (w.locked)
+        return { verdict: 'in-use', why: `locked (${w.locked})` };
+    if (!w.head)
+        return { verdict: 'kept', why: 'no HEAD (bare or unborn)' };
+    const ahead = await d.git(['rev-list', '--count', `HEAD..${w.head}`], repo.top);
+    if (ahead.status !== 0)
+        return { verdict: 'kept', why: `git could not compare it with ${repo.branch}: ${ahead.stderr.trim().split('\n')[0]}` };
+    const n = Number(ahead.stdout.trim());
+    if (n > 0)
+        return { verdict: 'kept', why: `${n} commit(s) not in ${repo.branch}` };
+    const status = await d.git(['--no-optional-locks', 'status', '--porcelain'], w.path);
+    if (status.status !== 0)
+        return { verdict: 'in-use', why: `git status failed: ${status.stderr.trim().split('\n')[0]}` };
+    const dirty = status.stdout.split('\n').filter(Boolean).length;
+    if (dirty)
+        return { verdict: 'in-use', why: `${dirty} uncommitted change(s)` };
+    if (!c.cwds)
+        return { verdict: 'in-use', why: 'could not read processes\' working folders (lsof), so nobody is proven out of it' };
+    const busy = await busyIn(w.path, c.procs, c.cwds, d.self);
+    if (busy)
+        return { verdict: 'in-use', why: busy };
+    const gd = await d.git(['rev-parse', '--absolute-git-dir'], w.path);
+    if (gd.status === 0) {
+        const g = gd.stdout.trim();
+        let latest = 0;
+        for (const f of ['index', 'HEAD', join('logs', 'HEAD')]) {
+            const s = await lstat(join(g, f)).catch(() => null);
+            if (s)
+                latest = Math.max(latest, s.mtimeMs);
+        }
+        if (d.now() - latest < WORKTREE_FRESH_MS)
+            return { verdict: 'in-use', why: `git activity ${ago(d.now(), latest)} (a lane may be starting or pausing)` };
+    }
+    return { verdict: 'safe' };
+}
+async function worktrees(c, repo) {
+    if (!repo) {
+        c.lines.push({ kind: 'worktrees', verdict: 'context', check: 'git worktrees', state: 'pass', says: 'not in a git repo here; run it from the repo to see its worktrees' });
+        return;
+    }
+    const list = await c.d.git(['worktree', 'list', '--porcelain'], repo.top);
+    if (list.status !== 0) {
+        c.lines.push({ kind: 'worktrees', verdict: 'context', check: 'git worktrees', state: 'warn', says: `git worktree list failed: ${list.stderr.trim()}` });
+        return;
+    }
+    const all = parseWorktrees(list.stdout);
+    const mine = await forms(repo.top);
+    const found = [];
+    for (const w of all.slice(1)) {
+        if (w.bare || mine.includes(w.path))
+            continue;
+        if (w.prunable) {
+            c.lines.push({ kind: 'worktrees', verdict: 'kept', check: `worktree ${c.t(w.path)}`, state: 'pass', path: w.path, says: 'its folder is gone; only git\'s record remains', next: 'git worktree prune' });
+            continue;
+        }
+        const s = await lstat(w.path).catch(() => null);
+        if (!s || !s.isDirectory())
+            continue;
+        found.push({ w, r: await checkWorktree(w, repo, c) });
+    }
+    found.sort((a, b) => Number(b.r.verdict === 'safe') - Number(a.r.verdict === 'safe'));
+    for (const { w, r } of found) {
+        const m = await c.budget.measure(w.path);
+        const label = `worktree ${c.t(w.path)}${w.branch ? ` (${w.branch})` : ' (detached)'}`;
+        const size = m ? { bytes: m.bytes, at_least: !m.complete || undefined } : {};
+        if (r.verdict === 'safe') {
+            c.lines.push({ kind: 'worktrees', verdict: 'safe', applies: true, check: label, state: 'warn', path: w.path, ...size,
+                says: `everything in it is already in ${repo.branch}, nothing uncommitted, nobody working in it`, next: `git worktree remove ${c.sh(w.path)}` });
+        }
+        else {
+            c.lines.push({ kind: 'worktrees', verdict: r.verdict, check: label, state: 'pass', path: w.path, ...size, says: r.why });
+        }
+    }
+    if (!found.length)
+        c.lines.push({ kind: 'worktrees', verdict: 'context', check: 'git worktrees', state: 'pass', says: 'no other worktrees of this repo' });
+}
+async function target(c, repo) {
+    const dirs = new Set();
+    if (c.d.env.CARGO_TARGET_DIR)
+        dirs.add(resolve(c.d.cwd, c.d.env.CARGO_TARGET_DIR));
+    for (const base of repo ? [repo.main, repo.top] : [c.d.cwd])
+        for (const t of [join(base, 'funpixel-mono', 'target'), join(base, 'target')])
+            dirs.add(t);
+    let scriptPath = null;
+    for (const base of repo ? [repo.top, repo.main] : []) {
+        const p = join(base, 'scripts', 'target-gc.sh');
+        if ((await lstat(p).catch(() => null))?.isFile()) {
+            scriptPath = p;
+            break;
+        }
+    }
+    const cmd = scriptPath ? `bash ${inside(scriptPath, c.d.cwd) ? relative(c.d.cwd, scriptPath) : c.sh(scriptPath)}` : null;
+    const days = Number(c.d.env.GC_DAYS) > 0 ? Number(c.d.env.GC_DAYS) : TARGET_GC_DAYS;
+    const maxEdge = Number(c.d.env.GC_MAX_EDGE_VARIANTS) > 0 ? Number(c.d.env.GC_MAX_EDGE_VARIANTS) : TARGET_MAX_EDGE_VARIANTS;
+    const building = cargoRuns(c.procs);
+    for (const t of dirs) {
+        const s = await lstat(t).catch(() => null);
+        if (!s || !s.isDirectory())
+            continue;
+        const label = `cargo ${c.t(t)}`;
+        if (building.length) {
+            c.lines.push({ kind: 'target', verdict: 'in-use', check: label, state: 'pass', path: t,
+                says: `cargo or rustc is running (pid ${building.slice(0, 3).map((p) => p.pid).join(', ')}${building.length > 3 ? ', …' : ''}): not measured while it builds`, next: cmd ? `after the build: ${cmd}` : undefined });
+            continue;
+        }
+        const cutoff = c.d.now() - days * 86400_000;
+        const inc = join(t, 'debug', 'incremental');
+        let stale = 0, recent = 0, staleBytes = 0, recentBytes = 0, atLeast = false;
+        let crates = [];
+        try {
+            crates = await readdir(inc);
+        }
+        catch { }
+        const aged = [];
+        for (const n of crates) {
+            const p = join(inc, n);
+            const st = await lstat(p).catch(() => null);
+            if (!st || !st.isDirectory())
+                continue;
+            const old = st.mtimeMs < cutoff;
+            if (old)
+                stale++;
+            else
+                recent++;
+            aged.push({ p, old });
+        }
+        aged.sort((a, b) => Number(b.old) - Number(a.old));
+        for (const a of aged) {
+            const m = await c.budget.measure(a.p);
+            if (!m) {
+                atLeast = true;
+                continue;
+            }
+            if (!m.complete)
+                atLeast = true;
+            if (a.old)
+                staleBytes += m.bytes;
+            else
+                recentBytes += m.bytes;
+        }
+        let edge = 0;
+        try {
+            edge = (await readdir(join(t, 'debug', 'deps'))).filter((n) => /^libfunpixel_edge-.*\.rlib$/.test(n)).length;
+        }
+        catch { }
+        const dead = [];
+        for (const p of ['dev-release', 'release'])
+            if ((await lstat(join(t, p)).catch(() => null))?.isDirectory())
+                dead.push(p);
+        const facts = [
+            `incremental: ${stale} cache(s) untouched ${days}+ days (${sizeText(staleBytes, atLeast)}), ${recent} recent (${sizeText(recentBytes, atLeast)})`,
+            `${edge} cop${edge === 1 ? 'y' : 'ies'} of the edge library (target-gc cleans the workspace crates above ${maxEdge})`,
+            ...(dead.length ? [`unused profile(s): ${dead.join(', ')}`] : []),
+        ].join('; ');
+        const actionable = stale > 0 || edge > maxEdge || dead.length > 0;
+        c.lines.push({
+            kind: 'target', verdict: actionable ? 'safe' : 'context', applies: false, check: label, state: actionable ? 'warn' : 'pass', path: t,
+            bytes: actionable ? staleBytes : staleBytes + recentBytes, at_least: atLeast || undefined,
+            says: actionable ? `${facts}. target-gc.sh drops caches of variants nobody builds and keeps the third-party dependencies built (never delete target/ by hand)` : facts,
+            next: actionable ? (cmd ?? 'cargo clean in its workspace (a full rebuild follows)') : undefined,
+        });
+    }
+}
+const DD_NAME = (n) => n === 'DerivedData' || /-dd$/i.test(n) || /derived-?data/i.test(n);
+const DD_MARKS = ['Build', 'Logs', 'info.plist', 'ModuleCache.noindex', 'Index.noindex', 'SourcePackages'];
+async function tempDerivedData(roots, until, now) {
+    const out = [];
+    const seen = new Set();
+    const walk = async (dir, left) => {
+        if (now() > until)
+            return;
+        let ents;
+        try {
+            ents = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of ents.slice(0, 5000)) {
+            if (!e.isDirectory() || e.name === 'node_modules' || e.name === '.git')
+                continue;
+            const p = join(dir, e.name);
+            if (DD_NAME(e.name)) {
+                let kids = [];
+                try {
+                    kids = await readdir(p);
+                }
+                catch {
+                    continue;
+                }
+                if (kids.some((k) => DD_MARKS.includes(k))) {
+                    out.push(p);
+                    continue;
+                }
+            }
+            if (left > 0)
+                await walk(p, left - 1);
+        }
+    };
+    for (const r of roots) {
+        const real = await realpath(r).catch(() => null);
+        if (!real || seen.has(real))
+            continue;
+        seen.add(real);
+        await walk(resolve(r), 2);
+    }
+    return out;
+}
+async function derivedData(c) {
+    const xcodeRoot = join(c.d.home, 'Library', 'Developer', 'Xcode', 'DerivedData');
+    const folders = [];
+    try {
+        for (const e of await readdir(xcodeRoot, { withFileTypes: true }))
+            if (e.isDirectory())
+                folders.push({ path: join(xcodeRoot, e.name), shared: e.name.endsWith('.noindex'), defaultLoc: true });
+    }
+    catch { }
+    for (const p of await tempDerivedData(c.d.tmpRoots, c.d.now() + 10_000, c.d.now))
+        folders.push({ path: p, shared: false, defaultLoc: false });
+    if (!folders.length) {
+        c.lines.push({ kind: 'derived-data', verdict: 'context', check: 'Xcode DerivedData', state: 'pass', says: 'none found' });
+        return;
+    }
+    const xbDefault = c.procs.filter((p) => XCODEBUILD(p) && !/-derivedDataPath\b/.test(p.args));
+    const xcodeAny = c.procs.filter(XCODE_ANY);
+    for (const f of folders) {
+        const label = `DerivedData ${c.t(f.path)}`;
+        let why = await busyIn(f.path, c.procs, c.cwds, c.d.self);
+        if (!why && f.shared && xcodeAny.length)
+            why = `a cache every Xcode build shares, and Xcode or xcodebuild is running (pid ${xcodeAny[0].pid})`;
+        if (!why && f.defaultLoc && xbDefault.length)
+            why = `xcodebuild pid ${xbDefault[0].pid} builds into the default DerivedData`;
+        const m = await c.budget.measure(f.path);
+        const size = m ? { bytes: m.bytes, at_least: !m.complete || undefined } : {};
+        if (why) {
+            c.lines.push({ kind: 'derived-data', verdict: 'in-use', check: label, state: 'pass', path: f.path, ...size, says: why });
+            continue;
+        }
+        if (!m) {
+            c.lines.push({ kind: 'derived-data', verdict: 'kept', check: label, state: 'pass', path: f.path, says: 'not measured: out of walk time (run it with --only derived-data)' });
+            continue;
+        }
+        if (m.newest > c.cutoff) {
+            c.lines.push({ kind: 'derived-data', verdict: 'kept', check: label, state: 'pass', path: f.path, ...size, says: `touched ${ago(c.d.now(), m.newest)}` });
+            continue;
+        }
+        if (!m.complete) {
+            c.lines.push({ kind: 'derived-data', verdict: 'kept', check: label, state: 'pass', path: f.path, ...size, says: `not proven idle: the walk ran out of time before it had seen every file` });
+            continue;
+        }
+        c.lines.push({ kind: 'derived-data', verdict: 'safe', applies: true, check: label, state: 'warn', path: f.path, ...size,
+            says: `last touched ${ago(c.d.now(), m.newest)}, no xcodebuild pointed at it; Xcode rebuilds it on the next build`, next: `rm -rf ${c.sh(f.path)}` });
+    }
+}
+function gcDeps(c, partial) {
+    return {
+        root: c.d.unityLocks, procs: async () => c.procs, now: c.d.now, staleMs: c.d.staleMs,
+        du: async (p) => { const m = await c.budget.measure(p); if (!m || !m.complete)
+            partial.add(p); return m?.bytes ?? 0; },
+    };
+}
+async function unityFolders(c, projects) {
+    const partial = new Set();
+    const plan = await gcPlan(c.o.roots, c.o.days, gcDeps(c, partial));
+    for (const f of plan.folders) {
+        c.lines.push({ kind: 'unity', verdict: 'safe', applies: true, check: `Unity ${c.t(f.path)}`, state: 'warn', path: f.path, bytes: f.bytes, at_least: partial.has(f.path) || undefined,
+            says: `untouched since ${f.touched.slice(0, 10)}, no Unity or queue job holds the project; Unity rebuilds ${f.folder}/ on the next open (minutes for a big project)`, next: `rm -rf ${c.sh(f.path)}` });
+    }
+    for (const s of plan.skipped)
+        c.lines.push({ kind: 'unity', verdict: 'in-use', check: `Unity ${c.t(s.project)}`, state: 'pass', path: s.project, says: s.why });
+    if (!projects.length)
+        c.lines.push({ kind: 'unity', verdict: 'context', check: 'Unity projects', state: 'pass', says: `none under ${c.o.roots.map(c.t).join(', ')} (pass the folders that hold them, e.g. ~/Documents/github)` });
+    else if (!plan.folders.length)
+        c.lines.push({ kind: 'unity', verdict: 'context', check: 'Unity projects', state: 'pass', says: `${projects.length} project(s); nothing idle for ${c.o.days} days${plan.recent ? ` (${plan.recent} folder(s) used more recently)` : ''}` });
+}
+const SCRATCH_KEEP = new Set(['.gitignore', 'probe.json']);
+async function scratchPlans(c, projects) {
+    const plans = [];
+    const held = [];
+    const g = gcDeps(c, new Set());
+    for (const project of projects) {
+        const dir = join(project, '.funtools', 'unity');
+        const s = await lstat(dir).catch(() => null);
+        if (!s || !s.isDirectory())
+            continue;
+        const why = await holdOf(project, g, c.procs);
+        if (why) {
+            held.push({ project, why });
+            continue;
+        }
+        const plan = { project, dir, entries: [], bytes: 0, atLeast: false };
+        for (const n of await readdir(dir).catch(() => [])) {
+            if (SCRATCH_KEEP.has(n))
+                continue;
+            const p = join(dir, n);
+            const m = await c.budget.measure(p);
+            if (!m || !m.complete || m.newest > c.cutoff)
+                continue;
+            plan.entries.push({ path: p, bytes: m.bytes });
+            plan.bytes += m.bytes;
+        }
+        if (plan.entries.length)
+            plans.push(plan);
+    }
+    return { plans, held };
+}
+async function scratch(c, projects) {
+    const { plans, held } = await scratchPlans(c, projects);
+    for (const p of plans) {
+        c.lines.push({ kind: 'scratch', verdict: 'safe', applies: true, check: `funtools scratch ${c.t(p.dir)}`, state: 'warn', path: p.dir, bytes: p.bytes,
+            says: `${p.entries.length} record(s), capture(s) or shot folder(s) older than ${c.o.days} days (probe.json, the latest report, stays); funtools writes them again on the next run`,
+            next: `funtools unity gc --disk ${c.sh(p.project)} --days ${c.o.days} --apply --only scratch` });
+    }
+    for (const h of held)
+        c.lines.push({ kind: 'scratch', verdict: 'in-use', check: `funtools scratch ${c.t(join(h.project, '.funtools', 'unity'))}`, state: 'pass', path: h.project, says: h.why });
+}
+async function context(c) {
+    const caches = join(c.d.home, 'Library', 'Caches');
+    const trash = join(c.d.home, '.Trash');
+    const docker = join(c.d.home, 'Library', 'Containers', 'com.docker.docker', 'Data', 'vms', '0', 'data', 'Docker.raw');
+    const one = async (path, check, next) => {
+        const m = await c.budget.measure(path, Math.min(c.d.walkMs, 15_000));
+        if (!m) {
+            c.lines.push({ kind: 'context', verdict: 'context', check, state: 'pass', path, says: 'not measured: out of walk time' });
+            return;
+        }
+        if (m.error === 'ENOENT') {
+            c.lines.push({ kind: 'context', verdict: 'context', check, state: 'pass', path, says: 'not here' });
+            return;
+        }
+        if (m.error) {
+            c.lines.push({ kind: 'context', verdict: 'context', check, state: 'pass', path, says: `unreadable (${m.error}${m.error === 'EPERM' ? ': the terminal needs Full Disk Access to size it' : ''})`, next });
+            return;
+        }
+        c.lines.push({ kind: 'context', verdict: 'context', check, state: 'pass', path, bytes: m.bytes, at_least: !m.complete || undefined, says: `${sizeText(m.bytes, !m.complete)}; never touched by funtools`, next });
+    };
+    await one(caches, 'Caches ~/Library/Caches', 'yours to decide: apps rebuild their caches, some slowly');
+    await one(trash, 'the Trash', 'empty it in Finder when you are sure');
+    const raw = await lstat(docker).catch(() => null);
+    if (raw)
+        c.lines.push({ kind: 'context', verdict: 'context', check: 'Docker disk image', state: 'pass', path: docker, bytes: alloc(raw), says: `${human(alloc(raw))} allocated (it never shrinks by itself); never touched by funtools`, next: 'docker system df, then docker system prune if you choose' });
+}
+export async function freeAt(path) {
+    const s = await statfs(path);
+    return { free: s.bavail * s.bsize, total: s.blocks * s.bsize };
+}
+export async function diskReport(o, d) {
+    const [procs, cwds] = await Promise.all([d.procs(), d.cwds()]);
+    const c = { d, o, procs, cwds, budget: new Budget(d), lines: [], t: (p) => tilde(p, d.home), sh: (p) => shellPath(p, d.home), cutoff: d.now() - o.days * 86400_000 };
+    const repo = (want(o, 'worktrees') || want(o, 'target')) ? await repoOf(d) : null;
+    if (want(o, 'worktrees'))
+        await worktrees(c, repo);
+    if (want(o, 'derived-data'))
+        await derivedData(c);
+    const projects = want(o, 'unity') || want(o, 'scratch') ? await findProjects(o.roots) : [];
+    if (want(o, 'unity'))
+        await unityFolders(c, projects);
+    if (want(o, 'scratch'))
+        await scratch(c, projects);
+    if (want(o, 'target'))
+        await target(c, repo);
+    if (want(o, 'context'))
+        await context(c);
+    const space = await d.free(d.cwd);
+    return finish(o, space, c.lines, false, 0);
+}
+function finish(o, space, lines, applied, freed) {
+    const threshold = o.below * 1024 ** 3;
+    const below = space.free < threshold;
+    const free = {
+        kind: 'free', verdict: 'free', check: 'free space', bytes: space.free,
+        state: below ? (o.strict ? 'fail' : 'warn') : 'pass',
+        says: `${human(space.free)} free of ${human(space.total)}${below ? `, below ${o.below} GB` : ` (threshold ${o.below} GB)`}`,
+        next: below ? 'reclaim from the list below, largest first' : undefined,
+    };
+    const order = { free: 0, failed: 1, removed: 2, safe: 3, 'in-use': 4, kept: 5, context: 6 };
+    const sorted = [...lines].sort((a, b) => order[a.verdict] - order[b.verdict] || (b.bytes ?? 0) - (a.bytes ?? 0));
+    const reclaimable = sorted.filter((l) => l.verdict === 'safe').reduce((t, l) => t + (l.bytes ?? 0), 0);
+    return { schema: 'funtools.disk/1', free_bytes: space.free, total_bytes: space.total, threshold_bytes: threshold, below, days: o.days, applied, reclaimable_bytes: reclaimable, freed_bytes: freed, lines: [free, ...sorted] };
+}
+export function applyRefusal(o) {
+    if (!o.apply)
+        return null;
+    if (!o.only?.length)
+        return `--apply deletes only kinds you name: --only ${APPLY_KINDS.join('|')} (read the report first: run it without --apply)`;
+    const ro = o.only.filter((k) => !APPLY_KINDS.includes(k));
+    if (ro.length)
+        return `${ro.join(', ')} ${ro.length === 1 ? 'is' : 'are'} report-only: ${ro.includes('target') ? 'reclaim target/ with bash scripts/target-gc.sh (the measured policy)' : 'funtools never touches them'}`;
+    return null;
+}
+export async function diskApply(o, d) {
+    const before = await diskReport(o, d);
+    const out = [];
+    let freed = 0;
+    const kinds = new Set(o.only ?? []);
+    const fresh = async () => ({ procs: await d.procs(), cwds: await d.cwds() });
+    const repo = kinds.has('worktrees') ? await repoOf(d) : null;
+    const unitySafe = before.lines.filter((l) => l.kind === 'unity' && l.verdict === 'safe');
+    for (const l of before.lines) {
+        if (l.verdict !== 'safe' || !l.applies || !kinds.has(l.kind) || !l.path) {
+            if (l.kind !== 'free')
+                out.push(l);
+            continue;
+        }
+        if (l.kind === 'unity' || l.kind === 'scratch')
+            continue;
+        const now = await fresh();
+        if (l.kind === 'worktrees' && repo) {
+            const wt = { path: l.path, head: (await d.git(['rev-parse', 'HEAD'], l.path)).stdout.trim() || undefined };
+            const r = await checkWorktree(wt, repo, { d, ...now });
+            if (r.verdict !== 'safe') {
+                out.push({ ...l, verdict: r.verdict, state: 'pass', applies: false, says: `${r.why} (checked again before removing)`, next: undefined });
+                continue;
+            }
+            const rm1 = await d.git(['worktree', 'remove', l.path], repo.top);
+            if (rm1.status !== 0) {
+                out.push({ ...l, verdict: 'failed', state: 'warn', says: `git worktree remove refused: ${rm1.stderr.trim().split('\n')[0]}`, next: undefined });
+                continue;
+            }
+            freed += l.bytes ?? 0;
+            out.push({ ...l, verdict: 'removed', state: 'pass', says: 'removed with git worktree remove (its branch stays)', next: undefined });
+            continue;
+        }
+        if (l.kind === 'derived-data') {
+            const busy = await busyIn(l.path, now.procs, now.cwds, d.self);
+            const s = await lstat(l.path).catch(() => null);
+            const m = s?.isDirectory() ? await measure(l.path, d.now() + d.walkMs, d.now) : null;
+            const why = busy ?? (!s || !s.isDirectory() ? 'no longer a directory' : !m?.complete ? 'not proven idle in time' : m.newest > d.now() - o.days * 86400_000 ? `touched ${ago(d.now(), m.newest)}` : null);
+            if (why) {
+                out.push({ ...l, verdict: 'in-use', state: 'pass', applies: false, says: `${why} (checked again before deleting)`, next: undefined });
+                continue;
+            }
+            await rm(l.path, { recursive: true, force: true });
+            freed += l.bytes ?? 0;
+            out.push({ ...l, verdict: 'removed', state: 'pass', says: 'deleted', next: undefined });
+        }
+    }
+    if (kinds.has('unity') && unitySafe.length) {
+        const procs = await d.procs();
+        const g = { root: d.unityLocks, procs: async () => procs, now: d.now, staleMs: d.staleMs, du: async () => 0 };
+        const folders = unitySafe.map((l) => ({ project: dirname(l.path), folder: basename(l.path), path: l.path, bytes: l.bytes ?? 0, touched: '' }));
+        const done = await gcApply({ folders, skipped: [], recent: 0, bytes: 0 }, g);
+        for (const f of done.removed) {
+            freed += f.bytes;
+            out.push({ ...unitySafe.find((l) => l.path === f.path), verdict: 'removed', state: 'pass', says: 'deleted', next: undefined });
+        }
+        for (const k of done.kept)
+            for (const l of unitySafe.filter((x) => dirname(x.path) === k.project))
+                out.push({ ...l, verdict: 'in-use', state: 'pass', applies: false, says: k.why, next: undefined });
+    }
+    if (kinds.has('scratch')) {
+        const procs = await d.procs();
+        const c = { d, o, procs, cwds: await d.cwds(), budget: new Budget(d), lines: [], t: (p) => tilde(p, d.home), sh: (p) => shellPath(p, d.home), cutoff: d.now() - o.days * 86400_000 };
+        const { plans, held } = await scratchPlans(c, await findProjects(o.roots));
+        for (const p of plans) {
+            let gone = 0;
+            for (const e of p.entries) {
+                const s = await lstat(e.path).catch(() => null);
+                if (!s)
+                    continue;
+                await rm(e.path, { recursive: s.isDirectory() && !s.isSymbolicLink(), force: true });
+                gone += e.bytes;
+            }
+            freed += gone;
+            out.push({ kind: 'scratch', verdict: 'removed', state: 'pass', check: `funtools scratch ${c.t(p.dir)}`, path: p.dir, bytes: gone, says: `deleted ${p.entries.length} entr${p.entries.length === 1 ? 'y' : 'ies'} older than ${o.days} days` });
+        }
+        for (const h of held)
+            out.push({ kind: 'scratch', verdict: 'in-use', state: 'pass', check: `funtools scratch ${c.t(join(h.project, '.funtools', 'unity'))}`, path: h.project, says: `${h.why} (checked again before deleting)` });
+    }
+    const space = await d.free(d.cwd);
+    return finish(o, space, out.filter((l) => !(l.kind === 'scratch' && l.verdict === 'safe' && kinds.has('scratch'))), true, freed);
+}
+export const realGit = (args, cwd) => new Promise((ok) => {
+    execFile('git', args, { cwd, timeout: 30_000, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const code = err?.code;
+        ok({ status: !err ? 0 : typeof code === 'number' ? code : 1, stdout: String(stdout ?? ''), stderr: String(stderr || (err ? err.message : '')) });
+    });
+});
+export const realCwds = () => new Promise((ok) => {
+    execFile('lsof', ['-a', '-d', 'cwd', '-Fpn'], { timeout: 30_000, maxBuffer: 32 * 1024 * 1024 }, (err, stdout) => {
+        const text = String(stdout ?? '');
+        ok(text.trim() ? parseLsofCwd(text) : err ? null : new Map());
+    });
+});
+export function realDiskDeps(over) {
+    return {
+        home: homedir(), tmpRoots: [tmpdir(), '/tmp'], cwd: process.cwd(), env: process.env, now: Date.now, git: realGit,
+        cwds: realCwds, free: freeAt, self: process.pid, budgetMs: 120_000, walkMs: 20_000, ...over,
+    };
+}