remnem 0.1.7 → 0.1.9

package/README.md

@@ -1,33 +1,52 @@
 # remnem
 
-**r**e**m**ove **n**ode_**m**odules — find every nested `node_modules` in a project (root + all workspaces + any nested ones) and delete them all, as fast as possible.
+**r**e**m**ove **n**ode_**m**odules — find every nested `node_modules` in a project (root + all workspaces + any nested ones) and delete them all, **instantly**.
 
-Written in Rust ([napi-rs](https://napi.rs)) with a parallel directory walker and parallel deletion. Uses the **same workspace resolution as [bun](https://bun.sh/docs/install/workspaces) and [pnpm](https://pnpm.io/pnpm-workspace_yaml)** to describe the workspace layout.
+A single self-contained CLI written in **Rust**: a lean, parallel, directory-only walker finds every `node_modules`, then each one is disposed of by an **O(1) rename** rather than a slow recursive unlink — so clearing a 1000-package monorepo takes a couple hundred milliseconds instead of tens of seconds.
 
 ```
 $ remnem
 root: /Users/you/dev/my-monorepo
-      package.json workspace (12 packages)
-found 13 node_modules totalling 2.4 GB:
-    318 MB  node_modules
-    1.1 GB  apps/web/node_modules
-    ...
-permanently delete these 13 directories? [y/N] y
-
-deleted: 13/13 node_modules (2.4 GB) in 412ms
+found 1947 node_modules:
+  node_modules
+  apps/web/node_modules
+  ...
+permanently delete these 1947 directories? [y/N] y
+
+deleted: 1947/1947 node_modules in 130ms
+(space is being reclaimed in the background)
 ```
 
-## Delete vs. Trash
+## How it's instant
+
+Physically deleting `node_modules` means unlinking hundreds of thousands of
+files — that is I/O-bound and unavoidably slow (tens of seconds on a big
+monorepo). remnem sidesteps that on the critical path:
 
-By default `remnem` **permanently deletes** each `node_modules` in parallel —
-space is reclaimed immediately.
+1. **Find** — a parallel, directory-only walk. It reads directory entries via
+   `readdir`'s `d_type` (no per-file `stat`), never looks at regular files, and
+   never descends *into* a `node_modules` (the whole subtree is going anyway).
+   So the walk is proportional to your *source* tree, not the installed
+   dependency tree.
+2. **Rename aside** — each `node_modules` is `rename`d to a hidden sibling in the
+   same directory. On one filesystem that is an O(1) metadata operation no matter
+   how large the tree is. The instant it returns, `node_modules` is gone from its
+   location — **a clean reinstall can start immediately**.
+3. **Reclaim in the background** — a detached background process `rm -rf`s the
+   renamed directories, so the disk-freeing I/O never blocks you. Space comes
+   back within a few seconds, hands-free.
 
-Pass **`-t` / `--trash`** to move them to the OS trash instead (Finder Trash on
-macOS, the freedesktop trash on Linux, the Recycle Bin on Windows). On the same
-volume that is a directory *rename* — O(1), effectively instant no matter how
-many files the tree holds — and recoverable from the trash. The disk space is
-reclaimed when you empty it. A `node_modules` on a *different* volume (rare)
-can't be renamed instantly, so those fall back to a direct delete.
+Pass **`--sync`** if you'd rather block until the space is actually reclaimed
+(e.g. a script that measures free disk right after).
+
+## Delete vs. Trash
+
+By default `remnem` **permanently deletes** (via the instant rename-then-reap
+above). Pass **`-t` / `--trash`** to move each `node_modules` to the OS trash
+instead (Finder Trash on macOS, the freedesktop trash on Linux, the Recycle Bin
+on Windows) — recoverable from the trash, with the space reclaimed when you empty
+it. A `node_modules` on a *different* volume (rare) can't be renamed instantly, so
+those fall back to a direct delete.
 
 ## Install
 
@@ -36,36 +55,29 @@ npm install -g remnem
 # or: bun install -g remnem
 ```
 
-The right prebuilt native binary is pulled in automatically for your platform
-via `optionalDependencies`. Supported: **macOS** (arm64, x64), **Linux** (arm64
-& x64, glibc & musl), **Windows** (arm64, x64).
+The right prebuilt binary is pulled in automatically for your platform via
+`optionalDependencies` — the main `remnem` package is a tiny launcher that execs
+it. Supported: **macOS** (arm64, x64), **Linux** (arm64 & x64, glibc & musl),
+**Windows** (arm64, x64).
 
 Then from any repo root:
 
 ```sh
-remnem
+remnem            # or: npx remnem  /  bunx remnem
 ```
 
 ### From source
 
 ```sh
-bun install
-bun run build      # builds the native addon for your host → remnem.<platform>.node
-bun link           # makes `remnem` available on your PATH
+cargo build --release       # produces target/release/remnem
+./target/release/remnem --help
 ```
 
 ## What it clears
 
 **Every `node_modules` directory** under the given root — the root's own, every
 workspace package's, and any stray nested ones — leaving all your source and
-`package.json` files untouched. The walker never descends *into* a
-`node_modules` (the whole subtree is going to be removed anyway), so it stays
-fast even on trees with hundreds of thousands of files.
-
-Workspace resolution (reading `package.json#workspaces` for bun/npm/yarn, or
-`pnpm-workspace.yaml#packages` for pnpm) is used to **report** the workspace
-layout; clearing always targets every nested `node_modules`, not only workspace
-packages.
+`package.json` files untouched.
 
 ## Usage
 
@@ -76,22 +88,27 @@ Arguments:
   path                 Project root to clean (default: current directory)
 
 Options:
-  -t, --trash          Move to the Trash instead of deleting (instant, recoverable)
+  -t, --trash          Move to the Trash instead of deleting (recoverable)
   -l, --list           List what would be cleared; touch nothing
-      --no-measure     Skip sizing each node_modules (faster; sizes show as 0)
+  -m, --measure        Size each node_modules (slow: walks every dependency tree)
+  -w, --workspace      Also resolve & report the bun/pnpm workspace layout (slow)
+      --sync           Wait for the disk space to actually free before returning
       --json           Print the raw result as JSON
   -y, --yes            Skip the confirmation prompt
   -h, --help           Show this help
 ```
 
-By default `remnem` permanently deletes each `node_modules`, after printing what it
-found and asking for confirmation (skipped with `-y`, or when stdout isn't a TTY,
-e.g. in CI). Use `-t` to move them to the Trash instead (space reclaimed when you
-empty it), or `-l` to list what would be cleared without touching anything.
+By default `remnem` deletes each `node_modules` after printing what it found and
+asking for confirmation (skipped with `-y`, or when stdin isn't a TTY, e.g. in
+CI). Use `-l` to list without touching anything, `-t` to move to the Trash, or
+`--sync` to wait for the space to be reclaimed.
+
+Sizing (`-m`) and workspace-layout resolution (`-w`) each require an extra tree
+walk, so they are **off by default** — the fast path does neither.
 
-## Workspace resolution
+## Workspace resolution (`-w`)
 
-`remnem` mirrors how bun and pnpm resolve workspace packages:
+With `-w`, `remnem` reports the workspace layout the way bun and pnpm resolve it:
 
 | Source | Field | Example |
 | --- | --- | --- |
@@ -108,34 +125,15 @@ matcher bun/npm/yarn use):
 - `!pattern` excludes previously-matched directories (`!**/test/**` drops a
   directory named `test` and its contents)
 
-A directory only counts as a workspace package when it contains its own
-`package.json`.
-
-## API
-
-The napi-rs core is also usable directly from JavaScript:
-
-```js
-const { clean, resolveWorkspace } = require("remnem");
-
-// Clear every nested node_modules under a root.
-//   trash: false (default) → permanent parallel delete; true → move to Trash.
-const result = clean({ root: "/path/to/repo", dryRun: false, measure: true, trash: false });
-// → { root, workspaceKind, workspacePackages, cleaned: [{ path, bytes, deleted, trashed, error }], totalBytes, count, failed }
-
-// Just inspect how bun/pnpm would see the workspace (no deletion).
-const ws = resolveWorkspace("/path/to/repo");
-// → { workspaceKind: "pnpm" | "package.json" | "none", workspacePackages: [...] }
-```
-
-See `index.d.ts` for the full typed surface.
+This is purely informational: clearing always targets every nested
+`node_modules`, not only workspace packages.
 
 ## Development
 
 ```sh
 cargo test                 # Rust unit tests (workspace resolution + glob semantics)
-bun run build:debug        # debug build
-bun run build              # release build (LTO)
+cargo build --release      # release build (LTO)
+node __test__/smoke.mjs ./target/release/remnem   # end-to-end smoke test
 ```
 
 ## License

package/bin/remnem.js

@@ -1,213 +1,96 @@
 #!/usr/bin/env node
 "use strict";
 
-const { clean } = require("../index.js");
-
-const HELP = `remnem — delete every nested node_modules, fast
-
-Usage:
-  remnem [path] [options]
-
-Arguments:
-  path                 Project root to clean (default: current directory)
-
-Options:
-  -t, --trash          Move to the Trash instead of deleting (instant, recoverable)
-  -l, --list           List what would be cleared; touch nothing
-      --no-measure     Skip sizing each node_modules (faster; sizes show as 0)
-      --json           Print the raw result as JSON
-  -y, --yes            Skip the confirmation prompt
-  -h, --help           Show this help
-
-Finds every node_modules directory under <path> (root + all workspace packages
-+ any nested ones), using the same workspace resolution as bun / pnpm to report
-the layout, then permanently deletes them in parallel.
-
-With -t, moves them to the Trash instead — on the same volume that is a rename
-(instant no matter how large) and recoverable in Finder; the space is reclaimed
-when you empty the Trash.
-`;
-
-function parseArgs(argv) {
-  const opts = {
-    root: undefined,
-    list: false,
-    measure: true,
-    trash: false,
-    json: false,
-    yes: false,
-    help: false,
-  };
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    switch (arg) {
-      case "-h":
-      case "--help":
-        opts.help = true;
-        break;
-      case "-l":
-      case "--list":
-        opts.list = true;
-        break;
-      case "-t":
-      case "--trash":
-        opts.trash = true;
-        break;
-      case "--no-measure":
-        opts.measure = false;
-        break;
-      case "--measure":
-        opts.measure = true;
-        break;
-      case "--json":
-        opts.json = true;
-        break;
-      case "-y":
-      case "--yes":
-        opts.yes = true;
-        break;
-      default:
-        if (arg.startsWith("-")) {
-          process.stderr.write(`remnem: unknown option ${arg}\n\n${HELP}`);
-          process.exit(2);
-        }
-        if (opts.root !== undefined) {
-          process.stderr.write(`remnem: unexpected extra argument ${arg}\n`);
-          process.exit(2);
-        }
-        opts.root = arg;
+// Thin launcher. remnem ships as a compiled Rust binary, one per platform, in an
+// optional dependency package (@leonsilicon/remnem-<platform>). This shim
+// resolves the binary for the current platform and hands off to it with the same
+// argv, stdio, and exit code — so `remnem` behaves exactly like the native
+// executable while still installing through npm's platform-package mechanism.
+
+const { spawnSync } = require("child_process");
+const { existsSync } = require("fs");
+const { join } = require("path");
+
+// Map Node's platform/arch to the npm sub-package that carries the binary. Keep
+// this in sync with the `optionalDependencies` in package.json and the `npm/*`
+// package directories.
+const PACKAGES = {
+  "darwin-arm64": "@leonsilicon/remnem-darwin-arm64",
+  "darwin-x64": "@leonsilicon/remnem-darwin-x64",
+  "linux-arm64-gnu": "@leonsilicon/remnem-linux-arm64-gnu",
+  "linux-arm64-musl": "@leonsilicon/remnem-linux-arm64-musl",
+  "linux-x64-gnu": "@leonsilicon/remnem-linux-x64-gnu",
+  "linux-x64-musl": "@leonsilicon/remnem-linux-x64-musl",
+  "win32-arm64-msvc": "@leonsilicon/remnem-win32-arm64-msvc",
+  "win32-x64-msvc": "@leonsilicon/remnem-win32-x64-msvc",
+};
+
+// On Linux, tell glibc from musl so we pick the matching binary package.
+function isMusl() {
+  if (process.platform !== "linux") return false;
+  try {
+    // `process.report` exposes the runtime's libc in its header on modern Node.
+    if (process.report && typeof process.report.getReport === "function") {
+      const report = process.report.getReport();
+      const header = report.header || {};
+      if (typeof header.glibcVersionRuntime === "string") return false;
     }
-  }
-  return opts;
-}
-
-function formatBytes(n) {
-  const bytes = typeof n === "bigint" ? Number(n) : n;
-  if (!bytes) return "0 B";
-  const units = ["B", "KB", "MB", "GB", "TB"];
-  const exp = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
-  const value = bytes / 1024 ** exp;
-  return `${value.toFixed(value >= 10 || exp === 0 ? 0 : 1)} ${units[exp]}`;
-}
-
-function relativizePath(root, p) {
-  if (p === root) return ".";
-  if (p.startsWith(root + "/")) return p.slice(root.length + 1);
-  return p;
-}
-
-// Confirmation prompt (synchronous) so a bare `remnem` in a real repo can't nuke
-// node_modules by a stray keystroke. Skipped with -y, with --list, or when not
-// attached to a TTY (CI / piped).
-function confirm(question) {
-  if (!process.stdin.isTTY) return true;
-  const fs = require("fs");
-  process.stdout.write(question);
-  const buf = Buffer.alloc(64);
-  let bytesRead = 0;
+  } catch {}
   try {
-    bytesRead = fs.readSync(0, buf, 0, buf.length, null);
+    // Fallback: the ldd on musl systems mentions musl.
+    return require("fs").readFileSync("/usr/bin/ldd", "utf8").includes("musl");
   } catch {
+    // Default to gnu; if wrong the resolution below fails loudly with guidance.
     return false;
   }
-  const answer = buf.toString("utf8", 0, bytesRead).trim().toLowerCase();
-  return answer === "y" || answer === "yes";
 }
 
-function main() {
-  const opts = parseArgs(process.argv.slice(2));
-  if (opts.help) {
-    process.stdout.write(HELP);
-    return;
-  }
-
-  // Phase 1: dry-run scan so we can show the user exactly what will go, then
-  // (unless -y / non-TTY) confirm before the real deletion.
-  const scan = clean({ root: opts.root, dryRun: true, measure: opts.measure });
-
-  const kindLabel =
-    scan.workspaceKind === "none"
-      ? "no workspace config"
-      : `${scan.workspaceKind} workspace (${scan.workspacePackages.length} package${
-          scan.workspacePackages.length === 1 ? "" : "s"
-        })`;
-
-  if (opts.json && opts.list) {
-    process.stdout.write(JSON.stringify(scan, replacer, 2) + "\n");
-    return;
+function platformKey() {
+  const { platform, arch } = process;
+  if (platform === "linux") {
+    return `linux-${arch}-${isMusl() ? "musl" : "gnu"}`;
   }
-
-  if (scan.count === 0) {
-    process.stdout.write(`remnem: no node_modules found under ${scan.root} (${kindLabel})\n`);
-    return;
-  }
-
-  process.stdout.write(`root: ${scan.root}\n`);
-  process.stdout.write(`      ${kindLabel}\n`);
-  process.stdout.write(
-    `found ${scan.count} node_modules${
-      opts.measure ? ` totalling ${formatBytes(scan.totalBytes)}` : ""
-    }:\n`,
-  );
-  for (const dir of scan.cleaned) {
-    const size = opts.measure ? `  ${formatBytes(dir.bytes).padStart(8)}` : "";
-    process.stdout.write(`${size}  ${relativizePath(scan.root, dir.path)}\n`);
-  }
-
-  if (opts.list) {
-    process.stdout.write(`\n(list only — nothing ${opts.trash ? "trashed" : "deleted"})\n`);
-    return;
-  }
-
-  const verb = opts.trash ? "move to Trash" : "permanently delete";
-  if (!opts.yes && !confirm(`\n${verb} these ${scan.count} directories? [y/N] `)) {
-    process.stdout.write("aborted.\n");
-    process.exit(1);
+  if (platform === "win32") {
+    return `win32-${arch}-msvc`;
   }
+  return `${platform}-${arch}`;
+}
 
-  // Phase 2: real disposal. Re-measure is unnecessary — reuse sizes we have.
-  const start = process.hrtime.bigint();
-  const result = clean({ root: opts.root, dryRun: false, measure: false, trash: opts.trash });
-  const elapsedMs = Number(process.hrtime.bigint() - start) / 1e6;
-
-  if (opts.json) {
-    process.stdout.write(JSON.stringify(result, replacer, 2) + "\n");
-    return;
+function resolveBinary() {
+  const key = platformKey();
+  const pkg = PACKAGES[key];
+  if (!pkg) {
+    return { error: `remnem: unsupported platform ${process.platform}-${process.arch}` };
   }
+  const exe = process.platform === "win32" ? "remnem.exe" : "remnem";
 
-  const done = result.count - result.failed;
-  const trashedCount = result.cleaned.filter((d) => d.trashed).length;
-  // Report how the space went: "trashed" (recoverable, empty Trash to reclaim)
-  // vs "deleted" (gone). A trash run that fell back to hard-remove for some
-  // items is noted so the count still adds up.
-  let action;
-  if (!opts.trash) {
-    action = "deleted";
-  } else if (trashedCount === done) {
-    action = "moved to Trash";
-  } else {
-    action = `moved to Trash (${done - trashedCount} hard-deleted)`;
-  }
-  process.stdout.write(
-    `\n${action}: ${done}/${result.count} node_modules${
-      opts.measure ? ` (${formatBytes(scan.totalBytes)})` : ""
-    } in ${elapsedMs.toFixed(0)}ms\n`,
-  );
-  if (opts.trash && trashedCount > 0) {
-    process.stdout.write(`empty the Trash to reclaim the space (or re-run without -t to delete).\n`);
-  }
-  if (result.failed > 0) {
-    for (const dir of result.cleaned) {
-      if (dir.error) {
-        process.stderr.write(`  failed: ${relativizePath(result.root, dir.path)} — ${dir.error}\n`);
-      }
-    }
-    process.exit(1);
-  }
+  // Prefer resolving through the package's own manifest so we find it wherever
+  // the package manager placed it (hoisted, nested, pnpm store, etc.).
+  try {
+    const manifest = require.resolve(`${pkg}/package.json`);
+    const binPath = join(manifest, "..", exe);
+    if (existsSync(binPath)) return { binPath };
+  } catch {}
+
+  return {
+    error:
+      `remnem: could not find the ${pkg} package for your platform.\n` +
+      `Install it with your package manager, or reinstall remnem so npm can pull the\n` +
+      `matching optional dependency (${pkg}).`,
+  };
 }
 
-function replacer(_key, value) {
-  return typeof value === "bigint" ? Number(value) : value;
+const { binPath, error } = resolveBinary();
+if (error) {
+  process.stderr.write(error + "\n");
+  process.exit(1);
 }
 
-main();
+// Hand off: inherit stdio so the interactive confirmation prompt and all output
+// pass straight through, and propagate the binary's exit code.
+const result = spawnSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+if (result.error) {
+  process.stderr.write(`remnem: failed to run ${binPath}: ${result.error.message}\n`);
+  process.exit(1);
+}
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -1,10 +1,8 @@
 {
   "name": "remnem",
-  "version": "0.1.7",
-  "description": "Find and delete every nested node_modules in a project as fast as possible (napi-rs / Rust)",
+  "version": "0.1.9",
+  "description": "Find and delete every nested node_modules in a project as fast as possible (Rust binary)",
   "type": "commonjs",
-  "main": "index.js",
-  "types": "index.d.ts",
   "license": "MIT",
   "author": "Leon Si",
   "homepage": "https://github.com/leonsilicon/remnem#readme",
@@ -22,7 +20,6 @@
     "clean",
     "cleaner",
     "delete",
-    "napi-rs",
     "rust",
     "bun",
     "pnpm"
@@ -31,52 +28,30 @@
     "remnem": "bin/remnem.js"
   },
   "files": [
-    "index.js",
-    "index.d.ts",
     "bin/remnem.js",
     "README.md",
     "LICENSE"
   ],
-  "napi": {
-    "binaryName": "remnem",
-    "targets": [
-      "x86_64-apple-darwin",
-      "aarch64-apple-darwin",
-      "x86_64-unknown-linux-gnu",
-      "aarch64-unknown-linux-gnu",
-      "x86_64-unknown-linux-musl",
-      "aarch64-unknown-linux-musl",
-      "x86_64-pc-windows-msvc",
-      "aarch64-pc-windows-msvc"
-    ],
-    "packageName": "@leonsilicon/remnem"
-  },
   "engines": {
     "node": ">= 18"
   },
   "optionalDependencies": {
-    "@leonsilicon/remnem-darwin-x64": "0.1.7",
-    "@leonsilicon/remnem-darwin-arm64": "0.1.7",
-    "@leonsilicon/remnem-linux-x64-gnu": "0.1.7",
-    "@leonsilicon/remnem-linux-arm64-gnu": "0.1.7",
-    "@leonsilicon/remnem-linux-x64-musl": "0.1.7",
-    "@leonsilicon/remnem-linux-arm64-musl": "0.1.7",
-    "@leonsilicon/remnem-win32-x64-msvc": "0.1.7",
-    "@leonsilicon/remnem-win32-arm64-msvc": "0.1.7"
+    "@leonsilicon/remnem-darwin-x64": "0.1.9",
+    "@leonsilicon/remnem-darwin-arm64": "0.1.9",
+    "@leonsilicon/remnem-linux-x64-gnu": "0.1.9",
+    "@leonsilicon/remnem-linux-arm64-gnu": "0.1.9",
+    "@leonsilicon/remnem-linux-x64-musl": "0.1.9",
+    "@leonsilicon/remnem-linux-arm64-musl": "0.1.9",
+    "@leonsilicon/remnem-win32-x64-msvc": "0.1.9",
+    "@leonsilicon/remnem-win32-arm64-msvc": "0.1.9"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "scripts": {
-    "build": "napi build --platform --release",
-    "build:debug": "napi build --platform",
-    "artifacts": "napi artifacts",
-    "prepublishOnly": "napi prepublish -t npm",
-    "test": "cargo test",
-    "version": "napi version"
+    "build": "cargo build --release",
+    "test": "cargo test"
   },
-  "devDependencies": {
-    "@napi-rs/cli": "^3.0.0"
-  }
-}
+  "devDependencies": {}
+}