@iyowei/sweep-node-modules 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iYoWei
+
+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,88 @@
+# sweep-node-modules
+
+工作区级 `node_modules` 清理工具: 一次扫描多个根目录, 跨项目列出各处 `node_modules` 与体积, 确认后批量删除, 回收磁盘空间。
+
+> 分层说明: 单项目清理工具管「进入某个项目, 清它自己的产物」; 本工具管「站在工作区层面, 一次清理很多个项目」。两者分层共存, 见 [ADR 0001](docs/adrs/0001-workspace-level-cleaner.md)。
+
+## 要求
+
+- 运行时二选一: **bun 或 node** 皆可 (双运行时, 装任一即可用)。
+- 取最新一代运行时 API: bun 任意近期版本; node 需原生支持 TypeScript 直跑的版本 (版本快照与实测记录见 [ADR 0006](docs/adrs/0006-dual-runtime-bun-first.md))。
+- 零第三方运行时依赖 (只用运行时内置能力)。
+- 平台: Windows / macOS / Linux 三平台均可运行 (见 [ADR 0007](docs/adrs/0007-platform-portability.md))。
+
+## 安装
+
+**npm** (推荐):
+
+```shell
+npm install -g @iyowei/sweep-node-modules
+```
+
+**从源码**:
+
+```shell
+chmod +x bin/sweep-nm
+
+# 软链进 ~/.local/bin, 启动器会挑选运行时 (Bun 优先, Node 回退)
+ln -sf "$HOME/self/development/sweep-node-modules/bin/sweep-nm" ~/.local/bin/sweep-nm
+```
+
+> 两种方式都支持 Bun / Node 双运行时 (装任一即可用); 从源码安装的 Windows 用户入口为 `bin\sweep-nm.cmd`。
+
+## 使用
+
+```shell
+# 预览: 列出配置中各根目录下所有 node_modules 与体积, 不动手
+sweep-nm
+
+# 复核无误后执行删除
+sweep-nm --yes
+
+# 临时追加排除(可重复)
+sweep-nm --exclude my-kits --exclude url-tool
+
+# 初始化向导: 交互式生成配置文件
+sweep-nm init
+```
+
+## 配置
+
+配置文件位置 (平台自适应): Windows 为 `%APPDATA%\sweep-node-modules\config.json`, 其余为 `~/.config/sweep-node-modules/config.json`; 可用 `--config` 或环境变量 `SWEEP_NM_CONFIG` 覆盖。
+
+```json
+{
+  "roots": [
+    "/Users/iyowei/workspace/development",
+    "/Users/iyowei/self/development"
+  ],
+  "exclude": ["my-kits"]
+}
+```
+
+- `roots`: 扫描根目录, 任意多个; 重复或嵌套的根按真实路径去重。
+- `exclude`: 排除名单; 从根到 `node_modules` 的任意一级目录名命中即跳过 (多排除 = 少删, 安全方向)。
+- 首次运行且无配置: 交互终端下自动进入初始化向导; 非交互环境 (脚本等) 以当前工作目录为根并提示, 不询问; 随时可用 `sweep-nm init` 重进向导。
+
+> 字段定义以[设计文档](docs/designs/config-and-initialization.md)为准。
+
+## 开发
+
+```shell
+bun install        # 安装 devDependencies, 并自动装好 git 钩子 (lefthook)
+
+bun run typecheck  # tsc --noEmit
+bun run lint       # oxlint
+bun run format     # prettier --write
+bun test           # bun test (243 条: 契约 / 鲁棒 / 压测 / 双载体 e2e / 伪终端冒烟)
+bun run bench      # 基准四组 (扫描 / 体积 / 真实工作区 / 压测)
+bun run conformance -- --target "bun src/cli.ts"  # 转写一致性验收 (40 条金样本, 见 docs/protocol/)
+```
+
+运行时双跑验证: `bun src/cli.ts` 与 `node src/cli.ts` 均可直接运行。
+
+提交与推送由 lefthook 把关: pre-commit 增量 (prettier 重暂存 + oxlint + 全量类型检查), pre-push 全量只读 (typecheck / test / oxlint / prettier `--check`)。
+
+## 文档
+
+- [工程技术文档总索引](docs/README.md)

package/bin/sweep-nm.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * npm 安装场景的启动器: 挑选运行时 (Bun 优先, 其次 Node) 后启动真实入口。
+ * 与 bin/sweep-nm (sh) / bin/sweep-nm.cmd (cmd) 同逻辑, 三者的差异只在宿主:
+ * 本文件同时承担 Unix 与 Windows 的 npm shim 目标 (shebang 必须是 node, 否则
+ * npm 的 cmd-shim 会按 shebang 解释器生成 Windows 上不存在的调用)。
+ * 退出码原样透传; 两个运行时都缺席时给出可操作提示并非零退出。
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** 探测命令是否可执行 (以 --version 的实际退出码为准, 不依赖 shell 内建) */
+const available = (command) =>
+  spawnSync(command, ['--version'], { stdio: 'ignore' }).status === 0;
+
+/** 挑选运行时: Bun 优先, 其次 Node; 皆无则 null (由调用处报错退出) */
+const pickRuntime = () => {
+  if (available('bun')) return 'bun';
+  if (available('node')) return 'node';
+  return null;
+};
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+// npm 包内是编译产物 (node 拒绝对 node_modules 内的 TS 做类型剥离, 见 package.json 的 build 脚本);
+// 仓库开发态无 dist, 回退直跑源码 (bun / node 皆可)
+const built = join(root, 'dist', 'cli.js');
+const entry = existsSync(built) ? built : join(root, 'src', 'cli.ts');
+const runtime = pickRuntime();
+
+if (runtime === null) {
+  process.stderr.write('sweep-nm: 未找到 bun 或 node, 请至少安装其一\n');
+  process.exit(1);
+}
+
+const { status } = spawnSync(runtime, [entry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+process.exit(status ?? 1);