@iyowei/sweep-node-modules 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +75 -48
- package/README.zh-CN.md +156 -0
- package/bin/sweep-nm.mjs +167 -20
- package/dist/cli.js +575 -224
- package/dist/manifest.json +7 -0
- package/package.json +34 -9
package/README.md
CHANGED
|
@@ -1,65 +1,69 @@
|
|
|
1
1
|
# sweep-node-modules
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**English** | [中文](README.zh-CN.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
A workspace-level cleaner for `node_modules`: scan several root directories in one pass, list every `node_modules` directory across your projects along with its size, and bulk-delete them after you confirm, reclaiming disk space.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
> Where this sits: single-project cleaners handle "go into one project and clean its own artifacts"; this tool handles "stand at the workspace level and clean many projects in one pass". The two layers coexist; see [ADR 0001](docs/adrs/0001-workspace-level-cleaner.md).
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
- 取最新一代运行时 API: bun 任意近期版本; node 需原生支持 TypeScript 直跑的版本 (源码方式与包方式取同一版本下限; 版本快照与实测记录见 [ADR 0006](docs/adrs/0006-dual-runtime-bun-first.md))。
|
|
11
|
-
- 零第三方运行时依赖 (只用运行时内置能力)。
|
|
12
|
-
- 平台: Windows / macOS / Linux 三平台均可运行 (见 [ADR 0007](docs/adrs/0007-platform-portability.md))。
|
|
9
|
+
## Requirements
|
|
13
10
|
|
|
14
|
-
|
|
11
|
+
- **Dual runtime** for the actual work: bun when available, node otherwise (identical behavior; bun starts faster).
|
|
12
|
+
- Modern runtime APIs only: any recent bun; for node, a version that runs TypeScript natively (the same version floor applies to the source install and the package install; version snapshot and test records in [ADR 0006](docs/adrs/0006-dual-runtime-bun-first.md)).
|
|
13
|
+
- Zero third-party runtime dependencies (built-in runtime capabilities only).
|
|
14
|
+
- Runs on Windows, macOS, and Linux (see [ADR 0007](docs/adrs/0007-platform-portability.md)).
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
## Installation
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
Three options; pick by the runtime your machine already has. **The `Requires` line under each option is a hard requirement:**
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
> **Only bun on the machine, no node?** Use option 1 or 3. Global installs (option 2) require node, whether you go through npm or bun.
|
|
21
|
+
|
|
22
|
+
Options 1 and 2 both pull the package from a registry. If your machine is configured with a mirror that has not synced the version you want yet, append `--registry=https://registry.npmjs.org` to the command to hit the official registry directly.
|
|
23
|
+
|
|
24
|
+
### 1. No install (for a quick trial)
|
|
21
25
|
|
|
22
26
|
```shell
|
|
23
|
-
#
|
|
27
|
+
# with bun
|
|
24
28
|
bunx @iyowei/sweep-node-modules
|
|
25
29
|
|
|
26
|
-
#
|
|
30
|
+
# with node (npx ships with npm, which itself requires node)
|
|
27
31
|
npx @iyowei/sweep-node-modules
|
|
28
32
|
```
|
|
29
33
|
|
|
30
|
-
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
34
|
+
- **Requires**: bun or node, matching the command you pick
|
|
35
|
+
- Zero install; the package is resolved once per run
|
|
36
|
+
- Note: `bunx` and `npx` are not interchangeable; each is tied to one runtime: a bun-only machine has no `npx`, and a node-only machine has no `bunx`
|
|
33
37
|
|
|
34
|
-
###
|
|
38
|
+
### 2. Global install via a package manager (recommended for regular use)
|
|
35
39
|
|
|
36
40
|
```shell
|
|
37
41
|
npm install -g @iyowei/sweep-node-modules
|
|
38
42
|
bun install -g @iyowei/sweep-node-modules
|
|
39
43
|
```
|
|
40
44
|
|
|
41
|
-
-
|
|
42
|
-
-
|
|
45
|
+
- **Requires**: **node**, for both commands. npm itself runs on node, and `bun install -g` only creates a symlink to the entry file; at execution time the OS kernel reads that file's shebang (node) to pick the interpreter, and the application layer never gets a say
|
|
46
|
+
- Install once, then run `sweep-nm` directly; when bun is present, the actual work still prefers bun
|
|
43
47
|
|
|
44
|
-
###
|
|
48
|
+
### 3. From source (for development, or machines without node)
|
|
45
49
|
|
|
46
50
|
**macOS / Linux**:
|
|
47
51
|
|
|
48
52
|
```shell
|
|
49
|
-
#
|
|
50
|
-
cd "
|
|
53
|
+
# clone, then cd into the repo root (adjust the path to your clone location)
|
|
54
|
+
cd "<your clone>/sweep-node-modules"
|
|
51
55
|
|
|
52
56
|
chmod +x bin/sweep-nm
|
|
53
57
|
|
|
54
|
-
#
|
|
58
|
+
# symlink it into ~/.local/bin (usually already on PATH); the launcher picks the runtime
|
|
55
59
|
ln -sf "$PWD/bin/sweep-nm" ~/.local/bin/sweep-nm
|
|
56
60
|
```
|
|
57
61
|
|
|
58
62
|
**Windows** (PowerShell):
|
|
59
63
|
|
|
60
64
|
```powershell
|
|
61
|
-
#
|
|
62
|
-
#
|
|
65
|
+
# add the repo's bin directory to your user PATH; one-time, effective after reopening the terminal
|
|
66
|
+
# adjust the path to your actual clone location (the launcher locates src relative to itself, so the script cannot be copied out on its own)
|
|
63
67
|
$bin = "$env:USERPROFILE\tools\sweep-node-modules\bin"
|
|
64
68
|
[Environment]::SetEnvironmentVariable(
|
|
65
69
|
'Path',
|
|
@@ -68,38 +72,41 @@ $bin = "$env:USERPROFILE\tools\sweep-node-modules\bin"
|
|
|
68
72
|
)
|
|
69
73
|
```
|
|
70
74
|
|
|
71
|
-
>
|
|
75
|
+
> Or skip the command line: add the `bin` directory to your user `Path` under System Properties → Environment Variables.
|
|
72
76
|
|
|
73
|
-
-
|
|
74
|
-
-
|
|
77
|
+
- **Requires**: bun or node, either works (the launcher is a shell / cmd script run by the OS; it does not depend on node)
|
|
78
|
+
- The most direct entry point; afterwards just run `sweep-nm` (on Windows via `bin\sweep-nm.cmd`)
|
|
75
79
|
|
|
76
|
-
##
|
|
80
|
+
## Usage
|
|
77
81
|
|
|
78
82
|
```shell
|
|
79
|
-
#
|
|
83
|
+
# preview: list every node_modules under the configured roots with its size; nothing is touched
|
|
80
84
|
sweep-nm
|
|
81
85
|
|
|
82
|
-
#
|
|
86
|
+
# once the list checks out, delete for real
|
|
83
87
|
sweep-nm --yes
|
|
84
88
|
|
|
85
|
-
#
|
|
89
|
+
# also delete "suspected install trees" (package manager / version manager / editor extension trees; skipped by default)
|
|
90
|
+
sweep-nm --yes --force
|
|
91
|
+
|
|
92
|
+
# add exclusions on the fly (repeatable)
|
|
86
93
|
sweep-nm --exclude my-kits --exclude url-tool
|
|
87
94
|
|
|
88
|
-
#
|
|
95
|
+
# clean only directories matched by the include list (repeatable, merged with config)
|
|
89
96
|
sweep-nm --include my-kits
|
|
90
97
|
|
|
91
|
-
#
|
|
98
|
+
# show the config file actually in effect (source / path / existence)
|
|
92
99
|
sweep-nm config
|
|
93
100
|
|
|
94
|
-
#
|
|
101
|
+
# init wizard: generate a config file interactively
|
|
95
102
|
sweep-nm init
|
|
96
103
|
```
|
|
97
104
|
|
|
98
|
-
|
|
105
|
+
The end of the header line reports the runtime actually in use for this run (e.g. `bun 1.4.2`); it appears on interactive terminals only, keeping non-TTY output noise-free.
|
|
99
106
|
|
|
100
|
-
##
|
|
107
|
+
## Configuration
|
|
101
108
|
|
|
102
|
-
|
|
109
|
+
The config file lives at a platform-appropriate path: `%APPDATA%\sweep-node-modules\config.json` on Windows, `~/.config/sweep-node-modules/config.json` everywhere else. Override it with `--config` or the `SWEEP_NM_CONFIG` environment variable; `sweep-nm config` reports the path and file status actually in effect for the current run. **The write side requires real paths**: if the config path or any of its ancestors involves a symlink (system links such as `/tmp` and `/var` included), `sweep-nm init` refuses to write before touching disk and points at the link; follow the prompt to rewrite the path in real form (e.g. `/private/tmp/x`) and it goes through.
|
|
103
110
|
|
|
104
111
|
```json
|
|
105
112
|
{
|
|
@@ -112,18 +119,38 @@ sweep-nm init
|
|
|
112
119
|
}
|
|
113
120
|
```
|
|
114
121
|
|
|
115
|
-
- `roots`:
|
|
116
|
-
- `exclude`:
|
|
117
|
-
-
|
|
118
|
-
-
|
|
119
|
-
-
|
|
122
|
+
- `roots`: the scan roots, any number of them; duplicate or nested roots are deduplicated by real path. **The delete side requires real paths**: no symlink may sit on a root or any of its ancestors (system links such as `/tmp` and `/var` included); if one is hit, `--yes` rejects the whole batch and tells you to rewrite the path in real form (e.g. `/private/tmp/x`), which clears it. Scanning is not subject to this: a root that is itself a symlink still gets scanned.
|
|
123
|
+
- `exclude`: the exclusion list; a name match at any directory level between a root and a `node_modules` skips it (more exclusions, less deletion: the safe direction). **Omit this field and a built-in default list applies** (package manager / version manager install trees, editor extension directories, system and application data roots; the list and its rationale are in the [design doc](docs/designs/config-and-initialization.md), section "Default exclusions"). These names never warn when they match nothing, since they vary by platform. Write the field explicitly (an empty array counts) and your own list takes over completely.
|
|
124
|
+
- **Suspected install trees stay out of the delete batch by default**: targets that look like install trees (e.g. `~/.bun/install/global/node_modules`, `<version dir>/lib/node_modules`, editor extension directories) are flagged in the list as `疑似安装树: <reason>` (suspected install tree, plus the reason) and keep their `node_modules` suffix; `--yes` does not delete them (reported as a failure, with an explanation of the skip). Cleaning them takes an explicit `--force`, which releases only this batch of targets and relaxes no deletion guard.
|
|
125
|
+
- **Cross-device targets stay out of the delete batch by default**: when a target and its owning root are not on the same filesystem (a cloud drive, network share, or container volume is mounted under the root and the entry lands on that volume), it is likewise not deleted; the list line notes the form at its end, `跨设备: 根与目标之间有挂载点` (a mount point lies between root and target) or `跨设备: 目标本体即挂载点` (the target itself is the mount point). For the first form, add that mount point as its own root and it cleans as usual; for the second, unmount the volume first; `--force` does not release this category.
|
|
126
|
+
- `include`: the inclusion list (a whitelist); only matches are included, matched the same way as `exclude`. Omitted or empty means no filtering (more inclusions, more deletion); when a name matches both lists, `exclude` wins. A misspelled name would leave the result empty, so unmatched names warn on stderr.
|
|
127
|
+
- `node_modules` and `.git` are always stripped from either list: the former is the tool's very target (under `exclude` it would rule out the only thing this tool does, under `include` it can never match), the latter is a directory the scan always skips. If stripping leaves `include` empty, that means no filtering, not "scan only `node_modules`".
|
|
128
|
+
- First run with no config: on an interactive terminal the init wizard starts automatically (the scan root defaults to your home directory); in non-interactive environments (scripts and the like) it falls back to the current working directory as the root and says so, without asking. Re-enter the wizard any time with `sweep-nm init`.
|
|
129
|
+
|
|
130
|
+
> Field definitions are authoritative in the [design doc](docs/designs/config-and-initialization.md).
|
|
131
|
+
|
|
132
|
+
## Safety guardrails
|
|
133
|
+
|
|
134
|
+
Deletion is the only irreversible action this tool performs, and a whole discipline of guards has grown around it. Below are the heavyweight ones; the full set, including an honest account of the known residual risks, lives in [the safety guardrails document](docs/safety-guardrails.md) (in Chinese).
|
|
135
|
+
|
|
136
|
+
> The tool's character in one line: when anything is uncertain, the default is not to delete.
|
|
137
|
+
|
|
138
|
+
**Nothing happens by default.** Preview is the default mode, and deletion requires an explicit `--yes`. With no config file, `--yes` is hard-rejected and nothing is deleted. On the run right after the wizard writes a config, preview is forced even if `--yes` was passed. `--force` releases only suspected install trees; it relaxes no deletion guard.
|
|
139
|
+
|
|
140
|
+
**What gets deleted is decided by both name and location.** Only directories named exactly `node_modules` are eligible, and only under the roots you declared; whether a target sits under a root is judged by path hierarchy rather than string prefixes, so `..` traversal and lookalike paths are rejected outright. Targets whose size cannot be measured are never deleted: keep rather than guess. Two categories are held back by default: suspected install trees (reinstalling them is painful or impossible; released only by an explicit `--force`) and cross-device targets that live on a different filesystem (`--force` does not release these either). A built-in default exclusion list (install-tree and system-data-root names from package managers, version managers, and editors) keeps the scan away from those trees.
|
|
141
|
+
|
|
142
|
+
**One failure stops the whole batch, and every path is re-checked first.** If a single target fails a check, the entire batch is abandoned with zero deletions, rather than letting the rest through; right before removal, the path from the root down to the target's parent is re-verified component by component, and a swap mid-way stops the batch. If a configured root, or any of its ancestors, has been swapped for a symlink, the delete batch is rejected with rewrite instructions; system links such as `/tmp` and `/var` count too, and rewriting to the real path clears it.
|
|
143
|
+
|
|
144
|
+
**Symlinks: the threshold follows reversibility.** For the same config, the read-only scan follows a symlinked root and still lists results, the irreversible delete rejects the batch, and `init` refuses to write a single byte through a link. The split is deliberate: a link's origin cannot be judged, so the irreversible step does not get the benefit of the doubt.
|
|
145
|
+
|
|
146
|
+
**Nothing in the output can be forged.** Every piece of external data (directory names from disk, command errors, list spellings) is sanitized before it reaches the output: control bytes stripped, newlines folded, so nothing can inject terminal control sequences or split a line into a fake trusted row; names that were rewritten get a note on the line. Skipped targets stay in the list with their markers, and the list ends with a skip count. A name that never matches warns on stderr, and a whitelist with zero matches states outright that the result must be empty. Errors carry an error code, plain language, the target, and a partial-deletion re-check hint; "nothing was deleted" and "deletion failed" are shown separately.
|
|
120
147
|
|
|
121
|
-
|
|
148
|
+
**The distribution chain proves itself.** Zero third-party runtime dependencies and no network calls on the run path. The artifact an npm installer gets verifies itself against a bundled manifest before use and is refused on mismatch; the release side passes a four-part gate: a clean checkout, an artifact built from this commit, manifest consistency, and a whitelist of files allowed into the published package, so stray files (say, a backup of the README) cannot slip in.
|
|
122
149
|
|
|
123
|
-
##
|
|
150
|
+
## Development
|
|
124
151
|
|
|
125
|
-
|
|
152
|
+
Environment setup, common commands, dual-runtime verification, and commit hooks: see the [development guide](docs/development.md).
|
|
126
153
|
|
|
127
|
-
##
|
|
154
|
+
## Documentation
|
|
128
155
|
|
|
129
|
-
- [
|
|
156
|
+
- [Engineering documentation index](docs/README.md)
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# sweep-node-modules
|
|
2
|
+
|
|
3
|
+
[English](README.md) | **中文**
|
|
4
|
+
|
|
5
|
+
工作区级 `node_modules` 清理工具: 一次扫描多个根目录, 跨项目列出各处 `node_modules` 与体积, 确认后批量删除, 回收磁盘空间。
|
|
6
|
+
|
|
7
|
+
> 分层说明: 单项目清理工具管「进入某个项目, 清它自己的产物」; 本工具管「站在工作区层面, 一次清理很多个项目」。两者分层共存, 见 [ADR 0001](docs/adrs/0001-workspace-level-cleaner.md)。
|
|
8
|
+
|
|
9
|
+
## 要求
|
|
10
|
+
|
|
11
|
+
- 业务逻辑**双运行时**: 有 bun 走 bun, 否则 node (功能一致, bun 启动更快)。
|
|
12
|
+
- 取最新一代运行时 API: bun 任意近期版本; node 需原生支持 TypeScript 直跑的版本 (源码方式与包方式取同一版本下限; 版本快照与实测记录见 [ADR 0006](docs/adrs/0006-dual-runtime-bun-first.md))。
|
|
13
|
+
- 零第三方运行时依赖 (只用运行时内置能力)。
|
|
14
|
+
- 平台: Windows / macOS / Linux 三平台均可运行 (见 [ADR 0007](docs/adrs/0007-platform-portability.md))。
|
|
15
|
+
|
|
16
|
+
## 安装
|
|
17
|
+
|
|
18
|
+
三种方式, 按你机器上已有的运行时挑。**每条下的「需要」是硬门槛**:
|
|
19
|
+
|
|
20
|
+
> **机器上只有 bun、没装 node?** 直接走 ① 或 ③; ② 的全局安装 (npm 与 bun 皆然) 都需要 node。
|
|
21
|
+
|
|
22
|
+
① ② 都经包注册表取包: 本机若配置了镜像源、且该镜像尚未同步到想装的版本, 可在命令后临时加 `--registry=https://registry.npmjs.org` 直连官方源。
|
|
23
|
+
|
|
24
|
+
### ① 免安装 (试用或偶尔用)
|
|
25
|
+
|
|
26
|
+
```shell
|
|
27
|
+
# 机器上有 bun
|
|
28
|
+
bunx @iyowei/sweep-node-modules
|
|
29
|
+
|
|
30
|
+
# 机器上有 node (npx 随 npm 一同安装, 本身就需要 node)
|
|
31
|
+
npx @iyowei/sweep-node-modules
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
- **需要**: bun 或 node, 与所选命令对应
|
|
35
|
+
- 特点: 零安装; 每次运行会解析一次包
|
|
36
|
+
- 注意: `bunx` 与 `npx` 各自依附一个运行时, 不是可互换的通用选项: 只有 bun 的机器没有 `npx`, 只有 node 的机器没有 `bunx`
|
|
37
|
+
|
|
38
|
+
### ② 包管理器全局安装 (常用推荐)
|
|
39
|
+
|
|
40
|
+
```shell
|
|
41
|
+
npm install -g @iyowei/sweep-node-modules
|
|
42
|
+
bun install -g @iyowei/sweep-node-modules
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- **需要**: **node** (两条命令都要)。npm 本身跑在 node 上; `bun install -g` 生成的是指向入口文件的符号链接, 执行时由系统内核读该文件的 shebang (node) 来决定解释器, 应用层插不上手
|
|
46
|
+
- 特点: 装一次后直接敲 `sweep-nm`; 有 bun 时业务逻辑仍优先走 bun
|
|
47
|
+
|
|
48
|
+
### ③ 从源码 (开发, 或无 node 环境)
|
|
49
|
+
|
|
50
|
+
**macOS / Linux**:
|
|
51
|
+
|
|
52
|
+
```shell
|
|
53
|
+
# 克隆后进入仓库根 (路径按你的实际位置调整)
|
|
54
|
+
cd "<克隆位置>/sweep-node-modules"
|
|
55
|
+
|
|
56
|
+
chmod +x bin/sweep-nm
|
|
57
|
+
|
|
58
|
+
# 软链进 ~/.local/bin (通常已在 PATH 中), 启动器会挑选运行时
|
|
59
|
+
ln -sf "$PWD/bin/sweep-nm" ~/.local/bin/sweep-nm
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**Windows** (PowerShell):
|
|
63
|
+
|
|
64
|
+
```powershell
|
|
65
|
+
# 把仓库的 bin 目录加入用户 PATH, 只需一次, 重开终端后生效
|
|
66
|
+
# 路径按你的实际克隆位置调整 (启动器靠自身位置定位 src, 故不能把脚本单独复制走)
|
|
67
|
+
$bin = "$env:USERPROFILE\tools\sweep-node-modules\bin"
|
|
68
|
+
[Environment]::SetEnvironmentVariable(
|
|
69
|
+
'Path',
|
|
70
|
+
[Environment]::GetEnvironmentVariable('Path', 'User') + ";$bin",
|
|
71
|
+
'User'
|
|
72
|
+
)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
> 也可以不经命令行: 在「系统属性 → 环境变量」里把该 `bin` 目录加到用户变量 `Path` 中。
|
|
76
|
+
|
|
77
|
+
- **需要**: bun 或 node 任一 (启动器是 shell / cmd 脚本, 由系统执行, 不依赖 node)
|
|
78
|
+
- 特点: 入口最直接; 之后直接敲 `sweep-nm` (Windows 经 `bin\sweep-nm.cmd`)
|
|
79
|
+
|
|
80
|
+
## 使用
|
|
81
|
+
|
|
82
|
+
```shell
|
|
83
|
+
# 预览: 列出配置中各根目录下所有 node_modules 与体积, 不动手
|
|
84
|
+
sweep-nm
|
|
85
|
+
|
|
86
|
+
# 复核无误后执行删除
|
|
87
|
+
sweep-nm --yes
|
|
88
|
+
|
|
89
|
+
# 连同「疑似安装树」一并删除 (包管理器 / 版本管理器 / 编辑器扩展等安装树, 默认跳过)
|
|
90
|
+
sweep-nm --yes --force
|
|
91
|
+
|
|
92
|
+
# 临时追加排除(可重复)
|
|
93
|
+
sweep-nm --exclude my-kits --exclude url-tool
|
|
94
|
+
|
|
95
|
+
# 只清理名单命中的目录(可重复, 与配置合并)
|
|
96
|
+
sweep-nm --include my-kits
|
|
97
|
+
|
|
98
|
+
# 查看实际生效的配置文件位置与状态 (来源 / 路径 / 是否存在)
|
|
99
|
+
sweep-nm config
|
|
100
|
+
|
|
101
|
+
# 初始化向导: 交互式生成配置文件
|
|
102
|
+
sweep-nm init
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
清单顶栏尾部会标注本次实际使用的运行时 (如 `bun 1.4.2`), 仅交互终端显示 (非 TTY 不增噪音)。
|
|
106
|
+
|
|
107
|
+
## 配置
|
|
108
|
+
|
|
109
|
+
配置文件位置 (平台自适应): Windows 为 `%APPDATA%\sweep-node-modules\config.json`, 其余为 `~/.config/sweep-node-modules/config.json`; 可用 `--config` 或环境变量 `SWEEP_NM_CONFIG` 覆盖, 本次实际生效的路径与文件状态用 `sweep-nm config` 查看。**写入侧须为真实路径形态**: 配置路径及其祖先链有符号链接介入 (系统链接 `/tmp`、`/var` 也在内) 时, `sweep-nm init` 落盘前会拒写并给出链接定位, 按提示改写成真实路径形态 (如 `/private/tmp/x`) 即放行。
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
{
|
|
113
|
+
"roots": [
|
|
114
|
+
"/Users/iyowei/workspace/development",
|
|
115
|
+
"/Users/iyowei/self/development"
|
|
116
|
+
],
|
|
117
|
+
"exclude": ["my-kits"],
|
|
118
|
+
"include": []
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
- `roots`: 扫描根目录, 任意多个; 重复或嵌套的根按真实路径去重。**删除侧须为真实路径形态**: 根及其祖先链不得有符号链接介入 (系统链接 `/tmp`、`/var` 也在内), 命中则 `--yes` 整批拒绝并按提示改写成真实路径 (如 `/private/tmp/x`) 即放行; 扫描侧不受此限 (根为符号链接照常扫描)。
|
|
123
|
+
- `exclude`: 排除名单; 从根到 `node_modules` 的任意一级目录名命中即跳过 (多排除 = 少删, 安全方向)。**不写该字段时取内置默认名单** (包管理器 / 版本管理器的安装树、编辑器扩展目录、系统与应用数据根, 词表与理由见[设计文档](docs/designs/config-and-initialization.md)「默认排除名单」; 这批名字零命中不告警, 它们依平台而异); 显式写出该字段 (含写空数组) 即以你自己的名单为准。
|
|
124
|
+
- **疑似安装树默认不进删除批**: 安装树形态的目标 (如 `~/.bun/install/global/node_modules`、`<版本目录>/lib/node_modules`、编辑器扩展目录) 在清单里带 `疑似安装树: <理由>` 标记且保留 `node_modules` 后缀, `--yes` 不删它们 (计失败并给跳过说明); 要清理须显式加 `--force`, 它只放行这一批目标, 不放宽删除安全闸。
|
|
125
|
+
- **跨设备目标默认不进删除批**: 目标与所属根不在同一文件系统时 (根之下挂了云盘 / 网络盘 / 容器卷, 条目落在那一卷上) 同样不删, 清单行尾标注 `跨设备: 根与目标之间有挂载点` 或 `跨设备: 目标本体即挂载点`; 前者把该挂载点加进 `roots` 即可照常清理, 后者 (目标本体就是挂载点) 只能先卸载该卷; `--force` 不放行这一类。
|
|
126
|
+
- `include`: 包含名单 (白名单); 命中才纳入, 口径与 `exclude` 同款; 缺省或空数组 = 不过滤 (多包含 = 多删); 与 `exclude` 同时命中时 `exclude` 优先。写错名字会让结果直接为空, 故未命中的名字会在 stderr 警示。
|
|
127
|
+
- 两份名单里的 `node_modules` 与 `.git` 一律被剔除: 前者是本工具的目标 (列入排除等于排掉唯一目标, 列入包含则永久零命中), 后者是扫描恒定跳过的目录; 剔除后 `include` 为空数组 = 不过滤 (不是「只扫 node_modules」)。
|
|
128
|
+
- 首次运行且无配置: 交互终端下自动进入初始化向导 (扫描根默认家目录); 非交互环境 (脚本等) 以当前工作目录为根并提示, 不询问; 随时可用 `sweep-nm init` 重进向导。
|
|
129
|
+
|
|
130
|
+
> 字段定义以[设计文档](docs/designs/config-and-initialization.md)为准。
|
|
131
|
+
|
|
132
|
+
## 安全防护
|
|
133
|
+
|
|
134
|
+
删除是这套工具唯一不可逆的动作, 围绕它攒下了一整套防护纪律。下面挑出分量最重的几条; 全量版 (含已知残余风险的诚实账) 见 [安全防护保障](docs/safety-guardrails.md)。
|
|
135
|
+
|
|
136
|
+
> 这套工具的性格, 一句话: 看不准的时候, 默认不删。
|
|
137
|
+
|
|
138
|
+
**默认什么都不做。** 预览是默认态, 删除要显式加 `--yes`; 没有配置文件时 `--yes` 被硬拒绝, 零删除; 向导刚写入配置的那一轮强制预览, 即便带了 `--yes` 也只预览。`--force` 只放行「疑似安装树」这一批目标, 不放宽任何删除安全闸。
|
|
139
|
+
|
|
140
|
+
**删什么, 由名字与归属双重判定。** 只认名字恰为 `node_modules` 的目录, 且必须落在声明的扫描根之下; 归属按路径层级判定, 不是字符串前缀, 上溯与冒名路径一概拒绝。体积测不到的目标一律不删: 宁可留着, 不猜。两类目标默认拦下: 删了装不回来的「疑似安装树」 (要清理须显式加 `--force`), 与落在另一文件系统上的跨设备目标 (`--force` 同样不放行); 另有一份缺省排除名单 (包管理器 / 版本管理器 / 编辑器扩展与系统数据根的名字) 挨着就不扫。
|
|
141
|
+
|
|
142
|
+
**一处不过, 整批不删; 动手前逐级复核。** 任一目标没通过检查, 整批一个都不删, 而不是逐条放行; 删除前自根至目标父目录逐级复核, 半路被掉包就整批停手。配置根或其祖先被换成符号链接时, 删除整批拒绝, 拒绝文案自带改写方向; 系统固有链接 (`/tmp`、`/var` 这类) 同样命中, 改写成真实路径形态即放行。
|
|
143
|
+
|
|
144
|
+
**符号链接: 门槛跟着可逆性走。** 同一份配置, 只读的扫描面照常跟进 (根为符号链接照常出清单), 不可逆的删除面整批拒绝, 写入面 (`init` 落盘) 有链接介入就一个字节不落。这个分叉是有意的: 链接的来路判不了, 就不放行不可逆的那一步。
|
|
145
|
+
|
|
146
|
+
**输出面不可伪造。** 一切外部数据 (磁盘上的目录名、命令报错、名单拼写) 进输出前先净化: 剥控制字节、折叠换行, 防终端控制序列注入, 也防换行劈出伪造的可信行; 名字被净化改写时行尾标注。被跳过的目标带标注留在清单里, 末尾有跳过计数。名单里没命中的名字会在 stderr 告警, 白名单全零命中还点明「结果必为空」; 错误文案含错误码、人话、目标定位与部分删除复查提示, 「没删」与「删失败」分开展示。
|
|
147
|
+
|
|
148
|
+
**分发链路可自证。** 零第三方运行时依赖, 运行路径无网络调用; npm 安装者拿到的产物用前先与随附清单对账摘要, 不符即拒收; 发布侧另设四重闸门: 干净检出、本提交产物、清单自洽、发布包文件白名单; 仓库根散落的文件 (如 README 的备份) 进不了包。
|
|
149
|
+
|
|
150
|
+
## 开发
|
|
151
|
+
|
|
152
|
+
环境准备、常用命令、双运行时验证与提交钩子, 见 [开发指南](docs/development.md)。
|
|
153
|
+
|
|
154
|
+
## 文档
|
|
155
|
+
|
|
156
|
+
- [工程技术文档总索引](docs/README.md)
|
package/bin/sweep-nm.mjs
CHANGED
|
@@ -6,38 +6,185 @@
|
|
|
6
6
|
* 包内只有产物, 开发态通常无产物):
|
|
7
7
|
* 本文件同时承担 Unix 与 Windows 的 npm shim 目标 (shebang 必须是 node, 否则
|
|
8
8
|
* npm 的 cmd-shim 会按 shebang 解释器生成 Windows 上不存在的调用)。
|
|
9
|
+
*
|
|
10
|
+
* 运行时解析防劫持 (安全审计项 runtime-resolution:bare-name-cwd-precedence-windows):
|
|
11
|
+
* Windows 上裸名执行会先搜当前工作目录 (CreateProcessW 的搜索序里「parent 的当前目录」居第 2 位;
|
|
12
|
+
* 本文件走的 Node spawn 亦然 —— libuv 的 search_path 以 NeedCurrentDirectoryForExePathW 门控
|
|
13
|
+
* 先试 cwd 再扫 PATH), 而本工具的调用现场恰是「在被扫目录里执行」, 目录内放一个同名
|
|
14
|
+
* bun.exe / bun.com 即可顶替真实运行时进入执行链。故 win32 下先按 PATH 解析出绝对路径
|
|
15
|
+
* (空条目与相对条目都会把解析引回当前目录, 一并跳过) 再探测与执行, 解析面与执行面都不再
|
|
16
|
+
* 触发任何搜索序; POSIX 侧 Node 走 execvp 只搜 PATH, 维持裸名原样。
|
|
17
|
+
*
|
|
18
|
+
* 产物自证 (审计项「发行面 dist/cli.js 与源码和提交无身份绑定」的运行时防线): 决定跑
|
|
19
|
+
* dist/cli.js 之前必须与随附的 dist/manifest.json 对账 (形状版本受支持, 且清单记的 cliSha256
|
|
20
|
+
* 必须等于实测摘要), 清单缺失 / 损坏 / 版本不支持 / 摘要不符一律拒收产物并给出指引, 不静默回退
|
|
21
|
+
* 源码 (静默回退会把产物漂移藏起来, 包内也没有源码可回退); 拒收指引按宿主分流 (仓库检出态给
|
|
22
|
+
* 源码入口与重构建, 包态给重装本包)。工作树脏净不进本判定 (开发态常脏), 那是发布闸门
|
|
23
|
+
* scripts/verify-release.ts 的职责; 清单字段契约见 scripts/release-artifact.ts (包内无法
|
|
24
|
+
* 跨语言复用该模块, 两边口径由 src/npm-launcher.smoke.test.ts 的集成用例钉住)。
|
|
25
|
+
*
|
|
9
26
|
* 退出码原样透传; 两个运行时都缺席时给出可操作提示并非零退出。
|
|
10
27
|
*/
|
|
11
28
|
import { spawnSync } from 'node:child_process';
|
|
12
|
-
import {
|
|
13
|
-
import {
|
|
29
|
+
import { createHash } from 'node:crypto';
|
|
30
|
+
import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
|
|
31
|
+
import { dirname, join, win32 } from 'node:path';
|
|
14
32
|
import { fileURLToPath } from 'node:url';
|
|
15
33
|
|
|
34
|
+
/** 产物与清单的文件名 (与 scripts/release-artifact.ts 的 CLI_FILE / MANIFEST_FILE 同值) */
|
|
35
|
+
const CLI_FILE = 'cli.js';
|
|
36
|
+
const MANIFEST_FILE = 'manifest.json';
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* win32 的候选可执行扩展名, 顺序与 Node 实际走的 libuv 搜索一致 (.com 先于 .exe)。
|
|
40
|
+
* 不展开 PATHEXT: .bat / .cmd 无法被 Node 无 shell 直接执行, 展开只会把不可执行的命中当成功;
|
|
41
|
+
* 保持该面与 libuv 等价也意味着本次收紧不改动 win32 上「哪些安装形态能命中」的既有行为。
|
|
42
|
+
*/
|
|
43
|
+
const WIN32_EXEC_EXTS = ['.com', '.exe'];
|
|
44
|
+
|
|
16
45
|
/** 探测命令是否可执行 (以 --version 的实际退出码为准, 不依赖 shell 内建) */
|
|
17
46
|
const available = (command) =>
|
|
18
47
|
spawnSync(command, ['--version'], { stdio: 'ignore' }).status === 0;
|
|
19
48
|
|
|
20
|
-
/**
|
|
21
|
-
const
|
|
22
|
-
|
|
23
|
-
|
|
49
|
+
/** 路径处是否为普通文件 (探针读不到即 false, 不抛; 目录名撞上候选名时不得当选) */
|
|
50
|
+
const isFileAt = (path) => {
|
|
51
|
+
try {
|
|
52
|
+
return statSync(path).isFile();
|
|
53
|
+
} catch {
|
|
54
|
+
return false;
|
|
55
|
+
}
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* 在 PATH 中解析命令的绝对路径 (win32 语义), 找不到返回 null。
|
|
60
|
+
* 只供 win32 分支调用: CreateProcessW 与 libuv 的裸名搜索序都会先搜当前目录, 本函数把
|
|
61
|
+
* 「当前目录」从解析面整个摘掉 —— 空条目 (Windows 上表示当前目录) 与相对条目 (同样按当前
|
|
62
|
+
* 目录解析) 一律跳过, 只认绝对目录; 条目两侧的引号按 libuv 同款剥掉 (Windows PATH 允许
|
|
63
|
+
* 引号包裹含空格的目录)。注入 pathEnv / fileProbe 供测试在非 win32 宿主上覆盖本函数。
|
|
64
|
+
*/
|
|
65
|
+
export const resolveWin32Executable = (name, pathEnv, fileProbe) => {
|
|
66
|
+
for (const raw of pathEnv.split(';')) {
|
|
67
|
+
const dir =
|
|
68
|
+
raw.length > 1 && raw.startsWith('"') && raw.endsWith('"')
|
|
69
|
+
? raw.slice(1, -1)
|
|
70
|
+
: raw;
|
|
71
|
+
if (dir === '' || !win32.isAbsolute(dir)) continue;
|
|
72
|
+
for (const ext of WIN32_EXEC_EXTS) {
|
|
73
|
+
const candidate = win32.join(dir, name + ext);
|
|
74
|
+
if (fileProbe(candidate)) return candidate;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
return null;
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* 挑选运行时: Bun 优先, 其次 Node; 皆无则 null (由调用处报错退出)。
|
|
82
|
+
* win32 下先按 PATH 解析绝对路径再探测 (理由见文件头「运行时解析防劫持」), POSIX 下维持
|
|
83
|
+
* 裸名 (execvp 只搜 PATH); 各参数显式传入供测试注入, 生产调用不传。
|
|
84
|
+
*/
|
|
85
|
+
export const pickRuntime = ({
|
|
86
|
+
platform = process.platform,
|
|
87
|
+
pathEnv = process.env.PATH ?? '',
|
|
88
|
+
fileProbe = isFileAt,
|
|
89
|
+
probe = available,
|
|
90
|
+
} = {}) => {
|
|
91
|
+
for (const name of ['bun', 'node']) {
|
|
92
|
+
const resolved =
|
|
93
|
+
platform === 'win32'
|
|
94
|
+
? resolveWin32Executable(name, pathEnv, fileProbe)
|
|
95
|
+
: name;
|
|
96
|
+
if (resolved !== null && probe(resolved)) return resolved;
|
|
97
|
+
}
|
|
98
|
+
return null;
|
|
99
|
+
};
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* 产物自证: 核对 dist/cli.js 与 dist/manifest.json 的摘要是否同源。
|
|
103
|
+
* 通过返回 null, 否则返回人话原因; 原因串全是本文件固定措辞, 不回显清单内容 (清单是外部
|
|
104
|
+
* 文件, 其文本不受控, 不落进输出面)。
|
|
105
|
+
*/
|
|
106
|
+
const artifactProblem = (distDir) => {
|
|
107
|
+
const manifestPath = join(distDir, MANIFEST_FILE);
|
|
108
|
+
if (!existsSync(manifestPath)) return `缺少产物清单 (dist/${MANIFEST_FILE})`;
|
|
109
|
+
let manifest;
|
|
110
|
+
try {
|
|
111
|
+
manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
|
|
112
|
+
} catch {
|
|
113
|
+
return `产物清单 (dist/${MANIFEST_FILE}) 损坏, 不是合法 JSON`;
|
|
114
|
+
}
|
|
115
|
+
// 形状版本先对: 异版本的字段语义无保证, 宁可拒收 (字面量 1 与 scripts/release-artifact.ts 的
|
|
116
|
+
// MANIFEST_SCHEMA_VERSION 同值, 改动须两处同步; 启动器随包分发, 包内无法 import 该模块)
|
|
117
|
+
if (manifest?.schemaVersion !== 1) {
|
|
118
|
+
return `产物清单 (dist/${MANIFEST_FILE}) 的 schemaVersion 不是受支持的版本 (期望 1)`;
|
|
119
|
+
}
|
|
120
|
+
const recorded = manifest?.cliSha256;
|
|
121
|
+
if (typeof recorded !== 'string') {
|
|
122
|
+
return `产物清单 (dist/${MANIFEST_FILE}) 缺少 cliSha256 字段`;
|
|
123
|
+
}
|
|
124
|
+
let actual;
|
|
125
|
+
try {
|
|
126
|
+
actual = createHash('sha256')
|
|
127
|
+
.update(readFileSync(join(distDir, CLI_FILE)))
|
|
128
|
+
.digest('hex');
|
|
129
|
+
} catch {
|
|
130
|
+
return `产物 (dist/${CLI_FILE}) 读不出来, 摘要算不出`;
|
|
131
|
+
}
|
|
132
|
+
if (recorded !== actual)
|
|
133
|
+
return `产物 (dist/${CLI_FILE}) 的摘要与清单记录不符`;
|
|
24
134
|
return null;
|
|
25
135
|
};
|
|
26
136
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
137
|
+
/**
|
|
138
|
+
* 本文件是否作为入口被直接执行。
|
|
139
|
+
* 经 realpath 比对而非字面路径: npm 在 Unix 上以符号链接 (或经 shim) 落 bin, 此时 argv[1] 是
|
|
140
|
+
* 链接路径而 import.meta.url 是解析后的真实路径。main 守卫只为让测试 import 本模块取函数时
|
|
141
|
+
* 不触发主流程, 判定失配的后果是入口静默不跑, 故除字面相等外只在 realpath 成功时采信。
|
|
142
|
+
*/
|
|
143
|
+
const isEntry = () => {
|
|
144
|
+
const entry = process.argv[1];
|
|
145
|
+
if (typeof entry !== 'string' || entry === '') return false;
|
|
146
|
+
const self = fileURLToPath(import.meta.url);
|
|
147
|
+
if (entry === self) return true;
|
|
148
|
+
try {
|
|
149
|
+
return realpathSync(entry) === self;
|
|
150
|
+
} catch {
|
|
151
|
+
return false;
|
|
152
|
+
}
|
|
153
|
+
};
|
|
33
154
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
155
|
+
const main = () => {
|
|
156
|
+
const root = dirname(dirname(fileURLToPath(import.meta.url)));
|
|
157
|
+
const distDir = join(root, 'dist');
|
|
158
|
+
const built = join(distDir, CLI_FILE);
|
|
159
|
+
const hasBuilt = existsSync(built);
|
|
160
|
+
// 有产物就得先自证 (与随附清单对账); 不通过即拒收, 退出码与「无运行时」同一档: 1
|
|
161
|
+
const problem = hasBuilt ? artifactProblem(distDir) : null;
|
|
162
|
+
if (problem !== null) {
|
|
163
|
+
// 处置指引按宿主分流: 仓库检出态 (有源码) 可走源码入口或重构建; 包态 (无源码) 只能重装本包
|
|
164
|
+
const advice = existsSync(join(root, 'src', 'cli.ts'))
|
|
165
|
+
? '用源码入口跑 (bun src/cli.ts 或 node src/cli.ts), 或重新构建 (bun run build)'
|
|
166
|
+
: '重装本包换一份完好分发 (npm install -g @iyowei/sweep-node-modules); 重装无效则说明该版本包有缺陷, 需发布者重新构建后再发';
|
|
167
|
+
process.stderr.write(
|
|
168
|
+
`sweep-nm: ${problem}, 已拒绝执行该产物 (无法证明它与构建清单同源)。\n` +
|
|
169
|
+
` 处置: ${advice}。\n`,
|
|
170
|
+
);
|
|
171
|
+
process.exit(1);
|
|
172
|
+
}
|
|
173
|
+
// npm 包内是编译产物 (node 拒绝对 node_modules 内的 TS 做类型剥离, 见 package.json 的 build 脚本);
|
|
174
|
+
// 仓库开发态无 dist, 回退直跑源码 (bun / node 皆可)
|
|
175
|
+
const entry = hasBuilt ? built : join(root, 'src', 'cli.ts');
|
|
176
|
+
const runtime = pickRuntime();
|
|
38
177
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
178
|
+
if (runtime === null) {
|
|
179
|
+
process.stderr.write('sweep-nm: 未找到 bun 或 node, 请至少安装其一\n');
|
|
180
|
+
process.exit(1);
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
const { status } = spawnSync(runtime, [entry, ...process.argv.slice(2)], {
|
|
184
|
+
stdio: 'inherit',
|
|
185
|
+
});
|
|
186
|
+
|
|
187
|
+
process.exit(status ?? 1);
|
|
188
|
+
};
|
|
42
189
|
|
|
43
|
-
|
|
190
|
+
if (isEntry()) main();
|