remnem 0.0.0 → 0.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leon Si
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# 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.
+
+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.
+
+```
+$ 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
+```
+
+## Delete vs. Trash
+
+By default `remnem` **permanently deletes** each `node_modules` in parallel —
+space is reclaimed immediately.
+
+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.
+
+## Install
+
+```sh
+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).
+
+Then from any repo root:
+
+```sh
+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
+```
+
+## 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.
+
+## 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
+```
+
+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.
+
+## Workspace resolution
+
+`remnem` mirrors how bun and pnpm resolve workspace packages:
+
+| Source | Field | Example |
+| --- | --- | --- |
+| bun / npm / yarn | `package.json` → `workspaces` | `["packages/*", "!packages/excluded"]` |
+| bun / npm / yarn | `package.json` → `workspaces.packages` | `{ "packages": ["libs/*"] }` |
+| pnpm | `pnpm-workspace.yaml` → `packages` | `- 'packages/*'`<br>`- '!**/test/**'` |
+
+Glob semantics match [picomatch](https://github.com/micromatch/picomatch) (the
+matcher bun/npm/yarn use):
+
+- `*` matches exactly one path segment (`packages/*` → `packages/a`, not `packages/a/b`)
+- `**` matches any number of segments, and a trailing `/**` is **optional**
+  (`components/**` matches `components` itself and everything beneath it)
+- `!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.
+
+## Development
+
+```sh
+cargo test                 # Rust unit tests (workspace resolution + glob semantics)
+bun run build:debug        # debug build
+bun run build              # release build (LTO)
+```
+
+## License
+
+MIT

package/bin/remnem.js

@@ -0,0 +1,213 @@
+#!/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;
+    }
+  }
+  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;
+  try {
+    bytesRead = fs.readSync(0, buf, 0, buf.length, null);
+  } catch {
+    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;
+  }
+
+  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);
+  }
+
+  // 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;
+  }
+
+  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);
+  }
+}
+
+function replacer(_key, value) {
+  return typeof value === "bigint" ? Number(value) : value;
+}
+
+main();

package/package.json

@@ -1 +1,82 @@
-{"name":"remnem","version":"0.0.0"}
+{
+  "name": "remnem",
+  "version": "0.1.7",
+  "description": "Find and delete every nested node_modules in a project as fast as possible (napi-rs / Rust)",
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "author": "Leon Si",
+  "homepage": "https://github.com/leonsilicon/remnem#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonsilicon/remnem.git"
+  },
+  "bugs": {
+    "url": "https://github.com/leonsilicon/remnem/issues"
+  },
+  "keywords": [
+    "node_modules",
+    "monorepo",
+    "workspace",
+    "clean",
+    "cleaner",
+    "delete",
+    "napi-rs",
+    "rust",
+    "bun",
+    "pnpm"
+  ],
+  "bin": {
+    "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"
+  },
+  "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"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0"
+  }
+}