node-modules-hunter 1.1.0 → 1.1.1

package/README.md

@@ -86,11 +86,11 @@ Search patterns: plain text is a case-insensitive substring (`nmh search lodash`
 | `--save-report <file>` / `--report <file>` | `scan`, `map`, `search`, `stats`: **also** write the printed report to a file — format picked by extension `.json` / `.md` / `.txt` (write failure = warning, exit unchanged) |
 | `--treemap [file]` / `--out <file>` | `nmh treemap <dirs>`: export one self-contained interactive HTML treemap (default `nmh-treemap.html`); `--json` prints the raw data instead |
 | `--reinstall` | With `stats` (focused view): naive npm-ci-style estimate of how long re-installing everything takes (pkg × 60 ms + bytes / 50 MB/s + 3 s per native-family build); assumptions surfaced in the JSON, labeled naif |
-| `--animate` / `--no-animate` | Live size counter while measuring: auto = real TTY only, `--animate` forces it even when piped; always suppressed under `--json`; `.nmhrc animate:false` mutes it |
+| `--animate` / `--no-animate` | Spinning braille loader while measuring (time-driven — rotates on its own, v1.1.1): auto = real TTY only, `--animate` forces it even when piped; always suppressed under `--json`; `.nmhrc animate:false` mutes it |
 | `--update-check` | Opt-in: peek npm for a newer release (non-blocking, 24 h cache, notice on stderr; also `updateCheck` in `.nmhrc`) |
 | `--config <file>` | Use this config file instead of the `.nmhrc` lookup (cwd → `$HOME`) |
 | `--json` | Machine-readable output (pipe into `jq`) |
-| `-q/--quiet`, `--verbose`, `--no-color` | Output control |
+| `-q/--quiet`, `--verbose`, `--no-color` | Output control — ANSI colors paint only on a real TTY, or with explicit opt-in (`--color` / `FORCE_COLOR`); pipes & CI get plain text by default, `--no-color`/`NO_COLOR` always win (v1.1.1) |
 
 The `.nmhrc` lookup walks every ancestor from cwd up to `$HOME` — and it honors `logDir`, the directory where delete recovery logs are written. Only keep a `.nmhrc` in directories you control: in a shared checkout, a parent directory you don't own could steer your recovery logs and scan defaults; when in doubt, pass an explicit `--config`.
 
@@ -413,7 +413,7 @@ For settings you always repeat, drop a `.nmhrc` (or `.nmhrc.json`) next to your
 }
 ```
 
-- Nearest file wins: looks from the current dir up **to** `$HOME` (inclusive), not beyond.
+- Nearest file wins: looks from the current dir up **to** `$HOME` (inclusive), not beyond. When your cwd lives **outside** the home tree, `$HOME/.nmhrc` is still honored as the final fallback (chain first, v1.1.1) — so `nmh config set` works everywhere.
 - `--config <file>` replaces the lookup entirely.
 - CLI flags always win; `exclude`/`keep` **merge** (config first, CLI appended); `defaultMode` pre-fills a bare `--delete` and the wizard's initial choice; unknown keys are warned about and ignored.
 - `--config` isn't a delete-mode switch — deleting still asks permission unless `--yes`/`--force`.
@@ -448,7 +448,7 @@ nmh config unset --default-exclude --animate     # keys out of the file
 
 ## Roadmap
 
-v0.1 shipped the MVP (scan · size · delete · wizard · guards · PM detection). v0.2 added **search, map, `--depend`, `-r` recursive audit and the `--pm` / `--exclude` / `--keep` / `--depth` / `--expand` filters**. v0.3 added the **`stats` suite (dup factor, waste, top-N, per-package tree), `stats -g` global analysis across PMs, report export (`--save-report`/`--report`), `--animate` and the `.nmhrc` config file**. v0.4 added the **analytics deep-cut: baselines (`--save-baseline`/`--compare`/`--history`), dedup suggestions with per-copy declared ranges, `nmh why`, the real `--by type` breakdown, the `--phantom`/`--dead` best-effort import audit and the opt-in `--update-check`**. v0.5 added the **vision & hygiene extras: license scan (`--licenses`/`--by licenses` with the copyleft-in-prod ⚠), the experimental Bloat Score (`--score`) and CO2 estimate (`--co2`), the deprecated check (`--online`, offline manifests + lazy cached registry fallback), the `nmh treemap` single-file HTML export and `--save-report` for map/search/stats**. v0.6 added the **lockfile-grade graph: `--graph` parses npm/yarn/pnpm/bun lockfiles (zero new dependencies) into a real dependency graph with a BFS depth histogram, `nmh why` upgrades to lockfile-grade required-by (transitive requirers, no more false "orphans"), and `--reinstall` estimates the npm-ci-style reinstall time**. v0.7 added the **full PRD §7.5 wizard menu (delete all / pick / search / map / detailed report / settings, with loop-backs), a serious banner box (TTY) + compact one-liner (non-TTY, `--json`-clean), and a richer `nmh version` (node + abi + OS/arch/kernel + tty, `--json`)**. The v0.7.1 patch re-scheduled the folder walker to a slot-per-readdir work queue: the old recursive limiter could deadlock (circular wait) on wide bushy trees like a 12-package pnpm workspace — freezing the scan with **zero output and exit code 0 mid-walk**. Trees of that shape are covered by a regression test now. The same patch hardened measurement: children are classified with `fs.lstat` instead of dirent `d_type`, because some filesystems (Android FUSE/sdcardfs) misreport hardlinked pnpm-store files as symlinks — one `typescript/lib` dir had 112 of 125 dirents lying, which made a whole pnpm virtual store measure 650 KB while `du` saw 66 MB — and entry sizes now dedupe hardlinks per entry (`du -sb`-style), keeping walk numbers in line with `du` (91 → 63 MB on the same tree). v0.8 makes the no-arg wizard scope-aware: when the cwd has no node_modules within depth 3, it climbs once to the nearest manifest ancestor (package.json, any PM lockfile, or `pnpm-workspace.yaml`, ≤8 hops — empty manifest dirs are skipped so the monorepo root still wins) and the whole menu runs there; the scope is frozen for the session (rescans never re-climb), a TTY note reveals the lift, non-TTY gets a warn line, and `--json` stays a pure payload. The v0.9 minor introduces **`nmh config` (info · set · add · remove · unset)** — manage the `.nmhrc` from the CLI instead of hand-editing JSON (`--default-exclude`/`--default-keep` list discipline with dedupe and clear, loader-grade validation, unknown-key preservation on write, `$HOME/.nmhrc` default target) — and the **`self` token** for `exclude`/`keep`: a scan-level guard that drops every entry inside the folder nmh runs from, wholesale, whatever target you point at (your own project can never be hunted by accident). v0.9.1 is a **live-audit hardening patch**: a scripted fixture farm × ~140 invoked combination runs surfaced five defects that are now fixed — delete guards additionally refuse a `node_modules` sitting *directly inside* `/` or `$HOME` (previously a `--dir ~ --delete -y` could sweep it away), the wizard's non-TTY fallback scan now honors `exclude`/`keep` from config and flags, a bare `--depth` failure message no longer swallows the value into `true`, the `--depend` guard messages are reconciled as map-only with actionable hints, and a failed `treemap --out` write exits 1 with a friendly 🛑 instead of a raw errno string. Audited-and-confirmed-as-designed along the way: positional targets are never comma-split (only `--dir` is), `--save-report` write failures warn and keep the exit code, `nmh search` matches top-level package names per PRD §7.3, and `nmh why` takes pkg-first arguments. v0.9.2 is an **independent-review hardening patch**: it closes the biggest hole the v0.9.1 audit missed — a TTY `--json --delete` used to execute with **zero confirmation** (machine output has no interactive prompt slot, and the non-TTY guard didn't cover the TTY branch; a pseudo-TTY reproduction proved rc=0 with the victim gone) — now `--json --delete` requires `--yes`/`--force` on every shell, TTY included. The same pass fixed the config family under `--quiet --json` (its payload was the one survivor the sweep missed — printed empty with rc 0), turned a silent bare/multi `--size` into a loud usage error like its sibling guards, and cleaned the last 10 pre-existing `tsc` errors (a leftover `depth` sentinel union) so `npm run typecheck` is finally clean. v0.9.3 is a **no-behavior-change cleanliness patch** from the same review: six dead symbols removed (`measurePackageRefs`, `SizedPackageRef`, `readLicense`, `listHasSelf`, `isVerbose`, `formatCount`), the write-only `MeasureProgress.currentEntry` field dropped, the twin `DepsAudit` interfaces collapsed to one canonical definition (re-exported from `core/result.ts`), the `self` guard moved to its semantic home (`core/guards.ts`), `ConfigError` now carries a machine-readable `code` instead of message string-matching, scan's private report writer now shares `writeReportSnapshot` with map/search/stats, the `analyze`/`info` stats aliases are documented, and `npm run typecheck` stays at zero errors. v0.9.4 is a **hardening patch for the review findings that change data/behavior**: `stripJsonC` is now fully quote-aware (a trailing comma inside a string value is no longer eaten — silent corruption fixed), `makeGlobMatcher` caps pathological patterns (512 chars / 8 `**`) up front, a delete op aimed at `/` refuses before scanning, the deprecated `truncated` flag means "a 201st item was refused" instead of "exactly at the cap", recovery logs get a random suffix (no same-millisecond overwrites), deprecated notes are ANSI-stripped at the source, `nmh why` reads its manifests/locks with bounded concurrency of 4, the `$HOME` guard ignores letter-case on macOS, the `.nmhrc` ancestor trust is documented in the README, and the self-guard-vs-symlinked-cwd claim is verified as a non-issue (Node resolves `process.cwd()` physically). v1.0.0 is the **stable-API release**: every `--json` payload is a frozen contract guarded by the 245-test suite, the exit-code table (0/1/2/3/4) is locked, `npm run typecheck` and `npm audit` are both clean, and the package ships to npm with a `v1.0.0` git tag once the remote is configured. v1.1.0 is the **stale-hunting edition**: `--stale <days>` grades entries by newest-of git commit → manifest mtime → folder mtime and drops no-evidence stragglers, `--fast-size` measures with `du -sk` (exact-walker fallback), results gain an `Idle` column, a proportional Share bar and `--sort size|path|idle|mtime`, discovery hides system noise by default (`--no-skip` restores the bare audit), `nmh update` self-updates npm-global installs, and `--trash=system|nmh` picks the backend with a restorable `~/.nmh/trash` fallback — all with zero new dependencies and additive-only JSON keys, guarded by the 267-test suite.
+v0.1 shipped the MVP (scan · size · delete · wizard · guards · PM detection). v0.2 added **search, map, `--depend`, `-r` recursive audit and the `--pm` / `--exclude` / `--keep` / `--depth` / `--expand` filters**. v0.3 added the **`stats` suite (dup factor, waste, top-N, per-package tree), `stats -g` global analysis across PMs, report export (`--save-report`/`--report`), `--animate` and the `.nmhrc` config file**. v0.4 added the **analytics deep-cut: baselines (`--save-baseline`/`--compare`/`--history`), dedup suggestions with per-copy declared ranges, `nmh why`, the real `--by type` breakdown, the `--phantom`/`--dead` best-effort import audit and the opt-in `--update-check`**. v0.5 added the **vision & hygiene extras: license scan (`--licenses`/`--by licenses` with the copyleft-in-prod ⚠), the experimental Bloat Score (`--score`) and CO2 estimate (`--co2`), the deprecated check (`--online`, offline manifests + lazy cached registry fallback), the `nmh treemap` single-file HTML export and `--save-report` for map/search/stats**. v0.6 added the **lockfile-grade graph: `--graph` parses npm/yarn/pnpm/bun lockfiles (zero new dependencies) into a real dependency graph with a BFS depth histogram, `nmh why` upgrades to lockfile-grade required-by (transitive requirers, no more false "orphans"), and `--reinstall` estimates the npm-ci-style reinstall time**. v0.7 added the **full PRD §7.5 wizard menu (delete all / pick / search / map / detailed report / settings, with loop-backs), a serious banner box (TTY) + compact one-liner (non-TTY, `--json`-clean), and a richer `nmh version` (node + abi + OS/arch/kernel + tty, `--json`)**. The v0.7.1 patch re-scheduled the folder walker to a slot-per-readdir work queue: the old recursive limiter could deadlock (circular wait) on wide bushy trees like a 12-package pnpm workspace — freezing the scan with **zero output and exit code 0 mid-walk**. Trees of that shape are covered by a regression test now. The same patch hardened measurement: children are classified with `fs.lstat` instead of dirent `d_type`, because some filesystems (Android FUSE/sdcardfs) misreport hardlinked pnpm-store files as symlinks — one `typescript/lib` dir had 112 of 125 dirents lying, which made a whole pnpm virtual store measure 650 KB while `du` saw 66 MB — and entry sizes now dedupe hardlinks per entry (`du -sb`-style), keeping walk numbers in line with `du` (91 → 63 MB on the same tree). v0.8 makes the no-arg wizard scope-aware: when the cwd has no node_modules within depth 3, it climbs once to the nearest manifest ancestor (package.json, any PM lockfile, or `pnpm-workspace.yaml`, ≤8 hops — empty manifest dirs are skipped so the monorepo root still wins) and the whole menu runs there; the scope is frozen for the session (rescans never re-climb), a TTY note reveals the lift, non-TTY gets a warn line, and `--json` stays a pure payload. The v0.9 minor introduces **`nmh config` (info · set · add · remove · unset)** — manage the `.nmhrc` from the CLI instead of hand-editing JSON (`--default-exclude`/`--default-keep` list discipline with dedupe and clear, loader-grade validation, unknown-key preservation on write, `$HOME/.nmhrc` default target) — and the **`self` token** for `exclude`/`keep`: a scan-level guard that drops every entry inside the folder nmh runs from, wholesale, whatever target you point at (your own project can never be hunted by accident). v0.9.1 is a **live-audit hardening patch**: a scripted fixture farm × ~140 invoked combination runs surfaced five defects that are now fixed — delete guards additionally refuse a `node_modules` sitting *directly inside* `/` or `$HOME` (previously a `--dir ~ --delete -y` could sweep it away), the wizard's non-TTY fallback scan now honors `exclude`/`keep` from config and flags, a bare `--depth` failure message no longer swallows the value into `true`, the `--depend` guard messages are reconciled as map-only with actionable hints, and a failed `treemap --out` write exits 1 with a friendly 🛑 instead of a raw errno string. Audited-and-confirmed-as-designed along the way: positional targets are never comma-split (only `--dir` is), `--save-report` write failures warn and keep the exit code, `nmh search` matches top-level package names per PRD §7.3, and `nmh why` takes pkg-first arguments. v0.9.2 is an **independent-review hardening patch**: it closes the biggest hole the v0.9.1 audit missed — a TTY `--json --delete` used to execute with **zero confirmation** (machine output has no interactive prompt slot, and the non-TTY guard didn't cover the TTY branch; a pseudo-TTY reproduction proved rc=0 with the victim gone) — now `--json --delete` requires `--yes`/`--force` on every shell, TTY included. The same pass fixed the config family under `--quiet --json` (its payload was the one survivor the sweep missed — printed empty with rc 0), turned a silent bare/multi `--size` into a loud usage error like its sibling guards, and cleaned the last 10 pre-existing `tsc` errors (a leftover `depth` sentinel union) so `npm run typecheck` is finally clean. v0.9.3 is a **no-behavior-change cleanliness patch** from the same review: six dead symbols removed (`measurePackageRefs`, `SizedPackageRef`, `readLicense`, `listHasSelf`, `isVerbose`, `formatCount`), the write-only `MeasureProgress.currentEntry` field dropped, the twin `DepsAudit` interfaces collapsed to one canonical definition (re-exported from `core/result.ts`), the `self` guard moved to its semantic home (`core/guards.ts`), `ConfigError` now carries a machine-readable `code` instead of message string-matching, scan's private report writer now shares `writeReportSnapshot` with map/search/stats, the `analyze`/`info` stats aliases are documented, and `npm run typecheck` stays at zero errors. v0.9.4 is a **hardening patch for the review findings that change data/behavior**: `stripJsonC` is now fully quote-aware (a trailing comma inside a string value is no longer eaten — silent corruption fixed), `makeGlobMatcher` caps pathological patterns (512 chars / 8 `**`) up front, a delete op aimed at `/` refuses before scanning, the deprecated `truncated` flag means "a 201st item was refused" instead of "exactly at the cap", recovery logs get a random suffix (no same-millisecond overwrites), deprecated notes are ANSI-stripped at the source, `nmh why` reads its manifests/locks with bounded concurrency of 4, the `$HOME` guard ignores letter-case on macOS, the `.nmhrc` ancestor trust is documented in the README, and the self-guard-vs-symlinked-cwd claim is verified as a non-issue (Node resolves `process.cwd()` physically). v1.0.0 is the **stable-API release**: every `--json` payload is a frozen contract guarded by the 245-test suite, the exit-code table (0/1/2/3/4) is locked, `npm run typecheck` and `npm audit` are both clean, and the package ships to npm with a `v1.0.0` git tag once the remote is configured. v1.1.0 is the **stale-hunting edition**: `--stale <days>` grades entries by newest-of git commit → manifest mtime → folder mtime and drops no-evidence stragglers, `--fast-size` measures with `du -sk` (exact-walker fallback), results gain an `Idle` column, a proportional Share bar and `--sort size|path|idle|mtime`, discovery hides system noise by default (`--no-skip` restores the bare audit), `nmh update` self-updates npm-global installs, and `--trash=system|nmh` picks the backend with a restorable `~/.nmh/trash` fallback — all with zero new dependencies and additive-only JSON keys, guarded by the 267-test suite. The v1.1.1 patch is a **polish-and-hardening pass driven by three user reports and a full live-exercise matrix** (26 sandbox fixtures × 223 real combinations): the measuring loader is a **time-driven spinner** (braille frames rotate on their own timer at 70 ms instead of per-update repaints, spinning on TTY, silent in pipes unless `--animate on`), `nmh help` renders a **complete manual** (own renderer — 14 commands + 5 stats subcommand views + grouped options + examples + the safety/exit footer, and the previously-missing `-h`/`--help`/`-v`/`--version` aliases finally work instead of slipping into the default scan), and ANSI colors are **TTY-only by design** (picocolors' `!!env.CI` guess had painted unknown escape bytes into piped GitHub Actions output and shredded substring assertions — CI is 9/9 green for the first time; local color comes from a real TTY or explicit `--color`/`FORCE_COLOR`). The same matrix surfaced two defects the suite had missed: an unknown first word (`nmh scanx`) used to fall through to a silent full-cwd scan with exit 0 — any non-path, non-command token is now a loud usage error (and a bare cwd-relative dir like `nmh node_modules` now correctly targets that folder); and `nmh config set` wrote `$HOME/.nmhrc` while scans walked cwd → `/` and never read it when the cwd lived outside the home tree — the home file is now the documented fallback (chain first). Meanwhile `os.homedir()` on Windows reads `USERPROFILE` (test helper pins both), `execFile('npm')` needs `shell: true` on win32 (`stats -g` exited 2 there), and system-trash-dependent flows run hermetically via `nmh trash` fallback. Suite: 44 files / 279 tests green.
 
 ## Development
 

package/dist/cli.js

@@ -3,6 +3,7 @@
 // src/cli.ts
 import { cac } from "cac";
 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 };
 }
 
@@ -2143,7 +2341,7 @@ async function collectScan(request) {
   const entryPaths = [...metaByPath.keys()];
   verboseLog(`found ${entryPaths.length} node_modules \u2014 measuring`);
   const measures = await collectMeasures(entryPaths, request.fastSize === true, permIssues);
-  clearProgress();
+  spinClear();
   const detect = createPmDetector();
   const pmLimiter = createLimiter(8);
   const pmResults = await Promise.all(entryPaths.map((entryPath) => pmLimiter(() => detect(entryPath))));
@@ -2223,7 +2421,7 @@ async function collectMeasures(entryPaths, fastSize, permIssues) {
   let measuredCount = 0;
   let bytesSoFar = 0;
   const bump = () => {
-    progressLine(`\u280B measuring ${measuredCount}/${entryCount} folders \xB7 ${formatBytes(bytesSoFar)}`);
+    spinUpdate(`measuring ${measuredCount}/${entryCount} folders \xB7 ${formatBytes(bytesSoFar)}`);
   };
   if (!fastSize) {
     return measureEntries(entryPaths, permIssues, {
@@ -2262,8 +2460,8 @@ async function collectMeasures(entryPaths, fastSize, permIssues) {
     const walked = await measureEntries(fallbackPaths, permIssues, {
       concurrency: 4,
       onProgress: (progress) => {
-        progressLine(
-          `\u280B measuring ${duCount + progress.measuredEntries}/${entryCount} folders \xB7 ${formatBytes(duBytes + progress.bytesSoFar)}`
+        spinUpdate(
+          `measuring ${duCount + progress.measuredEntries}/${entryCount} folders \xB7 ${formatBytes(duBytes + progress.bytesSoFar)}`
         );
       }
     });
@@ -2492,9 +2690,9 @@ async function installLatest(version) {
       return { ok: false, detail: err instanceof Error ? err.message : String(err) };
     }
   }
-  progressLine("\u280B updating via npm\u2026");
+  spinUpdate("updating via npm\u2026");
   const install = await runNpm(["install", "-g", "node-modules-hunter@" + version], 3e5);
-  clearProgress();
+  spinClear();
   if (install.code !== 0) {
     return { ok: false, detail: install.stderr.trim().slice(0, 300) || `npm exited ${install.code}` };
   }
@@ -2867,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;
@@ -3456,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;
@@ -3956,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();
@@ -4620,10 +4818,10 @@ async function executeAll(entries, request) {
     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);
@@ -5057,13 +5255,27 @@ 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;
   }
 }
@@ -5163,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 = [];
@@ -5179,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 };
         })
       )
@@ -5194,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) {
@@ -5233,6 +5445,8 @@ 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");
@@ -5286,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 };
@@ -5320,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;
@@ -5351,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
   });
@@ -5510,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];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-modules-hunter",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Hunt down bloated node_modules folders across your machine — scan, measure, and clean them with one command.",
   "type": "module",
   "license": "MIT",