@iyowei/sweep-node-modules-cli 0.2.1 → 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 CHANGED
@@ -1,23 +1,23 @@
1
1
  # sweep-node-modules-cli
2
2
 
3
- [![CI](https://github.com/iyowei/sweep-node-modules/actions/workflows/ci.yml/badge.svg)](https://github.com/iyowei/sweep-node-modules/actions/workflows/ci.yml)
3
+ [![CI](https://github.com/iyowei/clis/actions/workflows/ci.yml/badge.svg)](https://github.com/iyowei/clis/actions/workflows/ci.yml)
4
4
  [![npm version](https://img.shields.io/npm/v/@iyowei/sweep-node-modules-cli)](https://www.npmjs.com/package/@iyowei/sweep-node-modules-cli)
5
5
  [![npm downloads](https://img.shields.io/npm/dm/@iyowei/sweep-node-modules-cli)](https://www.npmjs.com/package/@iyowei/sweep-node-modules-cli)
6
6
  ![node](https://img.shields.io/node/v/@iyowei/sweep-node-modules-cli)
7
- ![bun](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fiyowei%2Fsweep-node-modules%2Fmain%2Fpackage.json&query=%24.packageManager&label=bun)
7
+ ![bun](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fiyowei%2Fclis%2Fmain%2Fpackage.json&query=%24.packageManager&label=bun)
8
8
 
9
9
  **English** | [中文](README.zh-CN.md)
10
10
 
11
11
  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. The CLI is a thin shell over the API package it is built on, [`@iyowei/sweep-node-modules`](https://www.npmjs.com/package/@iyowei/sweep-node-modules). For programmatic use from your own scripts and tools, reach for that package (its usage is documented there).
12
12
 
13
- > 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).
13
+ > 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](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/adrs/0001-workspace-level-cleaner.md).
14
14
 
15
15
  ## Requirements
16
16
 
17
17
  - **Dual runtime** for the actual work: bun when available, node otherwise (identical behavior; bun starts faster).
18
- - 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)).
18
+ - 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](https://github.com/iyowei/clis/blob/main/docs/adrs/0006-dual-runtime-bun-first.md)).
19
19
  - Zero third-party runtime dependencies (built-in runtime capabilities only).
20
- - Runs on Windows, macOS, and Linux (see [ADR 0007](../../docs/adrs/0007-platform-portability.md)).
20
+ - Runs on macOS, Linux, and Windows (covered by real Windows CI `verify-windows`). npm installs ship `bin/sweep-nm.mjs` (via npm's shim); the `.cmd` launcher (`bin/sweep-nm.cmd`) is for source checkouts only and is not independently run in CI (see [ADR 0007](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/adrs/0007-platform-portability.md)).
21
21
 
22
22
  ## Installation
23
23
 
@@ -57,7 +57,7 @@ bun install -g @iyowei/sweep-node-modules-cli
57
57
 
58
58
  ```shell
59
59
  # clone, then cd into the repo root (adjust the path to your clone location)
60
- cd "<your clone>/sweep-node-modules"
60
+ cd "<your clone>/clis"
61
61
 
62
62
  chmod +x packages/sweep-node-modules-cli/bin/sweep-nm
63
63
 
@@ -70,7 +70,7 @@ ln -sf "$PWD/packages/sweep-node-modules-cli/bin/sweep-nm" ~/.local/bin/sweep-nm
70
70
  ```powershell
71
71
  # add the repo's bin directory to your user PATH; one-time, effective after reopening the terminal
72
72
  # 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)
73
- $bin = "$env:USERPROFILE\tools\sweep-node-modules\packages\sweep-node-modules-cli\bin"
73
+ $bin = "$env:USERPROFILE\tools\clis\packages\sweep-node-modules-cli\bin"
74
74
  [Environment]::SetEnvironmentVariable(
75
75
  'Path',
76
76
  [Environment]::GetEnvironmentVariable('Path', 'User') + ";$bin",
@@ -80,7 +80,7 @@ $bin = "$env:USERPROFILE\tools\sweep-node-modules\packages\sweep-node-modules-cl
80
80
 
81
81
  > Or skip the command line: add the `bin` directory to your user `Path` under System Properties → Environment Variables.
82
82
 
83
- - **Requires**: bun or node, either works (the launcher is a shell / cmd script run by the OS; it does not depend on node); **node-only environments**: run one build first (`bun install && bun run build`) — node does not read the repo's path mappings, so an uncovered checkout cannot resolve the API package's artifacts
83
+ - **Requires**: bun or node, either works (the launcher is a shell / cmd script run by the OS; it does not depend on node); **node-only runtime**: the checkout must be built first, and building needs bun (`bun install && bun run build`) — node does not read the repo's path mappings, so an uncovered checkout cannot resolve the API package's artifacts
84
84
  - The most direct entry point; afterwards just run `sweep-nm` (on Windows via `packages\sweep-node-modules-cli\bin\sweep-nm.cmd`)
85
85
 
86
86
  ## Usage
@@ -92,7 +92,7 @@ sweep-nm
92
92
  # once the list checks out, delete for real
93
93
  sweep-nm --yes
94
94
 
95
- # also delete "suspected install trees" (package manager / version manager / editor extension trees; skipped by default)
95
+ # also delete "suspected install trees" (package manager / version manager / editor trees, hidden home-dir dirs, system-data-root names; skipped by default)
96
96
  sweep-nm --yes --force
97
97
 
98
98
  # add exclusions on the fly (repeatable)
@@ -106,46 +106,54 @@ sweep-nm config
106
106
 
107
107
  # init wizard: generate a config file interactively
108
108
  sweep-nm init
109
+
110
+ # self-update: detect your package manager (bun / npm / pnpm / yarn / volta) and upgrade
111
+ sweep-nm update
112
+ sweep-nm update --check
113
+
114
+ # full option list (also -h)
115
+ sweep-nm --help
109
116
  ```
110
117
 
111
118
  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.
112
119
 
120
+ ## Exit codes
121
+
122
+ `0` means success (preview and empty results included); `1` means anything else (deletion failure / batch abort / unattempted targets / broken or missing config / bad arguments / a run refused for lack of a config).
123
+
113
124
  ## Configuration
114
125
 
115
126
  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.
116
127
 
117
128
  ```json
118
129
  {
119
- "roots": [
120
- "/Users/iyowei/workspace/development",
121
- "/Users/iyowei/self/development"
122
- ],
130
+ "roots": ["/Users/you/workspace", "/Users/you/projects"],
123
131
  "exclude": ["my-kits"],
124
132
  "include": []
125
133
  }
126
134
  ```
127
135
 
128
136
  - `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.
129
- - `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.
130
- - **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.
137
+ - `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](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/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.
138
+ - **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, any `node_modules` under a hidden directory in the home dir, or under a system-data-root name such as `Library` / `.local` / `.config` / `.cache`) 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.
131
139
  - **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.
132
140
  - `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.
133
141
  - `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`".
134
142
  - 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`.
135
143
 
136
- > Field definitions are authoritative in the [design doc](../../docs/designs/config-and-initialization.md).
144
+ > Field definitions are authoritative in the [design doc](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/designs/config-and-initialization.md).
137
145
 
138
146
  ## Safety guardrails
139
147
 
140
- 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).
148
+ 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](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/designs/safety-guardrails.md) (in Chinese).
141
149
 
142
150
  > The tool's character in one line: when anything is uncertain, the default is not to delete.
143
151
 
144
152
  **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.
145
153
 
146
- **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.
154
+ **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, plus data-root names such as `Library` / `.local` / `.config` / `.cache` / `.claude`) keeps the scan away from those trees.
147
155
 
148
- **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.
156
+ **One failure stops the whole batch, and every path is re-checked first.** If a single target fails the pre-flight 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; a mid-way swap then stops the batch from dispatching further deletions (targets already dispatched run to completion and are reported as they are). 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.
149
157
 
150
158
  **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.
151
159
 
@@ -155,8 +163,9 @@ Deletion is the only irreversible action this tool performs, and a whole discipl
155
163
 
156
164
  ## Development
157
165
 
158
- Environment setup, common commands, dual-runtime verification, and commit hooks: see the [development guide](../../docs/development.md).
166
+ Environment setup, common commands, dual-runtime verification, and commit hooks: see the [development guide](https://github.com/iyowei/clis/blob/main/docs/development.md).
159
167
 
160
168
  ## Documentation
161
169
 
162
- - [Engineering documentation index](../../docs/README.md)
170
+ - [CLI package docs](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules-cli/docs/README.md)
171
+ - [Engineering documentation index](https://github.com/iyowei/clis/blob/main/docs/README.md)
package/README.zh-CN.md CHANGED
@@ -1,31 +1,31 @@
1
1
  # sweep-node-modules-cli
2
2
 
3
- [![CI](https://github.com/iyowei/sweep-node-modules/actions/workflows/ci.yml/badge.svg)](https://github.com/iyowei/sweep-node-modules/actions/workflows/ci.yml)
3
+ [![CI](https://github.com/iyowei/clis/actions/workflows/ci.yml/badge.svg)](https://github.com/iyowei/clis/actions/workflows/ci.yml)
4
4
  [![npm version](https://img.shields.io/npm/v/@iyowei/sweep-node-modules-cli)](https://www.npmjs.com/package/@iyowei/sweep-node-modules-cli)
5
5
  [![npm downloads](https://img.shields.io/npm/dm/@iyowei/sweep-node-modules-cli)](https://www.npmjs.com/package/@iyowei/sweep-node-modules-cli)
6
6
  ![node](https://img.shields.io/node/v/@iyowei/sweep-node-modules-cli)
7
- ![bun](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fiyowei%2Fsweep-node-modules%2Fmain%2Fpackage.json&query=%24.packageManager&label=bun)
7
+ ![bun](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fiyowei%2Fclis%2Fmain%2Fpackage.json&query=%24.packageManager&label=bun)
8
8
 
9
9
  [English](README.md) | **中文**
10
10
 
11
- 工作区级 `node_modules` 清理工具: 一次扫描多个根目录, 跨项目列出各处 `node_modules` 与体积, 确认后批量删除, 回收磁盘空间。本 CLI 是 API 包 [`@iyowei/sweep-node-modules`](https://www.npmjs.com/package/@iyowei/sweep-node-modules) 之上的一层薄壳。要在你自己的脚本与工具里做程序化调用, 请用该包 (用法见该包文档)。
11
+ 工作区级 `node_modules` 清理工具: 一次扫描多个根目录, 把各个项目里的 `node_modules` 连同体积一起列出来, 确认后批量删除, 回收磁盘空间。本 CLI 只是套在 API 包 [`@iyowei/sweep-node-modules`](https://www.npmjs.com/package/@iyowei/sweep-node-modules) 外面的一层薄壳。要在你自己的脚本与工具里直接调用, 请用该包 (用法见该包文档)。
12
12
 
13
- > 分层说明: 单项目清理工具管「进入某个项目, 清它自己的产物」; 本工具管「站在工作区层面, 一次清理很多个项目」。两者分层共存, 见 [ADR 0001](../../docs/adrs/0001-workspace-level-cleaner.md)。
13
+ > 分层说明: 单项目清理工具管「进入某个项目, 清它自己的产物」; 本工具管「站在工作区层面, 一次清理很多个项目」。两者分层共存, 见 [ADR 0001](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/adrs/0001-workspace-level-cleaner.md)。
14
14
 
15
15
  ## 要求
16
16
 
17
- - 业务逻辑**双运行时**: 有 bun 走 bun, 否则 node (功能一致, bun 启动更快)。
18
- - 取最新一代运行时 API: bun 任意近期版本; node 需原生支持 TypeScript 直跑的版本 (源码方式与包方式取同一版本下限; 版本快照与实测记录见 [ADR 0006](../../docs/adrs/0006-dual-runtime-bun-first.md))。
17
+ - 业务逻辑**双运行时**: 有 bun 走 bun, 没有就用 node (功能一致, bun 启动更快)。
18
+ - 运行时 API 取最新一代: bun 任意近期版本; node 要能原生直跑 TypeScript 的版本 (源码方式与包方式取同一版本下限; 版本快照与实测记录见 [ADR 0006](https://github.com/iyowei/clis/blob/main/docs/adrs/0006-dual-runtime-bun-first.md))。
19
19
  - 零第三方运行时依赖 (只用运行时内置能力)。
20
- - 平台: Windows / macOS / Linux 三平台均可运行 (见 [ADR 0007](../../docs/adrs/0007-platform-portability.md))。
20
+ - 平台: 支持 macOS、Linux 与 Windows (CI 已常驻真机 Windows 任务 `verify-windows` 覆盖核心测试与启动器)。npm 安装分发的是 `bin/sweep-nm.mjs` (由 npm 生成可执行 shim); `.cmd` 脚本 (`bin/sweep-nm.cmd`) 仅用于源码检出, 未在 CI 独立实跑 (详见 [ADR 0007](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/adrs/0007-platform-portability.md))。
21
21
 
22
22
  ## 安装
23
23
 
24
24
  三种方式, 按你机器上已有的运行时挑。**每条下的「需要」是硬门槛**:
25
25
 
26
- > **机器上只有 bun、没装 node?** 直接走 ① 或 ③; ② 的全局安装 (npm 与 bun 皆然) 都需要 node。
26
+ > **机器上只有 bun、没装 node?** 直接走 ① 或 ③; ② 的全局安装不管用 npm 还是 bun, 都需要 node。
27
27
 
28
- ① ② 都经包注册表取包: 本机若配置了镜像源、且该镜像尚未同步到想装的版本, 可在命令后临时加 `--registry=https://registry.npmjs.org` 直连官方源。
28
+ ① ② 的包都来自包注册表: 本机如果配了镜像源、镜像还没同步到想装的版本, 可以在命令后临时加 `--registry=https://registry.npmjs.org` 直连官方源。
29
29
 
30
30
  ### ① 免安装 (试用或偶尔用)
31
31
 
@@ -57,7 +57,7 @@ bun install -g @iyowei/sweep-node-modules-cli
57
57
 
58
58
  ```shell
59
59
  # 克隆后进入仓库根 (路径按你的实际位置调整)
60
- cd "<克隆位置>/sweep-node-modules"
60
+ cd "<克隆位置>/clis"
61
61
 
62
62
  chmod +x packages/sweep-node-modules-cli/bin/sweep-nm
63
63
 
@@ -70,7 +70,7 @@ ln -sf "$PWD/packages/sweep-node-modules-cli/bin/sweep-nm" ~/.local/bin/sweep-nm
70
70
  ```powershell
71
71
  # 把仓库的 bin 目录加入用户 PATH, 只需一次, 重开终端后生效
72
72
  # 路径按你的实际克隆位置调整 (启动器靠自身位置定位 src, 故不能把脚本单独复制走)
73
- $bin = "$env:USERPROFILE\tools\sweep-node-modules\packages\sweep-node-modules-cli\bin"
73
+ $bin = "$env:USERPROFILE\tools\clis\packages\sweep-node-modules-cli\bin"
74
74
  [Environment]::SetEnvironmentVariable(
75
75
  'Path',
76
76
  [Environment]::GetEnvironmentVariable('Path', 'User') + ";$bin",
@@ -80,7 +80,7 @@ $bin = "$env:USERPROFILE\tools\sweep-node-modules\packages\sweep-node-modules-cl
80
80
 
81
81
  > 也可以不经命令行: 在「系统属性 → 环境变量」里把该 `bin` 目录加到用户变量 `Path` 中。
82
82
 
83
- - **需要**: bun 或 node 任一 (启动器是 shell / cmd 脚本, 由系统执行, 不依赖 node); **仅 node 的环境**: 需先完成一次构建 (构建链以 bun 为工具: `bun install && bun run build`)——node 不解析仓库内的路径映射, 未经构建的检出态会找不到 API 包产物
83
+ - **需要**: bun 或 node 任一 (启动器是 shell / cmd 脚本, 由系统执行, 不依赖 node); **机器上只有 node 的话**: 克隆下来的代码要先构建一次, 而构建本身需要 bun (`bun install && bun run build`): node 不解析仓库里的路径映射, 没构建过的代码会找不到 API 包的产物
84
84
  - 特点: 入口最直接; 之后直接敲 `sweep-nm` (Windows 经 `packages\sweep-node-modules-cli\bin\sweep-nm.cmd`)
85
85
 
86
86
  ## 使用
@@ -92,7 +92,7 @@ sweep-nm
92
92
  # 复核无误后执行删除
93
93
  sweep-nm --yes
94
94
 
95
- # 连同「疑似安装树」一并删除 (包管理器 / 版本管理器 / 编辑器扩展等安装树, 默认跳过)
95
+ # 连同「疑似安装树」一并删除 (包管理器 / 版本管理器 / 编辑器扩展、家目录隐藏目录、系统数据根名; 默认跳过)
96
96
  sweep-nm --yes --force
97
97
 
98
98
  # 临时追加排除(可重复)
@@ -106,57 +106,66 @@ sweep-nm config
106
106
 
107
107
  # 初始化向导: 交互式生成配置文件
108
108
  sweep-nm init
109
+
110
+ # 自更新: 自动识别当前安装器 (bun / npm / pnpm / yarn / volta) 升级到最新版
111
+ sweep-nm update
112
+ sweep-nm update --check
113
+
114
+ # 完整选项表 (亦可 -h)
115
+ sweep-nm --help
109
116
  ```
110
117
 
111
- 清单顶栏尾部会标注本次实际使用的运行时 (如 `bun 1.4.2`), 仅交互终端显示 (非 TTY 不增噪音)。
118
+ 清单顶栏尾部会标注本次实际使用的运行时 (如 `bun 1.4.2`), 只在交互终端显示 (非 TTY 不添噪音)。
119
+
120
+ ## 退出码
121
+
122
+ `0` 表示成功 (预览与空结果也算); 其余一律 `1` (删除失败 / 整批中止 / 有目标没处理 / 配置损坏或不存在 / 参数错误 / 没有配置时拒绝执行)。
112
123
 
113
124
  ## 配置
114
125
 
115
- 配置文件位置 (平台自适应): 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`) 即放行。
126
+ 配置文件位置随平台走: 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`) 即可放行。
116
127
 
117
128
  ```json
118
129
  {
119
- "roots": [
120
- "/Users/iyowei/workspace/development",
121
- "/Users/iyowei/self/development"
122
- ],
130
+ "roots": ["/Users/you/workspace", "/Users/you/projects"],
123
131
  "exclude": ["my-kits"],
124
132
  "include": []
125
133
  }
126
134
  ```
127
135
 
128
- - `roots`: 扫描根目录, 任意多个; 重复或嵌套的根按真实路径去重。**删除侧须为真实路径形态**: 根及其祖先链不得有符号链接介入 (系统链接 `/tmp`、`/var` 也在内), 命中则 `--yes` 整批拒绝并按提示改写成真实路径 (如 `/private/tmp/x`) 即放行; 扫描侧不受此限 (根为符号链接照常扫描)。
129
- - `exclude`: 排除名单; 从根到 `node_modules` 的任意一级目录名命中即跳过 (多排除 = 少删, 安全方向)。**不写该字段时取内置默认名单** (包管理器 / 版本管理器的安装树、编辑器扩展目录、系统与应用数据根, 词表与理由见[设计文档](../../docs/designs/config-and-initialization.md)「默认排除名单」; 这批名字零命中不告警, 它们依平台而异); 显式写出该字段 (含写空数组) 即以你自己的名单为准。
130
- - **疑似安装树默认不进删除批**: 安装树形态的目标 (如 `~/.bun/install/global/node_modules`、`<版本目录>/lib/node_modules`、编辑器扩展目录) 在清单里带 `疑似安装树: <理由>` 标记且保留 `node_modules` 后缀, `--yes` 不删它们 (计失败并给跳过说明); 要清理须显式加 `--force`, 它只放行这一批目标, 不放宽删除安全闸。
131
- - **跨设备目标默认不进删除批**: 目标与所属根不在同一文件系统时 (根之下挂了云盘 / 网络盘 / 容器卷, 条目落在那一卷上) 同样不删, 清单行尾标注 `跨设备: 根与目标之间有挂载点` 或 `跨设备: 目标本体即挂载点`; 前者把该挂载点加进 `roots` 即可照常清理, 后者 (目标本体就是挂载点) 只能先卸载该卷; `--force` 不放行这一类。
132
- - `include`: 包含名单 (白名单); 命中才纳入, 口径与 `exclude` 同款; 缺省或空数组 = 不过滤 (多包含 = 多删); 与 `exclude` 同时命中时 `exclude` 优先。写错名字会让结果直接为空, 故未命中的名字会在 stderr 警示。
133
- - 两份名单里的 `node_modules` 与 `.git` 一律被剔除: 前者是本工具的目标 (列入排除等于排掉唯一目标, 列入包含则永久零命中), 后者是扫描恒定跳过的目录; 剔除后 `include` 为空数组 = 不过滤 (不是「只扫 node_modules」)。
134
- - 首次运行且无配置: 交互终端下自动进入初始化向导 (扫描根默认家目录); 非交互环境 (脚本等) 以当前工作目录为根并提示, 不询问; 随时可用 `sweep-nm init` 重进向导。
136
+ - `roots`: 扫描根目录, 数量不限; 重复或嵌套的根按真实路径去重。**要删除的话, 根必须是真实路径**: 根本身和它的祖先链上都不能有符号链接 (包括 `/tmp`、`/var` 这类系统自带的链接), 命中就 `--yes` 整批拒绝, 按提示改写成真实路径 (如 `/private/tmp/x`) 即可放行; 只扫描不受这条限制 (根是符号链接也照常扫)。
137
+ - `exclude`: 排除名单; 从根往下到 `node_modules` 的任意一级目录名命中就跳过 (排除越多, 删得越少, 安全方向)。**不写这个字段时, 用内置默认名单** (包管理器 / 版本管理器的安装树、编辑器扩展目录、系统与应用数据根, 词表与理由见[设计文档](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/designs/config-and-initialization.md)「默认排除名单」; 这些名字随平台而异, 一个都没命中也不会告警); 只要把该字段写出来 (哪怕写空数组), 就以你自己的名单为准。
138
+ - **疑似安装树默认不参与删除**: 长得像安装树的目标 (如 `~/.bun/install/global/node_modules`、`<版本目录>/lib/node_modules`、编辑器扩展目录、家目录下任意隐藏目录里的 `node_modules`, 或 `Library` / `.local` / `.config` / `.cache` 等系统数据根名下的) 在清单里会带 `疑似安装树: <理由>` 标记, 并保留 `node_modules` 后缀; `--yes` 不删这些 (算作失败, 并给出跳过说明); 要清理得显式加 `--force`, 它只放行这一批目标, 不放宽任何删除安全闸。
139
+ - **跨设备的目标默认也不删**: 目标跟它所属的根不在同一个文件系统时 (根下面挂了云盘 / 网络盘 / 容器卷, 而目标落在那一卷上) 同样不删; 清单行尾会标注 `跨设备: 根与目标之间有挂载点` 或 `跨设备: 目标本体即挂载点`。前一种把那个挂载点加进 `roots` 就能照常清理; 后一种 (目标本身就是挂载点) 只能先卸载那个卷; `--force` 不放行这一类。
140
+ - `include`: 包含名单 (白名单); 命中才纳入, 判定方式和 `exclude` 一样; 默认或空数组 = 不过滤 (包含越多, 删得越多); 同时被两份名单命中时 `exclude` 优先。名字写错会让结果直接为空, 所以没命中的名字会在 stderr 给出警示。
141
+ - 两份名单里出现的 `node_modules` 与 `.git` 都会被剔除: 前者是本工具的目标 (写进排除等于排掉唯一目标, 写进包含则永远零命中), 后者是扫描时一直跳过的目录; 剔除之后 `include` 若是空数组, 同样等于不过滤 (不是「只扫 node_modules」)。
142
+ - 首次运行且没有配置: 交互终端下自动进入初始化向导 (扫描根默认家目录); 非交互环境 (脚本等) 以当前工作目录为根并提示, 不询问; 随时可以用 `sweep-nm init` 重进向导。
135
143
 
136
- > 字段定义以[设计文档](../../docs/designs/config-and-initialization.md)为准。
144
+ > 字段定义以[设计文档](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/designs/config-and-initialization.md)为准。
137
145
 
138
146
  ## 安全防护
139
147
 
140
- 删除是这套工具唯一不可逆的动作, 围绕它攒下了一整套防护纪律。下面挑出分量最重的几条; 全量版 (含已知残余风险的诚实账) 见 [安全防护保障](../../docs/safety-guardrails.md)。
148
+ 删除是这套工具唯一不可逆的动作, 围绕它攒下了一整套防护纪律。下面挑出分量最重的几条; 全量版 (含已知残余风险的诚实账) 见 [安全防护保障](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules/docs/designs/safety-guardrails.md)。
141
149
 
142
150
  > 这套工具的性格, 一句话: 看不准的时候, 默认不删。
143
151
 
144
152
  **默认什么都不做。** 预览是默认态, 删除要显式加 `--yes`; 没有配置文件时 `--yes` 被硬拒绝, 零删除; 向导刚写入配置的那一轮强制预览, 即便带了 `--yes` 也只预览。`--force` 只放行「疑似安装树」这一批目标, 不放宽任何删除安全闸。
145
153
 
146
- **删什么, 由名字与归属双重判定。** 只认名字恰为 `node_modules` 的目录, 且必须落在声明的扫描根之下; 归属按路径层级判定, 不是字符串前缀, 上溯与冒名路径一概拒绝。体积测不到的目标一律不删: 宁可留着, 不猜。两类目标默认拦下: 删了装不回来的「疑似安装树」 (要清理须显式加 `--force`), 与落在另一文件系统上的跨设备目标 (`--force` 同样不放行); 另有一份缺省排除名单 (包管理器 / 版本管理器 / 编辑器扩展与系统数据根的名字) 挨着就不扫。
154
+ **删什么, 由名字与归属双重判定。** 只认名字恰好是 `node_modules` 的目录, 且必须落在声明的扫描根之下; 归属按路径层级判定, 不是字符串前缀, `..` 上溯与冒名路径一概拒绝。体积测不到的目标一律不删: 宁可留着, 不猜。两类目标默认拦下: 删了装不回来的「疑似安装树」 (要清理须显式加 `--force`), 与落在另一文件系统上的跨设备目标 (`--force` 同样不放行); 另有一份默认排除名单 (包管理器 / 版本管理器 / 编辑器扩展与 `Library` / `.local` / `.config` / `.cache` / `.claude` 等系统数据根的名字) 挨着就不扫。
147
155
 
148
- **一处不过, 整批不删; 动手前逐级复核。** 任一目标没通过检查, 整批一个都不删, 而不是逐条放行; 删除前自根至目标父目录逐级复核, 半路被掉包就整批停手。配置根或其祖先被换成符号链接时, 删除整批拒绝, 拒绝文案自带改写方向; 系统固有链接 (`/tmp`、`/var` 这类) 同样命中, 改写成真实路径形态即放行。
156
+ **一处不过, 整批不删; 动手前逐级复核。** 只要有一个目标没过检查, 整批一个都不删, 而不是逐条放行; 删除前从根到目标的父目录, 一级一级复核, 半路发现被掉包就停手, 不再往下删 (已经在删的条目会跑完, 并如实报告)。配置的根或它的祖先被换成符号链接时, 删除整批拒绝, 拒绝信息里直接给出改写方向; 系统自带的链接 (`/tmp`、`/var` 这类) 照样会被拦下, 改写成真实路径就放行。
149
157
 
150
- **符号链接: 门槛跟着可逆性走。** 同一份配置, 只读的扫描面照常跟进 (根为符号链接照常出清单), 不可逆的删除面整批拒绝, 写入面 (`init` 落盘) 有链接介入就一个字节不落。这个分叉是有意的: 链接的来路判不了, 就不放行不可逆的那一步。
158
+ **符号链接: 门槛跟着可逆性走。** 同一份配置, 只读的扫描照常跟进 (根为符号链接照常出清单), 不可逆的删除整批拒绝, 写入 (`init` 写盘) 只要路径上有链接, 就一个字节不落。这个分叉是有意的: 链接的来路判不了, 就不放行不可逆的那一步。
151
159
 
152
- **输出面不可伪造。** 一切外部数据 (磁盘上的目录名、命令报错、名单拼写) 进输出前先净化: 剥控制字节、折叠换行, 防终端控制序列注入, 也防换行劈出伪造的可信行; 名字被净化改写时行尾标注。被跳过的目标带标注留在清单里, 末尾有跳过计数。名单里没命中的名字会在 stderr 告警, 白名单全零命中还点明「结果必为空」; 错误文案含错误码、人话、目标定位与部分删除复查提示, 「没删」与「删失败」分开展示。
160
+ **输出不可伪造。** 一切外部数据 (磁盘上的目录名、命令报错、名单拼写) 进输出前先净化: 剥掉控制字节、折叠换行, 防终端控制序列注入, 也防换行劈出伪造的可信行; 名字被净化改写过的, 行尾会加标注。被跳过的目标带标注留在清单里, 末尾有跳过计数。名单里没命中的名字会在 stderr 告警, 白名单全零命中还点明「结果必为空」; 出错提示里带错误码、人话、目标定位和部分删除的复查提示, 「没删」与「删失败」分开展示。
153
161
 
154
- **分发链路可自证。** 零第三方运行时依赖, 运行路径无网络调用; npm 安装者拿到的产物用前先与随附清单对账摘要, 不符即拒收; 发布侧另设四重闸门: 干净检出、本提交产物、清单自洽、发布包文件白名单; 仓库根散落的文件 (如 README 的备份) 进不了包。
162
+ **分发链路可自证。** 零第三方运行时依赖, 运行过程中不发起任何网络调用; npm 安装的用户拿到的产物, 用之前先和随附清单核对摘要, 对不上就拒收; 发布侧还设了四道闸门: 干净检出、产物出自本次提交、清单自洽、发布包文件白名单; 仓库根目录下散落的文件 (比如 README 的备份) 进不了包。
155
163
 
156
164
  ## 开发
157
165
 
158
- 环境准备、常用命令、双运行时验证与提交钩子, 见 [开发指南](../../docs/development.md)。
166
+ 环境准备、常用命令、双运行时验证与提交钩子, 见 [开发指南](https://github.com/iyowei/clis/blob/main/docs/development.md)。
159
167
 
160
168
  ## 文档
161
169
 
162
- - [工程技术文档总索引](../../docs/README.md)
170
+ - [CLI 包文档入口](https://github.com/iyowei/clis/blob/main/packages/sweep-node-modules-cli/docs/README.md)
171
+ - [工程技术文档总索引](https://github.com/iyowei/clis/blob/main/docs/README.md)
@@ -0,0 +1,3 @@
1
+ # CLI 启动器隔离配置: 禁止自动加载当前工作目录的 bunfig.toml (防 preload 劫持与坏配置崩溃) 与 .env
2
+ preload = []
3
+ env = false