dev-prune-darwin-x64 1.6.0 → 1.8.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 +820 -0
- package/bin/dev-prune +0 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,820 @@
|
|
|
1
|
+
# dev-prune-darwin-x64
|
|
2
|
+
|
|
3
|
+
**Do not install this package.** Install [`dev-prune`](https://www.npmjs.com/package/dev-prune):
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install -g dev-prune
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
This package holds nothing but the prebuilt `dev-prune` binary for **darwin x64**.
|
|
10
|
+
It exists because npm has no other way to ship a per-platform executable: `dev-prune`
|
|
11
|
+
lists all seven platform packages as optional dependencies, and npm installs only the one
|
|
12
|
+
matching your machine. Installing this one directly gives you a binary with no launcher
|
|
13
|
+
and no upgrade path.
|
|
14
|
+
|
|
15
|
+
Documentation: <https://devprune.vkrishna04.me>
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
What follows is the dev-prune README, so this page describes the tool rather than just
|
|
20
|
+
refusing to be installed. Every command in it is run through the dispatcher package,
|
|
21
|
+
not through this one.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
<div align="center">
|
|
26
|
+
|
|
27
|
+
<img src="assets/github-readme-banner.png" alt="dev-prune — gigabytes back, nothing you can't rebuild" width="820" />
|
|
28
|
+
|
|
29
|
+
# `dev-prune`
|
|
30
|
+
|
|
31
|
+
### Gigabytes back. Nothing you can't rebuild.
|
|
32
|
+
|
|
33
|
+
**Reclaim the disk space your idle repositories are sitting on — without ever deleting
|
|
34
|
+
something a lockfile cannot put back.**
|
|
35
|
+
|
|
36
|
+
[](https://crates.io/crates/dev-prune) [](https://pypi.org/project/dev-prune/) [](LICENSE.md) [](https://www.rust-lang.org/) [](docs/RELEASES_AND_MANUAL_INSTALL.md)
|
|
37
|
+
|
|
38
|
+
[](https://github.com/Life-Experimentalist/dev-prune/actions/workflows/ci.yml) [](https://devprune.vkrishna04.me/) [](https://www.npmjs.com/package/dev-prune)
|
|
39
|
+
|
|
40
|
+
[**Website**](https://devprune.vkrishna04.me/) · [**Documentation**](docs/README.md) · [**CLI reference**](docs/CLI_REFERENCE.md) · [**Safety invariants**](docs/SAFETY_INVARIANTS.md) · [**Changelog**](CHANGELOG.md)
|
|
41
|
+
|
|
42
|
+
`devp` is the same binary under a shorter name · Windows, macOS and Linux · Apache-2.0 · by [VKrishna04](https://vkrishna04.me)
|
|
43
|
+
|
|
44
|
+
</div>
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
`node_modules`, `.venv`, `target` and `vendor` are the largest directories on most
|
|
49
|
+
developers' machines, and the least valuable: every byte in them is described by a
|
|
50
|
+
lockfile that is already committed. A project you have not opened since March is holding
|
|
51
|
+
gigabytes hostage for a build you are not running.
|
|
52
|
+
|
|
53
|
+
`dev-prune` finds those directories across every Git repository you register, and deletes
|
|
54
|
+
them — but only after proving the exact command that puts them back would succeed. It is
|
|
55
|
+
a single Rust binary, installs its own background schedule, and answers to two names:
|
|
56
|
+
`dev-prune` and `devp`.
|
|
57
|
+
|
|
58
|
+
> [!IMPORTANT]
|
|
59
|
+
> **The rule the whole tool is built around:** nothing is deleted unless dev-prune has
|
|
60
|
+
> just verified, read-only, that its lockfile can rebuild it. There is no flag to skip
|
|
61
|
+
> that check. `--ignore-idle` lifts the idle-day wait and *nothing else*.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Contents
|
|
66
|
+
|
|
67
|
+
<div align="center">
|
|
68
|
+
|
|
69
|
+
**Start here** [Install](#install) · [Editors](#in-your-editor) · [60-second tour](#60-second-tour) · [What it looks like](#what-it-looks-like)
|
|
70
|
+
|
|
71
|
+
**How it thinks** [Why it is safe](#why-it-is-safe) · [Features](#features) · [Commands](#commands) · [Ecosystems](#supported-ecosystems) · [Monorepos](#repositories-with-more-than-one-ecosystem)
|
|
72
|
+
|
|
73
|
+
**Running it** [Configuration](#configuration) · [Automation](#background-automation) · [Comparison](#how-it-compares) · [Architecture](#architecture) · [Docs](#documentation)
|
|
74
|
+
|
|
75
|
+
</div>
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Install
|
|
80
|
+
|
|
81
|
+
### One-liner
|
|
82
|
+
|
|
83
|
+
Pick the line for the shell you are actually typing into. Pasting the first one into a
|
|
84
|
+
Command Prompt is the most common install failure there is — it answers
|
|
85
|
+
`'sh' is not recognized as an internal or external command`, because `sh` is a Unix shell
|
|
86
|
+
and Windows does not ship one.
|
|
87
|
+
|
|
88
|
+
**Linux, macOS, or a Unix shell on Windows** — Git Bash, MSYS2, Cygwin, WSL:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
curl -fsSL https://devprune.vkrishna04.me/install.sh | sh
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
**Windows PowerShell** — the blue or black `PS>` prompt, and Windows Terminal's default:
|
|
95
|
+
|
|
96
|
+
```powershell
|
|
97
|
+
iwr -useb https://devprune.vkrishna04.me/install.ps1 | iex
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**Windows Command Prompt** — the `C:\>` prompt, which has no `iwr` of its own:
|
|
101
|
+
|
|
102
|
+
```bat
|
|
103
|
+
powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://devprune.vkrishna04.me/install.ps1 | iex"
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
All three download the prebuilt binary for your platform, verify its published SHA-256,
|
|
107
|
+
put it on `PATH`, and run `dev-prune setup`. Pass `--no-auto-setup` / `-NoAutoSetup` to
|
|
108
|
+
skip that last step.
|
|
109
|
+
|
|
110
|
+
Re-run any of them whenever you like. An install that is already current, complete and on
|
|
111
|
+
`PATH` is left exactly as it is and exits `0` without downloading; an older one is updated
|
|
112
|
+
in place; a newer one is not downgraded. `--force` / `-Force` writes it again regardless.
|
|
113
|
+
|
|
114
|
+
The Command Prompt form installs identically to the PowerShell one, but `cmd` cannot
|
|
115
|
+
inherit the `PATH` the installer sets in its own process, so `devp` resolves in the *next*
|
|
116
|
+
Command Prompt you open rather than the current one. PowerShell does not have that
|
|
117
|
+
problem.
|
|
118
|
+
|
|
119
|
+
### From a package manager
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npm install -g dev-prune # or: npx dev-prune status
|
|
123
|
+
uv tool install dev-prune # or: uvx dev-prune status
|
|
124
|
+
pipx install dev-prune
|
|
125
|
+
pip install dev-prune
|
|
126
|
+
cargo binstall dev-prune # fetches the prebuilt release archive
|
|
127
|
+
cargo install dev-prune # builds from source, needs Rust 1.88+
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
The npm and PyPI packages **contain the binary** — there is no download step at install
|
|
131
|
+
time, so they work under `npm ci --ignore-scripts`, behind a registry mirror and offline.
|
|
132
|
+
Everything but `cargo install` ships a prebuilt executable.
|
|
133
|
+
|
|
134
|
+
npm delivers it the way esbuild and Biome do: one small `dev-prune` package that lists
|
|
135
|
+
seven platform packages as optional dependencies, of which npm installs exactly the one
|
|
136
|
+
matching your machine. That is why there is no download step to block. Windows works from
|
|
137
|
+
1.8.0 onwards — earlier versions installed and then reported no binary to run, so a
|
|
138
|
+
machine still holding `dev-prune@1.7.0` needs `npm install -g dev-prune@latest`.
|
|
139
|
+
|
|
140
|
+
crates.io stores source and nothing else, so `cargo install` has no binary to fetch and
|
|
141
|
+
always compiles. [`cargo binstall`](https://github.com/cargo-bins/cargo-binstall) is the
|
|
142
|
+
one that downloads: `Cargo.toml` tells it where this project's release archives live, so
|
|
143
|
+
it unpacks the same executable the installers use, with no toolchain involved.
|
|
144
|
+
|
|
145
|
+
Homebrew and Scoop each have a one-file tap and bucket, which exist so that upgrades keep
|
|
146
|
+
arriving:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
brew tap Life-Experimentalist/tap
|
|
150
|
+
brew install dev-prune
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
```powershell
|
|
154
|
+
scoop bucket add life-experimentalist https://github.com/Life-Experimentalist/scoop-bucket
|
|
155
|
+
scoop install dev-prune
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Both also install straight from a URL with nothing tapped or added, because the file
|
|
159
|
+
carries the SHA-256 of the archive it installs — but a formula that belongs to no tap is
|
|
160
|
+
one `brew upgrade` will never look at again:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
brew install https://raw.githubusercontent.com/Life-Experimentalist/dev-prune/main/packaging/homebrew/dev-prune.rb
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
```powershell
|
|
167
|
+
scoop install https://raw.githubusercontent.com/Life-Experimentalist/dev-prune/main/packaging/scoop/dev-prune.json
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
WinGet is [submitted and in review](https://github.com/microsoft/winget-pkgs/pull/422809);
|
|
171
|
+
`winget install VKrishna04.dev-prune` starts resolving when that pull request merges.
|
|
172
|
+
|
|
173
|
+
The two Python entry points differ in where they land. `pip install` follows whichever
|
|
174
|
+
environment is active, so inside a virtualenv `devp` lives in that venv's `Scripts`/`bin`
|
|
175
|
+
and disappears with it; `pip install --user`, `pipx` and `uv tool install` are the
|
|
176
|
+
machine-wide forms. [Where each one puts the executables](docs/troubleshooting/INSTALLATION_ISSUES.md#6-uv-tool-install-put-the-executables-somewhere-unexpected).
|
|
177
|
+
|
|
178
|
+
### Direct download
|
|
179
|
+
|
|
180
|
+
Seven checksummed archives per release on
|
|
181
|
+
[GitHub Releases](https://github.com/Life-Experimentalist/dev-prune/releases) — Windows,
|
|
182
|
+
macOS and Linux on x64 and arm64, plus a 32-bit `windows-x86` build for machines with no
|
|
183
|
+
64-bit mode. The Linux binaries are statically linked against musl, so one file per
|
|
184
|
+
architecture runs on every distribution including Alpine.
|
|
185
|
+
|
|
186
|
+
Manual install and build-from-source:
|
|
187
|
+
[docs/RELEASES_AND_MANUAL_INSTALL.md](docs/RELEASES_AND_MANUAL_INSTALL.md).
|
|
188
|
+
|
|
189
|
+
### In your editor
|
|
190
|
+
|
|
191
|
+
There is a companion extension. It validates `.devprune.json` as you type — every key,
|
|
192
|
+
every adapter name, every enum, from the schema bundled inside it rather than fetched — and
|
|
193
|
+
puts the workspace's reclaimable size in the status bar, so you can see what a repository
|
|
194
|
+
is holding without leaving the window.
|
|
195
|
+
|
|
196
|
+
[](https://marketplace.visualstudio.com/items?itemName=VKrishna04.dev-prune) [](https://open-vsx.org/extension/VKrishna04/dev-prune)
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
code --install-extension VKrishna04.dev-prune
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Open VSX is the same extension for the editors that cannot reach Microsoft's marketplace —
|
|
203
|
+
VSCodium, Cursor, Windsurf, Positron, Kiro. You do not have to pick: `devp setup` offers
|
|
204
|
+
to install it once, at a terminal, into whichever of those it finds, each from its own
|
|
205
|
+
registry.
|
|
206
|
+
|
|
207
|
+
**JetBrains IDEs need no extension at all.** The config schema is registered with
|
|
208
|
+
[SchemaStore](https://www.schemastore.org/), so IntelliJ, PyCharm, WebStorm, GoLand,
|
|
209
|
+
RubyMine and Rider validate `.devprune.json` out of the box — as do Visual Studio, Neovim
|
|
210
|
+
and Zed.
|
|
211
|
+
|
|
212
|
+
**And your coding agent gets the same treatment.** `devp skill --agent <editor>` writes the
|
|
213
|
+
rules file that editor actually reads — `.github/copilot-instructions.md`, `.cursor/rules/`,
|
|
214
|
+
`CLAUDE.md`, `.junie/guidelines.md` and the rest — so an agent working in the repository
|
|
215
|
+
knows what dev-prune will and will not delete before it suggests anything.
|
|
216
|
+
|
|
217
|
+
Everything about editors, in one place:
|
|
218
|
+
[docs/IDE_INTEGRATION.md](docs/IDE_INTEGRATION.md).
|
|
219
|
+
|
|
220
|
+
### Let an AI assistant do it
|
|
221
|
+
|
|
222
|
+
Copy the prompt below and paste it to Claude Code, Cursor, GitHub Copilot, Windsurf, or
|
|
223
|
+
any terminal-capable agent — it installs, verifies, and registers your projects for you.
|
|
224
|
+
[More detail and per-tool notes.](docs/AI_SETUP_PROMPT.md)
|
|
225
|
+
|
|
226
|
+
````text
|
|
227
|
+
Install and set up `dev-prune` (binary name `devp`), a lockfile-safe workspace cleaner,
|
|
228
|
+
on this machine. Follow these steps exactly and do not improvise beyond them.
|
|
229
|
+
|
|
230
|
+
1. Detect the OS and run the matching official installer, nothing else:
|
|
231
|
+
- macOS or Linux:
|
|
232
|
+
curl -fsSL https://devprune.vkrishna04.me/install.sh | sh
|
|
233
|
+
- Windows (PowerShell):
|
|
234
|
+
iwr -useb https://devprune.vkrishna04.me/install.ps1 | iex
|
|
235
|
+
- If a Rust toolchain is already present and you cannot reach the network, you may
|
|
236
|
+
instead run: cargo install dev-prune
|
|
237
|
+
Do NOT download binaries from anywhere other than devprune.vkrishna04.me or the
|
|
238
|
+
project's GitHub releases, and do NOT edit PATH, the registry, or any OS scheduler by
|
|
239
|
+
hand — the installer and `devp setup` do all of that themselves.
|
|
240
|
+
|
|
241
|
+
2. Open a NEW terminal (so the updated PATH is in effect) and verify:
|
|
242
|
+
devp --version
|
|
243
|
+
devp doctor
|
|
244
|
+
`devp doctor` must exit 0. If it prints warnings, read them out to me; do not try to
|
|
245
|
+
"fix" the scheduler or hooks yourself — they are self-installing.
|
|
246
|
+
|
|
247
|
+
3. Ask me which project directories to keep clean, then register each one:
|
|
248
|
+
devp init <path>
|
|
249
|
+
Do not register directories I did not name. `devp init` only records a directory; it
|
|
250
|
+
never deletes anything on its own.
|
|
251
|
+
|
|
252
|
+
4. Show me the result and stop:
|
|
253
|
+
devp status
|
|
254
|
+
|
|
255
|
+
Notes you should rely on, not work around:
|
|
256
|
+
- Installation already registered a background pass (every 2 days) and, on Windows, a
|
|
257
|
+
windowless task that never flashes a console window. You do not need to configure any
|
|
258
|
+
of this.
|
|
259
|
+
- Nothing is ever deleted unless a lockfile can rebuild it, the repo has been idle past
|
|
260
|
+
the threshold, and (interactively) I confirm. Run `devp run --dry-run` if I want a
|
|
261
|
+
preview.
|
|
262
|
+
- To undo the whole thing later: `devp uninstall`.
|
|
263
|
+
````
|
|
264
|
+
|
|
265
|
+
Every install channel in detail: [docs/DISTRIBUTION.md](docs/DISTRIBUTION.md).
|
|
266
|
+
|
|
267
|
+
> [!TIP]
|
|
268
|
+
> **`devp` is a real executable, not a shell alias.** Installation puts a second binary
|
|
269
|
+
> next to `dev-prune`, so the short name works in cmd, PowerShell, bash, fish, an IDE
|
|
270
|
+
> terminal and a scheduled task alike — with no profile to re-source, and no chance of an
|
|
271
|
+
> upgrade leaving `devp` on the old version.
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## 60-second tour
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
devp init ~/Projects # register every Git repository under a tree
|
|
279
|
+
devp status # dashboard: what is tracked, what is reclaimable
|
|
280
|
+
devp run --dry-run # what a pass would delete — changes nothing
|
|
281
|
+
devp run # do it, after confirming
|
|
282
|
+
devp restore --last-run # put back exactly what that pass deleted
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
A few more worth knowing on day one:
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
devp stats # how much has been reclaimed so far, and by which repositories
|
|
289
|
+
devp caches # every package manager cache, sized. The report deletes nothing
|
|
290
|
+
devp status --drift # anything installed that the lockfiles don't record?
|
|
291
|
+
devp doctor . # why is this repository not being pruned?
|
|
292
|
+
devp doctor --fix # repair a broken integration — never a first-time install
|
|
293
|
+
devp -V # version, OS, architecture, config path, PATH audit
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
## What it looks like
|
|
299
|
+
|
|
300
|
+
<details open>
|
|
301
|
+
<summary><b><code>devp run --dry-run</code></b> — the plan, before anything is touched</summary>
|
|
302
|
+
|
|
303
|
+
```console
|
|
304
|
+
$ devp run --dry-run
|
|
305
|
+
|
|
306
|
+
dev-prune run (DRY RUN)
|
|
307
|
+
→ Scanning 4 registered repositories for prune candidates...
|
|
308
|
+
|
|
309
|
+
Prune Candidates & Space Savings Calculation
|
|
310
|
+
→ • ~/Code/acme-api → node_modules (412.7 MiB) [pnpm]
|
|
311
|
+
→ • ~/Code/acme-api → services/worker/.venv (188.2 MiB) [uv]
|
|
312
|
+
→ • ~/Code/render-farm → target (2.14 GiB) [cargo]
|
|
313
|
+
→ • ~/Code/edge-proxy → vendor (96.4 MiB) [go]
|
|
314
|
+
|
|
315
|
+
Summary (Dry Run)
|
|
316
|
+
→ Would free 2.82 GiB across 4 bloat directories.
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
</details>
|
|
320
|
+
|
|
321
|
+
<details>
|
|
322
|
+
<summary><b><code>devp status</code></b> — the dashboard, or a plain table with no TTY</summary>
|
|
323
|
+
|
|
324
|
+
```console
|
|
325
|
+
$ devp status
|
|
326
|
+
|
|
327
|
+
→ Global Config Location: ~/.config/dev-prune/registry.json
|
|
328
|
+
→ Background OS Daemon: Installed
|
|
329
|
+
→ Background Git Hooks: Installed
|
|
330
|
+
→ Global Command Timeout: 600s (10m)
|
|
331
|
+
→ Tracked Repositories: 4
|
|
332
|
+
→ Historical Space Saved: 6.31 GiB across 9 prune passes
|
|
333
|
+
|
|
334
|
+
dev-prune status
|
|
335
|
+
|
|
336
|
+
# Repository Status / Reason Adapters Bloat Last Activity Last Pruned
|
|
337
|
+
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
|
|
338
|
+
1 acme-api Candidate pnpm+uv 600.9 MiB 2026-04-02 Never
|
|
339
|
+
2 render-farm Candidate cargo 2.14 GiB 2026-03-11 2026-01-08
|
|
340
|
+
3 edge-proxy Candidate go 96.4 MiB 2026-05-19 Never
|
|
341
|
+
4 dashboard Active (not idle) npm 314.0 MiB 2026-08-12 2026-06-30
|
|
342
|
+
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
|
|
343
|
+
→ Total: 4 repos | 3 candidates | 3.13 GiB reclaimable
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Keys: `↑`/`↓` move, `p` pre-selects every candidate, `Space` deselects the one you are
|
|
347
|
+
keeping, `Enter` prunes the rest, `i` toggles ignore for a repository, `q` exits.
|
|
348
|
+
|
|
349
|
+
</details>
|
|
350
|
+
|
|
351
|
+
<details>
|
|
352
|
+
<summary><b><code>devp caches</code></b> — where the rest of the disk went</summary>
|
|
353
|
+
|
|
354
|
+
```console
|
|
355
|
+
$ devp caches
|
|
356
|
+
|
|
357
|
+
Package manager caches
|
|
358
|
+
|
|
359
|
+
npm cache 9.98 GiB ~/.npm
|
|
360
|
+
clear: npm cache clean --force
|
|
361
|
+
npm is used by 18 of 46 registered repositories · 567.75 MiB each
|
|
362
|
+
|
|
363
|
+
uv cache 6.22 GiB ~/.cache/uv
|
|
364
|
+
clear: uv cache prune
|
|
365
|
+
uv is used by 7 of 46 registered repositories · 909.77 MiB each
|
|
366
|
+
|
|
367
|
+
pnpm store 2.07 GiB /mnt/data/.pnpm-store
|
|
368
|
+
clear: pnpm store prune --store-dir /mnt/data/.pnpm-store
|
|
369
|
+
one store per filesystem, because a hardlink into node_modules cannot cross one
|
|
370
|
+
pnpm is used by 1 of 46 registered repositories · 2.09 GiB each
|
|
371
|
+
|
|
372
|
+
nuget global packages 1.44 GiB ~/.nuget/packages
|
|
373
|
+
clear: dotnet nuget locals global-packages --clear
|
|
374
|
+
every .NET project on the machine restores from here; re-downloaded on the next restore
|
|
375
|
+
|
|
376
|
+
… (pip, bun, both go caches, gradle wrapper distributions, both cargo
|
|
377
|
+
registry caches, and the pnpm store beside your home directory)
|
|
378
|
+
|
|
379
|
+
Total 21.99 GiB across 12 caches
|
|
380
|
+
|
|
381
|
+
→ Nothing above was deleted, and dev-prune never deletes any of it.
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
A cache lives outside every repository and is shared by all of them, so no single
|
|
385
|
+
lockfile can prove it recoverable — and it is what makes `devp restore` fast. `devp
|
|
386
|
+
caches` reports and prints the clear command; running it is your decision.
|
|
387
|
+
|
|
388
|
+
pnpm gets a row per filesystem rather than a single row. It hardlinks its store into
|
|
389
|
+
every `node_modules` it fills, and a hardlink cannot cross a filesystem, so projects
|
|
390
|
+
kept off the system disk have a store of their own at the root of *that* filesystem —
|
|
391
|
+
`V:\.pnpm-store` on a second Windows drive, `/mnt/data/.pnpm-store` on Linux,
|
|
392
|
+
`/Volumes/Work/.pnpm-store` on macOS. `pnpm store path` only ever answers for the
|
|
393
|
+
filesystem it is run on, so dev-prune looks at the root of every filesystem that holds
|
|
394
|
+
a registered repository, and each such row names its store in the command it prints.
|
|
395
|
+
|
|
396
|
+
</details>
|
|
397
|
+
|
|
398
|
+
<details>
|
|
399
|
+
<summary><b><code>devp doctor .</code></b> — the one reason a repository is being skipped</summary>
|
|
400
|
+
|
|
401
|
+
```console
|
|
402
|
+
$ devp doctor .
|
|
403
|
+
|
|
404
|
+
dev-prune doctor (~/Code/dashboard)
|
|
405
|
+
|
|
406
|
+
Repository
|
|
407
|
+
Git repository ✓ yes
|
|
408
|
+
Registered ✓ yes, since 2026-04-11
|
|
409
|
+
.devprune.json parses; idle_days 20
|
|
410
|
+
Opt-out none
|
|
411
|
+
Activity 2026-08-12 (0 days ago), threshold 20 — active
|
|
412
|
+
Size floor none — every recognised directory counts
|
|
413
|
+
Scan depth 6 levels below the root
|
|
414
|
+
|
|
415
|
+
Projects
|
|
416
|
+
|
|
417
|
+
. (npm)
|
|
418
|
+
Lockfile ✓ package-lock.json present
|
|
419
|
+
Bloat ✓ node_modules (314.0 MiB)
|
|
420
|
+
|
|
421
|
+
Verdict
|
|
422
|
+
✗ Would `devp run` prune this? No — active within the last 20 days.
|
|
423
|
+
`devp --ignore-idle run ~/Code/dashboard` overrides exactly that check and nothing else.
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
It runs no package manager and repairs nothing, so it is safe to run twice — once to see
|
|
427
|
+
the problem, once to confirm the fix. Without a path it audits the installation instead:
|
|
428
|
+
binary location and `PATH`, the registry and every setting in it, the integrations, which
|
|
429
|
+
package managers are reachable, and the release-check state.
|
|
430
|
+
|
|
431
|
+
|
|
432
|
+
|
|
433
|
+
</details>
|
|
434
|
+
|
|
435
|
+
---
|
|
436
|
+
|
|
437
|
+
## Why it is safe
|
|
438
|
+
|
|
439
|
+
Seven invariants, enforced in code rather than by convention, none of which has a bypass
|
|
440
|
+
flag. Full detail and the reasoning behind each in
|
|
441
|
+
[docs/SAFETY_INVARIANTS.md](docs/SAFETY_INVARIANTS.md).
|
|
442
|
+
|
|
443
|
+
| # | Invariant | What it prevents |
|
|
444
|
+
| :---: | :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
|
|
445
|
+
| 1 | **`.git` boundary** — only ever operates inside a directory holding a `.git` root | Deleting a `node_modules` that belongs to no repository and has no lockfile behind it |
|
|
446
|
+
| 2 | **Lockfile pre-verification** — the ecosystem's own read-only check must pass first | Deleting a tree whose lockfile has drifted, leaving a reinstall that fails |
|
|
447
|
+
| 3 | **Hybrid activity solver** — the later of the last commit and the newest source `mtime` | Pruning a project with a week of uncommitted work in it |
|
|
448
|
+
| 4 | **Atomic state writes** — write to a temp file, then rename | A registry corrupted by a crash or a power cut mid-write |
|
|
449
|
+
| 5 | **0ms ignore fast path** — `ignore.devprune.json` short-circuits before any parsing | A repository you opted out of being scanned at all |
|
|
450
|
+
| 6 | **Symlink and junction refusal** | Following a link out of the repository and deleting storage it does not own |
|
|
451
|
+
| 7 | **Nested repository boundary** | A submodule being deleted as part of its parent instead of on its own terms |
|
|
452
|
+
|
|
453
|
+
Verification is **read-only by default**: `npm ci --dry-run`, `uv lock --locked`, `cargo
|
|
454
|
+
metadata --locked`, `go mod download`. Each resolves the dependency graph against the
|
|
455
|
+
lockfile on disk and *fails* when the two disagree, instead of quietly rewriting the
|
|
456
|
+
lockfile and continuing. The writing form runs in exactly two cases — when no lockfile
|
|
457
|
+
exists at all, and when you have asked with `devp config set allow_manifest_rewrite true`
|
|
458
|
+
— because a pass can be started by the OS scheduler while you are away, and a background
|
|
459
|
+
process that leaves a dirty working tree is a surprise.
|
|
460
|
+
|
|
461
|
+
---
|
|
462
|
+
|
|
463
|
+
## Features
|
|
464
|
+
|
|
465
|
+
| What you get | What it means in practice |
|
|
466
|
+
| :-------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
467
|
+
| 🔒 **Lockfile-gated deletion** | Nothing goes without a passing read-only verification against `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `uv.lock`, `requirements.txt`, `Cargo.lock` or `go.sum` |
|
|
468
|
+
| 🧩 **Any number of ecosystems per repository** | uv, npm and cargo in one root, or spread across `frontend/`, `services/api/` and `tools/cli/` — each discovered, verified and pruned on its own terms |
|
|
469
|
+
| ↩️ **One-command restore** | `devp restore .` reinstalls a tree; `devp restore --last-run` puts back exactly what the most recent pass deleted, across every repository it touched |
|
|
470
|
+
| 🕒 **Activity-aware** | Combines `git log` timestamps with source-file `mtime`, so uncommitted work protects a repository just as a commit does |
|
|
471
|
+
| 📊 **Cache report** | `devp caches` sizes every package manager cache and store on the machine — npm to cargo to conda, Maven, Gradle, NuGet, vcpkg, Conan, Composer, CocoaPods and Hex — and prints the command that clears each. The report is read-only; `devp caches clear <manager>` runs that command for you, after asking. `devp config set cache_max_gb uv=10,npm=10` says how big is too big, per manager, and marks the ones past it — `devp caches clear --over-cap all` then empties exactly those, still only when you type it. Each manager also says how many of your registered repositories use it and what that works out to per repository, and `devp caches clear --unused all` empties the ones nothing uses at all. pnpm is reported once per filesystem, because a store it hardlinks into `node_modules` cannot cross one and projects kept off the system disk get a store of their own. Nothing on a schedule ever touches a cache, and Maven's `~/.m2/repository` is never cleared at all — it holds artifacts `mvn install:install-file` put there that no remote can hand back |
|
|
472
|
+
| 🩺 **`devp doctor`** | One read-only pass that ends by naming the *single* reason a repository would or would not be pruned. Runs no package manager, repairs nothing, safe to run twice. `devp doctor --fix` then mends what it found — installed-but-broken only |
|
|
473
|
+
| 🤖 **Self-installing automation** | OS-native scheduler (Task Scheduler, LaunchAgent, systemd user timer) and non-blocking Git hooks, installed at install time and restored after an upgrade. `auto_setup`, `auto_hooks`, `auto_daemon` or `DEV_PRUNE_NO_AUTO_SETUP=1` turn it off |
|
|
474
|
+
| ⚡ **0ms opt-out** | An `ignore.devprune.json` in a repository root is honoured by file presence alone — no read, no parse |
|
|
475
|
+
| 🔌 **`--json` on every reporting command** | `run`, `status`, `stats`, `trust` and `caches` each emit one versioned document on stdout, diagnostics on stderr. Built for scripts and agents |
|
|
476
|
+
| 🧠 **AI agent skill** | A token-lean `SKILL.md` embedded in the binary; `devp skill` exports it and prints onboarding prompts for Claude Code, Gemini Antigravity, Cursor, Windsurf, Copilot and OpenClaw |
|
|
477
|
+
| 🧰 **Editor extension** | Validates `.devprune.json` as you type and shows the workspace's reclaimable size in the status bar. `devp setup` offers to install it — once, only at a terminal — into VS Code, VSCodium, Cursor, Windsurf, Positron or Kiro, each from its own registry with the release `.vsix` as fallback. [docs/IDE_INTEGRATION.md](docs/IDE_INTEGRATION.md) |
|
|
478
|
+
| 🖼️ **File manager icons** | `devp icon` registers `*.devprune.json` with the OS file manager — a real `shared-mime-info` type plus hicolor icons on Linux, a folder icon on Windows. It never edits your editor settings, `PATH` or shell startup files |
|
|
479
|
+
| 🌏 **Unicode-safe paths** | A repository at `ワークスペース/项目目录名称测试/프론트엔드` scans, verifies, prunes and restores exactly like an ASCII one, on all three platforms. Terminal tables are padded by display *column*, not by character, so full-width CJK names keep `devp status` and `devp doctor` aligned. Accented Latin, Cyrillic, Arabic and emoji directory names too |
|
|
480
|
+
| 🚫 **No telemetry** | One optional unauthenticated `GET` to GitHub's public releases endpoint, at most weekly, no body and no identifier. Nothing else leaves the machine |
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
## Commands
|
|
485
|
+
|
|
486
|
+
| Command | Also | What it does |
|
|
487
|
+
| :--------------------- | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
488
|
+
| `devp init [PATHS]` | `scan`, `onboard` | Crawls directory trees for Git repositories and registers them, then runs the `setup` integration pass |
|
|
489
|
+
| `devp link [PATH]` | :------------------------------------------------------------------ | Registers one repository |
|
|
490
|
+
| `devp unlink [PATH]` | `--missing` | Unregisters one; `--missing` drops every entry whose directory is gone, in one pass |
|
|
491
|
+
| `devp undo` | :------------------------------------------------------------------ | Reverts the most recent `init` or `link` |
|
|
492
|
+
| `devp run [PATH]` | `--dry-run`, `--only`, `--skip`, `--except`, `--min-size`, `--json` | Prunes every registered repository, or one target |
|
|
493
|
+
| `devp status` | `--top N`, `--drift`, `--json` | Interactive dashboard; a plain table when there is no TTY. `--top N` shows only the N biggest repositories; `--drift` lists every environment holding packages its lockfile never recorded |
|
|
494
|
+
| `devp stats` | `--json` | What has already been reclaimed: lifetime total, prune passes, the last pass, and the biggest contributors |
|
|
495
|
+
| `devp completions` | `bash`, `zsh`, `fish`, `powershell`, `elvish` | Prints a shell completion script to stdout, generated from the same argument definitions the binary parses with |
|
|
496
|
+
| `devp caches` | `clear <manager\|all>`, `--json` | Sizes every package manager cache on the machine and prints the command that clears each. The report deletes nothing and nothing on a schedule ever will; `clear` empties one when you type it, after asking |
|
|
497
|
+
| `devp trust` | `--json` | What dev-prune may do on this machine: the guarantees the code enforces, then the scheduler, hooks and settings read live. Read-only |
|
|
498
|
+
| `devp restore [PATH]` | `--last-run` | Reinstalls dependencies for every project in a tree; `--last-run` undoes the last prune pass |
|
|
499
|
+
| `devp doctor [PATH]` | `--fix` | Diagnoses the installation, or one repository — ending with the single reason a pass would or would not touch it. `--fix` repairs what the checks found; it never performs a first-time install |
|
|
500
|
+
| `devp config [ACTION]` | `get`, `set`, `show`, `wizard`, `project`, `daemon`, `hook`, `icon` | Global settings, per-repository `.devprune.json`, scheduler, Git hooks, file manager icons |
|
|
501
|
+
| `devp setup` | `--status` | Installs any missing integration; `--status` only reports |
|
|
502
|
+
| `devp update` | `--offline`, `--install` | Prints the installed version, checks GitHub for a newer release, shows the upgrade command for your install channel; `--install` runs that upgrade through the channel that owns this copy |
|
|
503
|
+
| `devp skill` | `--agent <editor>` | Exports `SKILL.md` and prints AI agent onboarding prompts; `--agent` writes per-repository rules for 16 editors — Cursor, Windsurf, Antigravity, Cline, Roo, Kilo Code, Continue, Amazon Q, Kiro, Trae, Junie, Gemini CLI, Zed, Copilot, Aider or `AGENTS.md` |
|
|
504
|
+
| `devp man` | `--dir <dir>` | The manual as man pages, generated from the same argument definitions `--help` prints; alone it emits `devp(1)` to stdout, `--dir` writes the full set |
|
|
505
|
+
| `devp uninstall` | `--deep` | Removes the scheduler, hooks, both binaries and every other installed copy it can find on the machine; `--deep` also clears configuration |
|
|
506
|
+
| `devp -V` | :------------------------------------------------------------------ | Version plus an environment audit: OS, architecture, config path, PATH activation |
|
|
507
|
+
|
|
508
|
+
`devp hook`, `devp daemon` and `devp icon` are shorthands for the `config` subcommands of
|
|
509
|
+
the same name, and `install` / `uninstall` / `on` / `off` work wherever `enable` /
|
|
510
|
+
`disable` do — so `devp hook install` and `devp config hook enable` are the same command.
|
|
511
|
+
A misspelled action is rejected rather than quietly reported as status.
|
|
512
|
+
|
|
513
|
+
`--help` is the manual: every command and every `config` subcommand carries long-form
|
|
514
|
+
help with worked examples — `devp run --help`, `devp config hook --help`, and so on at
|
|
515
|
+
every level — while `-h` keeps the short version.
|
|
516
|
+
|
|
517
|
+
Exit codes are a contract: `0` success, `1` failure, `2` unusable arguments. Full flag
|
|
518
|
+
list, every setting and the `--json` schema: **[docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)**.
|
|
519
|
+
|
|
520
|
+
---
|
|
521
|
+
|
|
522
|
+
## Supported ecosystems
|
|
523
|
+
|
|
524
|
+
Adapters detect the project, verify the lockfile, and own the bloat directories:
|
|
525
|
+
|
|
526
|
+
| Ecosystem | Detected by | Bloat | Verification (read-only) | Restore |
|
|
527
|
+
| :---------------------------- | :------------------------------------------------------------ | :----------------------------------------- | :---------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------- |
|
|
528
|
+
| **npm** | `package-lock.json` | `node_modules` | `npm ci --dry-run --ignore-scripts` | `npm ci` |
|
|
529
|
+
| **pnpm** | `pnpm-lock.yaml` | `node_modules` | `pnpm install --lockfile-only --frozen-lockfile` | `pnpm install --frozen-lockfile` |
|
|
530
|
+
| **Yarn** | `yarn.lock` | `node_modules` | `yarn install --immutable --mode update-lockfile` (Berry); on Classic an existing `yarn.lock` is itself the proof | `yarn install --immutable` |
|
|
531
|
+
| **Bun** | `bun.lockb`, `bun.lock` | `node_modules` | `bun install --frozen-lockfile --dry-run --ignore-scripts` | `bun install --frozen-lockfile` |
|
|
532
|
+
| **uv** (Python) | `uv.lock`, `[tool.uv]` in `pyproject.toml` | `.venv` | `uv lock --locked` | `uv sync` |
|
|
533
|
+
| **Poetry** (Python) | `poetry.lock`, `[tool.poetry]` in `pyproject.toml` | `.venv` | `poetry check --lock`, plus no installed package the lockfile never recorded | `poetry install` |
|
|
534
|
+
| **PDM** (Python) | `pdm.lock`, `[tool.pdm]` or `pdm.backend` in `pyproject.toml` | `.venv`, `__pypackages__` | `pdm lock --check` | `pdm install` |
|
|
535
|
+
| **Pipenv** (Python) | `Pipfile` | `.venv` *(in-project installs only)* | `pipenv verify` | `pipenv install --deploy` |
|
|
536
|
+
| **venv** (Python) | `requirements.txt` + a directory containing `pyvenv.cfg` | every directory containing `pyvenv.cfg` | `requirements.txt` must exist and list at least one package | `python -m venv .venv && pip install -r requirements.txt` |
|
|
537
|
+
| **Cargo** (Rust) *(opt-in)* | `Cargo.toml` | `target` | `cargo metadata --locked` | *(rebuilt by the next `cargo build`)* |
|
|
538
|
+
| **Go** | `go.mod` | `vendor` | `go mod download` | `go mod vendor` |
|
|
539
|
+
| **Composer** (PHP) | `composer.json` | `vendor` | `composer validate --no-check-publish --no-check-all` | `composer install` |
|
|
540
|
+
| **Bundler** (Ruby) | `Gemfile` | `vendor/bundle` *(vendored installs only)* | `bundle lock --check` | `bundle install` |
|
|
541
|
+
| **CocoaPods** (Apple) | `Podfile` | `Pods` | `Podfile.lock` carries its `SPEC CHECKSUMS` section and is no older than the `Podfile` | `pod install` |
|
|
542
|
+
| **Mix** (Elixir) | `mix.exs` | `deps` | `mix.lock` is a complete Elixir map and no older than `mix.exs` | `mix deps.get` |
|
|
543
|
+
| **Terraform** | any `*.tf` / `*.tf.json` | `.terraform/providers` | `.terraform.lock.hcl` records at least one provider | `terraform init -backend=false` |
|
|
544
|
+
| **Gradle** *(opt-in)* | `build.gradle[.kts]`, `settings.gradle[.kts]` | `build`, `.gradle` | manifest present and readable — the rebuild-from-source proof | *(rebuilt by the next `./gradlew build`)* |
|
|
545
|
+
| **Maven** *(opt-in)* | `pom.xml` | `target` | `pom.xml` parses as a Maven manifest | *(rebuilt by the next `mvn package`)* |
|
|
546
|
+
| **SwiftPM** *(opt-in)* | `Package.swift` | `.build` | `Package.swift` declares a `Package(` — the rebuild-from-source proof | *(rebuilt by the next `swift build`)* |
|
|
547
|
+
| **Dart / Flutter** *(opt-in)* | `pubspec.yaml` | `.dart_tool` | `pubspec.lock` has a `packages:` section and is no older than `pubspec.yaml` | `dart pub get` / `flutter pub get` |
|
|
548
|
+
| **Mix `_build/`** *(opt-in)* | `mix.exs` | `_build` | `mix.exs` and `mix.lock` both present — the rebuild-from-source proof | *(rebuilt by the next `mix compile`)* |
|
|
549
|
+
| **vcpkg** (C/C++) *(opt-in)* | `vcpkg.json` | `vcpkg_installed` | `vcpkg.json` declares a non-empty `dependencies` list | *(rebuilt by the next `vcpkg install`)* |
|
|
550
|
+
| **CMake** (C/C++) *(opt-in)* | `CMakeLists.txt` | any tree holding a `CMakeCache.txt` | the tree's own `CMakeCache.txt` names a source directory inside this repository | *(rebuilt by the next `cmake --build`)* |
|
|
551
|
+
|
|
552
|
+
A required binary that is missing is a reason to skip, never a reason to delete: if `npm`
|
|
553
|
+
is not on `PATH`, the `node_modules` it owns is left exactly where it is.
|
|
554
|
+
|
|
555
|
+
The eight build-tool adapters ship **disabled**, because a build tree is regenerated
|
|
556
|
+
by recompiling, not downloading — it costs more to get back. `devp config set
|
|
557
|
+
enable_cargo true` / `enable_gradle true` / `enable_maven true` / `enable_swift true` /
|
|
558
|
+
`enable_dart true` / `enable_mix_build true` / `enable_vcpkg true` /
|
|
559
|
+
`enable_cmake_build true` switches them on, and their candidates wait for
|
|
560
|
+
`build_idle_days` (45 by default), applied as the *maximum* of it and `idle_days` — the
|
|
561
|
+
build-tool gate only ever makes pruning later, never earlier.
|
|
562
|
+
|
|
563
|
+
Any one adapter can be made to wait longer than the rest: `devp config set
|
|
564
|
+
adapter_idle_days cargo=90,npm=30` sets a per-adapter floor, applied as
|
|
565
|
+
`max(idle_days, build_idle_days, adapter_idle_days[name])`. `devp config wizard` edits
|
|
566
|
+
it beside the adapter checklist, grouped by language, where one heading sets the same
|
|
567
|
+
window for every adapter under it.
|
|
568
|
+
|
|
569
|
+
A download cache is a bet that re-downloading costs less than the disk it occupies,
|
|
570
|
+
and somewhere the bet stops paying. `devp config set cache_max_gb uv=10,npm=10` is
|
|
571
|
+
where you say where: a ceiling in gibibytes, per manager, measured against that
|
|
572
|
+
manager's whole footprint. A manager over its cap is **marked** in `devp caches` —
|
|
573
|
+
setting one deletes nothing — and `devp caches clear --over-cap all` empties exactly
|
|
574
|
+
what is marked, when you type it. It is keyed by the names `devp caches clear` takes
|
|
575
|
+
(`npm`, `pnpm`, `uv`, `pip`, `cargo`, `go`, `nuget`, …) rather than by adapter name,
|
|
576
|
+
because the two lists overlap without either containing the other. Empty by default:
|
|
577
|
+
no cache is too big until you say what too big is. The wizard sets caps as a third
|
|
578
|
+
column on the same checklist.
|
|
579
|
+
|
|
580
|
+
The report answers one more question the disk cannot: *who still needs this*. Beside each
|
|
581
|
+
manager it says how many of your registered repositories use it, and what its cache works
|
|
582
|
+
out to per repository — two repositories sharing a 12 GiB cache is 6 GiB each and worth a
|
|
583
|
+
look, forty sharing the same 12 GiB is 300 MiB each and is the cache doing its job. A
|
|
584
|
+
manager **no** registered repository uses is the one case where a count is enough to act
|
|
585
|
+
on: everything in it was downloaded for projects that are not on this disk any more, so
|
|
586
|
+
`devp caches clear --unused all` costs no re-download for anything you still have. The
|
|
587
|
+
count ignores whether an adapter is switched on, because the question is which managers
|
|
588
|
+
your projects *use*, not which ones a prune pass would touch, and it is shown only for the
|
|
589
|
+
managers that are also adapter names — `pip`, `conda`, `nuget`, `conan` and `hex` get
|
|
590
|
+
no number rather than a guess. With nothing registered, nothing is counted and
|
|
591
|
+
`--unused` refuses to run.
|
|
592
|
+
|
|
593
|
+
Bundler and Pipenv claim only the install that lives *inside* the repository: the
|
|
594
|
+
`vendor/bundle` a project gets from `bundle config set path vendor/bundle`, and the
|
|
595
|
+
`.venv` that appears when `PIPENV_VENV_IN_PROJECT` is set. Both tools default to a
|
|
596
|
+
shared store under your home directory instead, and dev-prune does not go near those at
|
|
597
|
+
all: a shared gem home or virtualenv directory is where other projects' dependencies are
|
|
598
|
+
*installed*, not a cache, and no single lockfile could prove its contents recoverable.
|
|
599
|
+
For the same reason Composer leaves `vendor/` alone entirely when a `vendor/bundle` is
|
|
600
|
+
sitting inside it: no `composer install` puts those gems back.
|
|
601
|
+
|
|
602
|
+
Any adapter can be switched off outright with `devp config set disabled_adapters
|
|
603
|
+
<names>` — a disabled adapter is not detected, not counted by `stats`, not probed
|
|
604
|
+
for by `doctor` and never pruned, exactly as if that ecosystem were not installed.
|
|
605
|
+
|
|
606
|
+
> [!TIP]
|
|
607
|
+
> Adding an ecosystem is documented end to end in
|
|
608
|
+
> [docs/ADDING_ADAPTERS.md](docs/ADDING_ADAPTERS.md) — trait, registration, tests.
|
|
609
|
+
|
|
610
|
+
### Repositories with more than one ecosystem
|
|
611
|
+
|
|
612
|
+
A repository is not assumed to be one project. dev-prune walks the root and up to
|
|
613
|
+
`scan_depth` levels below it — six by default, `devp config set scan_depth N` to change
|
|
614
|
+
it, or `"scan_depth"` in a repository's `.devprune.json` for just that tree. Every
|
|
615
|
+
directory a package manager recognises is verified and pruned on its own terms. All three
|
|
616
|
+
of these work:
|
|
617
|
+
|
|
618
|
+
```
|
|
619
|
+
monorepo/ monorepo/ monorepo/
|
|
620
|
+
├── package-lock.json ├── frontend/ ├── Cargo.toml
|
|
621
|
+
├── uv.lock │ └── pnpm-lock.yaml ├── web/
|
|
622
|
+
└── Cargo.toml ├── services/api/ │ └── package-lock.json
|
|
623
|
+
│ └── uv.lock └── scripts/
|
|
624
|
+
three managers, one root └── tools/cli/ └── requirements.txt
|
|
625
|
+
└── Cargo.toml
|
|
626
|
+
root + nested, mixed
|
|
627
|
+
one manager per subtree
|
|
628
|
+
```
|
|
629
|
+
|
|
630
|
+
Results are reported by repository-relative path, so a monorepo reads unambiguously:
|
|
631
|
+
|
|
632
|
+
```
|
|
633
|
+
• MyMonorepo → frontend/node_modules (412.7 MiB) [pnpm]
|
|
634
|
+
• MyMonorepo → services/api/.venv (188.2 MiB) [uv]
|
|
635
|
+
• MyMonorepo → tools/cli/target (1.4 GiB) [cargo]
|
|
636
|
+
```
|
|
637
|
+
|
|
638
|
+
The walk never descends into `node_modules`, `target`, `vendor`, virtual environments,
|
|
639
|
+
hidden directories, or nested repositories — a submodule is pruned as itself, never as
|
|
640
|
+
part of its parent.
|
|
641
|
+
|
|
642
|
+
When npm, pnpm, yarn and bun all claim the same `node_modules`, exactly one is chosen,
|
|
643
|
+
strongest signal first:
|
|
644
|
+
|
|
645
|
+
1. the `packageManager` field in `package.json`,
|
|
646
|
+
2. the bookkeeping files inside the installed tree (`node_modules/.pnpm`,
|
|
647
|
+
`.yarn-state.yml`, `.package-lock.json`) — whoever built what is actually on disk,
|
|
648
|
+
3. the most recently written lockfile.
|
|
649
|
+
|
|
650
|
+
For Python, uv or Poetry takes the environment whenever it recognises the project —
|
|
651
|
+
between the two, whichever one's lockfile is actually on disk wins — and the
|
|
652
|
+
`requirements.txt` adapter handles everything else.
|
|
653
|
+
|
|
654
|
+
---
|
|
655
|
+
|
|
656
|
+
## Configuration
|
|
657
|
+
|
|
658
|
+
Global settings live in `%APPDATA%\dev-prune` (Windows),
|
|
659
|
+
`~/Library/Application Support/dev-prune` (macOS) and `$XDG_CONFIG_HOME/dev-prune`
|
|
660
|
+
(Linux). `devp config wizard` opens all of them in a full-screen configurator, and runs itself
|
|
661
|
+
once on a first install — so the defaults are something you agreed to rather than
|
|
662
|
+
inherited — and again after an upgrade adds a setting you have never been shown.
|
|
663
|
+
|
|
664
|
+
| Key | Default | Meaning |
|
|
665
|
+
| :--------------------------------------------------------------------------------- | :-------: | :---------------------------------------------------------------------------------- |
|
|
666
|
+
| `idle_days` | `15` | How long a repository must be untouched to become a candidate |
|
|
667
|
+
| `min_size_mb` | `0` | Smallest bloat directory worth deleting; `0` disables the floor |
|
|
668
|
+
| `scan_depth` | `6` | Levels below a repository root that discovery descends |
|
|
669
|
+
| `require_confirmation` | `true` | Whether a pass asks before deleting |
|
|
670
|
+
| `allow_manifest_rewrite` | `false` | Whether verification may *repair* a drifted lockfile instead of refusing |
|
|
671
|
+
| `command_timeout_secs` | `600` | Ceiling on any one package manager command |
|
|
672
|
+
| `auto_setup` · `auto_daemon` · `auto_hooks` | `true` | Whether the integration pass may run unattended, and what it may install |
|
|
673
|
+
| `auto_hooks_chain` | `false` | Whether it may take a `core.hooksPath` another tool holds, forwarding every hook on |
|
|
674
|
+
| `check_interval_days` | `2` | How often the OS scheduler runs a pass |
|
|
675
|
+
| `update_check` | `true` | Whether the periodic release check runs |
|
|
676
|
+
| `update_check_interval_days` · `update_check_timeout_secs` | `7` · `5` | Minimum gap between checks, and how long one may hang |
|
|
677
|
+
| `enable_cargo` … `enable_cmake_build` | `false` | Turn on an opt-in build-tool adapter; `build_idle_days` (`45`) gates all eight |
|
|
678
|
+
| `adapter_idle_days` | *(none)* | Per-adapter idle floors, as `cargo=90,npm=30` — each raises only its own window |
|
|
679
|
+
| `disabled_adapters` | *(none)* | Adapters to leave alone entirely, by name — as if that ecosystem were not installed |
|
|
680
|
+
| `cache_max_gb` | *(none)* | Per-manager cache caps in GiB, as `uv=10,npm=10` — the cap itself deletes nothing |
|
|
681
|
+
|
|
682
|
+
Three of them — `idle_days` (as `override_idle_days`), `min_size_mb` and `scan_depth` —
|
|
683
|
+
also take a per-repository form in that project's `.devprune.json`, where they win for
|
|
684
|
+
that tree only. The rest are deliberately global: a project can commit its
|
|
685
|
+
`.devprune.json`, and a repository you have never read should not be able to grant itself
|
|
686
|
+
permission to have its manifests rewritten during an unattended pass.
|
|
687
|
+
|
|
688
|
+
An out-of-range value is rejected with the range in the message rather than silently
|
|
689
|
+
clamped. `scan_depth` included: `config set` accepts `1`–`32` and refuses anything else
|
|
690
|
+
outright — the clamp to that range survives only as the backstop for a hand-edited
|
|
691
|
+
config file.
|
|
692
|
+
|
|
693
|
+
---
|
|
694
|
+
|
|
695
|
+
## Background automation
|
|
696
|
+
|
|
697
|
+
Installation registers an OS-native scheduler — Windows Task Scheduler, a macOS
|
|
698
|
+
LaunchAgent, or a systemd user timer — that runs a pass every `check_interval_days`, plus
|
|
699
|
+
non-blocking `post-commit`, `post-checkout` and `post-merge` Git hooks that register new
|
|
700
|
+
repositories as you visit them. Both are reinstated after an upgrade if anything went
|
|
701
|
+
missing.
|
|
702
|
+
|
|
703
|
+
```bash
|
|
704
|
+
devp setup --status # what is installed, what is not, and why
|
|
705
|
+
devp config set auto_setup false # stop the unattended pass entirely
|
|
706
|
+
devp uninstall # remove the scheduler, hooks and the devp link
|
|
707
|
+
```
|
|
708
|
+
|
|
709
|
+
Git allows exactly one global `core.hooksPath`, so a tool holding it shuts every other one
|
|
710
|
+
out machine-wide. `devp hook install --chain` takes the slot and forwards each hook on to
|
|
711
|
+
the tool it displaced — husky, pre-commit and lefthook keep firing, in order, with their
|
|
712
|
+
own exit codes. It is opt-in, because rewiring another tool's Git configuration unasked is
|
|
713
|
+
not something an install should do.
|
|
714
|
+
|
|
715
|
+
Full decision flow: [docs/BACKGROUND_AUTOMATION.md](docs/BACKGROUND_AUTOMATION.md).
|
|
716
|
+
|
|
717
|
+
---
|
|
718
|
+
|
|
719
|
+
## How it compares
|
|
720
|
+
|
|
721
|
+
| | `dev-prune` | `npkill` | `cargo-clean-all` | `pyclean` | `git clean` | `dust` / `ncdu` | BleachBit |
|
|
722
|
+
| :---------------------------------------- | :-------------------------: | :------: | :---------------: | :-------: | :-------------: | :-------------: | :-------: |
|
|
723
|
+
| Ecosystems | **JS/TS, Python, Rust, Go** | Node | Rust | Python | untracked files | — | OS caches |
|
|
724
|
+
| Many projects per repository | **✓** | ✗ | ✗ | ✗ | n/a | n/a | ✗ |
|
|
725
|
+
| `.git` boundary enforced | **✓** | ✗ | ✓ | ✗ | ✓ | ✗ | ✗ |
|
|
726
|
+
| Lockfile verified before deleting | **✓** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
|
|
727
|
+
| Commit log **and** `mtime` activity check | **✓** | ✗ | `mtime` only | ✗ | ✗ | ✗ | ✗ |
|
|
728
|
+
| One-command restore | **✓** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
|
|
729
|
+
| Undo the last pass | **✓** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
|
|
730
|
+
| Background scheduler | **✓** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
|
|
731
|
+
| Git hook auto-registration | **✓** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
|
|
732
|
+
| Per-repository config + 0ms opt-out | **✓** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
|
|
733
|
+
| Machine-readable `--json` | **✓** | ✗ | ✗ | ✗ | ✗ | partial | ✗ |
|
|
734
|
+
| AI agent skill | **✓** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ |
|
|
735
|
+
| Runtime required | **none** (static binary) | Node.js | none | Python | none | none | Python |
|
|
736
|
+
|
|
737
|
+
Longer analysis: [docs/MARKET_ANALYSIS.md](docs/MARKET_ANALYSIS.md).
|
|
738
|
+
|
|
739
|
+
---
|
|
740
|
+
|
|
741
|
+
## Architecture
|
|
742
|
+
|
|
743
|
+
```mermaid
|
|
744
|
+
flowchart TD
|
|
745
|
+
UserCLI["CLI / TUI Interface<br/>(devp / dev-prune)"] --> Registry["Global Registry<br/>(~/.config/dev-prune/registry.json)"]
|
|
746
|
+
UserCLI --> Engine["Prune Engine"]
|
|
747
|
+
|
|
748
|
+
Engine --> FastIgnore{ignore.devprune.json?}
|
|
749
|
+
FastIgnore -->|Exists| Skip["Skip Repo O(1) 0ms"]
|
|
750
|
+
FastIgnore -->|Missing| PerRepoConfig["Read .devprune.json"]
|
|
751
|
+
|
|
752
|
+
PerRepoConfig --> GitScanner["Git Scanner & Activity Solver<br/>(.git commits + mtime fallback)"]
|
|
753
|
+
Engine --> PreCheck["Required Ecosystem Binary Pre-Checker"]
|
|
754
|
+
Engine --> Adapters["Multi-Ecosystem Adapters"]
|
|
755
|
+
|
|
756
|
+
Adapters --> NPM["npm (package-lock.json -> node_modules)"]
|
|
757
|
+
Adapters --> PNPM["pnpm (pnpm-lock.yaml -> node_modules)"]
|
|
758
|
+
Adapters --> Yarn["yarn (yarn.lock -> node_modules)"]
|
|
759
|
+
Adapters --> Bun["bun (bun.lock -> node_modules)"]
|
|
760
|
+
Adapters --> UV["uv (uv.lock -> .venv)"]
|
|
761
|
+
Adapters --> Venv["venv (requirements.txt -> venv)"]
|
|
762
|
+
Adapters --> Cargo["cargo (Cargo.lock -> target)"]
|
|
763
|
+
Adapters --> Go["go (go.sum -> vendor)"]
|
|
764
|
+
|
|
765
|
+
Adapters --> LockfileCheck{"Lockfile Verification<br/>& Two-Tier Sync"}
|
|
766
|
+
LockfileCheck -->|Success / Present| Prune["Safe Deletion of Bloat Dirs"]
|
|
767
|
+
LockfileCheck -->|Failed & Missing| Abort["Abort Deletion & Log Fix Snippet"]
|
|
768
|
+
|
|
769
|
+
Daemon["OS Background Daemon Scheduler<br/>(Task Scheduler / LaunchAgent / systemd)"] -->|Every 2 Days| Engine
|
|
770
|
+
GitHooks["Git Auto-Registration Hooks<br/>(post-commit / post-checkout / post-merge)"] -->|On Git Activity| Registry
|
|
771
|
+
```
|
|
772
|
+
|
|
773
|
+
- **Registry** — Serde-backed, written atomically, holding registered paths and settings.
|
|
774
|
+
- **Engine** — coordinates activity discovery, verification and space calculation.
|
|
775
|
+
- **FastIgnore** — presence check for `ignore.devprune.json`; no read, no parse.
|
|
776
|
+
- **GitScanner** — `git log` timestamps plus source-file `mtime`.
|
|
777
|
+
- **PreCheck** — confirms the package manager binaries a pass will actually need.
|
|
778
|
+
- **Adapters** — one per ecosystem, each owning detection, verification and restore.
|
|
779
|
+
- **LockfileCheck** — the gate; failure aborts the deletion and prints the exact fix command.
|
|
780
|
+
- **Daemon / GitHooks** — the unattended pass, and registration as you work.
|
|
781
|
+
|
|
782
|
+
Deeper: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) ·
|
|
783
|
+
[HLD](docs/architecture/HLD.md) · [LLD](docs/architecture/LLD.md).
|
|
784
|
+
|
|
785
|
+
---
|
|
786
|
+
|
|
787
|
+
## Documentation
|
|
788
|
+
|
|
789
|
+
| | |
|
|
790
|
+
| :------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
|
|
791
|
+
| [Documentation hub](docs/README.md) | Index of everything below |
|
|
792
|
+
| [CLI reference](docs/CLI_REFERENCE.md) | Every command, flag, setting, exit code and `--json` document |
|
|
793
|
+
| [Safety invariants](docs/SAFETY_INVARIANTS.md) | The seven guarantees, and why each exists |
|
|
794
|
+
| [Architecture](docs/ARCHITECTURE.md) · [HLD](docs/architecture/HLD.md) · [LLD](docs/architecture/LLD.md) | How it is built |
|
|
795
|
+
| [Background automation](docs/BACKGROUND_AUTOMATION.md) | Schedulers, hooks, chaining, and turning it all off |
|
|
796
|
+
| [IDE & editor integration](docs/IDE_INTEGRATION.md) | The extension, schema IntelliSense, and every editor it works in |
|
|
797
|
+
| [Adding an adapter](docs/ADDING_ADAPTERS.md) | End-to-end tutorial for a new ecosystem |
|
|
798
|
+
| [Releases & manual install](docs/RELEASES_AND_MANUAL_INSTALL.md) · [Distribution](docs/DISTRIBUTION.md) | Every install channel, and building from source |
|
|
799
|
+
| [Troubleshooting](docs/troubleshooting/README.md) | Symptom-first, with the fix for each |
|
|
800
|
+
| [Privacy](docs/PRIVACY.md) | The one network request, in full |
|
|
801
|
+
| [Market analysis](docs/MARKET_ANALYSIS.md) | Where this sits among the alternatives |
|
|
802
|
+
| [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md) · [Changelog](CHANGELOG.md) | |
|
|
803
|
+
|
|
804
|
+
---
|
|
805
|
+
|
|
806
|
+
## License & privacy
|
|
807
|
+
|
|
808
|
+
Copyright 2026 [VKrishna04](https://vkrishna04.me). Licensed under the Apache License,
|
|
809
|
+
Version 2.0 — see [LICENSE.md](LICENSE.md). Every source file carries an
|
|
810
|
+
[SPDX](https://spdx.dev/) identifier, so automated licence scanners see the same
|
|
811
|
+
answer the file header does.
|
|
812
|
+
|
|
813
|
+
> [!IMPORTANT]
|
|
814
|
+
> **No analytics, no diagnostics, no usage data** — none collected, none sent. Your
|
|
815
|
+
> workspace structure, directory paths and repository names never leave the machine.
|
|
816
|
+
>
|
|
817
|
+
> `dev-prune` makes exactly one network request: an unauthenticated `GET` to GitHub's
|
|
818
|
+
> public releases endpoint, to tell you when a newer version exists. It has no body,
|
|
819
|
+
> carries no identifier, and runs at most once a week. Turn it off with `devp config set
|
|
820
|
+
> update_check false`. Full detail in [docs/PRIVACY.md](docs/PRIVACY.md).
|
package/bin/dev-prune
CHANGED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dev-prune-darwin-x64",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.8.0",
|
|
4
4
|
"description": "Prebuilt dev-prune binary for darwin x64. Installed automatically by the 'dev-prune' package; not meant to be depended on directly.",
|
|
5
5
|
"os": ["darwin"],
|
|
6
6
|
"cpu": ["x64"],
|
|
7
|
-
"files": ["bin", "LICENSE.md"],
|
|
7
|
+
"files": ["bin", "LICENSE.md", "README.md"],
|
|
8
8
|
"license": "Apache-2.0",
|
|
9
9
|
"author": "VKrishna04",
|
|
10
10
|
"homepage": "https://devprune.vkrishna04.me",
|