dev-prune 1.8.0 → 1.9.0

package/README.md

@@ -263,6 +263,7 @@ A few more worth knowing on day one:
 ```bash
 devp stats                  # how much has been reclaimed so far, and by which repositories
 devp caches                 # every package manager cache, sized. The report deletes nothing
+devp caches docker          # what Docker holds, and the prune commands. Read-only, permanently
 devp status --drift         # anything installed that the lockfiles don't record?
 devp doctor .               # why is this repository not being pruned?
 devp doctor --fix           # repair a broken integration — never a first-time install
@@ -355,6 +356,13 @@ Package manager caches
   Total                  21.99 GiB  across 12 caches
 
 → Nothing above was deleted, and dev-prune never deletes any of it.
+
+Container engines
+
+  docker                          47.64 GiB  36.69 GiB reclaimable · devp caches docker
+
+  Container images, volumes and build cache are not package manager caches and are not in
+  the total above — dev-prune reports them and never deletes them.
 ```
 
 A cache lives outside every repository and is shared by all of them, so no single
@@ -371,6 +379,64 @@ a registered repository, and each such row names its store in the command it pri
 
 </details>
 
+<details>
+<summary><b><code>devp caches docker</code></b> — the engine that is usually bigger than all of them</summary>
+
+```console
+$ devp caches docker
+
+Container engines
+
+  docker
+
+  Images            37.36 GiB     29.28 GiB reclaimable   41 items, 9 in use
+  Containers         1.19 GiB      1.12 GiB reclaimable   12 items, 3 in use
+  Local Volumes      2.79 GiB           0 B reclaimable   5 items, 2 in use
+  Build Cache        6.29 GiB      6.29 GiB reclaimable   41 items, 0 in use
+
+  Total             47.64 GiB     36.69 GiB reclaimable
+
+  Reclaim it yourself             what it takes with it
+  docker builder prune            the build cache; costs a slower next build
+  docker image prune              dangling images no tag points at any more
+  docker container prune          stopped containers and each writable layer
+  docker system prune             the three above at once; volumes untouched
+  docker system prune --volumes   adds unused volumes — the one that deletes data
+
+  Nothing above was deleted, and nothing dev-prune runs on a schedule will ever delete it.
+  An image has no lockfile to prove it can be rebuilt, and a named volume is the one thing
+  here that cannot be rebuilt at all — so this command measures, prints the commands, and
+  leaves the decision with you.
+```
+
+Clearing 6 GiB of npm cache while a Docker install nobody has looked at in a year sits on
+40 GiB is the mistake this exists to prevent. `devp caches podman` and `devp caches
+nerdctl` are the same report for those engines, and `devp caches containers` runs every
+one it finds and lists any local Kubernetes clusters (kind, k3d, minikube) by name.
+
+**It is read-only, permanently.** There is no flag and no `clear` verb that makes
+dev-prune run one of those commands — `devp caches clear docker` is a usage error that
+says so — and no scheduler or Git hook reaches this code at all. That is the same rule
+as everywhere else rather than extra caution: an image has no lockfile to prove it can be
+rebuilt, the Dockerfile that built it may not be on this disk, and a named volume is the
+one thing on the machine that cannot be rebuilt at all.
+
+The figures come from the engine's own `system df`, not a walk of the disk. On Docker
+Desktop and Podman the store lives inside a VM disk image the host filesystem cannot see,
+so a size taken off the disk would be wrong by orders of magnitude in the reassuring
+direction — and asking is the only way to learn what is *reclaimable*, which is the
+figure that decides anything. 40 GB of images with 38 GB dangling is a different
+situation from 40 GB with 2 GB dangling.
+
+An engine that is installed with its daemon stopped is reported as exactly that, quoting
+the engine's own first line, and contributes no figures: a blank, not a zero. An engine
+that is not installed is absent from the report rather than listed as missing. Local
+Kubernetes clusters are named and deliberately not sized — their nodes are containers
+belonging to an engine already in the table, so a figure beside the cluster name would be
+the same gigabytes counted twice.
+
+</details>
+
 <details>
 <summary><b><code>devp doctor .</code></b> — the one reason a repository is being skipped</summary>
 
@@ -444,6 +510,7 @@ process that leaves a dirty working tree is a surprise.
 | 🧩 **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                                                                                                                                                                                                       |
 | ↩️ **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                                                                                                                                                                                                       |
 | 🕒 **Activity-aware**                          | Combines `git log` timestamps with source-file `mtime`, so uncommitted work protects a repository just as a commit does                                                                                                                                                                                                                                     |
+| 🐳 **Container report**                        | `devp caches docker` (also `podman`, `nerdctl`, or `containers` for all of them plus local Kubernetes clusters) breaks a container engine's disk into images, containers, local volumes and build cache, each with what the engine itself calls reclaimable, and prints the prune commands narrowest first with what each takes with it. **Read-only, permanently** — `devp caches clear docker` is a usage error, and no scheduler or hook reaches this code: an image has no lockfile to prove it can be rebuilt, and a named volume cannot be rebuilt at all. `devp caches` carries a one-line summary per engine, outside its own total |
 | 📊 **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 |
 | 🩺 **`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                                                                                                                 |
 | 🤖 **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                                                                                                             |
@@ -467,9 +534,10 @@ process that leaves a dirty working tree is a surprise.
 | `devp undo`            | :------------------------------------------------------------------ | Reverts the most recent `init` or `link`                                                                                                                                                                                                                      |
 | `devp run [PATH]`      | `--dry-run`, `--only`, `--skip`, `--except`, `--min-size`, `--json` | Prunes every registered repository, or one target                                                                                                                                                                                                             |
 | `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                                                                    |
-| `devp stats`           | `--json`                                                            | What has already been reclaimed: lifetime total, prune passes, the last pass, and the biggest contributors                                                                                                                                                    |
+| `devp stats`           | `--json`                                                            | What has already been reclaimed: lifetime total from pruning, a separate lifetime total from `devp caches clear`, prune passes, the last pass, and the biggest contributors                                                                                                                                                    |
 | `devp completions`     | `bash`, `zsh`, `fish`, `powershell`, `elvish`                       | Prints a shell completion script to stdout, generated from the same argument definitions the binary parses with                                                                                                                                               |
 | `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                                                  |
+| `devp caches docker`   | `podman`, `nerdctl`, `containers [ENGINE]`, `--json`                | What a container engine holds — images, containers, volumes, build cache — each sized, with what the engine calls reclaimable, then the prune commands. Read-only permanently: it prints them, you run them                                                |
 | `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                                                                                                                          |
 | `devp restore [PATH]`  | `--last-run`                                                        | Reinstalls dependencies for every project in a tree; `--last-run` undoes the last prune pass                                                                                                                                                                  |
 | `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                                                               |

package/bin/dev-prune.js

@@ -66,7 +66,18 @@ const fallbacks = [
 const binaryPath =
   bundledBinary() || fallbacks.find((c) => fs.existsSync(c)) || exeName;
 
-const child = spawn(binaryPath, process.argv.slice(2), { stdio: 'inherit' });
+let child;
+try {
+  child = spawn(binaryPath, process.argv.slice(2), { stdio: 'inherit' });
+} catch (err) {
+  // Windows throws out of `spawn` itself when the loader refuses the image — a
+  // wrong-architecture or truncated binary — because there is no child to emit an
+  // 'error' event on. Everywhere else the same failure arrives asynchronously. Without
+  // this branch the message written for exactly that case never runs, and the user gets
+  // a raw Node stack trace instead. `reportLaunchFailure` is a hoisted function
+  // declaration, so it is callable from above its definition; it never returns.
+  reportLaunchFailure(err);
+}
 
 // Forward termination to the child. Ctrl+C already reaches it through the shared
 // process group, but a bare `kill` of this wrapper — process managers, CI timeouts —
@@ -85,11 +96,19 @@ for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
 
 // Without this, a missing binary surfaces as an unhandled 'error' event and a Node
 // stack trace instead of an actionable message.
-child.on('error', (err) => {
-  if (err.code === 'ENOENT' && binaryPath !== exeName && fs.existsSync(binaryPath)) {
-    // The file is right there, yet the loader said "no such file" — the kernel's
-    // report for a binary it cannot load, typically one built for a different
-    // architecture. "Install what you already installed" would loop the user.
+child.on('error', reportLaunchFailure);
+
+function reportLaunchFailure(err) {
+  // ENOENT on a file that is demonstrably there, or Windows' UNKNOWN: both are a loader
+  // refusing the image rather than a file that is missing.
+  if (
+    (err.code === 'ENOENT' || err.code === 'UNKNOWN') &&
+    binaryPath !== exeName &&
+    fs.existsSync(binaryPath)
+  ) {
+    // The file is right there, yet the loader would not take it — typically a binary
+    // built for a different architecture. "Install what you already installed" would
+    // loop the user.
     console.error(
       `dev-prune: '${binaryPath}' exists but could not be executed.\n\n` +
         `It may be built for a different architecture than ${process.platform}-${process.arch},\n` +
@@ -116,7 +135,7 @@ child.on('error', (err) => {
     console.error(`dev-prune: failed to launch ${binaryPath}: ${err.message}`);
   }
   process.exit(127);
-});
+}
 
 // `code` is null when the child was killed by a signal; `code || 0` reported success
 // in that case. Mirror the shell convention of 128 + signal number instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-prune",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Universal, lockfile-safe workspace pruner. Reclaims disk space from idle Git repositories by deleting only dependency and build directories a lockfile can rebuild.",
   "bin": {
     "dev-prune": "./bin/dev-prune.js",
@@ -12,13 +12,13 @@
     "LICENSE.md"
   ],
   "optionalDependencies": {
-    "dev-prune-darwin-arm64": "1.8.0",
-    "dev-prune-darwin-x64": "1.8.0",
-    "dev-prune-linux-arm64": "1.8.0",
-    "dev-prune-linux-x64": "1.8.0",
-    "dev-prune-windows-arm64": "1.8.0",
-    "dev-prune-windows-x64": "1.8.0",
-    "dev-prune-windows-x86": "1.8.0"
+    "dev-prune-darwin-arm64": "1.9.0",
+    "dev-prune-darwin-x64": "1.9.0",
+    "dev-prune-linux-arm64": "1.9.0",
+    "dev-prune-linux-x64": "1.9.0",
+    "dev-prune-windows-arm64": "1.9.0",
+    "dev-prune-windows-x64": "1.9.0",
+    "dev-prune-windows-x86": "1.9.0"
   },
   "engines": {
     "node": ">=20"