@voidmatcha/d4c 0.1.1

package/README.md

@@ -0,0 +1,73 @@
+# d4c
+
+**Find and reclaim `node_modules` trees you stopped using.**
+
+Dry-run by default. Never deletes a tree it cannot restore.
+
+```bash
+npx d4c gc                    # what could be reclaimed
+npx d4c gc --yes              # actually delete
+npx d4c history               # what was deleted, and how to restore it
+```
+
+## Why
+
+On the machine this was built for, 976 `node_modules` trees held 53.6 GB
+that had seen no activity in 30 days — more than the free space left on
+the disk.
+
+Old worktrees, benchmark runs, abandoned experiments, PR checkouts. Every
+one of them regenerable from a lockfile in about a second.
+
+## What it will not touch
+
+- Trees with no lockfile anywhere that could rebuild them. A lockfile in a
+  parent directory only counts if that directory declares the tree as a
+  workspace member.
+- Trees with recent activity — measured from `node_modules` mtime and git
+  index mtime, whichever is more recent.
+- Symlinked `node_modules`. The real tree lives elsewhere.
+- Anything spanning a mount boundary.
+- Anything matched by `--exclude`.
+
+Every guard is re-checked immediately before deletion, not trusted from
+the earlier scan.
+
+## Options
+
+```
+d4c gc [options]
+
+  --days N          Idle threshold in days (default 30, minimum 1)
+  --exclude PATTERN Protect matching paths. Repeatable. Full match;
+                    use a/** for a subtree, **/a for any depth.
+  --min-size SIZE   Ignore trees smaller than this (e.g. 10M, 1G)
+  --depth N         How deep to search (default 8)
+  --yes             Actually delete. Without it nothing is removed.
+  --json            Machine-readable output on stdout only.
+
+d4c history [--limit N] [--json]
+```
+
+## The number is a lower bound
+
+Idle age comes from mtime, which records the last install or git
+operation — not the last read. **A project you still use can look idle,
+and a long-running process leaves no trace at all.** Check the list before
+passing `--yes`.
+
+Sizes come from `st_blocks`, so they track what deletion actually frees
+(measured within ~3% of real freed space). Trees whose files are shared
+through APFS clones will be over-reported, since clone sharing is
+invisible to `st_blocks`.
+
+## Recovery
+
+Every deletion is appended to `~/.local/state/d4c/deletions.jsonl` the
+moment it happens — so an interrupted run is still fully recorded.
+`d4c history` prints each project with the install command that rebuilds
+it, matched to the lockfile that was there.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,854 @@
+#!/usr/bin/env node
+
+// ../core/src/reap/index.ts
+import { lstat as lstat2, stat as stat2, rm } from "node:fs/promises";
+import { basename, join as join3 } from "node:path";
+
+// ../core/src/fs/trees.ts
+import { readdir, lstat, stat, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+var LOCKFILES = [
+  "npm-shrinkwrap.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lock",
+  "bun.lockb"
+];
+var SKIP_DIRS = new Set([
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  ".Trash",
+  "Library"
+]);
+var DAY_MS = 86400000;
+var ACTIVITY_FILES = [".git/index", ".git/HEAD", ".git/FETCH_HEAD"];
+async function lastActivityMs(projectRoot, nodeModulesMtimeMs) {
+  let latest = nodeModulesMtimeMs;
+  for (const rel of ACTIVITY_FILES) {
+    try {
+      const st = await lstat(join(projectRoot, rel));
+      if (st.mtimeMs > latest)
+        latest = st.mtimeMs;
+    } catch {}
+  }
+  return latest;
+}
+function globMatches(pattern, rel) {
+  let re = "";
+  for (let i = 0;i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        re += ".*";
+        i++;
+      } else
+        re += "[^/]*";
+      continue;
+    }
+    re += ch.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp("^" + re + "$").test(rel);
+}
+async function declaresWorkspaceMember(dir, projectRoot) {
+  const rel = projectRoot.slice(dir.length + 1);
+  if (rel === "" || rel.startsWith("/"))
+    return false;
+  const globs = [];
+  try {
+    const pkg = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
+    const w = pkg.workspaces;
+    if (Array.isArray(w))
+      globs.push(...w);
+    else if (w && Array.isArray(w.packages))
+      globs.push(...w.packages);
+  } catch {}
+  try {
+    const yaml = await readFile(join(dir, "pnpm-workspace.yaml"), "utf8");
+    for (const line of yaml.split(`
+`)) {
+      const m = /^\s*-\s*['"]?([^'"#]+?)['"]?\s*$/.exec(line);
+      if (m)
+        globs.push(m[1].trim());
+    }
+  } catch {}
+  return globs.some((g) => globMatches(g, rel));
+}
+async function detectLockfile(projectRoot, scanRoot) {
+  for (const name of LOCKFILES) {
+    try {
+      const st = await lstat(join(projectRoot, name));
+      if (st.isFile())
+        return { lockfile: name, lockfileDir: projectRoot };
+    } catch {}
+  }
+  let dir = dirname(projectRoot);
+  for (;; ) {
+    if (!dir.startsWith(scanRoot))
+      break;
+    for (const name of LOCKFILES) {
+      try {
+        const st = await lstat(join(dir, name));
+        if (!st.isFile())
+          continue;
+        if (await declaresWorkspaceMember(dir, projectRoot)) {
+          return { lockfile: name, lockfileDir: dir };
+        }
+      } catch {}
+    }
+    if (dir === scanRoot)
+      break;
+    const parent = dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return { lockfile: null, lockfileDir: null };
+}
+function allocatedSize(st) {
+  return st.blocks * 512;
+}
+async function measureTree(tree, opts = {}) {
+  const m = await measure(tree.path, opts.statBatchSize ?? 256, opts.onUnreadable);
+  tree.sizeBytes = m.sizeBytes;
+  tree.externallyLinkedBytes = m.externallyLinkedBytes;
+  tree.fileCount = m.fileCount;
+  tree.crossesMountBoundary = m.crossesMountBoundary;
+  return tree;
+}
+async function measure(dir, batchSize, onUnreadable) {
+  let fileCount = 0;
+  let rootDev = null;
+  let crossesMountBoundary = false;
+  const inodes = new Map;
+  const stack = [dir];
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    let entries;
+    try {
+      entries = await readdir(cur, { withFileTypes: true });
+    } catch {
+      onUnreadable?.(cur);
+      continue;
+    }
+    const files = [];
+    for (const e of entries) {
+      const p = join(cur, e.name);
+      if (e.isDirectory())
+        stack.push(p);
+      else if (e.isSymbolicLink())
+        fileCount++;
+      else if (e.isFile())
+        files.push(p);
+    }
+    for (let i = 0;i < files.length; i += batchSize) {
+      const stats = await Promise.all(files.slice(i, i + batchSize).map((f) => lstat(f).catch(() => null)));
+      for (const st of stats) {
+        if (st === null)
+          continue;
+        if (rootDev === null)
+          rootDev = st.dev;
+        else if (st.dev !== rootDev)
+          crossesMountBoundary = true;
+        fileCount++;
+        const key = `${st.dev}:${st.ino}`;
+        const seen = inodes.get(key);
+        if (seen === undefined)
+          inodes.set(key, { size: allocatedSize(st), nlink: st.nlink, seen: 1 });
+        else
+          seen.seen++;
+      }
+    }
+  }
+  let sizeBytes = 0;
+  let externallyLinkedBytes = 0;
+  for (const { size, nlink, seen } of inodes.values()) {
+    if (seen < nlink)
+      externallyLinkedBytes += size;
+    else
+      sizeBytes += size;
+  }
+  return { sizeBytes, externallyLinkedBytes, fileCount, crossesMountBoundary };
+}
+async function findDependencyTrees(root, opts = {}) {
+  const maxDepth = opts.maxDepth ?? 8;
+  const batchSize = opts.statBatchSize ?? 256;
+  const dirConcurrency = opts.dirConcurrency ?? 16;
+  const skip = new Set([...SKIP_DIRS, ...opts.skip ?? []]);
+  const out = [];
+  const now = Date.now();
+  const queue = [{ dir: root, depth: 0 }];
+  const visit = async (dir, depth) => {
+    if (depth > maxDepth) {
+      opts.onDepthLimit?.(dir);
+      return;
+    }
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      opts.onUnreadable?.(dir);
+      return;
+    }
+    const nm = entries.find((e) => e.name === "node_modules");
+    if (nm) {
+      const nmPath = join(dir, "node_modules");
+      if (nm.isDirectory() && !nm.isSymbolicLink()) {
+        try {
+          const st = await stat(nmPath);
+          const tree = {
+            path: nmPath,
+            projectRoot: dir,
+            sizeBytes: null,
+            externallyLinkedBytes: null,
+            fileCount: null,
+            crossesMountBoundary: false,
+            idleDays: Math.max(0, Math.floor((now - await lastActivityMs(dir, st.mtimeMs)) / DAY_MS)),
+            ...await detectLockfile(dir, root)
+          };
+          out.push(tree);
+          opts.onTree?.(tree);
+        } catch {}
+      }
+    }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.isSymbolicLink())
+        continue;
+      if (skip.has(e.name))
+        continue;
+      queue.push({ dir: join(dir, e.name), depth: depth + 1 });
+    }
+  };
+  let active = 0;
+  const workers = Array.from({ length: dirConcurrency }, async () => {
+    for (;; ) {
+      if (opts.signal?.aborted === true)
+        return;
+      const next = queue.pop();
+      if (next === undefined) {
+        if (active === 0)
+          return;
+        await new Promise((r) => setTimeout(r, 1));
+        continue;
+      }
+      active++;
+      try {
+        await visit(next.dir, next.depth);
+      } finally {
+        active--;
+      }
+    }
+  });
+  await Promise.all(workers);
+  return out;
+}
+
+// ../core/src/reap/filter.ts
+function toRegExp(pattern) {
+  let out = "";
+  for (let i = 0;i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        out += ".*";
+        i++;
+      } else {
+        out += "[^/]*";
+      }
+      continue;
+    }
+    out += ch.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp("^" + out + "$");
+}
+function matchesAny(path, patterns) {
+  return patterns.some((p) => toRegExp(p).test(path));
+}
+var UNITS = {
+  "": 1,
+  b: 1,
+  k: 1024,
+  kb: 1024,
+  kib: 1024,
+  m: 1024 ** 2,
+  mb: 1024 ** 2,
+  mib: 1024 ** 2,
+  g: 1024 ** 3,
+  gb: 1024 ** 3,
+  gib: 1024 ** 3,
+  t: 1024 ** 4,
+  tb: 1024 ** 4,
+  tib: 1024 ** 4
+};
+function parseSize(input) {
+  const m = /^(\d+(?:\.\d+)?)\s*([a-zA-Z]*)$/.exec(input.trim());
+  if (m === null)
+    return null;
+  const unit = UNITS[m[2].toLowerCase()];
+  if (unit === undefined)
+    return null;
+  const n = Number(m[1]) * unit;
+  return Number.isFinite(n) && n >= 0 ? Math.round(n) : null;
+}
+
+// ../core/src/reap/log.ts
+import { appendFile, mkdir, readFile as readFile2 } from "node:fs/promises";
+import { dirname as dirname2, join as join2 } from "node:path";
+function defaultLogPath(env = process.env) {
+  const state = env.XDG_STATE_HOME ?? join2(env.HOME ?? ".", ".local", "state");
+  return join2(state, "d4c", "deletions.jsonl");
+}
+async function appendDeletion(logPath, input) {
+  const rec = {
+    at: new Date().toISOString(),
+    runId: input.runId,
+    root: input.root,
+    projectRoot: input.tree.projectRoot,
+    path: input.tree.path,
+    freedBytes: input.freedBytes,
+    idleDays: input.tree.idleDays,
+    lockfile: input.tree.lockfile,
+    lockfileDir: input.tree.lockfileDir
+  };
+  await mkdir(dirname2(logPath), { recursive: true });
+  await appendFile(logPath, JSON.stringify(rec) + `
+`, "utf8");
+}
+async function readHistory(logPath) {
+  let raw;
+  try {
+    raw = await readFile2(logPath, "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split(`
+`)) {
+    if (line.trim() === "")
+      continue;
+    try {
+      const v = JSON.parse(line);
+      if (typeof v.projectRoot === "string")
+        out.push(v);
+    } catch {}
+  }
+  return out;
+}
+function restoreCommand(lockfile) {
+  switch (lockfile) {
+    case "yarn.lock":
+      return "yarn install";
+    case "pnpm-lock.yaml":
+      return "pnpm install";
+    case "bun.lock":
+    case "bun.lockb":
+      return "bun install";
+    default:
+      return "npm install";
+  }
+}
+
+// ../core/src/reap/index.ts
+function relativeTo(path, root) {
+  if (path === root)
+    return ".";
+  const prefix = root.endsWith("/") ? root : root + "/";
+  return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+var DEFAULT_IDLE_THRESHOLD_DAYS = 30;
+async function planReap(root, opts = {}) {
+  const idleThresholdDays = opts.idleThresholdDays ?? DEFAULT_IDLE_THRESHOLD_DAYS;
+  if (idleThresholdDays < 1) {
+    throw new RangeError("idleThresholdDays must be at least 1");
+  }
+  const diagnostics = { unreadableDirs: 0, depthLimited: 0 };
+  const trees = await findDependencyTrees(root, {
+    ...opts,
+    signal: opts.signal,
+    onUnreadable: (p) => {
+      diagnostics.unreadableDirs++;
+      opts.onUnreadable?.(p);
+    },
+    onDepthLimit: (p) => {
+      diagnostics.depthLimited++;
+      opts.onDepthLimit?.(p);
+    }
+  });
+  const candidates = [];
+  const skipped = [];
+  let totalBytes = 0;
+  const exclude = opts.exclude ?? [];
+  const minSizeBytes = opts.minSizeBytes ?? 0;
+  for (const tree of trees) {
+    if (matchesAny(relativeTo(tree.projectRoot, root), exclude)) {
+      skipped.push({ tree, reason: "excluded" });
+      continue;
+    }
+    if (tree.idleDays < idleThresholdDays) {
+      skipped.push({ tree, reason: "recently-modified" });
+      continue;
+    }
+    if (tree.lockfile === null) {
+      skipped.push({ tree, reason: "no-lockfile" });
+      continue;
+    }
+    let plannedMtimeMs = 0;
+    try {
+      plannedMtimeMs = (await lstat2(tree.path)).mtimeMs;
+    } catch {
+      continue;
+    }
+    candidates.push({ tree, plannedMtimeMs });
+  }
+  let interrupted = opts.signal?.aborted === true;
+  for (const c of candidates) {
+    if (opts.signal?.aborted === true) {
+      interrupted = true;
+      break;
+    }
+    await measureTree(c.tree, { statBatchSize: opts.statBatchSize, onUnreadable: opts.onUnreadable });
+    totalBytes += c.tree.sizeBytes ?? 0;
+    opts.onMeasured?.(c.tree);
+  }
+  const tooSmall = candidates.filter((c) => (c.tree.sizeBytes ?? 0) < minSizeBytes);
+  for (const c of tooSmall)
+    skipped.push({ tree: c.tree, reason: "below-min-size" });
+  const kept = candidates.filter((c) => (c.tree.sizeBytes ?? 0) >= minSizeBytes);
+  candidates.length = 0;
+  candidates.push(...kept);
+  candidates.sort((a, b) => (b.tree.sizeBytes ?? 0) - (a.tree.sizeBytes ?? 0));
+  return {
+    root,
+    idleThresholdDays,
+    exclude,
+    minSizeBytes,
+    candidates,
+    skipped,
+    reclaimableBytes: candidates.reduce((s, c) => s + (c.tree.sizeBytes ?? 0), 0),
+    totalBytes,
+    treeCount: trees.length,
+    diagnostics,
+    interrupted
+  };
+}
+async function verifyStillReapable(c) {
+  const { tree, plannedMtimeMs } = c;
+  if (basename(tree.path) !== "node_modules")
+    return "not-a-node-modules-path";
+  let st;
+  try {
+    st = await lstat2(tree.path);
+  } catch {
+    return "vanished";
+  }
+  if (st.isSymbolicLink())
+    return "became-symlink";
+  if (!st.isDirectory())
+    return "not-a-node-modules-path";
+  if (st.mtimeMs !== plannedMtimeMs)
+    return "changed-since-plan";
+  if (c.tree.crossesMountBoundary)
+    return "crosses-mount-boundary";
+  if (tree.lockfile === null || tree.lockfileDir === null)
+    return "lockfile-vanished";
+  for (const f of [tree.lockfile, "package.json"]) {
+    try {
+      const st2 = await stat2(join3(tree.lockfileDir, f));
+      if (!st2.isFile())
+        return "lockfile-vanished";
+    } catch {
+      return "lockfile-vanished";
+    }
+  }
+  return null;
+}
+async function executeReap(plan, opts = {}) {
+  const apply = opts.apply === true;
+  const runId = opts.runId ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const logPath = !apply ? null : opts.logPath === null ? null : opts.logPath ?? defaultLogPath();
+  const deleted = [];
+  const aborted = [];
+  let interrupted = false;
+  for (const c of plan.candidates) {
+    if (opts.signal?.aborted === true) {
+      interrupted = true;
+      break;
+    }
+    const problem = await verifyStillReapable(c);
+    if (problem !== null) {
+      aborted.push({ tree: c.tree, reason: problem });
+      opts.onProgress?.(c.tree, "aborted");
+      continue;
+    }
+    if (!apply)
+      continue;
+    try {
+      await rm(c.tree.path, { recursive: true, force: false });
+      const freedBytes = c.tree.sizeBytes ?? 0;
+      deleted.push({ tree: c.tree, freedBytes });
+      if (logPath !== null) {
+        try {
+          await appendDeletion(logPath, { tree: c.tree, freedBytes, runId, root: plan.root });
+        } catch {}
+      }
+      opts.onProgress?.(c.tree, "deleted");
+    } catch (e) {
+      aborted.push({ tree: c.tree, reason: "delete-failed", detail: String(e) });
+      opts.onProgress?.(c.tree, "aborted");
+    }
+  }
+  return {
+    dryRun: !apply,
+    deleted,
+    aborted,
+    freedBytes: deleted.reduce((s, d) => s + d.freedBytes, 0),
+    interrupted,
+    runId,
+    logPath
+  };
+}
+
+// src/render.ts
+function humanBytes(n) {
+  const u = ["B", "KiB", "MiB", "GiB", "TiB"];
+  let v = n, i = 0;
+  while (v >= 1024 && i < u.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v < 10 && i > 0 ? v.toFixed(1) : Math.round(v)} ${u[i]}`;
+}
+function relativize(path, root) {
+  return path.startsWith(root) ? "." + path.slice(root.length) : path;
+}
+
+// src/commands/gc.ts
+async function gc(args) {
+  const showProgress = process.stderr.isTTY === true;
+  let found = 0;
+  let measured = 0;
+  let measuredBytes = 0;
+  let lastDraw = 0;
+  const draw = (line) => {
+    const now = Date.now();
+    if (now - lastDraw < 100)
+      return;
+    lastDraw = now;
+    process.stderr.write(`\r${line.padEnd(60)}`);
+  };
+  const onTree = showProgress ? () => {
+    found++;
+    draw(`  finding trees… ${found}`);
+  } : undefined;
+  const onMeasured = showProgress ? (t) => {
+    measured++;
+    measuredBytes += t.sizeBytes ?? 0;
+    draw(`  measuring… ${measured} candidate(s), ${humanBytes(measuredBytes)}`);
+  } : undefined;
+  const ac = new AbortController;
+  let interrupts = 0;
+  const onSigint = () => {
+    interrupts++;
+    if (interrupts === 1) {
+      ac.abort();
+      process.stderr.write(`
+  stopping after the current tree… (Ctrl+C again to force)
+`);
+    } else {
+      process.exit(130);
+    }
+  };
+  process.on("SIGINT", onSigint);
+  const plan = await planReap(args.cwd, {
+    idleThresholdDays: args.days,
+    maxDepth: args.depth,
+    signal: ac.signal,
+    exclude: args.exclude,
+    minSizeBytes: args.minSizeBytes,
+    onTree,
+    onMeasured
+  });
+  if (showProgress)
+    process.stderr.write("\r" + " ".repeat(62) + "\r");
+  const result = await executeReap(plan, { apply: args.yes, logPath: args.logPath, signal: ac.signal });
+  process.off("SIGINT", onSigint);
+  if (args.json) {
+    process.stdout.write(JSON.stringify({
+      schemaVersion: 1,
+      root: args.cwd,
+      idleThresholdDays: plan.idleThresholdDays,
+      exclude: plan.exclude,
+      minSizeBytes: plan.minSizeBytes,
+      dryRun: result.dryRun,
+      interrupted: plan.interrupted || result.interrupted,
+      totalBytes: plan.totalBytes,
+      treeCount: plan.treeCount,
+      diagnostics: plan.diagnostics,
+      reclaimableBytes: plan.reclaimableBytes,
+      freedBytes: result.freedBytes,
+      candidates: plan.candidates.map((c) => ({
+        path: c.tree.path,
+        projectRoot: c.tree.projectRoot,
+        sizeBytes: c.tree.sizeBytes ?? 0,
+        externallyLinkedBytes: c.tree.externallyLinkedBytes ?? 0,
+        idleDays: c.tree.idleDays,
+        lockfile: c.tree.lockfile
+      })),
+      skipped: plan.skipped.map((s) => ({
+        projectRoot: s.tree.projectRoot,
+        sizeBytes: s.tree.sizeBytes,
+        idleDays: s.tree.idleDays,
+        reason: s.reason
+      })),
+      runId: result.runId,
+      logPath: result.logPath,
+      deleted: result.deleted.map((d2) => ({ path: d2.tree.path, freedBytes: d2.freedBytes })),
+      aborted: result.aborted.map((a) => ({ path: a.tree.path, reason: a.reason }))
+    }) + `
+`);
+    return 0;
+  }
+  const out = [];
+  out.push("D4C — dependency garbage collection", "");
+  if (plan.candidates.length === 0) {
+    out.push(`Nothing to reclaim. Scanned ${plan.treeCount} tree(s);`);
+    out.push(`none has been untouched for ${plan.idleThresholdDays}+ days with a lockfile present.`);
+    const noLock = plan.skipped.filter((s) => s.reason === "no-lockfile");
+    if (noLock.length > 0) {
+      out.push("", `${noLock.length} idle tree(s) skipped: no lockfile, so they could not be regenerated.`);
+    }
+    process.stdout.write(out.join(`
+`) + `
+`);
+    return 0;
+  }
+  const verb = result.dryRun ? "Would reclaim" : "Reclaimed";
+  const bytes = result.dryRun ? plan.reclaimableBytes : result.freedBytes;
+  out.push(`${verb} ${humanBytes(bytes)} from ${plan.candidates.length} tree(s)`);
+  out.push(`untouched for ${plan.idleThresholdDays}+ days, from ${plan.treeCount} tree(s) scanned.`, "");
+  for (const c of plan.candidates.slice(0, 20)) {
+    out.push(`  ${humanBytes(c.tree.sizeBytes ?? 0).padStart(9)}  ${String(c.tree.idleDays).padStart(4)}d  ${relativize(c.tree.projectRoot, args.cwd)}`);
+  }
+  if (plan.candidates.length > 20)
+    out.push(`  ... and ${plan.candidates.length - 20} more`);
+  if (result.aborted.length > 0) {
+    out.push("", `${result.aborted.length} skipped at the last check:`);
+    for (const a of result.aborted.slice(0, 10)) {
+      out.push(`  ${a.reason.padEnd(24)} ${relativize(a.tree.projectRoot, args.cwd)}`);
+    }
+  }
+  const externallyLinked = plan.candidates.reduce((n, c) => n + (c.tree.externallyLinkedBytes ?? 0), 0);
+  if (externallyLinked > 0) {
+    out.push("", `${humanBytes(externallyLinked)} in these trees is hardlinked from outside`);
+    out.push("and will not be freed by deleting them. It is excluded from the total above.");
+  }
+  const excluded = plan.skipped.filter((s) => s.reason === "excluded");
+  if (excluded.length > 0) {
+    out.push("", `${excluded.length} tree(s) protected by --exclude.`);
+  }
+  const d = plan.diagnostics;
+  if (d.unreadableDirs > 0 || d.depthLimited > 0) {
+    out.push("");
+    if (d.unreadableDirs > 0) {
+      out.push(`${d.unreadableDirs} director${d.unreadableDirs === 1 ? "y" : "ies"} could not be read;`);
+      out.push("trees inside them are missing from these totals.");
+    }
+    if (d.depthLimited > 0) {
+      out.push(`${d.depthLimited} path(s) hit the depth limit and were not searched further.`);
+    }
+  }
+  if (plan.interrupted || result.interrupted) {
+    out.push("");
+    out.push("Interrupted. The trees listed above are what was handled before stopping;");
+    out.push("anything else was left untouched.");
+  }
+  out.push("");
+  out.push("Idle age is measured from the last install or modification, not the");
+  out.push("last time the tree was read. A project you still use can look idle.");
+  out.push("");
+  out.push("Restore any of these by running `npm install` in the project.");
+  if (result.logPath !== null && result.deleted.length > 0) {
+    out.push(`Recorded in ${result.logPath} — see \`d4c history\`.`);
+  }
+  if (result.dryRun)
+    out.push("", "Nothing was deleted. Re-run with --yes to apply.");
+  process.stdout.write(out.join(`
+`) + `
+`);
+  return plan.interrupted || result.interrupted ? 130 : 0;
+}
+var DEFAULT_DAYS = DEFAULT_IDLE_THRESHOLD_DAYS;
+
+// src/commands/history.ts
+function groupByRun(records) {
+  const runs = new Map;
+  for (const r of records) {
+    const list = runs.get(r.runId) ?? [];
+    list.push(r);
+    runs.set(r.runId, list);
+  }
+  return runs;
+}
+async function history(args) {
+  const path = args.logPath ?? defaultLogPath();
+  const records = await readHistory(path);
+  if (args.json) {
+    process.stdout.write(JSON.stringify({ schemaVersion: 1, logPath: path, records }) + `
+`);
+    return 0;
+  }
+  if (records.length === 0) {
+    process.stdout.write(`No deletions recorded.
+Log would be at ${path}
+`);
+    return 0;
+  }
+  const runs = [...groupByRun(records).entries()].reverse().slice(0, args.limit);
+  const out = [`D4C — deletion history (${path})`, ""];
+  for (const [runId, recs] of runs) {
+    const freed = recs.reduce((s, r) => s + r.freedBytes, 0);
+    out.push(`${recs[0].at}  run ${runId}`);
+    out.push(`  ${recs.length} tree(s), ${humanBytes(freed)} freed, scanned from ${recs[0].root}`);
+    for (const r of recs.slice(0, 10)) {
+      out.push(`    ${humanBytes(r.freedBytes).padStart(9)}  ${r.projectRoot}`);
+    }
+    if (recs.length > 10)
+      out.push(`    ... and ${recs.length - 10} more`);
+    out.push("");
+  }
+  const cmds = new Set(records.map((r) => restoreCommand(r.lockfile)));
+  out.push("Restore any project by running its install command in that directory:");
+  for (const c of cmds)
+    out.push(`  ${c}`);
+  out.push("", "Use --json for the full list.");
+  process.stdout.write(out.join(`
+`) + `
+`);
+  return 0;
+}
+
+// src/args.ts
+var VALUE_FLAGS = new Set(["--days", "--exclude", "--min-size", "--limit", "--log", "--depth"]);
+function parseArgs(argv) {
+  const flags = new Set;
+  const values = new Map;
+  const errors = [];
+  let command;
+  for (let i = 0;i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      if (command === undefined)
+        command = a;
+      else
+        errors.push(`unexpected argument: ${a}`);
+      continue;
+    }
+    const eq = a.indexOf("=");
+    const key = eq >= 0 ? a.slice(0, eq) : a;
+    if (VALUE_FLAGS.has(key)) {
+      const v = eq >= 0 ? a.slice(eq + 1) : argv[++i];
+      if (v === undefined) {
+        errors.push(`${key} requires a value`);
+        continue;
+      }
+      const list = values.get(key) ?? [];
+      list.push(v);
+      values.set(key, list);
+    } else {
+      flags.add(key);
+    }
+  }
+  return { command, flags, values, errors };
+}
+function firstValue(p, key) {
+  return p.values.get(key)?.[0];
+}
+
+// src/index.ts
+var USAGE = `d4c — dependency storage tooling for Git worktrees
+
+Usage:
+  d4c gc [options]
+  d4c history [--limit N] [--json]
+
+  gc        Report node_modules trees idle long enough to delete safely,
+            and delete them with --yes. Dry-run by default.
+  history   Show what previous runs deleted, and how to restore it.
+
+Options:
+  --days N          Idle threshold in days (default ${DEFAULT_DAYS})
+  --exclude PATTERN Protect matching paths. Repeatable. Supports * and **.
+  --min-size SIZE   Ignore trees smaller than this (e.g. 10M, 1G)
+  --depth N         How deep to search below the current directory (default 8)
+  --yes             Actually delete. Without it nothing is removed.
+  --json            Machine-readable output on stdout only.
+  --limit N         history: how many runs to show (default 5)
+`;
+async function main(argv) {
+  const p = parseArgs(argv);
+  if (p.command === undefined || p.flags.has("--help") || p.command === "help") {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (p.errors.length > 0) {
+    for (const e of p.errors)
+      process.stderr.write(`${e}
+`);
+    return 70;
+  }
+  if (p.command === "gc") {
+    const daysRaw = firstValue(p, "--days");
+    const days = daysRaw === undefined ? DEFAULT_DAYS : Number(daysRaw);
+    if (!Number.isFinite(days) || days < 1) {
+      process.stderr.write(`--days must be at least 1
+`);
+      return 70;
+    }
+    const depthRaw = firstValue(p, "--depth");
+    if (depthRaw !== undefined && (!Number.isFinite(Number(depthRaw)) || Number(depthRaw) < 1)) {
+      process.stderr.write(`--depth must be a positive number
+`);
+      return 70;
+    }
+    const sizeRaw = firstValue(p, "--min-size");
+    const minSizeBytes = sizeRaw === undefined ? 0 : parseSize(sizeRaw) ?? -1;
+    if (minSizeBytes < 0) {
+      process.stderr.write(`--min-size: cannot parse ${JSON.stringify(sizeRaw)}
+`);
+      return 70;
+    }
+    return gc({
+      json: p.flags.has("--json"),
+      yes: p.flags.has("--yes"),
+      days,
+      cwd: process.cwd(),
+      exclude: p.values.get("--exclude") ?? [],
+      minSizeBytes,
+      logPath: firstValue(p, "--log"),
+      depth: depthRaw === undefined ? undefined : Number(depthRaw)
+    });
+  }
+  if (p.command === "history") {
+    const limitRaw = firstValue(p, "--limit");
+    const limit = limitRaw === undefined ? 5 : Number(limitRaw);
+    if (!Number.isFinite(limit) || limit < 1) {
+      process.stderr.write(`--limit must be a positive number
+`);
+      return 70;
+    }
+    return history({ json: p.flags.has("--json"), limit, logPath: firstValue(p, "--log") });
+  }
+  process.stderr.write(`unknown command: ${p.command}
+
+${USAGE}`);
+  return 70;
+}
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}).catch((err) => {
+  process.stderr.write(`internal error: ${err?.stack ?? err}
+`);
+  process.exitCode = 70;
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@voidmatcha/d4c",
+  "version": "0.1.1",
+  "description": "Reclaim node_modules disk space safely. Deletes only what a lockfile can rebuild, records everything it removes.",
+  "keywords": [
+    "node_modules",
+    "disk-space",
+    "cleanup",
+    "gc",
+    "monorepo",
+    "worktree",
+    "npm",
+    "pnpm",
+    "yarn",
+    "bun"
+  ],
+  "license": "MIT",
+  "author": "voidmatcha",
+  "type": "module",
+  "bin": {
+    "d4c": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "bun build ../../packages/cli/src/index.ts --target=node --outfile dist/index.js --minify"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voidmatcha/d4c"
+  }
+}