node-modules-hunter 1.0.0 → 1.1.1

package/dist/cli.js

@@ -2,7 +2,8 @@
 
 // src/cli.ts
 import { cac } from "cac";
-import path24 from "path";
+import path25 from "path";
+import { existsSync } from "fs";
 
 // src/utils/logger.ts
 import pc from "picocolors";
@@ -82,11 +83,38 @@ function progressAllowed() {
   if (state.progress === "on") return true;
   return state.isTTY;
 }
-function progressLine(message) {
-  if (state.quiet || !progressAllowed()) return;
-  process.stdout.write(CLEAR_LINE + colors.dim(message));
+var SPIN_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var SPIN_MS = 70;
+var spinTimer = null;
+var spinFrame = 0;
+var spinMsg = "";
+function spinPaint() {
+  process.stdout.write(CLEAR_LINE + colors.dim(`${SPIN_FRAMES[spinFrame]} ${spinMsg}`));
+}
+function startSpin() {
+  spinFrame = 0;
+  spinPaint();
+  const timer = setInterval(() => {
+    spinFrame = (spinFrame + 1) % SPIN_FRAMES.length;
+    spinPaint();
+  }, SPIN_MS);
+  spinTimer = timer;
+  if (typeof timer.unref === "function") timer.unref();
+}
+function spinUpdate(message) {
+  spinMsg = message;
+  if (state.quiet || !progressAllowed() || spinTimer !== null) return;
+  if (!state.isTTY) {
+    spinPaint();
+    return;
+  }
+  startSpin();
 }
-function clearProgress() {
+function spinClear() {
+  if (spinTimer !== null) {
+    clearInterval(spinTimer);
+    spinTimer = null;
+  }
   if (state.quiet || !progressAllowed()) return;
   process.stdout.write(CLEAR_LINE);
 }
@@ -216,6 +244,165 @@ function renderVersionDetail(detail) {
   ].join("\n");
 }
 
+// src/utils/help.ts
+var COMMANDS = [
+  { usage: "nmh", desc: "interactive wizard: arrow menu (delete all / pick / search / map / report / settings)" },
+  { usage: "nmh <path> [path\u2026]", desc: "shortcut: scan given path(s); one-liner actions via flags (--delete, --search, \u2026)" },
+  { usage: "nmh scan [dir]", desc: "full scan across targets (default: cwd)" },
+  { usage: "nmh clean [dir]", desc: "scan + delete everything safe (trash by default)" },
+  { usage: "nmh search <pattern> [dir\u2026]", desc: "find installed packages by name (+ versions & sizes) \u2014 read-only" },
+  { usage: "nmh map [dir]", desc: "project \u2192 PM \u2192 size \u2192 top packages \u2192 declared deps \u2014 read-only" },
+  { usage: "nmh stats [dir]", desc: "size analytics: dup factor, waste, top-N, per-package tree (aliases: analyze, info)" },
+  { usage: "nmh why <pkg> [dir\u2026]", desc: "reverse depend: where is <pkg> and who requires it \u2014 read-only" },
+  { usage: "nmh treemap [dir]", desc: "single-file interactive HTML treemap \u2192 nmh-treemap.html" },
+  { usage: "nmh stats -g", desc: "global installs across npm/pnpm/yarn/bun \u2014 read-only" },
+  { usage: "nmh config <op>", desc: "manage .nmhrc from the CLI: info \xB7 set \xB7 add \xB7 remove \xB7 unset" },
+  { usage: "nmh update", desc: "self-update: compare installed vs npm latest, install if global" },
+  { usage: "nmh version", desc: "banner: tool version, node+abi, OS/arch/kernel, tty (alias: -v / --version)" },
+  { usage: "nmh help", desc: "this help (alias: -h / --help)" }
+];
+var STAT_SUBCOMMANDS = [
+  { usage: "stats --by type [dir]", desc: "breakdown per dependency field (dep/dev/optional/peer/transitive)" },
+  { usage: "stats --licenses [dir]", desc: "license buckets (+ \u26A0 copyleft inside production deps)" },
+  { usage: "stats --score / --co2", desc: "experimental: composite bloat score 0-100 / rough CO2 estimate" },
+  { usage: "stats --graph [dir]", desc: "dependency graph from the lockfile \u2014 npm/yarn/pnpm/bun, no extra deps" },
+  { usage: "stats --reinstall [dir]", desc: 'naive npm-ci-style "how long would reinstalling everything take"' }
+];
+var GROUPS = [
+  {
+    title: "Actions",
+    flags: [
+      { usage: "--delete [mode]", desc: "delete found folders: hard | trash (soft alias) \u2014 no value = pick interactively" },
+      { usage: "--trash system|nmh", desc: "v1.1: whose trash takes victims \u2014 system backend (default) or restorable ~/.nmh/trash" },
+      { usage: "--dry-run", desc: "preview what would be deleted \u2014 nothing is touched" },
+      { usage: "-y, --yes", desc: "answer yes to every prompt (required for non-TTY deletes)" },
+      { usage: "-f, --force", desc: "skip all confirmations (implies --yes)" },
+      { usage: "--search <pattern>", desc: "search installed packages (substring, glob, or /regex/) \u2014 read-only" },
+      { usage: "-m, --map", desc: "map projects: PM, size, top packages, declared deps \u2014 read-only" },
+      { usage: "--depend [pkg]", desc: "map only: show declared deps; with a value, list who declares it" },
+      { usage: "--tree", desc: "map/stats only: list per-project packages (tree view, with sizes)" },
+      { usage: "--why <pkg>", desc: "read-only: explain an installed package \u2014 instances and requirers" },
+      { usage: "--stats", desc: "stats report: overview + dup factor + waste + top sizes \u2014 read-only" },
+      { usage: "--treemap [file]", desc: "treemap export: single-file HTML (default nmh-treemap.html; --out is an alias)" },
+      { usage: "-d, --dir <paths>", desc: "target dir(s), comma separated or repeated; globs and ~ allowed" },
+      { usage: "--size <mode>", desc: "output shape: 'total' (just aggregate) or 'each' (default: per-folder table)" },
+      { usage: "--save-report <file>", desc: "also write the printed report to a file (.json/.md/.txt; --report <file> aliases it)" },
+      { usage: "--update-check", desc: "peek npm for a newer release (non-blocking, 24 h cache; also settable in .nmhrc)" }
+    ]
+  },
+  {
+    title: "Stale hunting & output shape (v1.1)",
+    flags: [
+      { usage: "--stale <days>", desc: "keep only projects idle >= <days>; ladder = git commit \u2192 manifest \u2192 folder mtime; no evidence = dropped" },
+      { usage: "--fast-size", desc: "measure with one `du -sk` per entry (KiB granularity) instead of walking every file" },
+      { usage: "--sort <key>", desc: "order results: size (default, desc) | path | idle (oldest project first) | mtime (newest first)" },
+      { usage: "--no-skip", desc: "stop hiding system noise (.Trash*, Library/, *.app) during discovery \u2014 default: hidden" },
+      { usage: "--animate / --no-animate", desc: "live size counter while measuring: auto = real TTY only" },
+      { usage: "--json", desc: "machine-readable payload (pipe into jq); additive-only keys \u2014 v1.0 keys stay frozen" },
+      { usage: "-q, --quiet", desc: "minimal output \u2014 pretty tables/notes mute, the --json payload still prints" },
+      { usage: "--verbose", desc: "debug chatter on stderr" },
+      { usage: "--no-color", desc: "disable ANSI colors (auto: colors only on a real TTY or with --color / FORCE_COLOR)" },
+      { usage: "--color", desc: "force ANSI colors even on a piped run (wins over a config color:false)" }
+    ]
+  },
+  {
+    title: "Scoping & filters",
+    flags: [
+      { usage: "-r, --recursive", desc: "also look INSIDE found node_modules (nested audit; totals stay top-level only)" },
+      { usage: "--pm [family]", desc: "filter by detected PM: npm|pnpm|yarn|bun|vp \u2014 no value lists what was detected" },
+      { usage: "--exclude <globs>", desc: "exclude paths from results (comma list of globs, e.g. **/e2e/**)" },
+      { usage: "--keep <pkgs>", desc: 'refuse to delete node_modules of these projects (comma list, glob ok; "self" works)' },
+      { usage: "--depth <n>", desc: "max scan depth in levels below the target" },
+      { usage: "--expand", desc: "full absolute paths + extra detail in output" }
+    ]
+  },
+  {
+    title: "Stats suite",
+    flags: [
+      { usage: "--top <n>", desc: "rows in the focused size list (default 10)" },
+      { usage: "--by <mode>", desc: "breakdown mode \u2014 'size' (alias: package), 'type', 'licenses'" },
+      { usage: "-g, --global", desc: "analyze global installs (per-PM prefix scan; read-only)" },
+      { usage: "--config <file>", desc: "use this config file instead of the .nmhrc lookup (cwd \u2192 home)" },
+      { usage: "--save-baseline <name>", desc: "save a metadata snapshot of this run to ~/.nmh/baselines/<name>.json" },
+      { usage: "--compare <name>", desc: "diff this run against a stored baseline (totals, per-folder, package movers)" },
+      { usage: "--history", desc: "list stored baselines \u2014 no scan at all" },
+      { usage: "--phantom", desc: "stats only: imports found in sources but declared nowhere (best-effort regex audit)" },
+      { usage: "--dead", desc: "stats only: installed + declared but never imported (best-effort regex audit)" },
+      { usage: "--licenses", desc: "stats only: bucket instances by license field; flags copyleft in production deps" },
+      { usage: "--score", desc: "stats only: experimental composite bloat score 0-100" },
+      { usage: "--co2", desc: "stats only: experimental carbon estimate (storage-year + one redownload)" },
+      { usage: "--online", desc: "stats only: deprecated scan \u2014 offline manifests + lazy cached registry fallback" },
+      { usage: "--graph", desc: "stats only: dependency graph from the lockfile (npm/yarn/pnpm/bun) with BFS depth" },
+      { usage: "--reinstall", desc: "stats only: naive npm-ci-style estimate of the time to reinstall everything" },
+      { usage: "--out <file>", desc: "treemap only: where to write the HTML file (same as --treemap <file>)" }
+    ]
+  },
+  {
+    title: "Config family",
+    flags: [
+      { usage: "--default-exclude <globs>", desc: 'manage the persisted exclude list (comma list; special value "self")' },
+      { usage: "--default-keep <pkgs>", desc: 'manage the persisted keep list (comma list; special value "self")' },
+      { usage: "--default-mode <mode>", desc: "set the persisted delete default (hard | soft | trash)" },
+      { usage: "--log-dir <dir>", desc: "set the persisted recovery-log directory (logDir)" }
+    ]
+  }
+];
+var EXAMPLES = [
+  ["nmh", "wizard; the no-args menu auto-climbs to the nearest project root"],
+  ["nmh --dir=./proj,~/code/*/node_modules", "multi-target scan"],
+  ["nmh . --stale 90 --delete=trash -y", "bury the stale boneyard, restorable trash"],
+  ["nmh why react --expand", "reverse-depend: who declares + who requires"],
+  ["nmh stats --by type --json", "dep-field breakdown as a machine payload"],
+  ["nmh stats -g --top 20", "the 20 biggest global installs across PMs"],
+  ["nmh config set default-mode trash", "persist a default delete mode in .nmhrc"]
+];
+var flagWidth = (groups) => {
+  let width = 0;
+  for (const group of groups) for (const item of group.flags) width = Math.max(width, item.usage.length);
+  return width;
+};
+var commandWidth = (items) => {
+  let width = 0;
+  for (const item of items) width = Math.max(width, item.usage.length);
+  return width;
+};
+function renderSection(title, items, width) {
+  const lines = [colors.bold(title)];
+  for (const item of items) {
+    lines.push(colors.cyan(item.usage.padEnd(width + 2)) + colors.dim(item.desc));
+  }
+  return lines;
+}
+function renderHelp() {
+  const lines = [];
+  lines.push(colors.bold("nmh") + colors.dim(" \u2014 hunt bloated node_modules folders: scan, measure, clean safely (npm/pnpm/yarn/bun)"));
+  lines.push("");
+  lines.push(colors.bold("Usage"));
+  lines.push(`  ${colors.cyan("nmh <command|targets> [options]")}`);
+  lines.push("");
+  lines.push(...renderSection("Commands", COMMANDS, commandWidth(COMMANDS)));
+  lines.push("");
+  lines.push(...renderSection("Stats subcommands", STAT_SUBCOMMANDS, Math.max(commandWidth(STAT_SUBCOMMANDS), commandWidth(COMMANDS))));
+  lines.push("");
+  const width = flagWidth(GROUPS);
+  for (const group of GROUPS) {
+    lines.push(...renderSection(`Options \u2014 ${group.title}`, group.flags, width));
+    lines.push("");
+  }
+  lines.push(colors.bold("Examples"));
+  for (const [cmd, note2] of EXAMPLES) {
+    lines.push(`  ${colors.cyan(cmd.padEnd(40))}${colors.dim(note2)}`);
+  }
+  lines.push("");
+  lines.push(colors.dim("Safety first: guards refuse dangerous targets (exit 3), deletes confirm unless --yes/--force, symlinks never get followed."));
+  lines.push(colors.dim("Exit codes: 0 ok \xB7 1 usage error \xB7 2 nothing found \xB7 3 guard refused \xB7 4 permission denied."));
+  lines.push(colors.dim("Everything is documented in depth at: https://github.com/jhedev96/node-modules-hunter"));
+  return lines.join("\n") + "\n";
+}
+function printHelp() {
+  process.stdout.write(renderHelp());
+}
+
 // src/utils/future-flags.ts
 var FUTURE_FLAGS = /* @__PURE__ */ new Set([
   "empty"
@@ -329,6 +516,17 @@ async function loadConfig(explicitPath, cwd) {
     if (current === home || current === path2.dirname(current)) break;
     current = path2.dirname(current);
   }
+  const homeChain = cwd === home || cwd.startsWith(home + path2.sep);
+  if (!homeChain) {
+    for (const name of FILE_NAMES) {
+      const candidate = path2.join(home, name);
+      const body = await readMaybe(candidate);
+      if (body !== null) {
+        verboseLog(`config: found ${candidate}`);
+        return { values: parseConfigBody(body, candidate), source: candidate };
+      }
+    }
+  }
   return { values: {}, source: null };
 }
 
@@ -354,8 +552,13 @@ async function writeDeleteLog(payload2) {
       entries: payload2.results.map((row) => ({
         path: row.path,
         status: row.status,
-        error: row.error ?? null
-      }))
+        error: row.error ?? null,
+        // v1.1 additive: which trash took it (system | nmh) — trash rows only
+        ...row.backend !== void 0 ? { backend: row.backend } : {}
+      })),
+      // v1.1 additive: nmh-trash batch dir / fallback marker when applicable
+      ...payload2.trashBatch !== void 0 ? { trashBatch: payload2.trashBatch } : {},
+      ...payload2.trashFallback === true ? { trashFallback: true } : {}
     };
     await fs3.writeFile(file, JSON.stringify(body, null, 2));
     return file;
@@ -558,6 +761,11 @@ function formatBytes(bytes) {
   }
   return `${value.toFixed(1)} ${units[unitIndex]}`;
 }
+function formatIdle(days) {
+  if (days === void 0) return "\u2014";
+  if (days === 0) return "now";
+  return `${days.toLocaleString("en-US")}d`;
+}
 function formatAge(mtimeMs, now = Date.now()) {
   if (mtimeMs == null) return "\u2014";
   const diff = Math.max(0, now - mtimeMs);
@@ -692,9 +900,14 @@ function makeSearchMatcher(pattern) {
 // src/core/walker.ts
 import fs6 from "fs/promises";
 import path6 from "path";
+var SYSTEM_SKIP_NAMES = /* @__PURE__ */ new Set([".Trash", ".Trashes", "Library"]);
+function isSystemNoise(name) {
+  return SYSTEM_SKIP_NAMES.has(name) || name.startsWith(".Trash-") || name.endsWith(".app");
+}
 async function scanForNodeModules(roots, options = {}) {
   const maxDepth = options.maxDepth ?? Number.POSITIVE_INFINITY;
   const recursive = options.recursive === true;
+  const skipSystem = options.skipSystem !== false;
   const isExcluded = options.excludes && options.excludes.length > 0 ? makeGlobMatcher(options.excludes) : null;
   const entries = [];
   const permissionIssues = [];
@@ -730,6 +943,7 @@ async function scanForNodeModules(roots, options = {}) {
         }
         for (const dirent of dirents) {
           if (dirent.name === ".git") continue;
+          if (skipSystem && isSystemNoise(dirent.name)) continue;
           const child = path6.join(job.dir, dirent.name);
           const st = await fs6.lstat(child).catch(() => null);
           if (st === null) continue;
@@ -1000,11 +1214,11 @@ async function measureEntry(entryPath, permIssues = []) {
     );
   }
   const packageCount = await countTopLevelPackages(entryPath);
-  const stat = await fs8.lstat(entryPath).then(
+  const stat2 = await fs8.lstat(entryPath).then(
     (value) => value,
     () => null
   );
-  return { size, packageCount, mtimeMs: stat?.mtimeMs ?? null };
+  return { size, packageCount, mtimeMs: stat2?.mtimeMs ?? null };
 }
 async function countTopLevelPackages(entryPath) {
   return (await listTopLevelPackages(entryPath)).length;
@@ -1031,8 +1245,105 @@ async function measureEntries(entryPaths, permIssues = [], options = {}) {
   return results;
 }
 
-// src/core/pm-detect.ts
+// src/core/du-size.ts
+import { promisify } from "util";
+import { execFile } from "child_process";
 import fs9 from "fs/promises";
+var execFileP = promisify(execFile);
+async function measureEntryFast(entryPath) {
+  try {
+    const { stdout } = await execFileP("du", ["-sk", "--", entryPath], {
+      maxBuffer: 8 * 1024,
+      timeout: 3e4
+    });
+    const line = stdout.split("\n").find((value) => value.includes("	")) ?? "";
+    const tabIndex = line.lastIndexOf("	");
+    const kb = Number.parseInt(line.slice(0, tabIndex).trim(), 10);
+    const echoed = line.slice(tabIndex + 1);
+    if (!Number.isInteger(kb) || kb < 0 || echoed !== entryPath) return null;
+    const [packageCount, stat2] = await Promise.all([
+      countTopLevelPackages(entryPath),
+      fs9.lstat(entryPath).catch(() => null)
+    ]);
+    return { size: kb * 1024, packageCount, mtimeMs: stat2?.mtimeMs ?? null };
+  } catch {
+    return null;
+  }
+}
+
+// src/core/activity.ts
+import { promisify as promisify2 } from "util";
+import { execFile as execFile2 } from "child_process";
+import { stat } from "fs/promises";
+import { dirname, join } from "path";
+var execFileP2 = promisify2(execFile2);
+var DAY_MS = 864e5;
+var GIT_TIMEOUT_MS = 4e3;
+async function hasGitDir(dir) {
+  try {
+    await stat(join(dir, ".git"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function mtimeOf(dir, file) {
+  try {
+    return (await stat(join(dir, file))).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+async function findUp(start, test) {
+  let dir = start;
+  for (; ; ) {
+    if (await test(dir)) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+async function lastCommitSeconds(gitDir) {
+  try {
+    const { stdout } = await execFileP2(
+      "git",
+      ["-C", gitDir, "log", "-1", "--format=%ct"],
+      { maxBuffer: 64 * 1024, timeout: GIT_TIMEOUT_MS }
+    );
+    const seconds = Number.parseInt(stdout.trim(), 10);
+    return Number.isNaN(seconds) ? null : seconds;
+  } catch {
+    return null;
+  }
+}
+async function computeActivity(entryPath, now = Date.now()) {
+  const startDir = dirname(entryPath);
+  const gitDir = await findUp(startDir, hasGitDir);
+  if (gitDir !== null) {
+    const seconds = await lastCommitSeconds(gitDir);
+    if (seconds !== null) {
+      return { idleDays: idleFrom(seconds * 1e3, now), source: "git" };
+    }
+  }
+  const manifestMtime = await findUp(startDir, async (dir) => await mtimeOf(dir, "package.json") !== null);
+  if (manifestMtime !== null) {
+    const mtime = await mtimeOf(manifestMtime, "package.json");
+    if (mtime !== null) {
+      return { idleDays: idleFrom(mtime, now), source: "manifest" };
+    }
+  }
+  const folderMtime = await mtimeOf(startDir, "node_modules");
+  if (folderMtime !== null) {
+    return { idleDays: idleFrom(folderMtime, now), source: "mtime" };
+  }
+  return null;
+}
+function idleFrom(signalMs, now) {
+  return Math.max(0, Math.floor((now - signalMs) / DAY_MS));
+}
+
+// src/core/pm-detect.ts
+import fs10 from "fs/promises";
 import path9 from "path";
 var LOCKFILE_PRIORITY = [
   { family: "pnpm", files: ["pnpm-workspace.yaml", "pnpm-lock.yaml"] },
@@ -1113,7 +1424,7 @@ async function detectLockfilesAt(dir) {
 }
 async function fileExists(p) {
   try {
-    const st = await fs9.stat(p);
+    const st = await fs10.stat(p);
     return st.isFile();
   } catch {
     return false;
@@ -1150,9 +1461,9 @@ function knownFamily(name) {
 // src/core/guards.ts
 import os2 from "os";
 import path10 from "path";
-import fs10 from "fs/promises";
+import fs11 from "fs/promises";
 async function checkDeleteTarget(candidate) {
-  const st = await fs10.lstat(candidate).then(
+  const st = await fs11.lstat(candidate).then(
     (value) => value,
     () => null
   );
@@ -1229,13 +1540,23 @@ function renderScanResult(result, options) {
   if (options.sizeMode === "total" || isSilent()) return renderScanTotals(result);
   return renderScanTable(result, options);
 }
+var BAR_CELLS = 12;
+function renderBar(size, max) {
+  if (max <= 0 || size <= 0) return colors.dim("\xB7");
+  const cells = Math.max(1, Math.round(size / max * BAR_CELLS));
+  return colors.cyan("\u2588".repeat(Math.min(cells, BAR_CELLS)));
+}
 function renderScanTable(result, options) {
+  const showIdle = result.entries.some((entry) => entry.idleDays !== void 0);
+  const maxSize = result.entries.reduce((max, entry) => entry.nested === true ? max : Math.max(max, entry.size), 0);
   const table = new Table({
     head: [
       colors.dim("Path"),
       colors.dim("Size"),
+      colors.dim("Share"),
       colors.dim("Pkgs"),
       colors.dim("PM"),
+      ...showIdle ? [colors.dim("Idle")] : [],
       colors.dim("Modified")
     ],
     style: { head: [], border: colorEnabled() ? ["gray"] : [] }
@@ -1246,8 +1567,10 @@ function renderScanTable(result, options) {
     table.push([
       label,
       formatBytes(entry.size),
+      nested ? colors.dim("\xB7") : renderBar(entry.size, maxSize),
       entry.packageCount > 0 ? String(entry.packageCount) : "0",
       pmLabel(entry.pm),
+      ...showIdle ? [formatIdle(entry.idleDays)] : [],
       formatAge(entry.mtimeMs)
     ]);
   };
@@ -1291,6 +1614,8 @@ function renderScanJson(result) {
       pmProjectRoot: entry.pm.projectRoot,
       nested: entry.nested === true,
       ownerPath: entry.ownerPath ?? entry.path,
+      // v1.1 additive — keys appear only when --stale/--sort idle ran (frozen-contract friendly)
+      ...entry.idleDays !== void 0 ? { idleDays: entry.idleDays, activitySource: entry.activitySource } : {},
       modifiedAt: entry.mtimeMs == null ? null : new Date(entry.mtimeMs).toISOString()
     }))
   };
@@ -1348,8 +1673,13 @@ function renderDeleteJson(outcome, mode, dryRun) {
       status: row.status,
       size: row.size,
       sizeFormatted: formatBytes(row.size),
-      error: row.error ?? null
-    }))
+      error: row.error ?? null,
+      // v1.1 additive — trash backend per row, only when trash mode ran
+      ...row.backend !== void 0 ? { backend: row.backend } : {}
+    })),
+    // v1.1 additive — nmh-internal trash batch dir / fallback flag, only when used
+    ...outcome.trashBatch !== void 0 ? { trashBatch: outcome.trashBatch } : {},
+    ...outcome.trashFallback === true ? { trashFallback: true } : {}
   };
   return JSON.stringify(payload2, null, 2);
 }
@@ -1989,7 +2319,8 @@ async function collectScan(request) {
   const walk = await scanForNodeModules(walkRoots, {
     maxDepth: request.maxDepth,
     recursive: request.recursive,
-    excludes: walkExcludes
+    excludes: walkExcludes,
+    skipSystem: request.skipSystem
   });
   const permIssues = [...walk.permissionIssues];
   collected.push(...walk.entries);
@@ -1999,6 +2330,7 @@ async function collectScan(request) {
         maxDepth: request.maxDepth,
         recursive: true,
         excludes: walkExcludes,
+        skipSystem: request.skipSystem,
         initialOwner: direct
       });
       permIssues.push(...inner.permissionIssues);
@@ -2008,28 +2340,39 @@ async function collectScan(request) {
   const metaByPath = new Map(collected.map((entry) => [entry.path, entry]));
   const entryPaths = [...metaByPath.keys()];
   verboseLog(`found ${entryPaths.length} node_modules \u2014 measuring`);
-  const entryCount = entryPaths.length;
-  let bytesSoFar = 0;
-  let measuredCount = 0;
-  const measures = await measureEntries(entryPaths, permIssues, {
-    concurrency: 4,
-    onProgress: (progress) => {
-      measuredCount = progress.measuredEntries;
-      bytesSoFar = progress.bytesSoFar;
-      progressLine(
-        `\u280B measuring ${measuredCount}/${entryCount} folders \xB7 ${formatBytes(bytesSoFar)}`
-      );
-    }
-  });
-  clearProgress();
+  const measures = await collectMeasures(entryPaths, request.fastSize === true, permIssues);
+  spinClear();
   const detect = createPmDetector();
   const pmLimiter = createLimiter(8);
   const pmResults = await Promise.all(entryPaths.map((entryPath) => pmLimiter(() => detect(entryPath))));
   verboseLog(`scan finished in ${Date.now() - started} ms`);
+  const activityByPath = /* @__PURE__ */ new Map();
+  if (request.stale !== void 0 || request.sort === "idle") {
+    const activityLimiter = createLimiter(8);
+    const cache = /* @__PURE__ */ new Map();
+    const activityFor = (entryPath) => {
+      const startDir = path12.dirname(entryPath);
+      let pending = cache.get(startDir);
+      if (pending === void 0) {
+        pending = computeActivity(entryPath);
+        cache.set(startDir, pending);
+      }
+      return pending;
+    };
+    await Promise.all(
+      entryPaths.map(
+        (entryPath) => activityLimiter(async () => {
+          const activity = await activityFor(entryPath);
+          if (activity !== null) activityByPath.set(entryPath, activity);
+        })
+      )
+    );
+  }
   const cwd = request.cwd;
   let entries = entryPaths.map((entryPath, index) => {
     const measure = measures.get(entryPath) ?? { size: 0, packageCount: 0, mtimeMs: null };
     const meta = metaByPath.get(entryPath);
+    const activity = activityByPath.get(entryPath);
     return {
       path: entryPath,
       displayPath: shortenPath(entryPath, cwd),
@@ -2037,11 +2380,19 @@ async function collectScan(request) {
       packageCount: measure.packageCount,
       pm: pmResults[index],
       mtimeMs: measure.mtimeMs,
+      ...activity !== void 0 ? { idleDays: activity.idleDays, activitySource: activity.source } : {},
       nested: meta?.nested,
       ownerPath: meta?.ownerPath
     };
   });
-  entries.sort((a, b) => b.size - a.size);
+  const cmpStr = (x, y) => x < y ? -1 : x > y ? 1 : 0;
+  const comparators = {
+    size: (a, b) => b.size - a.size || cmpStr(a.path, b.path),
+    path: (a, b) => cmpStr(a.path, b.path) || b.size - a.size,
+    idle: (a, b) => (b.idleDays ?? -1) - (a.idleDays ?? -1) || b.size - a.size,
+    mtime: (a, b) => (b.mtimeMs ?? Number.NEGATIVE_INFINITY) - (a.mtimeMs ?? Number.NEGATIVE_INFINITY) || b.size - a.size
+  };
+  entries.sort(comparators[request.sort ?? "size"]);
   entries = await applyFilters(entries, request);
   const topEntries = entries.filter((entry) => !entry.nested);
   const totals = {
@@ -2065,6 +2416,59 @@ async function collectScan(request) {
   else if (permIssues.length > 0) code = 4;
   return { code, result };
 }
+async function collectMeasures(entryPaths, fastSize, permIssues) {
+  const entryCount = entryPaths.length;
+  let measuredCount = 0;
+  let bytesSoFar = 0;
+  const bump = () => {
+    spinUpdate(`measuring ${measuredCount}/${entryCount} folders \xB7 ${formatBytes(bytesSoFar)}`);
+  };
+  if (!fastSize) {
+    return measureEntries(entryPaths, permIssues, {
+      concurrency: 4,
+      onProgress: (progress) => {
+        measuredCount = progress.measuredEntries;
+        bytesSoFar = progress.bytesSoFar;
+        bump();
+      }
+    });
+  }
+  const measures = /* @__PURE__ */ new Map();
+  const duLimiter = createLimiter(8);
+  const fallbackPaths = [];
+  await Promise.all(
+    entryPaths.map(
+      (entryPath) => duLimiter(async () => {
+        const fast = await measureEntryFast(entryPath);
+        if (fast === null) {
+          fallbackPaths.push(entryPath);
+          return;
+        }
+        measures.set(entryPath, fast);
+        measuredCount += 1;
+        bytesSoFar += fast.size;
+        bump();
+      })
+    )
+  );
+  verboseLog(
+    `fast-size: ${measures.size} entr${measures.size === 1 ? "y" : "ies"} via du, ${fallbackPaths.length} via walker fallback`
+  );
+  if (fallbackPaths.length > 0) {
+    const duBytes = bytesSoFar;
+    const duCount = measures.size;
+    const walked = await measureEntries(fallbackPaths, permIssues, {
+      concurrency: 4,
+      onProgress: (progress) => {
+        spinUpdate(
+          `measuring ${duCount + progress.measuredEntries}/${entryCount} folders \xB7 ${formatBytes(duBytes + progress.bytesSoFar)}`
+        );
+      }
+    });
+    for (const [entryPath, measure] of walked) measures.set(entryPath, measure);
+  }
+  return measures;
+}
 async function applyFilters(entries, request) {
   const wantsPm = request.pmFilter !== void 0 && request.pmFilter.length > 0;
   const wantedFamilies = new Set(request.pmFilter ?? []);
@@ -2073,12 +2477,15 @@ async function applyFilters(entries, request) {
   const excludeMatcher = request.excludes !== void 0 && request.excludes.length > 0 ? makeGlobMatcher(request.excludes) : null;
   const selfGuard = (request.excludes?.includes(SELF_TOKEN) ?? false) || (request.keep?.includes(SELF_TOKEN) ?? false);
   const guardRoot = selfGuard ? path12.resolve(request.cwd) : null;
-  if (!wantsPm && !keepMatcher && !excludeMatcher && !selfGuard) return entries;
+  const wantsStale = request.stale !== void 0;
+  const isStale = (entry) => wantsStale && entry.idleDays !== void 0 && entry.idleDays >= (request.stale ?? 0);
+  if (!wantsPm && !keepMatcher && !excludeMatcher && !selfGuard && !wantsStale) return entries;
   const survivingTops = /* @__PURE__ */ new Set();
   for (const entry of entries) {
     if (entry.nested) continue;
     if (guardRoot !== null && insideRoot(entry.path, guardRoot)) continue;
     if (wantsPm && !matchPm(entry)) continue;
+    if (wantsStale && !isStale(entry)) continue;
     if (excludeMatcher && excludeMatcher(entry.path)) continue;
     if (keepMatcher) {
       const name = await projectNameFor(entry.path);
@@ -2137,10 +2544,203 @@ function emptyResult(targets, unresolvable = []) {
   };
 }
 
-// src/commands/config.ts
-import fs11 from "fs/promises";
+// src/commands/update.ts
+import { promisify as promisify3 } from "util";
+import { execFile as execFile3 } from "child_process";
+import fs13 from "fs/promises";
+
+// src/utils/update-check.ts
+import fs12 from "fs/promises";
 import path13 from "path";
 import { homedir as homedir6 } from "os";
+var UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+function cacheFile() {
+  return path13.join(homedir6(), ".nmh", "cache", "update-check.json");
+}
+function registryUrl() {
+  return process.env.NMH_REGISTRY_JSON ?? "https://registry.npmjs.org/node-modules-hunter/latest";
+}
+function isNewer(current, latest) {
+  const triple = (v) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(.*)$/.exec(v.trim());
+    return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3]), match[4] ?? ""];
+  };
+  const now = triple(current);
+  const next = triple(latest);
+  if (now === null || next === null) return false;
+  for (let i = 0; i < 3; i += 1) {
+    if (next[i] > now[i]) return true;
+    if (next[i] < now[i]) return false;
+  }
+  return false;
+}
+function updateNote(latest, current) {
+  return `update tersedia: ${current} \u2192 ${latest} \u2014 npm i -g node-modules-hunter (cek 24 jam sekali, opt-in via --update-check)`;
+}
+async function readFreshCache() {
+  try {
+    const parsed = JSON.parse(await fs12.readFile(cacheFile(), "utf8"));
+    const age = Date.now() - new Date(parsed.checkedAt).getTime();
+    if (Number.isFinite(age) && age >= 0 && age < UPDATE_CACHE_TTL_MS && typeof parsed.latest === "string") {
+      return parsed.latest;
+    }
+  } catch {
+  }
+  return null;
+}
+async function writeCache(latest) {
+  try {
+    const entry = { checkedAt: (/* @__PURE__ */ new Date()).toISOString(), latest };
+    await fs12.mkdir(path13.dirname(cacheFile()), { recursive: true });
+    await fs12.writeFile(cacheFile(), `${JSON.stringify(entry, null, 2)}
+`, "utf8");
+  } catch (err) {
+    verboseLog(`update-cache write failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function parseLatestVersion(payload2) {
+  if (typeof payload2 !== "object" || payload2 === null) return null;
+  const version = payload2.version;
+  if (typeof version !== "string" || version.length === 0) return null;
+  return tripleOf(version) ? version : null;
+}
+function tripleOf(version) {
+  return /^\d+\.\d+\.\d+/.test(version.trim());
+}
+async function checkForUpdate() {
+  try {
+    const fresh = await readFreshCache();
+    const latest = fresh ?? await fetchLatest();
+    if (latest === null) return null;
+    return isNewer(toolVersion(), latest) ? updateNote(latest, toolVersion()) : null;
+  } catch (err) {
+    verboseLog(`update check failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+async function fetchLatest() {
+  try {
+    const response = await fetch(registryUrl(), { signal: AbortSignal.timeout(4e3) });
+    if (!response.ok) {
+      verboseLog(`update check: registry responded ${response.status}`);
+      return null;
+    }
+    const latest = parseLatestVersion(await response.json());
+    if (latest !== null) await writeCache(latest);
+    return latest;
+  } catch (err) {
+    verboseLog(`update check: registry unreachable (${err instanceof Error ? err.message : String(err)})`);
+    return null;
+  }
+}
+
+// src/commands/update.ts
+var execFileP3 = promisify3(execFile3);
+async function runNpm(args, timeoutMs) {
+  const win32 = process.platform === "win32";
+  try {
+    const { stdout } = await execFileP3(win32 ? "npm.cmd" : "npm", args, {
+      timeout: timeoutMs,
+      maxBuffer: 1024 * 1024,
+      shell: win32,
+      windowsHide: true
+    });
+    return { code: 0, stdout, stderr: "" };
+  } catch (err) {
+    const failure = err;
+    return { code: failure.code ?? 1, stdout: failure.stdout ?? "", stderr: failure.stderr ?? "" };
+  }
+}
+var VERSION_SHAPE = /^\d+\.\d+\.\d+/;
+async function latestVersion() {
+  const override = process.env.NMH_UPDATE_LATEST_JSON;
+  if (typeof override === "string" && override.length > 0) {
+    try {
+      const parsed = JSON.parse(await fs13.readFile(override, "utf8"));
+      return typeof parsed.version === "string" && VERSION_SHAPE.test(parsed.version) ? parsed.version : null;
+    } catch (err) {
+      verboseLog(`update: override file unreadable (${err instanceof Error ? err.message : String(err)})`);
+      return null;
+    }
+  }
+  const view = await runNpm(["view", "node-modules-hunter", "version"], 6e4);
+  if (view.code !== 0) {
+    verboseLog(`npm view failed (rc ${view.code}): ${view.stderr.trim().slice(0, 200)}`);
+    return null;
+  }
+  const version = view.stdout.trim();
+  return VERSION_SHAPE.test(version) ? version : null;
+}
+async function isNpmGlobal() {
+  const forced = process.env.NMH_UPDATE_GLOBAL;
+  if (forced === "1") return true;
+  if (forced === "0") return false;
+  const ls = await runNpm(["ls", "-g", "node-modules-hunter", "--depth=0"], 6e4);
+  return ls.code === 0 && ls.stdout.includes("node-modules-hunter");
+}
+async function installLatest(version) {
+  const installCommand = `npm install -g node-modules-hunter@${version}`;
+  const fake = process.env.NMH_UPDATE_FAKE_INSTALL;
+  if (typeof fake === "string" && fake.length > 0) {
+    try {
+      await fs13.writeFile(fake, `${installCommand}
+`, "utf8");
+      return { ok: true, detail: installCommand };
+    } catch (err) {
+      return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  spinUpdate("updating via npm\u2026");
+  const install = await runNpm(["install", "-g", "node-modules-hunter@" + version], 3e5);
+  spinClear();
+  if (install.code !== 0) {
+    return { ok: false, detail: install.stderr.trim().slice(0, 300) || `npm exited ${install.code}` };
+  }
+  return { ok: true, detail: installCommand };
+}
+async function runUpdate(request) {
+  const current = toolVersion();
+  const latest = await latestVersion();
+  if (latest === null) {
+    const message = "cannot read the latest version \u2014 is the registry reachable? (npm view node-modules-hunter version)";
+    if (request.json) errorLog(message);
+    else errorLog(`\u26A0 ${message}`);
+    return 1;
+  }
+  const global = await isNpmGlobal();
+  const method = global ? "npm-global" : "manual";
+  if (!isNewer(current, latest)) {
+    const result2 = { current, latest, updated: false, method };
+    if (request.json) payload(JSON.stringify(result2, null, 2));
+    else log(`nmh ${current} sudah versi terbaru (registry: ${latest}) \u2014 tak ada yang diinstall`);
+    return 0;
+  }
+  if (!global) {
+    const result2 = { current, latest, updated: false, method };
+    const advice = [
+      `nmh ${current} terpasang di luar npm global \u2014 update manual:`,
+      "  npm i -g node-modules-hunter        (atau: pnpm add -g / bunx / brew upgrade node-modules-hunter)"
+    ];
+    if (request.json) payload(JSON.stringify(result2, null, 2));
+    else for (const line of advice) note(line);
+    return 0;
+  }
+  const install = await installLatest(latest);
+  if (!install.ok) {
+    errorLog(`\u26A0 update gagal: ${install.detail}`);
+    errorLog(`  coba manual: npm install -g node-modules-hunter@${latest}`);
+    return 1;
+  }
+  const result = { current, latest, updated: true, method: "npm-global" };
+  if (request.json) payload(JSON.stringify(result, null, 2));
+  else log(`\u2713 terupdate ${current} \u2192 ${latest} (npm install -g node-modules-hunter)`);
+  return 0;
+}
+
+// src/commands/config.ts
+import fs14 from "fs/promises";
+import path14 from "path";
+import { homedir as homedir7 } from "os";
 var VALID_MODES2 = /* @__PURE__ */ new Set(["hard", "soft", "trash"]);
 var KNOWN_KEYS = ["defaultMode", "depth", "exclude", "keep", "color", "animate", "updateCheck", "logDir"];
 var KEY_TO_FLAG = {
@@ -2218,9 +2818,9 @@ function parseBool(raw2, label) {
 function configWriteTarget(explicitFile, cwd) {
   if (explicitFile !== void 0 && explicitFile.length > 0) {
     const raw2 = expandTilde(explicitFile);
-    return path13.isAbsolute(raw2) ? raw2 : path13.resolve(cwd, raw2);
+    return path14.isAbsolute(raw2) ? raw2 : path14.resolve(cwd, raw2);
   }
-  return path13.join(homedir6(), DEFAULT_TARGET);
+  return path14.join(homedir7(), DEFAULT_TARGET);
 }
 function listMutation(op, flag, given) {
   const key = LIST_KEYS[flag];
@@ -2287,7 +2887,7 @@ function assemble(request) {
 async function readRawConfig(file) {
   let body;
   try {
-    body = await fs11.readFile(file, "utf8");
+    body = await fs14.readFile(file, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") return {};
     throw new ConfigError(`config unreadable: ${file} (${err.code ?? String(err)})`);
@@ -2334,8 +2934,8 @@ async function writeConfigMutation(file, mutation) {
   }
   const body = `${JSON.stringify(raw2, null, 2)}
 `;
-  await fs11.mkdir(path13.dirname(file), { recursive: true });
-  await fs11.writeFile(file, body, "utf8");
+  await fs14.mkdir(path14.dirname(file), { recursive: true });
+  await fs14.writeFile(file, body, "utf8");
   return applied;
 }
 var INFO_DEFAULTS = {
@@ -2426,7 +3026,7 @@ async function runConfigCommand(request) {
 }
 
 // src/commands/search.ts
-import path14 from "path";
+import path15 from "path";
 async function collectSearch(request) {
   const scan = await collectScan({
     targets: request.targets,
@@ -2444,7 +3044,7 @@ async function collectSearch(request) {
   const outcomes = await Promise.all(
     scan.result.entries.map(
       (entry) => limiter(async () => {
-        const pathMatch = match(entry.path) || match(path14.relative(request.cwd, entry.path));
+        const pathMatch = match(entry.path) || match(path15.relative(request.cwd, entry.path));
         const packages = await listTopLevelPackages(entry.path);
         const matched = packages.filter((pkg) => match(pkg.name));
         const matches = await Promise.all(
@@ -2465,12 +3065,12 @@ async function collectSearch(request) {
           )
         );
         searched += 1;
-        progressLine(`\u280B searching ${searched}/${entryCount} node_modules\u2026`);
+        spinUpdate(`searching ${searched}/${entryCount} node_modules\u2026`);
         return { entry, pathMatch, matches };
       })
     )
   );
-  clearProgress();
+  spinClear();
   const results = outcomes.filter((outcome) => outcome.pathMatch || outcome.matches.length > 0);
   verboseLog(`search '${request.pattern}': ${results.length}/${entryCount} entries matched`);
   let code = 0;
@@ -2497,11 +3097,11 @@ async function runSearch(request) {
 }
 
 // src/commands/why.ts
-import path16 from "path";
+import path17 from "path";
 
 // src/core/lockfile.ts
-import fs12 from "fs/promises";
-import path15 from "path";
+import fs15 from "fs/promises";
+import path16 from "path";
 var ROOT = "\xABroot\xBB";
 var MAX_LOCKFILE_BYTES = 8 * 1024 * 1024;
 function nameOfPackageKey(key) {
@@ -2583,9 +3183,9 @@ function buildGraph(pm, file, parsed) {
 async function readNpmLockGraph(projectDir, file = "package-lock.json") {
   let text2;
   try {
-    const stat = await fs12.stat(`${projectDir}/${file}`);
-    if (!stat.isFile() || stat.size > MAX_LOCKFILE_BYTES) return null;
-    text2 = await fs12.readFile(`${projectDir}/${file}`, "utf8");
+    const stat2 = await fs15.stat(`${projectDir}/${file}`);
+    if (!stat2.isFile() || stat2.size > MAX_LOCKFILE_BYTES) return null;
+    text2 = await fs15.readFile(`${projectDir}/${file}`, "utf8");
   } catch {
     return null;
   }
@@ -2606,9 +3206,9 @@ async function readProjectLockGraph(projectDir) {
 async function readYarnLockGraph(projectDir) {
   let text2;
   try {
-    const stat = await fs12.stat(path15.join(projectDir, "yarn.lock"));
-    if (!stat.isFile() || stat.size > MAX_LOCKFILE_BYTES) return null;
-    text2 = await fs12.readFile(path15.join(projectDir, "yarn.lock"), "utf8");
+    const stat2 = await fs15.stat(path16.join(projectDir, "yarn.lock"));
+    if (!stat2.isFile() || stat2.size > MAX_LOCKFILE_BYTES) return null;
+    text2 = await fs15.readFile(path16.join(projectDir, "yarn.lock"), "utf8");
   } catch {
     return null;
   }
@@ -2616,7 +3216,7 @@ async function readYarnLockGraph(projectDir) {
   if (parsed === null) return null;
   let rootDirect = 0;
   try {
-    const manifest = JSON.parse(await fs12.readFile(path15.join(projectDir, "package.json"), "utf8"));
+    const manifest = JSON.parse(await fs15.readFile(path16.join(projectDir, "package.json"), "utf8"));
     for (const field of ["dependencies", "devDependencies", "optionalDependencies"]) {
       const map = manifest[field];
       if (map === void 0 || typeof map !== "object") continue;
@@ -2751,9 +3351,9 @@ function nameOfSpecKey(key) {
 async function readPnpmLockGraph(projectDir) {
   let text2;
   try {
-    const stat = await fs12.stat(path15.join(projectDir, "pnpm-lock.yaml"));
-    if (!stat.isFile() || stat.size > MAX_LOCKFILE_BYTES) return null;
-    text2 = await fs12.readFile(path15.join(projectDir, "pnpm-lock.yaml"), "utf8");
+    const stat2 = await fs15.stat(path16.join(projectDir, "pnpm-lock.yaml"));
+    if (!stat2.isFile() || stat2.size > MAX_LOCKFILE_BYTES) return null;
+    text2 = await fs15.readFile(path16.join(projectDir, "pnpm-lock.yaml"), "utf8");
   } catch {
     return null;
   }
@@ -2810,9 +3410,9 @@ function collectPnpmNodes(section, edges, nodeNames) {
 async function readBunLockGraph(projectDir) {
   let text2;
   try {
-    const stat = await fs12.stat(path15.join(projectDir, "bun.lock"));
-    if (!stat.isFile() || stat.size > MAX_LOCKFILE_BYTES) return null;
-    text2 = await fs12.readFile(path15.join(projectDir, "bun.lock"), "utf8");
+    const stat2 = await fs15.stat(path16.join(projectDir, "bun.lock"));
+    if (!stat2.isFile() || stat2.size > MAX_LOCKFILE_BYTES) return null;
+    text2 = await fs15.readFile(path16.join(projectDir, "bun.lock"), "utf8");
   } catch {
     return null;
   }
@@ -2957,7 +3557,7 @@ async function runWhy(request) {
         if (target === void 0) return null;
         const declaredBy = await classify(entry.path, request.pkg);
         const targetVersion = await packageVersion(target.path);
-        const lock = await readProjectLockGraph(path16.dirname(entry.path));
+        const lock = await readProjectLockGraph(path17.dirname(entry.path));
         let requiredBy;
         let requiredByGrade;
         if (lock !== null) {
@@ -3014,91 +3614,6 @@ async function runWhy(request) {
   return code;
 }
 
-// src/utils/update-check.ts
-import fs13 from "fs/promises";
-import path17 from "path";
-import { homedir as homedir7 } from "os";
-var UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
-function cacheFile() {
-  return path17.join(homedir7(), ".nmh", "cache", "update-check.json");
-}
-function registryUrl() {
-  return process.env.NMH_REGISTRY_JSON ?? "https://registry.npmjs.org/node-modules-hunter/latest";
-}
-function isNewer(current, latest) {
-  const triple = (v) => {
-    const match = /^(\d+)\.(\d+)\.(\d+)(.*)$/.exec(v.trim());
-    return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3]), match[4] ?? ""];
-  };
-  const now = triple(current);
-  const next = triple(latest);
-  if (now === null || next === null) return false;
-  for (let i = 0; i < 3; i += 1) {
-    if (next[i] > now[i]) return true;
-    if (next[i] < now[i]) return false;
-  }
-  return false;
-}
-function updateNote(latest, current) {
-  return `update tersedia: ${current} \u2192 ${latest} \u2014 npm i -g node-modules-hunter (cek 24 jam sekali, opt-in via --update-check)`;
-}
-async function readFreshCache() {
-  try {
-    const parsed = JSON.parse(await fs13.readFile(cacheFile(), "utf8"));
-    const age = Date.now() - new Date(parsed.checkedAt).getTime();
-    if (Number.isFinite(age) && age >= 0 && age < UPDATE_CACHE_TTL_MS && typeof parsed.latest === "string") {
-      return parsed.latest;
-    }
-  } catch {
-  }
-  return null;
-}
-async function writeCache(latest) {
-  try {
-    const entry = { checkedAt: (/* @__PURE__ */ new Date()).toISOString(), latest };
-    await fs13.mkdir(path17.dirname(cacheFile()), { recursive: true });
-    await fs13.writeFile(cacheFile(), `${JSON.stringify(entry, null, 2)}
-`, "utf8");
-  } catch (err) {
-    verboseLog(`update-cache write failed: ${err instanceof Error ? err.message : String(err)}`);
-  }
-}
-function parseLatestVersion(payload2) {
-  if (typeof payload2 !== "object" || payload2 === null) return null;
-  const version = payload2.version;
-  if (typeof version !== "string" || version.length === 0) return null;
-  return tripleOf(version) ? version : null;
-}
-function tripleOf(version) {
-  return /^\d+\.\d+\.\d+/.test(version.trim());
-}
-async function checkForUpdate() {
-  try {
-    const fresh = await readFreshCache();
-    const latest = fresh ?? await fetchLatest();
-    if (latest === null) return null;
-    return isNewer(toolVersion(), latest) ? updateNote(latest, toolVersion()) : null;
-  } catch (err) {
-    verboseLog(`update check failed: ${err instanceof Error ? err.message : String(err)}`);
-    return null;
-  }
-}
-async function fetchLatest() {
-  try {
-    const response = await fetch(registryUrl(), { signal: AbortSignal.timeout(4e3) });
-    if (!response.ok) {
-      verboseLog(`update check: registry responded ${response.status}`);
-      return null;
-    }
-    const latest = parseLatestVersion(await response.json());
-    if (latest !== null) await writeCache(latest);
-    return latest;
-  } catch (err) {
-    verboseLog(`update check: registry unreachable (${err instanceof Error ? err.message : String(err)})`);
-    return null;
-  }
-}
-
 // src/commands/map.ts
 async function collectMap(request) {
   const scan = await collectScan({
@@ -3139,12 +3654,12 @@ async function collectMap(request) {
           )
         );
         mapped += 1;
-        progressLine(`\u280B mapping ${mapped}/${entryCount} projects\u2026`);
+        spinUpdate(`mapping ${mapped}/${entryCount} projects\u2026`);
         return { entry, project, topPackages, declared };
       })
     )
   );
-  clearProgress();
+  spinClear();
   let code = 0;
   if (projects.length === 0) code = 2;
   else if (scan.result.permissionIssues.length > 0) code = 4;
@@ -3190,7 +3705,7 @@ async function runMap(request) {
 }
 
 // src/commands/treemap.ts
-import fs14 from "fs/promises";
+import fs16 from "fs/promises";
 import path18 from "path";
 
 // src/core/treemap.ts
@@ -3421,8 +3936,8 @@ async function runTreemap(request) {
   }
   const outPath = path18.resolve(request.cwd, request.out);
   try {
-    await fs14.mkdir(path18.dirname(outPath), { recursive: true });
-    await fs14.writeFile(outPath, renderTreemapHtml(data), "utf8");
+    await fs16.mkdir(path18.dirname(outPath), { recursive: true });
+    await fs16.writeFile(outPath, renderTreemapHtml(data), "utf8");
   } catch (err) {
     errorLog(`\u{1F6D1} could not write the treemap file \u2192 ${outPath} \u2014 ${err instanceof Error ? err.message : String(err)}`);
     return 1;
@@ -3435,7 +3950,7 @@ async function runTreemap(request) {
 // src/core/deps-audit.ts
 import { glob as glob2 } from "tinyglobby";
 import path19 from "path";
-import fs15 from "fs/promises";
+import fs17 from "fs/promises";
 var SOURCE_GLOB = "**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts,vue,svelte,astro}";
 var SOURCE_IGNORES = ["**/node_modules/**", "**/.git/**"];
 var MAX_FILES_PER_PROJECT = 2e3;
@@ -3503,9 +4018,9 @@ async function collectDepsAudit(projects, installedNames) {
         await limiter(async () => {
           let code;
           try {
-            const stat = await fs15.stat(path19.join(project.dir, file));
-            if (stat.size > MAX_FILE_BYTES) return;
-            code = await fs15.readFile(path19.join(project.dir, file), "utf8");
+            const stat2 = await fs17.stat(path19.join(project.dir, file));
+            if (stat2.size > MAX_FILE_BYTES) return;
+            code = await fs17.readFile(path19.join(project.dir, file), "utf8");
           } catch {
             return;
           }
@@ -3546,7 +4061,7 @@ async function collectDepsAudit(projects, installedNames) {
 import path21 from "path";
 
 // src/utils/registry-deprecated.ts
-import fs16 from "fs/promises";
+import fs18 from "fs/promises";
 import path20 from "path";
 import os3 from "os";
 var MAX_REGISTRY_DEPRECATED_FETCHES = 25;
@@ -3562,7 +4077,7 @@ async function registryDeprecated(name, version, cacheDir, base = "https://regis
   if (name.length === 0 || version.length === 0) return null;
   const file = cachePath(cacheDir, name, version);
   try {
-    const cached2 = JSON.parse(await fs16.readFile(file, "utf8"));
+    const cached2 = JSON.parse(await fs18.readFile(file, "utf8"));
     if (typeof cached2.checkedAt === "string") {
       const age = Date.now() - Date.parse(cached2.checkedAt);
       if (Number.isFinite(age) && age >= 0 && age < DEPRECATED_TTL_MS) {
@@ -3589,8 +4104,8 @@ async function registryDeprecated(name, version, cacheDir, base = "https://regis
 }
 async function writeDeprecatedCache(file, message) {
   try {
-    await fs16.mkdir(path20.dirname(file), { recursive: true });
-    await fs16.writeFile(file, JSON.stringify({ checkedAt: (/* @__PURE__ */ new Date()).toISOString(), message }), "utf8");
+    await fs18.mkdir(path20.dirname(file), { recursive: true });
+    await fs18.writeFile(file, JSON.stringify({ checkedAt: (/* @__PURE__ */ new Date()).toISOString(), message }), "utf8");
   } catch {
   }
 }
@@ -3639,13 +4154,13 @@ async function collectStats(request) {
           )
         );
         measuredEntries += 1;
-        progressLine(`\u280B analyzing ${measuredEntries}/${entryCount} node_modules\u2026`);
+        spinUpdate(`analyzing ${measuredEntries}/${entryCount} node_modules\u2026`);
         const graph2 = request.graph === true ? await readProjectLockGraph(declared?.projectDir ?? path21.dirname(entry.path)) : void 0;
         return { entry, project, topPackages, declared, graph: graph2 };
       })
     )
   );
-  clearProgress();
+  spinClear();
   const byName = /* @__PURE__ */ new Map();
   const versionsByName = /* @__PURE__ */ new Map();
   const members = /* @__PURE__ */ new Map();
@@ -4094,13 +4609,20 @@ async function saveBaselineQuiet(name, snapshot) {
 import { confirm, select, isCancel } from "@clack/prompts";
 
 // src/core/deleter.ts
-import fs17 from "fs/promises";
+import fs20 from "fs/promises";
 
 // src/utils/trash.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
+import { execFile as execFile4 } from "child_process";
+import { promisify as promisify4 } from "util";
+import fs19 from "fs/promises";
+import path22 from "path";
+import { homedir as homedir8 } from "os";
+var execFileAsync = promisify4(execFile4);
 async function trashBackend() {
+  const forced = process.env.NMH_TRASH_BACKEND;
+  if (forced === "windows-com" || forced === "macos-finder" || forced === "linux-gio" || forced === "linux-trash-cli" || forced === "none") {
+    return forced;
+  }
   switch (process.platform) {
     case "win32":
       return "windows-com";
@@ -4181,6 +4703,30 @@ async function commandExists(bin) {
     return false;
   }
 }
+async function createTrashBatch(home) {
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const hex = Math.random().toString(16).slice(2, 5);
+  const batchDir = path22.join(home ?? homedir8(), ".nmh", "trash", `trash-${stamp}-${hex}`);
+  await fs19.mkdir(batchDir, { recursive: true });
+  return batchDir;
+}
+async function nmhTrashMove(entryPath, batchDir) {
+  const parent = path22.basename(path22.dirname(entryPath));
+  const storedAs = `${parent}-node_modules-${Math.random().toString(16).slice(2, 5)}`;
+  const destination = path22.join(batchDir, storedAs);
+  try {
+    await fs19.rename(entryPath, destination);
+  } catch (err) {
+    if (err?.code !== "EXDEV") throw err;
+    await fs19.cp(entryPath, destination, { recursive: true, dereference: false, verbatimSymlinks: true });
+    await fs19.rm(entryPath, { recursive: true, force: true });
+  }
+  return storedAs;
+}
+async function appendTrashManifest(batchDir, row) {
+  await fs19.appendFile(path22.join(batchDir, "manifest.jsonl"), `${JSON.stringify(row)}
+`, "utf8");
+}
 
 // src/core/deleter.ts
 async function deleteEntries(entries, request) {
@@ -4188,39 +4734,76 @@ async function deleteEntries(entries, request) {
   const limiter = createLimiter(request.concurrency ?? 8);
   const rows = [];
   let done = 0;
-  const runOne = async (entry, attempt) => {
+  const runOne = async (entry, attempt, backend) => {
     const failure = await attempt().catch(
       (err) => err instanceof Error ? err.message : String(err)
     );
-    const row = failure ? { path: entry.path, size: entry.size, status: "failed", error: failure } : { path: entry.path, size: entry.size, status: request.mode === "hard" ? "deleted" : "trashed" };
+    const row = failure ? { path: entry.path, size: entry.size, status: "failed", error: failure } : {
+      path: entry.path,
+      size: entry.size,
+      status: request.mode === "hard" ? "deleted" : "trashed",
+      ...backend !== void 0 ? { backend } : {}
+    };
     rows.push(row);
     done += 1;
     request.onRow?.(row, done, total);
   };
+  const outcome = { results: rows, freed: 0, deleted: 0, failed: 0, permissionDenied: false };
   if (request.mode === "hard") {
     await Promise.all(entries.map((entry) => limiter(() => runOne(entry, () => removeHard(entry.path)))));
   } else {
-    const backend = await trashBackend();
-    if (backend === "none") throw new TrashUnavailableError();
-    await Promise.all(
-      entries.map(
-        (entry) => limiter(() => runOne(entry, () => moveToTrash([entry.path], backend).then(() => null)))
-      )
-    );
+    const trashMode = request.trashMode ?? "system";
+    const systemBackend = trashMode === "system" ? await trashBackend() : null;
+    const useNmhTrash = systemBackend === null || systemBackend === "none";
+    if (useNmhTrash) {
+      const via = request.trashMode === "nmh" ? "explicit" : "fallback";
+      const batchDir = await createTrashBatch();
+      outcome.trashBatch = batchDir;
+      if (via === "fallback") outcome.trashFallback = true;
+      await Promise.all(
+        entries.map(
+          (entry) => limiter(
+            () => runOne(
+              entry,
+              async () => {
+                const storedAs = await nmhTrashMove(entry.path, batchDir);
+                await appendTrashManifest(batchDir, {
+                  originalPath: entry.path,
+                  storedAs,
+                  size: entry.size,
+                  trashedAt: (/* @__PURE__ */ new Date()).toISOString(),
+                  nmh: toolVersion(),
+                  via
+                });
+                return null;
+              },
+              "nmh"
+            )
+          )
+        )
+      );
+    } else {
+      const backend = systemBackend;
+      await Promise.all(
+        entries.map(
+          (entry) => limiter(
+            () => runOne(entry, () => moveToTrash([entry.path], backend).then(() => null), "system")
+          )
+        )
+      );
+    }
   }
   const completed = rows.filter((row) => row.status !== "failed");
   const failedRows = rows.filter((row) => row.status === "failed");
-  return {
-    results: rows,
-    freed: completed.reduce((sum2, row) => sum2 + row.size, 0),
-    deleted: completed.length,
-    failed: failedRows.length,
-    permissionDenied: failedRows.some((row) => /EACCES|EPERM/.test(row.error ?? ""))
-  };
+  outcome.freed = completed.reduce((sum2, row) => sum2 + row.size, 0);
+  outcome.deleted = completed.length;
+  outcome.failed = failedRows.length;
+  outcome.permissionDenied = failedRows.some((row) => /EACCES|EPERM/.test(row.error ?? ""));
+  return outcome;
 }
 async function removeHard(target) {
   try {
-    await fs17.rm(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 300 });
+    await fs20.rm(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 300 });
     return null;
   } catch (err) {
     const code = err?.code ?? "ERR";
@@ -4233,22 +4816,32 @@ async function removeHard(target) {
 async function executeAll(entries, request) {
   const outcome = await deleteEntries(entries, {
     mode: request.mode,
+    trashMode: request.trashMode,
     onRow: (_row, done, total) => {
-      progressLine(`\u{1F5D1}  ${done}/${total} folders\u2026`);
+      spinUpdate(`\u{1F5D1}  ${done}/${total} folders\u2026`);
     }
   });
-  clearProgress();
+  spinClear();
   if (request.json) payload(renderDeleteJson(outcome, request.mode, false));
   else {
     const summary = renderDeleteSummary(outcome, request.mode);
     if (summary) log(summary);
+    if (outcome.trashBatch !== void 0) {
+      if (outcome.trashFallback === true) {
+        note(`no OS trash backend (install gio or trash-cli) \u2014 fell back to the restorable nmh trash: ${outcome.trashBatch}`);
+      } else {
+        note(`restorable nmh trash: ${outcome.trashBatch} (manifest: manifest.jsonl \u2014 restore by moving folders back)`);
+      }
+    }
   }
   await writeDeleteLog({
     mode: request.mode,
     results: outcome.results,
     freed: outcome.freed,
     deleted: outcome.deleted,
-    failed: outcome.failed
+    failed: outcome.failed,
+    ...outcome.trashBatch !== void 0 ? { trashBatch: outcome.trashBatch } : {},
+    ...outcome.trashFallback === true ? { trashFallback: true } : {}
   });
   const code = outcome.permissionDenied ? 4 : outcome.failed > 0 ? 1 : 0;
   return { code, outcome };
@@ -4264,7 +4857,9 @@ async function deleteFlow(request) {
     recursive: request.recursive,
     excludes: request.excludes,
     keep: request.keep,
-    pmFilter: request.pmFilter
+    pmFilter: request.pmFilter,
+    stale: request.stale,
+    skipSystem: request.skipSystem
   });
   if (scan.result.unresolvable.length > 0) {
     for (const suspect of scan.result.unresolvable) {
@@ -4309,7 +4904,7 @@ async function deleteFlow(request) {
     return 1;
   }
   if (request.json) {
-    const { code: code2 } = await executeAll(safeEntries, { mode, json: true });
+    const { code: code2 } = await executeAll(safeEntries, { mode, json: true, trashMode: request.trashMode });
     return code2;
   }
   if (!request.assumeYes) {
@@ -4324,7 +4919,7 @@ async function deleteFlow(request) {
       return 0;
     }
   }
-  const { code } = await executeAll(safeEntries, { mode, json: false });
+  const { code } = await executeAll(safeEntries, { mode, json: false, trashMode: request.trashMode });
   return code;
 }
 async function resolveMode(requested, json, dryRun) {
@@ -4389,14 +4984,17 @@ async function runClean(request) {
     excludes: request.excludes,
     keep: request.keep,
     pmFilter: request.pmFilter,
+    stale: request.stale,
+    skipSystem: request.skipSystem,
+    trashMode: request.trashMode,
     maxDepth: request.maxDepth,
     blockedMode: "filter"
   });
 }
 
 // src/commands/wizard.ts
-import fs18 from "fs/promises";
-import path22 from "path";
+import fs21 from "fs/promises";
+import path23 from "path";
 import { confirm as confirm2, isCancel as isCancel2, multiselect, outro, select as select2, text } from "@clack/prompts";
 
 // src/utils/banner.ts
@@ -4447,7 +5045,7 @@ var PROJECT_MANIFESTS = /* @__PURE__ */ new Set([
 ]);
 async function hasProjectManifest(dir) {
   try {
-    const names = await fs18.readdir(dir);
+    const names = await fs21.readdir(dir);
     for (const name of names) {
       if (PROJECT_MANIFESTS.has(name)) return true;
     }
@@ -4459,13 +5057,13 @@ async function hasProjectManifest(dir) {
 async function resolveWizardScope(cwd) {
   const here = await scanForNodeModules([cwd], { maxDepth: WIZARD_DEPTH });
   if (here.entries.length > 0) return { root: cwd, from: cwd, climbed: false, scouted: false };
-  let dir = path22.dirname(cwd);
-  for (let hop = 0; hop < WIZARD_MAX_CLIMB && dir !== path22.dirname(dir); hop += 1) {
+  let dir = path23.dirname(cwd);
+  for (let hop = 0; hop < WIZARD_MAX_CLIMB && dir !== path23.dirname(dir); hop += 1) {
     if (await hasProjectManifest(dir)) {
       const probe = await scanForNodeModules([dir], { maxDepth: WIZARD_DEPTH });
       if (probe.entries.length > 0) return { root: dir, from: cwd, climbed: true, scouted: true };
     }
-    dir = path22.dirname(dir);
+    dir = path23.dirname(dir);
   }
   return { root: cwd, from: cwd, climbed: false, scouted: true };
 }
@@ -4651,19 +5249,33 @@ function sum(entries) {
 }
 
 // src/commands/global.ts
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-import fs19 from "fs/promises";
-import path23 from "path";
-var execFileAsync2 = promisify2(execFile2);
+import { execFile as execFile5 } from "child_process";
+import { promisify as promisify5 } from "util";
+import fs22 from "fs/promises";
+import path24 from "path";
+var execFileAsync2 = promisify5(execFile5);
 var PROBE_TIMEOUT = 8e3;
+function lastLine(stdout) {
+  const line = stdout.split("\n").map((row) => row.trim()).filter(Boolean).pop();
+  return line && line.length > 0 ? line : null;
+}
 async function probeViaCommand(cmd, argv) {
   try {
     const { stdout } = await execFileAsync2(cmd, argv, { timeout: PROBE_TIMEOUT });
-    const line = stdout.split("\n").map((row) => row.trim()).filter(Boolean).pop();
-    return line && line.length > 0 ? line : null;
+    return lastLine(stdout);
   } catch (err) {
     verboseLog(`global probe: ${cmd} ${argv.join(" ")} failed (${err instanceof Error ? err.message.split("\n")[0] : String(err)})`);
+  }
+  if (process.platform !== "win32") return null;
+  try {
+    const { stdout } = await execFileAsync2(cmd, argv, {
+      timeout: PROBE_TIMEOUT,
+      shell: true,
+      windowsHide: true
+    });
+    return lastLine(stdout);
+  } catch (err) {
+    verboseLog(`global probe: ${cmd} ${argv.join(" ")} via shell failed (${err instanceof Error ? err.message.split("\n")[0] : String(err)})`);
     return null;
   }
 }
@@ -4678,7 +5290,7 @@ async function probeRoot(cmd, argv, shape, fallback) {
 }
 async function isDir(candidate) {
   try {
-    return (await fs19.stat(candidate)).isDirectory();
+    return (await fs22.stat(candidate)).isDirectory();
   } catch {
     return false;
   }
@@ -4704,12 +5316,12 @@ async function inspectDeadBins(root, binDir, refs) {
     else if (binField && typeof binField === "object") binNames = Object.keys(binField);
     else continue;
     for (const binName of binNames) {
-      const link = path23.join(binDir, binName);
+      const link = path24.join(binDir, binName);
       try {
-        const linkStat = await fs19.lstat(link);
+        const linkStat = await fs22.lstat(link);
         if (!linkStat.isSymbolicLink()) continue;
         try {
-          await fs19.stat(link);
+          await fs22.stat(link);
         } catch {
           issues.push({ name: ref.name, kind: "broken bin symlink", detail: binName });
         }
@@ -4722,40 +5334,40 @@ async function inspectDeadBins(root, binDir, refs) {
 }
 async function resolvePmRoots(pmFilter) {
   const npmFallback = {
-    root: path23.join(expandTilde("~"), "lib", "node_modules"),
-    binDir: path23.join(expandTilde("~"), "bin"),
+    root: path24.join(expandTilde("~"), "lib", "node_modules"),
+    binDir: path24.join(expandTilde("~"), "bin"),
     source: "fallback"
   };
   const pnpmFallback = await pnpmFallbackSpec();
   const yarnFallback = {
-    root: path23.join(expandTilde("~"), ".config", "yarn", "global", "node_modules"),
-    binDir: path23.join(expandTilde("~"), ".config", "yarn", "global", "bin"),
+    root: path24.join(expandTilde("~"), ".config", "yarn", "global", "node_modules"),
+    binDir: path24.join(expandTilde("~"), ".config", "yarn", "global", "bin"),
     source: "fallback"
   };
   const bunFallback = {
-    root: path23.join(expandTilde("~"), ".bun", "install", "global", "node_modules"),
-    binDir: path23.join(expandTilde("~"), ".bun", "bin"),
+    root: path24.join(expandTilde("~"), ".bun", "install", "global", "node_modules"),
+    binDir: path24.join(expandTilde("~"), ".bun", "bin"),
     source: "fallback"
   };
   const wanted = pmFilter ?? ["npm", "pnpm", "yarn", "bun"];
   const results = [];
   for (const pm of wanted) {
     let spec = null;
-    if (pm === "npm") spec = await probeRoot("npm", ["root", "-g"], (dir) => ({ root: dir, binDir: path23.join(path23.dirname(path23.dirname(dir)), "bin"), source: "pm" }), npmFallback);
+    if (pm === "npm") spec = await probeRoot("npm", ["root", "-g"], (dir) => ({ root: dir, binDir: path24.join(path24.dirname(path24.dirname(dir)), "bin"), source: "pm" }), npmFallback);
     else if (pm === "pnpm") spec = await probeRoot("pnpm", ["root", "-g"], (dir) => ({ root: dir, binDir: null, source: "pm" }), pnpmFallback);
-    else if (pm === "yarn") spec = await probeRoot("yarn", ["global", "dir"], (dir) => ({ root: path23.join(dir, "node_modules"), binDir: path23.join(dir, "bin"), source: "pm" }), yarnFallback);
-    else if (pm === "bun") spec = await probeRoot("bun", ["pm", "-g"], (dir) => ({ root: dir, binDir: path23.join(path23.dirname(path23.dirname(dir)), "bin"), source: "pm" }), bunFallback);
+    else if (pm === "yarn") spec = await probeRoot("yarn", ["global", "dir"], (dir) => ({ root: path24.join(dir, "node_modules"), binDir: path24.join(dir, "bin"), source: "pm" }), yarnFallback);
+    else if (pm === "bun") spec = await probeRoot("bun", ["pm", "-g"], (dir) => ({ root: dir, binDir: path24.join(path24.dirname(path24.dirname(dir)), "bin"), source: "pm" }), bunFallback);
     if (spec) results.push({ pm, spec });
     else verboseLog(`global: ${pm} \u2014 no global node_modules found`);
   }
   return results;
 }
 async function pnpmFallbackSpec() {
-  const base = path23.join(expandTilde("~"), ".local", "share", "pnpm", "global");
+  const base = path24.join(expandTilde("~"), ".local", "share", "pnpm", "global");
   try {
-    const versions = (await fs19.readdir(base)).filter((name) => /^\d+$/.test(name)).sort((a, b) => Number(b) - Number(a));
+    const versions = (await fs22.readdir(base)).filter((name) => /^\d+$/.test(name)).sort((a, b) => Number(b) - Number(a));
     for (const version of versions) {
-      const root = path23.join(base, version, "node_modules");
+      const root = path24.join(base, version, "node_modules");
       if (await isDir(root)) return { root, binDir: null, source: "fallback" };
     }
   } catch {
@@ -4763,7 +5375,7 @@ async function pnpmFallbackSpec() {
   return null;
 }
 async function runGlobal(request) {
-  progressLine("\u280B probing global prefixes\u2026");
+  spinUpdate("probing global prefixes\u2026");
   const pmRoots = await resolvePmRoots(request.pmFilter);
   const reports = [];
   const permissionIssues = [];
@@ -4779,7 +5391,7 @@ async function runGlobal(request) {
             ref.symlinked ? Promise.resolve(null) : measureEntry(ref.path)
           ]);
           done += 1;
-          progressLine(`\u280B global ${pm} \u2014 ${done}/${refs.length} packages`);
+          spinUpdate(`global ${pm} \u2014 ${done}/${refs.length} packages`);
           return { name: ref.name, version, symlinked: ref.symlinked, size: measure === null ? null : measure.size };
         })
       )
@@ -4794,7 +5406,7 @@ async function runGlobal(request) {
       dead
     });
   }
-  clearProgress();
+  spinClear();
   const byName = /* @__PURE__ */ new Map();
   for (const report of reports) {
     for (const pkg of report.packages) {
@@ -4833,12 +5445,19 @@ function finish(request, outcome) {
 
 // src/cli.ts
 var cli = cac("nmh");
+cli.option("-h, --help", "Show the full help screen (commands, options, examples)");
+cli.option("-v, --version", "Show the version banner (tool version, node+abi, OS/arch/kernel \u2014 --json for plain fields)");
 cli.option("-d, --dir <paths>", "Target dir(s), comma separated or repeated; globs and ~ allowed");
 cli.option("--delete [mode]", "Delete found folders: hard | soft | trash (soft = trash; no value = pick interactively)");
 cli.option("--dry-run", "Preview what would be deleted \u2014 nothing is touched");
 cli.option("-y, --yes", "Answer yes to every prompt");
 cli.option("-f, --force", "Skip all confirmations (implies --yes)");
 cli.option("--size <mode>", "'total' (just aggregate) or 'each' (default); numeric top-N lands later");
+cli.option("--stale <days>", "v1.1: only projects idle >= <days> (git activity signal \u2014 last commit, else manifest, else folder mtime)");
+cli.option("--fast-size", "v1.1: measure with one `du -sk` per entry (KiB granularity) instead of walking every file");
+cli.option("--sort <key>", "v1.1: order results \u2014 size (default, desc) | path | idle (oldest project first) | mtime (newest first)");
+cli.option("--no-skip", "v1.1: audit everything \u2014 stop hiding .Trash*, Library/, and *.app dirs during discovery (default: hidden)");
+cli.option("--trash <mode>", "v1.1: trash mode for delete ops \u2014 'system' (default: gio/Finder/Recycle Bin) or 'nmh' (restorable ~/.nmh/trash + manifest)");
 cli.option("--json", "Machine-readable JSON output");
 cli.option("-q, --quiet", "Minimal output \u2014 pretty tables/notes mute, but the --json payload still prints");
 cli.option("--verbose", "Debug chatter on stderr");
@@ -4881,9 +5500,33 @@ cli.option("--default-keep <pkgs>", 'config family: manage the persisted keep li
 cli.option("--default-mode <mode>", "config family: set the persisted defaultMode (hard | soft | trash)");
 cli.option("--log-dir <dir>", "config family: set the persisted recovery-log directory (logDir)");
 var PM_FAMILIES = /* @__PURE__ */ new Set(["npm", "pnpm", "yarn", "bun", "vp"]);
+var KNOWN_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "scan",
+  "clean",
+  "search",
+  "map",
+  "why",
+  "treemap",
+  "stats",
+  "analyze",
+  "info",
+  "config",
+  "update",
+  "version",
+  "help"
+]);
 function looksLikePath(text2) {
   return text2.includes("/") || text2.includes("\\") || text2.startsWith(".") || text2.startsWith("~") || /^[A-Za-z]:/.test(text2);
 }
+function resolveSubcommand(positionals, cwd) {
+  if (positionals.length === 0) return { subcommand: null, unknown: null };
+  const first = positionals[0];
+  if (KNOWN_SUBCOMMANDS.has(first)) return { subcommand: first, unknown: null };
+  if (existsSync(path25.resolve(cwd, first)) || looksLikePath(first)) {
+    return { subcommand: null, unknown: null };
+  }
+  return { subcommand: null, unknown: first };
+}
 function normalizeDelete(value) {
   if (value === void 0 || value === false) return { given: false, mode: null };
   if (value === true) return { given: true, mode: null };
@@ -4915,7 +5558,7 @@ async function main() {
     return 0;
   }
   if (flags.help === true || positionals[0] === "help") {
-    cli.outputHelp();
+    printHelp();
     return 0;
   }
   const explicitConfig = typeof flags.config === "string" && flags.config.length > 0 ? flags.config : null;
@@ -4946,11 +5589,13 @@ async function main() {
   const cliColorExplicit = process.argv.includes("--color") || process.argv.includes("--color=true");
   const json = flags.json === true || Array.isArray(flags.json) && flags.json.includes(true);
   const progress = normalizeAnimate(process.argv, config.animate);
+  const isTTY = process.stdout.isTTY === true;
+  const colorForced = cliColorExplicit || process.env.FORCE_COLOR !== void 0 && process.env.FORCE_COLOR !== "0" && process.env.FORCE_COLOR !== "false";
   configureLogger({
     verbose: flags.verbose === true,
     quiet: flags.quiet === true,
     noColor: flags.noColor === true || flags.color === false || // explicit CLI --no-color wins over config
-    config.color === false && !cliColorExplicit,
+    config.color === false && !cliColorExplicit || !isTTY && !colorForced,
     // --json shares stdout with the live counter → counter must stay silent
     progress: json ? "off" : progress
   });
@@ -4978,6 +5623,59 @@ async function main() {
     errorLog("--size given more than once \u2014 pass a single value (total | each)");
     return 1;
   }
+  let stale;
+  if (flags.stale !== void 0) {
+    if (flags.stale === true) {
+      errorLog("--stale needs a value \u2014 use --stale=<days> (e.g. --stale=90)");
+      return 1;
+    }
+    if (Array.isArray(flags.stale)) {
+      errorLog("--stale given more than once \u2014 pass a single value (days)");
+      return 1;
+    }
+    const days = Number(flags.stale);
+    if (!Number.isInteger(days) || days < 1 || days > 365e3) {
+      errorLog(`invalid --stale: ${String(flags.stale)} (expected a positive whole number of days)`);
+      return 1;
+    }
+    stale = days;
+  }
+  const fastSize = flags.fastSize === true || Array.isArray(flags.fastSize) && flags.fastSize.includes(true);
+  let sort;
+  if (flags.sort !== void 0) {
+    if (flags.sort === true) {
+      errorLog("--sort needs a value \u2014 use --sort=size | path | idle | mtime");
+      return 1;
+    }
+    if (Array.isArray(flags.sort)) {
+      errorLog("--sort given more than once \u2014 pass a single key");
+      return 1;
+    }
+    const key = String(flags.sort);
+    if (key !== "size" && key !== "path" && key !== "idle" && key !== "mtime") {
+      errorLog(`invalid --sort: ${key} (expected size | path | idle | mtime)`);
+      return 1;
+    }
+    sort = key;
+  }
+  const skipSystem = flags.skip !== false;
+  let trashMode;
+  if (flags.trash !== void 0) {
+    if (flags.trash === true) {
+      errorLog("--trash needs a value \u2014 use --trash=system or --trash=nmh");
+      return 1;
+    }
+    if (Array.isArray(flags.trash)) {
+      errorLog("--trash given more than once \u2014 pass a single mode");
+      return 1;
+    }
+    const mode = String(flags.trash);
+    if (mode !== "system" && mode !== "nmh") {
+      errorLog(`invalid --trash: ${mode} (expected system | nmh)`);
+      return 1;
+    }
+    trashMode = mode;
+  }
   const deleted = normalizeDelete(flags.delete);
   if (deleted === "invalid") {
     errorLog(`invalid --delete: ${String(flags.delete)} (expected 'hard' | 'soft' | 'trash')`);
@@ -5023,7 +5721,7 @@ async function main() {
     }
   }
   if (reportPath !== null) {
-    const ext = path24.extname(reportPath).toLowerCase();
+    const ext = path25.extname(reportPath).toLowerCase();
     if (!REPORT_EXTENSIONS.includes(ext)) {
       errorLog(`unknown report format: ${reportPath} (expected .json/.md/.txt)`);
       return 1;
@@ -5052,7 +5750,12 @@ async function main() {
   const cwd = process.cwd();
   const dryRun = flags.dryRun === true;
   const assumeYes = flags.yes === true || flags.force === true;
-  const subcommand = positionals[0] === void 0 || looksLikePath(positionals[0]) ? null : positionals[0];
+  const resolvedSub = resolveSubcommand(positionals, cwd);
+  if (resolvedSub.unknown !== null) {
+    errorLog(`unknown command '${resolvedSub.unknown}' \u2014 run \`nmh help\` for the command list (paths are passed to \`nmh scan\` or \`--dir\`)`);
+    return 1;
+  }
+  const subcommand = resolvedSub.subcommand;
   const rest = subcommand ? positionals.slice(1) : positionals;
   const dirTargets = splitTargets(flags.dir);
   const targets = [...rest, ...dirTargets];
@@ -5064,9 +5767,12 @@ async function main() {
     errorLog("--save-report rides along with scan \u2014 delete/clean runs are not scan reports");
     return 1;
   }
+  if (trashMode !== void 0 && !deleted.given && subcommand !== "clean") {
+    warn("--trash only matters for delete/clean runs \u2014 ignored for scans and read-only commands");
+  }
   if (deleted.given || subcommand === "clean") {
     for (const candidate of targets.length > 0 ? targets : [""]) {
-      if (isRootPath(path24.resolve(cwd, candidate))) {
+      if (isRootPath(path25.resolve(cwd, candidate))) {
         errorLog("refusing a delete op over the filesystem root \u2014 point --dir at the project directory you want cleaned");
         return 1;
       }
@@ -5084,12 +5790,23 @@ async function main() {
     pmFilter: pm.family !== null ? [pm.family] : void 0,
     listPm: pm.given && pm.family === null,
     expand,
-    saveReport: reportPath ?? void 0
+    saveReport: reportPath ?? void 0,
+    stale,
+    fastSize,
+    sort,
+    skipSystem
   };
   if (subcommand === "version") {
     printVersion(json);
     return 0;
   }
+  if (subcommand === "update") {
+    if (deleted.given || rest.length > 0) {
+      errorLog("update takes no arguments \u2014 plain `nmh update` (add --json for the payload)");
+      return 1;
+    }
+    return runUpdate({ json });
+  }
   if (subcommand === "config") {
     const ops = /* @__PURE__ */ new Set(["info", "set", "add", "remove", "unset"]);
     const opRaw = rest[0];
@@ -5355,10 +6072,17 @@ async function main() {
       excludes: excludes.length > 0 ? excludes : void 0,
       keep: keep.length > 0 ? keep : void 0,
       pmFilter: pm.family !== null ? [pm.family] : void 0,
-      maxDepth: effectiveDepth
+      maxDepth: effectiveDepth,
+      stale,
+      skipSystem,
+      trashMode
     });
   }
   if (deleted.given) {
+    if (trashMode !== void 0 && deleted.mode === "hard") {
+      errorLog("--trash applies to trash mode \u2014 hard delete is permanent by design, there is no trash to choose");
+      return 1;
+    }
     return runDelete({
       targets,
       cwd,
@@ -5370,7 +6094,10 @@ async function main() {
       excludes: excludes.length > 0 ? excludes : void 0,
       keep: keep.length > 0 ? keep : void 0,
       pmFilter: pm.family !== null ? [pm.family] : void 0,
-      maxDepth: effectiveDepth
+      maxDepth: effectiveDepth,
+      stale,
+      skipSystem,
+      trashMode
     });
   }
   if (positionals.length > 0 || dirTargets.length > 0) {