cleanix-cli 1.0.1__tar.gz → 1.2.0__tar.gz

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.
Files changed (91) hide show
  1. cleanix_cli-1.2.0/MANIFEST.in +4 -0
  2. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/PKG-INFO +90 -5
  3. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/README.md +89 -4
  4. cleanix_cli-1.2.0/RELEASING.md +64 -0
  5. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/__init__.py +1 -1
  6. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/__init__.py +16 -0
  7. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/base.py +31 -7
  8. cleanix_cli-1.2.0/cleanix/cleaners/big_files.py +83 -0
  9. cleanix_cli-1.2.0/cleanix/cleaners/browser_profiles.py +319 -0
  10. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/bsd.py +16 -10
  11. cleanix_cli-1.2.0/cleanix/cleaners/containerd.py +82 -0
  12. cleanix_cli-1.2.0/cleanix/cleaners/containers.py +235 -0
  13. cleanix_cli-1.2.0/cleanix/cleaners/downloads.py +91 -0
  14. cleanix_cli-1.2.0/cleanix/cleaners/duplicates.py +164 -0
  15. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/macos.py +16 -4
  16. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/macos_extra.py +19 -7
  17. cleanix_cli-1.2.0/cleanix/cleaners/project_cruft.py +185 -0
  18. cleanix_cli-1.2.0/cleanix/cleaners/toolchains.py +149 -0
  19. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cli.py +361 -13
  20. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/config.py +52 -2
  21. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/history.py +36 -3
  22. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/report.py +23 -0
  23. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/safety.py +60 -15
  24. cleanix_cli-1.2.0/cleanix/scheduler/__init__.py +34 -0
  25. cleanix_cli-1.2.0/cleanix/scheduler/cron.py +137 -0
  26. cleanix_cli-1.2.0/cleanix/scheduler/launchd.py +158 -0
  27. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/scheduler/systemd.py +6 -2
  28. cleanix_cli-1.2.0/cleanix.1 +202 -0
  29. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/PKG-INFO +90 -5
  30. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/SOURCES.txt +18 -0
  31. cleanix_cli-1.2.0/packaging/README.md +49 -0
  32. cleanix_cli-1.2.0/packaging/aur/PKGBUILD +40 -0
  33. cleanix_cli-1.2.0/packaging/homebrew/cleanix.rb +45 -0
  34. cleanix_cli-1.2.0/packaging/rpm/cleanix-cli.spec +56 -0
  35. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/pyproject.toml +1 -1
  36. cleanix_cli-1.2.0/requirements.txt +2 -0
  37. cleanix_cli-1.2.0/scripts/gen_manpage.py +105 -0
  38. cleanix_cli-1.2.0/tests/test_cleanix.py +817 -0
  39. cleanix_cli-1.0.1/cleanix/cleaners/containers.py +0 -82
  40. cleanix_cli-1.0.1/cleanix/scheduler/__init__.py +0 -1
  41. cleanix_cli-1.0.1/tests/test_cleanix.py +0 -265
  42. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/__main__.py +0 -0
  43. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/ai_cli.py +0 -0
  44. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/ai_tools.py +0 -0
  45. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/app_cruft.py +0 -0
  46. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/apple_litter.py +0 -0
  47. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/apps.py +0 -0
  48. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/apt.py +0 -0
  49. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/broken_symlinks.py +0 -0
  50. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/browsers.py +0 -0
  51. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/coredumps.py +0 -0
  52. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/desktop_extras.py +0 -0
  53. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/dev_caches.py +0 -0
  54. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/distro_pkg.py +0 -0
  55. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/dnf.py +0 -0
  56. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/editor_litter.py +0 -0
  57. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/font_cache.py +0 -0
  58. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/ide.py +0 -0
  59. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/kernels.py +0 -0
  60. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/lang_caches.py +0 -0
  61. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/linux_extras.py +0 -0
  62. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/localizations.py +0 -0
  63. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/logs.py +0 -0
  64. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/memory.py +0 -0
  65. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/more_pkg.py +0 -0
  66. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/npm_cache.py +0 -0
  67. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/packaging_extras.py +0 -0
  68. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/pacman.py +0 -0
  69. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/pip_cache.py +0 -0
  70. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/snapshots.py +0 -0
  71. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/sys_extras.py +0 -0
  72. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/temp_files.py +0 -0
  73. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/thumbnails.py +0 -0
  74. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/trash.py +0 -0
  75. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/user_cache.py +0 -0
  76. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/virtualization.py +0 -0
  77. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/completion.py +0 -0
  78. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/__init__.py +0 -0
  79. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/context.py +0 -0
  80. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/engine.py +0 -0
  81. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/models.py +0 -0
  82. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/platform.py +0 -0
  83. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/quarantine.py +0 -0
  84. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/registry.py +0 -0
  85. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/utils.py +0 -0
  86. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/reset.py +0 -0
  87. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/dependency_links.txt +0 -0
  88. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/entry_points.txt +0 -0
  89. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/requires.txt +0 -0
  90. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/top_level.txt +0 -0
  91. {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/setup.cfg +0 -0
@@ -0,0 +1,4 @@
1
+ include README.md RELEASING.md LICENSE requirements.txt
2
+ include cleanix.1
3
+ recursive-include packaging *
4
+ include scripts/gen_manpage.py
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cleanix-cli
3
- Version: 1.0.1
3
+ Version: 1.2.0
4
4
  Summary: A safe, thorough scheduled system cleaner for every *nix (Linux, macOS, BSD).
5
5
  Author: cleanix-cli contributors
6
6
  License: MIT
@@ -46,7 +46,8 @@ temp files, package-manager leftovers, orphaned packages, broken symlinks,
46
46
  package-update config residue, rotated logs, trash, thumbnails, browser/dev
47
47
  caches, container cruft — and only **removes** anything after you confirm.
48
48
 
49
- It can run on a **schedule** (via a systemd timer) to periodically analyze the
49
+ It can run on a **schedule** (a systemd timer on Linux/BSD, a launchd agent on
50
+ macOS) to periodically analyze the
50
51
  system and notify you. Scheduled runs *never delete anything*; they only produce
51
52
  a report so you can review and clean on your own terms.
52
53
 
@@ -122,6 +123,84 @@ last day is always left alone, so cleaning never disturbs a live agent session.
122
123
  Cleaners never offer the same path twice: dedicated cleaners own their
123
124
  directories and the generic `~/.cache` catch-all defers to them.
124
125
 
126
+ ## More reclamation & review
127
+
128
+ - **Old toolchain versions** (`toolchains`). Version managers hoard
129
+ multi-gigabyte installed runtimes — old `~/.nvm` node builds, `~/.pyenv` /
130
+ `~/.rbenv` versions, `rustup` toolchains, SDKMAN candidates, `asdf` installs.
131
+ Cleanix keeps the **active** version (always protected) plus the newest
132
+ `keep_toolchain_versions` (default 2) and offers the rest for removal. It
133
+ *skips a manager entirely if it can't prove which version is active* — pair
134
+ with `clean --quarantine` to make removals reversible. Disable with
135
+ `prune_old_toolchains: false`.
136
+ - **Stale project cruft** (`project_cruft`, report-only). Finds regenerable
137
+ `node_modules` / `.venv` / `target` / `.gradle` dirs in projects under
138
+ `project_scan_dirs` you haven't touched in `project_stale_days` (default 120).
139
+ - **Large files** (`big_files`, report-only). The biggest files in `$HOME`, so
140
+ you can see what filled the disk. Never deletes — just a sized list + `rm` hint.
141
+ - **Duplicate files** (`duplicates`, report-only). Identical large files (same
142
+ size + SHA-256) grouped with the space reclaimable by keeping one copy.
143
+ - **Stale downloads** (`downloads`, report-only). Old, large installers/ISOs in
144
+ `~/Downloads` (which stays hard-protected from deletion).
145
+ - **Orphaned browser profiles** (`browser_profiles`, report-only). Secondary
146
+ Chrome/Chromium/Firefox profiles idle for `browser_profile_stale_days`, with a
147
+ clear warning that a profile holds bookmarks/passwords/history.
148
+
149
+ ## Working with what a scan finds
150
+
151
+ - `cleanix explain <id>` — read-only, shows the **exact** paths/commands one
152
+ cleaner would consider (with size, root, delete-vs-report), for building trust.
153
+ - `cleanix clean --interactive` — pick individual items from a checklist before
154
+ removing (selection is per-item, not just per-cleaner).
155
+ - `cleanix clean --simulate` — write the exact target list to a file, delete
156
+ nothing (stronger than the dry-run summary).
157
+ - `cleanix clean --execute` — writes a **per-file audit manifest** to
158
+ `~/.local/state/cleanix/runs/` and prints the real `df` free-space change.
159
+ - `--profile safe|balanced|aggressive` — one flag to bundle the opt-in settings
160
+ (aggressive enables offline-repo/backup/locale/all-image pruning; it never
161
+ bundles volume removal).
162
+ - `--min-size 100M` — ignore items below a threshold to cut table noise.
163
+ - `cleanix scan --json` emits a **versioned** schema (`schema_version`, host,
164
+ os, `cleanable_bytes` vs `report_only_bytes`) for CI/tooling.
165
+ - `cleanix dashboard` — lifetime reclaim trend (sparkline) plus the last
166
+ scheduled scan's top sources, at a glance.
167
+
168
+ ## Install & packaging
169
+
170
+ - **PyPI:** `pip install cleanix-cli` (or `pipx install cleanix-cli`).
171
+ - **Standalone binaries** are attached to each [GitHub Release] alongside a
172
+ `SHA256SUMS` file and keyless **build-provenance attestations** — verify a
173
+ download with `gh attestation verify <file> --repo CloudOpsWorld/cleanix-cli`.
174
+ - **Homebrew / AUR / Fedora** packaging lives under [`packaging/`](packaging/),
175
+ along with a `cleanix.1` **man page** generated from the CLI
176
+ (`python scripts/gen_manpage.py`).
177
+
178
+ [GitHub Release]: https://github.com/CloudOpsWorld/cleanix-cli/releases
179
+
180
+ ## Container leftovers (Docker / Podman / nerdctl / crictl)
181
+
182
+ A *leftover* is anything the engine keeps that **no existing container
183
+ references** and can be regenerated. Each category is surfaced as its own item
184
+ whose estimated size matches exactly what pruning it reclaims — so the number
185
+ you see is the number you get (no more counting unused-but-tagged images or
186
+ volumes you never asked to touch):
187
+
188
+ - **Dangling (untagged) images** — `docker image prune -f`
189
+ - **Stopped containers** (writable layers) — `docker container prune -f`
190
+ - **Build cache** — `docker builder prune -f`
191
+ - **Unused networks** — `docker network prune -f`
192
+
193
+ Two categories stay **opt-in** because they can destroy real work:
194
+
195
+ - `docker_prune_all_images` — also remove *tagged* images not used by any
196
+ container (`image prune -a`); frees more but forces a re-pull next time.
197
+ - `docker_prune_volumes` — also remove unused anonymous volumes, which may hold
198
+ databases or other real data.
199
+
200
+ > On macOS, Docker Desktop stores everything in a VM disk image. Pruning frees
201
+ > space *inside* the VM; the host-side `Docker.raw` file may not shrink until
202
+ > Docker Desktop compacts it.
203
+
125
204
  ## Shell completion
126
205
 
127
206
  ```bash
@@ -197,7 +276,10 @@ sudo cleanix clean --only memory_macos --execute # macOS `purge`
197
276
  that declares the platforms it applies to.
198
277
  - **Root-aware.** Cleaners that need root are clearly flagged and skipped (with a
199
278
  note) when you run unprivileged.
200
- - **Scheduling.** Install a systemd timer that scans daily/weekly and reports.
279
+ - **Scheduling.** Install a periodic read-only scan that reports (and notifies)
280
+ on a daily/weekly/monthly cadence — a **systemd user timer** on Linux, a
281
+ **launchd LaunchAgent** on macOS, and a **cron job** on the BSDs (or any
282
+ system with `crontab` but no systemd). Same `cleanix schedule` command on all.
201
283
 
202
284
  ## Install
203
285
 
@@ -234,7 +316,8 @@ cleanix clean --execute --yes --only trash,pip_cache
234
316
  # Emit the scan report as JSON (for tooling / notifications)
235
317
  cleanix scan --json
236
318
 
237
- # Install a systemd timer that scans weekly and notifies you
319
+ # Install a weekly read-only scan that notifies you
320
+ # (systemd timer on Linux/BSD, launchd agent on macOS)
238
321
  cleanix schedule install --frequency weekly
239
322
 
240
323
  # Check / remove the schedule
@@ -423,7 +506,9 @@ cleanix/
423
506
  # BSD
424
507
  bsd (freebsd pkg, distfiles/work dirs, pkgin)
425
508
  scheduler/
426
- systemd.py # install/uninstall/status of a user systemd timer
509
+ __init__.py # backend() — picks systemd or launchd for the OS
510
+ systemd.py # install/uninstall/status of a user systemd timer (Linux/BSD)
511
+ launchd.py # install/uninstall/status of a launchd LaunchAgent (macOS)
427
512
  ```
428
513
 
429
514
  To add a cleaner: subclass `Cleaner`, set `id`/`name`/`platforms`/`requires_root`,
@@ -11,7 +11,8 @@ temp files, package-manager leftovers, orphaned packages, broken symlinks,
11
11
  package-update config residue, rotated logs, trash, thumbnails, browser/dev
12
12
  caches, container cruft — and only **removes** anything after you confirm.
13
13
 
14
- It can run on a **schedule** (via a systemd timer) to periodically analyze the
14
+ It can run on a **schedule** (a systemd timer on Linux/BSD, a launchd agent on
15
+ macOS) to periodically analyze the
15
16
  system and notify you. Scheduled runs *never delete anything*; they only produce
16
17
  a report so you can review and clean on your own terms.
17
18
 
@@ -87,6 +88,84 @@ last day is always left alone, so cleaning never disturbs a live agent session.
87
88
  Cleaners never offer the same path twice: dedicated cleaners own their
88
89
  directories and the generic `~/.cache` catch-all defers to them.
89
90
 
91
+ ## More reclamation & review
92
+
93
+ - **Old toolchain versions** (`toolchains`). Version managers hoard
94
+ multi-gigabyte installed runtimes — old `~/.nvm` node builds, `~/.pyenv` /
95
+ `~/.rbenv` versions, `rustup` toolchains, SDKMAN candidates, `asdf` installs.
96
+ Cleanix keeps the **active** version (always protected) plus the newest
97
+ `keep_toolchain_versions` (default 2) and offers the rest for removal. It
98
+ *skips a manager entirely if it can't prove which version is active* — pair
99
+ with `clean --quarantine` to make removals reversible. Disable with
100
+ `prune_old_toolchains: false`.
101
+ - **Stale project cruft** (`project_cruft`, report-only). Finds regenerable
102
+ `node_modules` / `.venv` / `target` / `.gradle` dirs in projects under
103
+ `project_scan_dirs` you haven't touched in `project_stale_days` (default 120).
104
+ - **Large files** (`big_files`, report-only). The biggest files in `$HOME`, so
105
+ you can see what filled the disk. Never deletes — just a sized list + `rm` hint.
106
+ - **Duplicate files** (`duplicates`, report-only). Identical large files (same
107
+ size + SHA-256) grouped with the space reclaimable by keeping one copy.
108
+ - **Stale downloads** (`downloads`, report-only). Old, large installers/ISOs in
109
+ `~/Downloads` (which stays hard-protected from deletion).
110
+ - **Orphaned browser profiles** (`browser_profiles`, report-only). Secondary
111
+ Chrome/Chromium/Firefox profiles idle for `browser_profile_stale_days`, with a
112
+ clear warning that a profile holds bookmarks/passwords/history.
113
+
114
+ ## Working with what a scan finds
115
+
116
+ - `cleanix explain <id>` — read-only, shows the **exact** paths/commands one
117
+ cleaner would consider (with size, root, delete-vs-report), for building trust.
118
+ - `cleanix clean --interactive` — pick individual items from a checklist before
119
+ removing (selection is per-item, not just per-cleaner).
120
+ - `cleanix clean --simulate` — write the exact target list to a file, delete
121
+ nothing (stronger than the dry-run summary).
122
+ - `cleanix clean --execute` — writes a **per-file audit manifest** to
123
+ `~/.local/state/cleanix/runs/` and prints the real `df` free-space change.
124
+ - `--profile safe|balanced|aggressive` — one flag to bundle the opt-in settings
125
+ (aggressive enables offline-repo/backup/locale/all-image pruning; it never
126
+ bundles volume removal).
127
+ - `--min-size 100M` — ignore items below a threshold to cut table noise.
128
+ - `cleanix scan --json` emits a **versioned** schema (`schema_version`, host,
129
+ os, `cleanable_bytes` vs `report_only_bytes`) for CI/tooling.
130
+ - `cleanix dashboard` — lifetime reclaim trend (sparkline) plus the last
131
+ scheduled scan's top sources, at a glance.
132
+
133
+ ## Install & packaging
134
+
135
+ - **PyPI:** `pip install cleanix-cli` (or `pipx install cleanix-cli`).
136
+ - **Standalone binaries** are attached to each [GitHub Release] alongside a
137
+ `SHA256SUMS` file and keyless **build-provenance attestations** — verify a
138
+ download with `gh attestation verify <file> --repo CloudOpsWorld/cleanix-cli`.
139
+ - **Homebrew / AUR / Fedora** packaging lives under [`packaging/`](packaging/),
140
+ along with a `cleanix.1` **man page** generated from the CLI
141
+ (`python scripts/gen_manpage.py`).
142
+
143
+ [GitHub Release]: https://github.com/CloudOpsWorld/cleanix-cli/releases
144
+
145
+ ## Container leftovers (Docker / Podman / nerdctl / crictl)
146
+
147
+ A *leftover* is anything the engine keeps that **no existing container
148
+ references** and can be regenerated. Each category is surfaced as its own item
149
+ whose estimated size matches exactly what pruning it reclaims — so the number
150
+ you see is the number you get (no more counting unused-but-tagged images or
151
+ volumes you never asked to touch):
152
+
153
+ - **Dangling (untagged) images** — `docker image prune -f`
154
+ - **Stopped containers** (writable layers) — `docker container prune -f`
155
+ - **Build cache** — `docker builder prune -f`
156
+ - **Unused networks** — `docker network prune -f`
157
+
158
+ Two categories stay **opt-in** because they can destroy real work:
159
+
160
+ - `docker_prune_all_images` — also remove *tagged* images not used by any
161
+ container (`image prune -a`); frees more but forces a re-pull next time.
162
+ - `docker_prune_volumes` — also remove unused anonymous volumes, which may hold
163
+ databases or other real data.
164
+
165
+ > On macOS, Docker Desktop stores everything in a VM disk image. Pruning frees
166
+ > space *inside* the VM; the host-side `Docker.raw` file may not shrink until
167
+ > Docker Desktop compacts it.
168
+
90
169
  ## Shell completion
91
170
 
92
171
  ```bash
@@ -162,7 +241,10 @@ sudo cleanix clean --only memory_macos --execute # macOS `purge`
162
241
  that declares the platforms it applies to.
163
242
  - **Root-aware.** Cleaners that need root are clearly flagged and skipped (with a
164
243
  note) when you run unprivileged.
165
- - **Scheduling.** Install a systemd timer that scans daily/weekly and reports.
244
+ - **Scheduling.** Install a periodic read-only scan that reports (and notifies)
245
+ on a daily/weekly/monthly cadence — a **systemd user timer** on Linux, a
246
+ **launchd LaunchAgent** on macOS, and a **cron job** on the BSDs (or any
247
+ system with `crontab` but no systemd). Same `cleanix schedule` command on all.
166
248
 
167
249
  ## Install
168
250
 
@@ -199,7 +281,8 @@ cleanix clean --execute --yes --only trash,pip_cache
199
281
  # Emit the scan report as JSON (for tooling / notifications)
200
282
  cleanix scan --json
201
283
 
202
- # Install a systemd timer that scans weekly and notifies you
284
+ # Install a weekly read-only scan that notifies you
285
+ # (systemd timer on Linux/BSD, launchd agent on macOS)
203
286
  cleanix schedule install --frequency weekly
204
287
 
205
288
  # Check / remove the schedule
@@ -388,7 +471,9 @@ cleanix/
388
471
  # BSD
389
472
  bsd (freebsd pkg, distfiles/work dirs, pkgin)
390
473
  scheduler/
391
- systemd.py # install/uninstall/status of a user systemd timer
474
+ __init__.py # backend() — picks systemd or launchd for the OS
475
+ systemd.py # install/uninstall/status of a user systemd timer (Linux/BSD)
476
+ launchd.py # install/uninstall/status of a launchd LaunchAgent (macOS)
392
477
  ```
393
478
 
394
479
  To add a cleaner: subclass `Cleaner`, set `id`/`name`/`platforms`/`requires_root`,
@@ -0,0 +1,64 @@
1
+ # Releasing cleanix-cli
2
+
3
+ Publishing is fully automated via GitHub Actions, modeled on a
4
+ push-to-`main`-triggers-release flow.
5
+
6
+ ## Workflows
7
+
8
+ | Workflow | Trigger | What it does |
9
+ |----------|---------|--------------|
10
+ | `.github/workflows/ci.yml` | push / PR to `main`/`master` | Test matrix (Ubuntu + macOS × Python 3.9–3.13), advisory ruff lint & mypy |
11
+ | `.github/workflows/build.yml` | `workflow_call` / manual | Runs tests, builds standalone binaries (Linux + macOS via PyInstaller) and the wheel/sdist (`python -m build` + `twine check`) |
12
+ | `.github/workflows/release.yml` | push to `main`/`master` | Detects a new version, tags it, builds artifacts, creates a GitHub Release, and publishes to PyPI |
13
+
14
+ ## How a release happens
15
+
16
+ 1. Bump the version in **both** `pyproject.toml` and `cleanix/__init__.py`
17
+ (the release workflow fails if they disagree).
18
+ 2. Commit and push to `main`.
19
+ 3. `release.yml` will:
20
+ - see the version has no matching `vX.Y.Z` git tag,
21
+ - create and push that tag,
22
+ - build binaries + wheel/sdist,
23
+ - create a GitHub Release with the binaries and package attached,
24
+ - publish the wheel/sdist to PyPI.
25
+
26
+ If the tag already exists, the release is skipped — so pushing unrelated commits
27
+ never re-releases.
28
+
29
+ ## One-time PyPI setup (Trusted Publishing — recommended)
30
+
31
+ No API token required. On PyPI:
32
+
33
+ 1. Create the project owner/account, then go to **PyPI → Your projects →
34
+ Publishing → Add a new pending publisher** with:
35
+ - Owner: your GitHub org/user
36
+ - Repository: `cleanix-cli`
37
+ - Workflow name: `release.yml`
38
+ - Environment: `pypi`
39
+ 2. In the GitHub repo, create an **Environment** named `pypi`
40
+ (Settings → Environments) — optionally add required reviewers for a manual
41
+ approval gate before publish.
42
+
43
+ That's it: `release.yml` requests an OIDC token (`id-token: write`) and PyPI
44
+ trusts it.
45
+
46
+ ### Alternative: API token
47
+
48
+ If you prefer a token, add a repository secret `PYPI_API_TOKEN` and uncomment the
49
+ `password:` line in the `publish-pypi` job of `release.yml`.
50
+
51
+ ## Testing the pipeline first
52
+
53
+ - Run **Build** manually (Actions → Build → Run workflow) to confirm binaries and
54
+ the package build without cutting a release.
55
+ - Optionally point at **TestPyPI** first by adding `repository-url:
56
+ https://test.pypi.org/legacy/` to the publish step.
57
+
58
+ ## Local dry run
59
+
60
+ ```bash
61
+ pip install build twine
62
+ python -m build
63
+ twine check dist/*
64
+ ```
@@ -1,4 +1,4 @@
1
1
  """Cleanix — a safe, thorough scheduled system cleaner for Linux, macOS and BSD."""
2
2
 
3
- __version__ = "1.0.1"
3
+ __version__ = "1.2.0"
4
4
  __all__ = ["__version__"]
@@ -25,6 +25,13 @@ from cleanix.cleaners.dev_caches import DevCacheCleaner
25
25
  from cleanix.cleaners.pip_cache import PipCacheCleaner
26
26
  from cleanix.cleaners.npm_cache import NpmCacheCleaner
27
27
  from cleanix.cleaners.containers import DockerCleaner, PodmanCleaner
28
+ from cleanix.cleaners.containerd import CrictlCleaner, NerdctlCleaner
29
+ from cleanix.cleaners.toolchains import ToolchainVersionCleaner
30
+ from cleanix.cleaners.project_cruft import ProjectCruftCleaner
31
+ from cleanix.cleaners.big_files import BigFileReporter
32
+ from cleanix.cleaners.downloads import DownloadsReporter
33
+ from cleanix.cleaners.browser_profiles import BrowserProfileReporter
34
+ from cleanix.cleaners.duplicates import DuplicateFileReporter
28
35
 
29
36
  # Logs / crashes
30
37
  from cleanix.cleaners.logs import JournalCleaner, RotatedLogCleaner
@@ -171,6 +178,10 @@ ALL_CLEANERS: List[Type[Cleaner]] = [
171
178
  NpmCacheCleaner,
172
179
  DockerCleaner,
173
180
  PodmanCleaner,
181
+ NerdctlCleaner,
182
+ CrictlCleaner,
183
+ # Language / toolchain versions
184
+ ToolchainVersionCleaner,
174
185
  # Logs & crashes
175
186
  RotatedLogCleaner,
176
187
  JournalCleaner,
@@ -247,6 +258,11 @@ ALL_CLEANERS: List[Type[Cleaner]] = [
247
258
  SnapshotReporter,
248
259
  TimeMachineReporter,
249
260
  DeviceBackupReporter,
261
+ ProjectCruftCleaner,
262
+ BigFileReporter,
263
+ DownloadsReporter,
264
+ BrowserProfileReporter,
265
+ DuplicateFileReporter,
250
266
  # macOS extras
251
267
  MacExtraCachesCleaner,
252
268
  MacContainerCacheCleaner,
@@ -25,6 +25,20 @@ SCOPE_USER = "user"
25
25
  SCOPE_SYSTEM = "system"
26
26
 
27
27
 
28
+ def _path_present(p: Path) -> bool:
29
+ """True if ``p`` exists (or is a dangling symlink), never raising.
30
+
31
+ ``Path.exists()`` does *not* swallow ``EPERM`` — on macOS a SIP-protected
32
+ entry under ``/Library/Caches`` raises ``PermissionError`` — so a bare
33
+ ``p.exists()`` in a cleaner would abort the whole scan. We treat any
34
+ unreadable path as "not present" (we couldn't size or remove it anyway).
35
+ """
36
+ try:
37
+ return p.exists() or p.is_symlink()
38
+ except OSError:
39
+ return False
40
+
41
+
28
42
  class Cleaner(abc.ABC):
29
43
  """Base class for all cleaners.
30
44
 
@@ -76,7 +90,7 @@ class Cleaner(abc.ABC):
76
90
  ) -> Optional[CleanableItem]:
77
91
  """Build a PATH item for ``path`` if it exists and is non-empty."""
78
92
  p = Path(path)
79
- if not p.exists() and not p.is_symlink():
93
+ if not _path_present(p):
80
94
  return None
81
95
  size = path_size(p)
82
96
  return CleanableItem(
@@ -100,7 +114,7 @@ class Cleaner(abc.ABC):
100
114
  ) -> Optional[CleanableItem]:
101
115
  """Build a *report-only* PATH item (surfaced with size, never deleted)."""
102
116
  p = Path(path)
103
- if not p.exists() and not p.is_symlink():
117
+ if not _path_present(p):
104
118
  return None
105
119
  return CleanableItem(
106
120
  cleaner_id=self.id,
@@ -156,18 +170,28 @@ class Cleaner(abc.ABC):
156
170
  return report
157
171
 
158
172
  def _scan_all_users(self) -> List[CleanableItem]:
159
- """Run a per-user cleaner once for each target user, de-duplicating
160
- by path so shared/system directories are never offered twice."""
173
+ """Run a per-user cleaner once for each target user, de-duplicating so
174
+ shared directories and identical commands are never offered twice.
175
+
176
+ Command items are keyed by their argv: a per-user cleaner that yields a
177
+ fixed command (e.g. ``brew cleanup``) would otherwise appear once per
178
+ target user when running as root, yet the engine runs it only once."""
161
179
  items: List[CleanableItem] = []
162
- seen: set = set()
180
+ seen_paths: set = set()
181
+ seen_commands: set = set()
163
182
  for user in get_target_users():
164
183
  with use_user(user):
165
184
  for item in self.find_items():
166
185
  if item is None:
167
186
  continue
168
187
  if item.path is not None:
169
- if item.path in seen:
188
+ if item.path in seen_paths:
189
+ continue
190
+ seen_paths.add(item.path)
191
+ elif item.command is not None:
192
+ key = tuple(item.command)
193
+ if key in seen_commands:
170
194
  continue
171
- seen.add(item.path)
195
+ seen_commands.add(key)
172
196
  items.append(item)
173
197
  return items
@@ -0,0 +1,83 @@
1
+ """Large-file finder (report-only).
2
+
3
+ A user who has filled their disk usually wants to *see* what is eating the
4
+ space, not have cleanix guess which giant files are junk — a 40 GiB video or VM
5
+ image may be exactly what they wanted to keep. So this cleaner never deletes
6
+ anything: it walks the home tree, surfaces the biggest files (with sizes and a
7
+ manual removal hint), and leaves the decision to the human.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import heapq
13
+ import os
14
+ import stat
15
+ from typing import Iterable, List, Tuple
16
+
17
+ from cleanix.cleaners.base import Cleaner
18
+ from cleanix.core.models import CleanableItem
19
+ from cleanix.core.platform import ALL
20
+ from cleanix.core.utils import (
21
+ _allocated_bytes,
22
+ home,
23
+ human_size,
24
+ modified_within,
25
+ walk_pruned,
26
+ )
27
+
28
+ # Leave anything touched within the last few minutes alone: a very recent mtime
29
+ # suggests the file is being actively written (a download in progress, a render
30
+ # still spooling), and its size is not yet meaningful.
31
+ _IN_USE_MINUTES = 5.0
32
+
33
+
34
+ class BigFileReporter(Cleaner):
35
+ id = "big_files"
36
+ name = "Large files"
37
+ description = "Biggest files in your home directory (report only)"
38
+ requires_root = False
39
+ platforms = (ALL,)
40
+
41
+ def find_items(self) -> Iterable[CleanableItem]:
42
+ min_bytes = int(
43
+ getattr(self.config, "big_file_min_size_mb", 500.0) * 1024 * 1024
44
+ )
45
+ top_n = int(getattr(self.config, "big_files_top_n", 20))
46
+ if top_n <= 0:
47
+ return
48
+
49
+ # Keep a running min-heap of the top-N largest files seen so far. Each
50
+ # entry is (size, path); the smallest sits at heap[0] and is evicted
51
+ # once the heap is full and a bigger file arrives.
52
+ heap: List[Tuple[int, str]] = []
53
+
54
+ for dirpath, _dirnames, filenames in walk_pruned(home()):
55
+ for name in filenames:
56
+ fpath = os.path.join(dirpath, name)
57
+ try:
58
+ st = os.lstat(fpath)
59
+ except OSError:
60
+ continue
61
+ # Files only, never symlinks (walk_pruned already avoids
62
+ # descending through symlinked dirs).
63
+ if not stat.S_ISREG(st.st_mode):
64
+ continue
65
+ size = _allocated_bytes(st)
66
+ if size < min_bytes:
67
+ continue
68
+ if modified_within(fpath, _IN_USE_MINUTES):
69
+ continue
70
+ if len(heap) < top_n:
71
+ heapq.heappush(heap, (size, fpath))
72
+ elif size > heap[0][0]:
73
+ heapq.heapreplace(heap, (size, fpath))
74
+
75
+ # Emit largest-first.
76
+ for size, fpath in sorted(heap, key=lambda t: t[0], reverse=True):
77
+ item = self.report_item(
78
+ fpath,
79
+ f"Large file: {os.path.basename(fpath)} ({human_size(size)})",
80
+ hint="review and remove manually if no longer needed: rm <path>",
81
+ )
82
+ if item:
83
+ yield item