node-modules-hunter 1.1.1 → 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
@@ -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
@@ -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. 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.
+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

@@ -248,6 +248,7 @@ function renderVersionDetail(detail) {
 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" },
@@ -257,7 +258,7 @@ var COMMANDS = [
   { 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 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)" }
 ];
@@ -287,6 +288,8 @@ var GROUPS = [
       { 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)" }
     ]
   },
@@ -349,11 +352,14 @@ var GROUPS = [
 ];
 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) => {
@@ -2548,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";
@@ -2652,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;
@@ -2698,41 +2743,86 @@ async function installLatest(version) {
   }
   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;
 }
@@ -2948,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 = [
     "",
@@ -2985,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);
@@ -4606,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";
@@ -4938,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"
   });
@@ -4995,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) {
@@ -5031,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([
@@ -5069,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,
@@ -5093,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,
@@ -5124,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;
     }
@@ -5139,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));
@@ -5182,7 +5277,7 @@ async function deleteFlow2(kind, entries, options) {
       })),
       required: true
     });
-    if (isCancel2(picked)) {
+    if (isCancel3(picked)) {
       outro("cancelled \u2014 nothing deleted");
       return 0;
     }
@@ -5197,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;
   }
@@ -5220,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 ?? {};
@@ -5495,6 +5590,10 @@ 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)");
@@ -5513,8 +5612,10 @@ var KNOWN_SUBCOMMANDS = /* @__PURE__ */ new Set([
   "config",
   "update",
   "version",
-  "help"
+  "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);
 }
@@ -5549,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) {
@@ -5599,7 +5704,8 @@ async function main() {
     // --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);
   }
@@ -5800,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"]);
@@ -6128,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.1",
+  "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",