node-modules-hunter 1.1.0 → 1.2.0

package/README.md

@@ -28,6 +28,8 @@ Node.js ≥ 18 required.
 
 ```
 nmh                                # interactive wizard: arrow menu (delete all / pick / search / map / report / settings)
+nmh wizard --dir=./a,./b           # v1.2: the wizard on explicit targets (skips the auto-climb)
+nmh wizard -- stats --dir=./a      # v1.2: open a read-only view first, then the wizard menu
 nmh <path> [path…]                 # shortcut: scan given path(s)
 nmh scan [dir]                     # full scan (default: cwd)
 nmh clean [dir]                    # scan + delete everything safe (trash by default)
@@ -44,7 +46,9 @@ nmh stats -g                       # global installs across npm/pnpm/yarn/bun
 # aliases: `analyze` and `info` behave exactly like `stats` (recognition from PRD-era names)
 nmh why <pkg> [dir…]               # reverse depend: where is <pkg> and what requires it — read-only
 nmh treemap [dir]                  # single-file interactive HTML treemap → nmh-treemap.html
-nmh update                         # self-update: compare installed vs npm latest, install if global
+nmh update --check                 # v1.2: compare installed vs registry — nothing installs
+nmh update --info                  # v1.2: full registry detail (npm view style)
+nmh update -y                      # install the newer version without asking (-n declines, --force skips the ask)
 
 nmh --dir=A,B,glob/*/node_modules  # targets: comma list, globs, ~ — combine with flags below
 nmh version | --version | -v        # banner: tool version, node+abi, OS/arch/kernel distro, tty — --json for plain fields
@@ -86,11 +90,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`.
 
@@ -322,6 +326,8 @@ pasang ulang semuanya sekali : ~6.7s
 
 Read-only items return to the menu; a delete run ends with the freed-space summary and the rescue-log pointer. Non-TTY (piped/CI): no menu — a compact one-line banner + a read-only scan, and `--json` suppresses even that for clean machine output. The v0.8 auto-scope climbs to the nearest project root (package.json / any PM lockfile / `pnpm-workspace.yaml`, ≤8 hops of ancestors — empty manifest dirs are skipped so the monorepo root still wins) and sticks for the whole session; the TTY shows a dim note, non-TTY a warn line, `--json` stays a pure payload.
 
+**Explicit targeting (v1.2)**: `nmh wizard` is a registered command now (same menu as the bare invocation). Give it `--dir=./repo1,./repo2` and the menu runs on those targets as-is — the auto-climb is skipped for explicit scopes. `nmh --wizard` is the flag form. The **`--` router** opens a read-only view before the menu: `nmh wizard -- stats --dir=./repo1` runs the full stats report first (the view segment is parsed by the same dispatcher — all its flags/guards apply, and flags before `--` belong to the wizard), then drops you into the menu. Views: `stats` (aliases `analyze`, `info`), `map`, `search`, `why`, `treemap`. All explicit wizard forms need a TTY — a piped run refuses with exit `1` and directions (the bare `nmh` fallback scan is untouched).
+
 ## Safety first (the whole point)
 
 - **Guards refuse to delete** (exit code `3`): the filesystem root, `$HOME` itself, a `node_modules` sitting **directly inside** `/` or `$HOME`, anything not named exactly `node_modules`, and targets with unresolvable paths (symlink loops).
@@ -351,7 +357,7 @@ The classic question — *which of these `node_modules` can I actually kill?*
 
 - **`--fast-size`** swaps the byte-exact walker for one `du -sk` per entry (KiB granularity — sizes are always multiples of 1024); anything `du` can't measure falls back to the exact walker silently. Scan-only knob: delete runs always measure exactly so the freed-bytes number stays honest. Windows has no `du`, so it always walks.
 - **Default skip-list flip**: discovery now hides name-based system noise (`.Trash`, `.Trashes`, `.Trash-<uid>`, `Library`, `*.app`) wherever it sits in the tree; pass **`--no-skip`** to restore the bare full-tree v1.0 audit. `.git` stays skipped always (even with `--no-skip`), and direct targets are never filtered — the skip only shapes what discovery finds.
-- **`nmh update`** compares your installed version with the npm registry; if nmh lives in the npm global tree, it runs `npm install -g node-modules-hunter@<latest>` for you — otherwise you get an honest how-to note for your install method. `--json` payload: `{ current, latest, updated, method }`.
+- **`nmh update` is consented (v1.2)**: the plain run shows the facts and asks before installing (`@clack` confirm on a TTY; a piped/`--json` run needs `-y` to install or `-n` to decline — without an answer it refuses with exit `1`, the same protocol as deletes). `--check` is the compact compare for scripts/CI (exit 0 whether or not an update exists, never installs), `--info` is the full `npm view`-style read-out (description, tarball + size + file count, engines, license, publish time), and the two are mutually exclusive. `--force` skips the ask when an update exists — an already-latest install is checked and reported, never blindly reinstalled. Non-npm-global installs keep the honest how-to note. `--json` payload: `{ current, latest, updated, method }` frozen + additive `{ updateAvailable, detail? }`.
 - **`--json` stays additive**: new optional keys `idleDays`, `activitySource`, `backend`, `trashBatch`, `trashFallback` appear only when a v1.1 feature is active; every v1.0 payload key is unchanged (the frozen v1.0 contract, extended minor-version-safely).
 
 ## Exit codes
@@ -413,7 +419,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 +454,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. v1.2.0 is the **consent-and-targeting edition**: `nmh update` stops installing on faith — the plain run shows the facts and asks (`-y`/`-n` on pipes, `--force` to skip the ask, and an already-latest install is never reinstalled), while `--check` and `--info` are read-only registry views (compact compare vs full `npm view` detail, mutually exclusive); and the wizard becomes a first-class command — `nmh wizard --dir=./a,./b` scopes the menu to explicit targets (no auto-climb), `nmh --wizard` is the flag form, and the `--` router (`nmh wizard -- stats --dir=./a`) opens a read-only view through the full dispatcher before the menu; pipes refuse every explicit wizard form with exit 1 and directions while the bare `nmh` fallback scan stays untouched. The update messages were also unified to Indonesian (the smoke matrix caught `--check` speaking English next to an Indonesian default). Suite: 46 files / 295 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,171 @@ 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 wizard [--dir \u2026]", desc: "v1.2: the wizard on explicit targets (--dir=./a,./b skips the auto-climb); -- <view> opens a view first" },
+  { 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: "v1.2: shows the facts and asks before installing \u2014 --check / --info compare only; -y installs, -n declines, --force skips the ask" },
+  { 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: "--wizard", desc: "v1.2: open the wizard explicitly \u2014 same as bare `nmh`, but a pipe refuses with directions instead of a scan" },
+      { usage: "update: --check \xB7 --info \xB7 -y \xB7 -n \xB7 -f", desc: "v1.2: read-only views vs consented install \u2014 see `nmh update` row above" },
+      { 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 wizard --dir=./repo1,./repo2", "wizard scoped to explicit targets \u2014 no auto-climb"],
+  ["nmh wizard -- stats --dir=./repo1", "v1.2 router: stats view first, then the wizard menu"],
+  ["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 update --check", "compare installed vs registry \u2014 nothing installs"],
+  ["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 +522,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 +2347,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 +2427,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 +2466,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)}`
         );
       }
     });
@@ -2350,6 +2554,7 @@ function emptyResult(targets, unresolvable = []) {
 import { promisify as promisify3 } from "util";
 import { execFile as execFile3 } from "child_process";
 import fs13 from "fs/promises";
+import { confirm } from "@clack/prompts";
 
 // src/utils/update-check.ts
 import fs12 from "fs/promises";
@@ -2454,24 +2659,62 @@ async function runNpm(args, timeoutMs) {
   }
 }
 var VERSION_SHAPE = /^\d+\.\d+\.\d+/;
-async function latestVersion() {
+function manifestDetailFrom(parsed) {
+  const detail = {};
+  if (typeof parsed.description === "string") detail.description = parsed.description;
+  if (typeof parsed.license === "string") detail.license = parsed.license;
+  const dist = parsed.dist;
+  if (dist !== null && typeof dist === "object") {
+    const d = dist;
+    if (typeof d.tarball === "string") detail.tarball = d.tarball;
+    if (typeof d.unpackedSize === "number") detail.unpackedSize = formatBytes(d.unpackedSize);
+    if (typeof d.fileCount === "number") detail.fileCount = d.fileCount;
+  }
+  const engines = parsed.engines;
+  if (engines !== null && typeof engines === "object") {
+    const e = engines;
+    if (typeof e.node === "string") detail.engines = e.node;
+  }
+  return detail;
+}
+async function latestManifest() {
   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;
+      const version = parsed.version;
+      if (typeof version !== "string" || !VERSION_SHAPE.test(version)) return null;
+      return { version, detail: manifestDetailFrom(parsed) };
     } 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);
+  const view = await runNpm(["view", "node-modules-hunter", "--json"], 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;
+  try {
+    const parsed = JSON.parse(view.stdout);
+    const version = parsed.version;
+    if (typeof version !== "string" || !VERSION_SHAPE.test(version)) return null;
+    const detail = manifestDetailFrom(parsed);
+    detail.publishedAt = await publishedTime(version);
+    return { version, detail };
+  } catch {
+    return null;
+  }
+}
+async function publishedTime(version) {
+  const times = await runNpm(["view", "node-modules-hunter", "time", "--json"], 3e4);
+  if (times.code !== 0) return void 0;
+  try {
+    const parsed = JSON.parse(times.stdout);
+    return typeof parsed[version] === "string" ? parsed[version] : void 0;
+  } catch {
+    return void 0;
+  }
 }
 async function isNpmGlobal() {
   const forced = process.env.NMH_UPDATE_GLOBAL;
@@ -2492,49 +2735,94 @@ 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}` };
   }
   return { ok: true, detail: installCommand };
 }
+function renderInfo(current, manifest, updateAvailable, global) {
+  const d = manifest.detail;
+  const rows = [
+    `installed   ${current}`,
+    `latest      ${manifest.version}`,
+    `update      ${updateAvailable ? `tersedia \u2014 jalankan \`nmh update\`${global ? "" : " (atau: npm i -g node-modules-hunter)"}` : "tidak ada \u2014 ini versi terbaru"}`
+  ];
+  if (d.description !== void 0) rows.push(`summary     ${d.description}`);
+  if (d.tarball !== void 0) {
+    const size = d.unpackedSize === void 0 ? "" : ` (${d.unpackedSize}${d.fileCount === void 0 ? "" : `, ${d.fileCount} files`})`;
+    rows.push(`tarball     ${d.tarball}${size}`);
+  }
+  if (d.engines !== void 0) rows.push(`engines     node ${d.engines}`);
+  if (d.license !== void 0) rows.push(`license     ${d.license}`);
+  if (d.publishedAt !== void 0) rows.push(`published   ${d.publishedAt}`);
+  return rows;
+}
 async function runUpdate(request) {
   const current = toolVersion();
-  const latest = await latestVersion();
-  if (latest === null) {
+  const manifest = await latestManifest();
+  if (manifest === 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 latest = manifest.version;
   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`);
+  const updateAvailable = isNewer(current, latest);
+  const result = (updated) => ({ current, latest, updated, method, updateAvailable });
+  if (request.mode === "info") {
+    if (request.json) payload(JSON.stringify({ ...result(false), detail: manifest.detail }, null, 2));
+    else log(["nmh update \u2014 info registry (npm view node-modules-hunter)", ...renderInfo(current, manifest, updateAvailable, global)].join("\n"));
+    return 0;
+  }
+  if (request.mode === "check") {
+    if (request.json) payload(JSON.stringify(result(false), null, 2));
+    else if (updateAvailable) log(`\u2191 update tersedia: ${current} \u2192 ${latest} \u2014 jalankan \`nmh update\` untuk menginstall`);
+    else log(`\u2713 nmh ${current} sudah versi terbaru (registry: ${latest})`);
+    return 0;
+  }
+  if (!updateAvailable) {
+    if (request.json) payload(JSON.stringify(result(false), null, 2));
+    else log(`\u2713 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));
+    if (request.json) payload(JSON.stringify(result(false), 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}`);
+  let install = request.force || request.answer === "yes";
+  if (!install && request.answer === "none") {
+    if (request.json || !isTTYOut()) {
+      errorLog("update butuh jawaban eksplisit \u2014 -y untuk menginstall, -n untuk menolak (--check/--info untuk lihat saja)");
+      return 1;
+    }
+    const admitted = await confirm({
+      message: `Update nmh ${current} \u2192 ${latest} via npm install -g?`,
+      initialValue: true
+    });
+    install = admitted === true;
+  }
+  if (!install) {
+    if (request.json) payload(JSON.stringify(result(false), null, 2));
+    else log(`\u2715 tetap nmh ${current} \u2014 update ke ${latest} tidak diinstall`);
+    return 0;
+  }
+  const installation = await installLatest(latest);
+  if (!installation.ok) {
+    errorLog(`\u26A0 update gagal: ${installation.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));
+  if (request.json) payload(JSON.stringify(result(true), null, 2));
   else log(`\u2713 terupdate ${current} \u2192 ${latest} (npm install -g node-modules-hunter)`);
   return 0;
 }
@@ -2750,7 +3038,7 @@ var INFO_DEFAULTS = {
   updateCheck: "off",
   logDir: "~/.nmh"
 };
-function renderInfo(source, values) {
+function renderInfo2(source, values) {
   const row = (key, value) => `  ${colors.dim(key.padEnd(12, " "))}${value}`;
   const lines = [
     "",
@@ -2787,7 +3075,7 @@ async function runConfigCommand(request) {
         );
         return 0;
       }
-      log(renderInfo(loaded.source, loaded.values));
+      log(renderInfo2(loaded.source, loaded.values));
       return 0;
     }
     const file = configWriteTarget(request.explicitFile, request.cwd);
@@ -2867,12 +3155,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 +3744,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 +4244,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();
@@ -4408,7 +4696,7 @@ async function saveBaselineQuiet(name, snapshot) {
 }
 
 // src/commands/delete.ts
-import { confirm, select, isCancel } from "@clack/prompts";
+import { confirm as confirm2, select, isCancel as isCancel2 } from "@clack/prompts";
 
 // src/core/deleter.ts
 import fs20 from "fs/promises";
@@ -4620,10 +4908,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);
@@ -4740,13 +5028,13 @@ async function resolveMode(requested, json, dryRun) {
       ],
       initialValue: "trash"
     });
-    if (isCancel(choice)) return "cancelled";
+    if (isCancel2(choice)) return "cancelled";
     return choice;
   }
   return "trash";
 }
 async function confirmDeletion(count, size, mode) {
-  const answer = await confirm({
+  const answer = await confirm2({
     message: mode === "hard" ? `Delete ${count} folder(s) \u2014 ${formatBytes(size)} \u2014 PERMANENTLY (no undo)?` : `Move ${count} folder(s) \u2014 ${formatBytes(size)} \u2014 to the OS trash?`,
     initialValue: mode !== "hard"
   });
@@ -4797,7 +5085,7 @@ async function runClean(request) {
 // src/commands/wizard.ts
 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";
+import { confirm as confirm3, isCancel as isCancel3, multiselect, outro, select as select2, text } from "@clack/prompts";
 
 // src/utils/banner.ts
 function widthOf(plain) {
@@ -4833,6 +5121,9 @@ async function runWizard(cwd, options = {}) {
   if (!isTTYOut()) return runFallbackScan(cwd, options);
   return runInteractiveWizard(cwd, options);
 }
+function wizardTargets(options) {
+  return options.targets !== void 0 && options.targets.length > 0 ? options.targets : ["."];
+}
 var WIZARD_DEPTH = 3;
 var WIZARD_MAX_CLIMB = 8;
 var PROJECT_MANIFESTS = /* @__PURE__ */ new Set([
@@ -4871,12 +5162,13 @@ async function resolveWizardScope(cwd) {
 }
 async function runFallbackScan(cwd, options) {
   if (!options.json) log(renderCompactBanner());
-  const scope = await resolveWizardScope(cwd);
+  const explicit = options.targets !== void 0 && options.targets.length > 0;
+  const scope = explicit ? { root: cwd, from: cwd, climbed: false, scouted: false } : await resolveWizardScope(cwd);
   if (!options.json && scope.climbed) {
     warn(`no node_modules within 3 levels of cwd \u2014 scoped to the project root above: ${scope.root}`);
   }
   const outcome = await collectScan({
-    targets: ["."],
+    targets: wizardTargets(options),
     cwd: scope.root,
     maxDepth: WIZARD_DEPTH,
     excludes: options.excludes,
@@ -4895,14 +5187,15 @@ async function runFallbackScan(cwd, options) {
   return outcome.code;
 }
 async function runInteractiveWizard(cwd, options) {
-  log(renderFullBanner());
-  const scope = await resolveWizardScope(cwd);
+  const explicit = options.targets !== void 0 && options.targets.length > 0;
+  if (options.banner !== false) log(renderFullBanner());
+  const scope = explicit ? { root: cwd, from: cwd, climbed: false, scouted: false } : await resolveWizardScope(cwd);
   if (scope.climbed) {
     log(colors.dim(`cwd has no node_modules in 3 levels \u2014 scoped up to the project root ${scope.root}`));
   }
   for (; ; ) {
     const scan = await collectScan({
-      targets: ["."],
+      targets: wizardTargets(options),
       cwd: scope.root,
       maxDepth: WIZARD_DEPTH,
       excludes: options.excludes,
@@ -4926,7 +5219,7 @@ async function runInteractiveWizard(cwd, options) {
         { value: "quit", label: "\u23F9  Exit nmh" }
       ]
     });
-    if (isCancel2(choice) || choice === "quit") {
+    if (isCancel3(choice) || choice === "quit") {
       outro("bye \u{1F44B} \u2014 nothing deleted");
       return 0;
     }
@@ -4941,18 +5234,18 @@ async function runInteractiveWizard(cwd, options) {
           placeholder: "e.g. lodash, react-dom, es*build, /react(-dom)?/i",
           validate: (value) => value.trim().length === 0 ? "give a pattern \u2014 substring, glob, or /regex/" : void 0
         });
-        if (isCancel2(pattern)) {
+        if (isCancel3(pattern)) {
           warn("search skipped \u2014 back to the menu");
           continue;
         }
-        await runSearch({ pattern: String(pattern).trim(), targets: ["."], cwd: scope.root, maxDepth: WIZARD_DEPTH });
+        await runSearch({ pattern: String(pattern).trim(), targets: wizardTargets(options), cwd: scope.root, maxDepth: WIZARD_DEPTH });
         break;
       }
       case "map":
-        await runMap({ targets: ["."], cwd: scope.root, maxDepth: WIZARD_DEPTH });
+        await runMap({ targets: wizardTargets(options), cwd: scope.root, maxDepth: WIZARD_DEPTH });
         break;
       case "stats":
-        await runStats({ targets: ["."], cwd: scope.root, maxDepth: WIZARD_DEPTH });
+        await runStats({ targets: wizardTargets(options), cwd: scope.root, maxDepth: WIZARD_DEPTH });
         break;
       case "settings":
         log(renderSettings(options.settings, scope));
@@ -4984,7 +5277,7 @@ async function deleteFlow2(kind, entries, options) {
       })),
       required: true
     });
-    if (isCancel2(picked)) {
+    if (isCancel3(picked)) {
       outro("cancelled \u2014 nothing deleted");
       return 0;
     }
@@ -4999,11 +5292,11 @@ async function deleteFlow2(kind, entries, options) {
     outro("cancelled \u2014 nothing deleted");
     return 0;
   }
-  const admitted = await confirm2({
+  const admitted = await confirm3({
     message: mode === "hard" ? `Delete ${selected.length} folder(s) \u2014 ${formatBytes(sum(selected))} \u2014 PERMANENTLY (no undo)?` : `Move ${selected.length} folder(s) \u2014 ${formatBytes(sum(selected))} \u2014 to the OS trash?`,
     initialValue: mode !== "hard"
   });
-  if (isCancel2(admitted) || admitted === false) {
+  if (isCancel3(admitted) || admitted === false) {
     outro("cancelled \u2014 nothing deleted");
     return 0;
   }
@@ -5022,7 +5315,7 @@ async function pickDeleteMode(defaultMode) {
     ],
     initialValue: defaultMode ?? "trash"
   });
-  return isCancel2(modeChoice) ? null : modeChoice;
+  return isCancel3(modeChoice) ? null : modeChoice;
 }
 function renderSettings(settings, scope) {
   const values = settings?.values ?? {};
@@ -5057,13 +5350,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 +5470,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 +5486,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 +5501,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 +5540,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");
@@ -5281,14 +5590,44 @@ cli.option("--reinstall", "stats only: naive npm-ci-style estimate of the time t
 cli.option("--treemap [file]", "treemap export: single-file HTML (vanilla JS, no deps); default nmh-treemap.html in cwd");
 cli.option("--out <file>", "treemap only: where to write the HTML file (same as --treemap <file>)");
 cli.option("--update-check", "opt-in: peek npm for a newer release (non-blocking, 24 h cache; also settable in .nmhrc)");
+cli.option("--check", "update only: compare installed vs registry and exit \u2014 never installs");
+cli.option("--info", "update only: full registry detail (npm view style) \u2014 never installs");
+cli.option("-n, --no", "update only: decline the update on the command line (nothing installs)");
+cli.option("--wizard", "open the interactive wizard explicitly (same as the bare `nmh`); needs a TTY");
 cli.option("--default-exclude <globs>", 'config family: manage the persisted exclude list (comma list; special value "self")');
 cli.option("--default-keep <pkgs>", 'config family: manage the persisted keep list (comma list; special value "self")');
 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",
+  "wizard"
+]);
+var WIZARD_VIEWS = /* @__PURE__ */ new Set(["stats", "analyze", "info", "map", "search", "why", "treemap"]);
 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 };
@@ -5311,8 +5650,12 @@ function normalizeDepth(value) {
   if (typeof value === "number" && Number.isInteger(value) && value >= 0) return value;
   return "invalid";
 }
-async function main() {
-  const parsed = cli.parse(process.argv, { run: false });
+var updateNoticeShown = false;
+async function runCli(userArgs) {
+  const dd = userArgs.indexOf("--");
+  const routerTokens = dd >= 0 ? userArgs.slice(dd + 1) : null;
+  const headArgs = dd >= 0 ? userArgs.slice(0, dd) : userArgs;
+  const parsed = cli.parse(["node", "nmh", ...headArgs], { run: false });
   const flags = parsed.options;
   const positionals = (parsed.args ?? []).filter((token) => typeof token === "string");
   if (flags.version === true) {
@@ -5320,7 +5663,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,15 +5694,18 @@ 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
   });
-  if (flags.updateCheck === true || config.updateCheck === true) {
+  if (!updateNoticeShown && (flags.updateCheck === true || config.updateCheck === true)) {
+    updateNoticeShown = true;
     const notice = await checkForUpdate().catch(() => null);
     if (notice !== null) note(notice);
   }
@@ -5510,7 +5856,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];
@@ -5555,12 +5906,71 @@ async function main() {
     printVersion(json);
     return 0;
   }
+  if (flags.check !== void 0 && flags.check !== false && subcommand !== "update") {
+    errorLog("--check only works with the update command \u2014 nmh update --check");
+    return 1;
+  }
+  if (flags.info !== void 0 && flags.info !== false && subcommand !== "update") {
+    errorLog("--info only works with the update command \u2014 nmh update --info");
+    return 1;
+  }
   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 (flags.check === true && flags.info === true) {
+      errorLog("--check and --info are two different read-only views \u2014 pick one (nmh update --check | --info)");
+      return 1;
+    }
+    return runUpdate({
+      json,
+      mode: flags.check === true ? "check" : flags.info === true ? "info" : "default",
+      answer: flags.yes === true ? "yes" : flags.no === true ? "no" : "none",
+      force: flags.force === true
+    });
+  }
+  const wizardIntent = subcommand === "wizard" || flags.wizard === true;
+  if (routerTokens !== null && !wizardIntent) {
+    errorLog("the `--` router belongs to the wizard \u2014 nmh wizard -- stats|map|search|why|treemap \u2026");
+    return 1;
+  }
+  let routerView = null;
+  if (routerTokens !== null) {
+    const view = routerTokens[0];
+    if (typeof view !== "string" || !WIZARD_VIEWS.has(view)) {
+      errorLog(`unknown wizard view: ${String(view ?? "(empty)")} \u2014 the router opens a read-only view: stats (analyze, info) | map | search | why | treemap`);
+      return 1;
+    }
+    routerView = routerTokens;
+  }
+  if (wizardIntent) {
+    if (rest.length > 0) {
+      errorLog("wizard takes no positional targets \u2014 scope it with --dir=./repo1,./repo2 (or `nmh wizard -- <view> \u2026`)");
+      return 1;
+    }
+    if (deleted.given) {
+      errorLog("--delete does not belong to the wizard \u2014 the menu asks for the mode itself");
+      return 1;
+    }
+    if (!isTTYOut()) {
+      errorLog("the wizard needs a TTY (it is an arrow-key menu) \u2014 use nmh scan / --dir / the plain commands instead; bare `nmh` in a pipe stays a read-only scan");
+      return 1;
+    }
+    if (routerView !== null) {
+      log(renderFullBanner());
+      const viewCode = await runCli(routerView);
+      if (viewCode === 1) return 1;
+    }
+    return runWizard(cwd, {
+      defaultMode: config.defaultMode,
+      json,
+      settings: { source: configSource, values: config },
+      excludes: excludes.length > 0 ? excludes : void 0,
+      keep: keep.length > 0 ? keep : void 0,
+      targets: dirTargets.length > 0 ? dirTargets : void 0,
+      banner: routerView === null
+    });
   }
   if (subcommand === "config") {
     const ops = /* @__PURE__ */ new Set(["info", "set", "add", "remove", "unset"]);
@@ -5883,6 +6293,9 @@ function normalizeAnimate(argv, configAnimate) {
   if (argv.includes("--animate") || argv.includes("--animate=true")) return "on";
   return configAnimate === false ? "off" : "auto";
 }
+function main() {
+  return runCli(process.argv.slice(2));
+}
 main().then((code) => {
   if (code !== 0) process.exitCode = code;
 }).catch((err) => {

package/package.json

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