cleanix-cli 1.0.1__tar.gz → 1.1.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 (73) hide show
  1. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/PKG-INFO +35 -5
  2. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/README.md +34 -4
  3. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/__init__.py +1 -1
  4. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/base.py +31 -7
  5. cleanix_cli-1.1.0/cleanix/cleaners/containers.py +206 -0
  6. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/macos.py +16 -4
  7. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/macos_extra.py +19 -7
  8. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cli.py +7 -5
  9. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/config.py +6 -0
  10. cleanix_cli-1.1.0/cleanix/scheduler/__init__.py +22 -0
  11. cleanix_cli-1.1.0/cleanix/scheduler/launchd.py +158 -0
  12. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix_cli.egg-info/PKG-INFO +35 -5
  13. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix_cli.egg-info/SOURCES.txt +1 -0
  14. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/pyproject.toml +1 -1
  15. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/tests/test_cleanix.py +173 -0
  16. cleanix_cli-1.0.1/cleanix/cleaners/containers.py +0 -82
  17. cleanix_cli-1.0.1/cleanix/scheduler/__init__.py +0 -1
  18. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/__main__.py +0 -0
  19. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/__init__.py +0 -0
  20. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/ai_cli.py +0 -0
  21. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/ai_tools.py +0 -0
  22. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/app_cruft.py +0 -0
  23. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/apple_litter.py +0 -0
  24. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/apps.py +0 -0
  25. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/apt.py +0 -0
  26. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/broken_symlinks.py +0 -0
  27. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/browsers.py +0 -0
  28. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/bsd.py +0 -0
  29. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/coredumps.py +0 -0
  30. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/desktop_extras.py +0 -0
  31. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/dev_caches.py +0 -0
  32. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/distro_pkg.py +0 -0
  33. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/dnf.py +0 -0
  34. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/editor_litter.py +0 -0
  35. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/font_cache.py +0 -0
  36. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/ide.py +0 -0
  37. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/kernels.py +0 -0
  38. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/lang_caches.py +0 -0
  39. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/linux_extras.py +0 -0
  40. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/localizations.py +0 -0
  41. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/logs.py +0 -0
  42. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/memory.py +0 -0
  43. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/more_pkg.py +0 -0
  44. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/npm_cache.py +0 -0
  45. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/packaging_extras.py +0 -0
  46. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/pacman.py +0 -0
  47. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/pip_cache.py +0 -0
  48. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/snapshots.py +0 -0
  49. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/sys_extras.py +0 -0
  50. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/temp_files.py +0 -0
  51. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/thumbnails.py +0 -0
  52. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/trash.py +0 -0
  53. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/user_cache.py +0 -0
  54. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/cleaners/virtualization.py +0 -0
  55. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/completion.py +0 -0
  56. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/__init__.py +0 -0
  57. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/context.py +0 -0
  58. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/engine.py +0 -0
  59. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/history.py +0 -0
  60. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/models.py +0 -0
  61. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/platform.py +0 -0
  62. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/quarantine.py +0 -0
  63. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/registry.py +0 -0
  64. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/report.py +0 -0
  65. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/safety.py +0 -0
  66. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/core/utils.py +0 -0
  67. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/reset.py +0 -0
  68. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix/scheduler/systemd.py +0 -0
  69. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix_cli.egg-info/dependency_links.txt +0 -0
  70. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix_cli.egg-info/entry_points.txt +0 -0
  71. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix_cli.egg-info/requires.txt +0 -0
  72. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/cleanix_cli.egg-info/top_level.txt +0 -0
  73. {cleanix_cli-1.0.1 → cleanix_cli-1.1.0}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: cleanix-cli
3
- Version: 1.0.1
3
+ Version: 1.1.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,30 @@ 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
+ ## Container leftovers (Docker / Podman)
127
+
128
+ A *leftover* is anything the engine keeps that **no existing container
129
+ references** and can be regenerated. Each category is surfaced as its own item
130
+ whose estimated size matches exactly what pruning it reclaims — so the number
131
+ you see is the number you get (no more counting unused-but-tagged images or
132
+ volumes you never asked to touch):
133
+
134
+ - **Dangling (untagged) images** — `docker image prune -f`
135
+ - **Stopped containers** (writable layers) — `docker container prune -f`
136
+ - **Build cache** — `docker builder prune -f`
137
+ - **Unused networks** — `docker network prune -f`
138
+
139
+ Two categories stay **opt-in** because they can destroy real work:
140
+
141
+ - `docker_prune_all_images` — also remove *tagged* images not used by any
142
+ container (`image prune -a`); frees more but forces a re-pull next time.
143
+ - `docker_prune_volumes` — also remove unused anonymous volumes, which may hold
144
+ databases or other real data.
145
+
146
+ > On macOS, Docker Desktop stores everything in a VM disk image. Pruning frees
147
+ > space *inside* the VM; the host-side `Docker.raw` file may not shrink until
148
+ > Docker Desktop compacts it.
149
+
125
150
  ## Shell completion
126
151
 
127
152
  ```bash
@@ -197,7 +222,9 @@ sudo cleanix clean --only memory_macos --execute # macOS `purge`
197
222
  that declares the platforms it applies to.
198
223
  - **Root-aware.** Cleaners that need root are clearly flagged and skipped (with a
199
224
  note) when you run unprivileged.
200
- - **Scheduling.** Install a systemd timer that scans daily/weekly and reports.
225
+ - **Scheduling.** Install a periodic read-only scan that reports (and notifies)
226
+ on a daily/weekly/monthly cadence — a **systemd user timer** on Linux/BSD, a
227
+ **launchd LaunchAgent** on macOS. Same `cleanix schedule` command on both.
201
228
 
202
229
  ## Install
203
230
 
@@ -234,7 +261,8 @@ cleanix clean --execute --yes --only trash,pip_cache
234
261
  # Emit the scan report as JSON (for tooling / notifications)
235
262
  cleanix scan --json
236
263
 
237
- # Install a systemd timer that scans weekly and notifies you
264
+ # Install a weekly read-only scan that notifies you
265
+ # (systemd timer on Linux/BSD, launchd agent on macOS)
238
266
  cleanix schedule install --frequency weekly
239
267
 
240
268
  # Check / remove the schedule
@@ -423,7 +451,9 @@ cleanix/
423
451
  # BSD
424
452
  bsd (freebsd pkg, distfiles/work dirs, pkgin)
425
453
  scheduler/
426
- systemd.py # install/uninstall/status of a user systemd timer
454
+ __init__.py # backend() — picks systemd or launchd for the OS
455
+ systemd.py # install/uninstall/status of a user systemd timer (Linux/BSD)
456
+ launchd.py # install/uninstall/status of a launchd LaunchAgent (macOS)
427
457
  ```
428
458
 
429
459
  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,30 @@ 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
+ ## Container leftovers (Docker / Podman)
92
+
93
+ A *leftover* is anything the engine keeps that **no existing container
94
+ references** and can be regenerated. Each category is surfaced as its own item
95
+ whose estimated size matches exactly what pruning it reclaims — so the number
96
+ you see is the number you get (no more counting unused-but-tagged images or
97
+ volumes you never asked to touch):
98
+
99
+ - **Dangling (untagged) images** — `docker image prune -f`
100
+ - **Stopped containers** (writable layers) — `docker container prune -f`
101
+ - **Build cache** — `docker builder prune -f`
102
+ - **Unused networks** — `docker network prune -f`
103
+
104
+ Two categories stay **opt-in** because they can destroy real work:
105
+
106
+ - `docker_prune_all_images` — also remove *tagged* images not used by any
107
+ container (`image prune -a`); frees more but forces a re-pull next time.
108
+ - `docker_prune_volumes` — also remove unused anonymous volumes, which may hold
109
+ databases or other real data.
110
+
111
+ > On macOS, Docker Desktop stores everything in a VM disk image. Pruning frees
112
+ > space *inside* the VM; the host-side `Docker.raw` file may not shrink until
113
+ > Docker Desktop compacts it.
114
+
90
115
  ## Shell completion
91
116
 
92
117
  ```bash
@@ -162,7 +187,9 @@ sudo cleanix clean --only memory_macos --execute # macOS `purge`
162
187
  that declares the platforms it applies to.
163
188
  - **Root-aware.** Cleaners that need root are clearly flagged and skipped (with a
164
189
  note) when you run unprivileged.
165
- - **Scheduling.** Install a systemd timer that scans daily/weekly and reports.
190
+ - **Scheduling.** Install a periodic read-only scan that reports (and notifies)
191
+ on a daily/weekly/monthly cadence — a **systemd user timer** on Linux/BSD, a
192
+ **launchd LaunchAgent** on macOS. Same `cleanix schedule` command on both.
166
193
 
167
194
  ## Install
168
195
 
@@ -199,7 +226,8 @@ cleanix clean --execute --yes --only trash,pip_cache
199
226
  # Emit the scan report as JSON (for tooling / notifications)
200
227
  cleanix scan --json
201
228
 
202
- # Install a systemd timer that scans weekly and notifies you
229
+ # Install a weekly read-only scan that notifies you
230
+ # (systemd timer on Linux/BSD, launchd agent on macOS)
203
231
  cleanix schedule install --frequency weekly
204
232
 
205
233
  # Check / remove the schedule
@@ -388,7 +416,9 @@ cleanix/
388
416
  # BSD
389
417
  bsd (freebsd pkg, distfiles/work dirs, pkgin)
390
418
  scheduler/
391
- systemd.py # install/uninstall/status of a user systemd timer
419
+ __init__.py # backend() — picks systemd or launchd for the OS
420
+ systemd.py # install/uninstall/status of a user systemd timer (Linux/BSD)
421
+ launchd.py # install/uninstall/status of a launchd LaunchAgent (macOS)
392
422
  ```
393
423
 
394
424
  To add a cleaner: subclass `Cleaner`, set `id`/`name`/`platforms`/`requires_root`,
@@ -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.1.0"
4
4
  __all__ = ["__version__"]
@@ -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,206 @@
1
+ """Container-engine leftovers (Docker / Podman).
2
+
3
+ A "leftover" here is anything the engine keeps around that is **not referenced
4
+ by an existing container** and can be regenerated: dangling (untagged) images,
5
+ stopped containers, unused networks and build cache. Rather than lumping these
6
+ into one opaque ``system prune`` with a bogus size, we surface each category as
7
+ its own item whose estimated size matches *exactly* what pruning that category
8
+ reclaims — so the number you see is the number you get.
9
+
10
+ Two categories stay opt-in because they can destroy real work:
11
+ * unused **volumes** (``docker_prune_volumes``) — may hold databases, etc.
12
+ * all unused **images** (``docker_prune_all_images``) — tagged images with no
13
+ container are removed too, forcing a re-pull on next use.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ import re
20
+ from typing import Iterable, Optional
21
+
22
+ from cleanix.cleaners.base import Cleaner, SCOPE_SYSTEM
23
+ from cleanix.core.models import CleanableItem
24
+ from cleanix.core.utils import run_command, which
25
+
26
+ _SIZE_RE = re.compile(r"([\d.]+)\s*([KMGT]?B)", re.IGNORECASE)
27
+ _UNIT = {"B": 1, "KB": 1024, "MB": 1024**2, "GB": 1024**3, "TB": 1024**4}
28
+
29
+
30
+ def _parse_size(text: str) -> int:
31
+ """Parse the first size token in ``text`` (e.g. "1.2GB") into bytes."""
32
+ m = _SIZE_RE.search(text or "")
33
+ if not m:
34
+ return 0
35
+ value = float(m.group(1))
36
+ unit = m.group(2).upper()
37
+ return int(value * _UNIT.get(unit, 1))
38
+
39
+
40
+ class _ContainerCleaner(Cleaner):
41
+ binary = ""
42
+ requires_root = False
43
+
44
+ def available(self) -> Optional[str]:
45
+ if not which(self.binary):
46
+ return f"{self.binary} not found"
47
+ # The binary can be installed while the engine is unreachable — a
48
+ # stopped Docker daemon, or a Podman machine that was never started
49
+ # (macOS runs Podman inside a Linux VM). ``info`` is the cheap standard
50
+ # liveness probe; skip with a clear reason rather than emitting prunes
51
+ # that only fail at execute time.
52
+ code, _out, _err = run_command([self.binary, "info"], timeout=20)
53
+ if code != 0:
54
+ return f"{self.binary} installed but not running"
55
+ return None
56
+
57
+ # -- low-level probes ----------------------------------------------------
58
+ def _df_reclaimable(self) -> dict:
59
+ """Reclaimable bytes per ``system df`` row, keyed by ``Type``.
60
+
61
+ Keys seen in practice: ``Images``, ``Containers``, ``Local Volumes``,
62
+ ``Build Cache``. Missing/failed probes yield an empty mapping.
63
+ """
64
+ code, out, _err = run_command(
65
+ [self.binary, "system", "df", "--format", "{{json .}}"], timeout=30
66
+ )
67
+ result: dict = {}
68
+ if code != 0 or not out.strip():
69
+ return result
70
+ for line in out.splitlines():
71
+ line = line.strip()
72
+ if not line:
73
+ continue
74
+ try:
75
+ row = json.loads(line)
76
+ except json.JSONDecodeError:
77
+ continue
78
+ row_type = row.get("Type")
79
+ if row_type:
80
+ result[row_type] = _parse_size(row.get("Reclaimable", ""))
81
+ return result
82
+
83
+ def _dangling_images_size(self) -> int:
84
+ """Total size of untagged (dangling) images — what ``image prune``
85
+ removes without ``-a``."""
86
+ code, out, _err = run_command(
87
+ [self.binary, "images", "--filter", "dangling=true",
88
+ "--format", "{{.Size}}"],
89
+ timeout=30,
90
+ )
91
+ if code != 0:
92
+ return 0
93
+ return sum(_parse_size(line) for line in out.splitlines() if line.strip())
94
+
95
+ def _stopped_containers(self) -> tuple:
96
+ """``(count, reclaimable_bytes)`` for stopped containers.
97
+
98
+ ``ps --size`` reports ``"<writable> (virtual <total>)"``; the writable
99
+ layer is what ``container prune`` actually reclaims, so we take the
100
+ first size token on each line.
101
+ """
102
+ code, out, _err = run_command(
103
+ [self.binary, "ps", "-a", "--size",
104
+ "--filter", "status=exited",
105
+ "--filter", "status=created",
106
+ "--filter", "status=dead",
107
+ "--format", "{{.Size}}"],
108
+ timeout=30,
109
+ )
110
+ if code != 0:
111
+ return 0, 0
112
+ lines = [ln for ln in out.splitlines() if ln.strip()]
113
+ return len(lines), sum(_parse_size(ln) for ln in lines)
114
+
115
+ def _unused_networks(self) -> int:
116
+ """Count of user-defined networks not used by any container.
117
+
118
+ The ``dangling=true`` network filter (Docker 20.10+, Podman 4+) means
119
+ "unreferenced"; on engines that don't support it the probe fails and we
120
+ report zero rather than guessing.
121
+ """
122
+ code, out, _err = run_command(
123
+ [self.binary, "network", "ls", "--filter", "dangling=true",
124
+ "--format", "{{.ID}}"],
125
+ timeout=30,
126
+ )
127
+ if code != 0:
128
+ return 0
129
+ return sum(1 for ln in out.splitlines() if ln.strip())
130
+
131
+ # -- item assembly -------------------------------------------------------
132
+ def find_items(self) -> Iterable[CleanableItem]:
133
+ df = self._df_reclaimable()
134
+
135
+ # 1) Images — dangling only by default, all-unused when opted in.
136
+ if self.config.docker_prune_all_images:
137
+ size = df.get("Images", 0)
138
+ if size > 0:
139
+ yield self.command_item(
140
+ [self.binary, "image", "prune", "-a", "-f"],
141
+ "Unused images (not referenced by any container)",
142
+ size=size,
143
+ )
144
+ else:
145
+ size = self._dangling_images_size()
146
+ if size > 0:
147
+ yield self.command_item(
148
+ [self.binary, "image", "prune", "-f"],
149
+ "Dangling (untagged) images",
150
+ size=size,
151
+ )
152
+
153
+ # 2) Stopped containers (writable layers).
154
+ count, size = self._stopped_containers()
155
+ if count > 0:
156
+ noun = "container" if count == 1 else "containers"
157
+ yield self.command_item(
158
+ [self.binary, "container", "prune", "-f"],
159
+ f"{count} stopped {noun}",
160
+ size=size,
161
+ )
162
+
163
+ # 3) Build cache.
164
+ size = df.get("Build Cache", 0)
165
+ if size > 0:
166
+ yield self.command_item(
167
+ [self.binary, "builder", "prune", "-f"],
168
+ "Build cache",
169
+ size=size,
170
+ )
171
+
172
+ # 4) Unused networks (no reclaimable disk, but real leftovers).
173
+ count = self._unused_networks()
174
+ if count > 0:
175
+ noun = "network" if count == 1 else "networks"
176
+ yield self.command_item(
177
+ [self.binary, "network", "prune", "-f"],
178
+ f"{count} unused {noun}",
179
+ size=0,
180
+ )
181
+
182
+ # 5) Unused volumes — opt-in, may hold real data.
183
+ if self.config.docker_prune_volumes:
184
+ size = df.get("Local Volumes", 0)
185
+ if size > 0:
186
+ yield self.command_item(
187
+ [self.binary, "volume", "prune", "-f"],
188
+ "Unused (anonymous) volumes",
189
+ size=size,
190
+ )
191
+
192
+
193
+ class DockerCleaner(_ContainerCleaner):
194
+ id = "docker"
195
+ scope = SCOPE_SYSTEM
196
+ name = "Docker leftovers"
197
+ description = "Dangling images, stopped containers, build cache, networks"
198
+ binary = "docker"
199
+
200
+
201
+ class PodmanCleaner(_ContainerCleaner):
202
+ id = "podman"
203
+ scope = SCOPE_SYSTEM
204
+ name = "Podman leftovers"
205
+ description = "Dangling images, stopped containers, build cache, networks"
206
+ binary = "podman"
@@ -95,6 +95,11 @@ class HomebrewCleaner(Cleaner):
95
95
  def available(self):
96
96
  if not which("brew"):
97
97
  return "brew not found"
98
+ # Homebrew hard-refuses to run as root ("Running Homebrew as root is
99
+ # extremely dangerous"), so skip cleanly instead of emitting a command
100
+ # that will only error at execute time (e.g. under `sudo cleanix`).
101
+ if hasattr(os, "geteuid") and os.geteuid() == 0:
102
+ return "skipped as root (Homebrew must run as the owning user)"
98
103
  return None
99
104
 
100
105
  def find_items(self) -> Iterable[CleanableItem]:
@@ -158,9 +163,16 @@ class XcodeCleaner(Cleaner):
158
163
  item = self.path_item(path, label)
159
164
  if item:
160
165
  yield item
161
- # Unavailable simulators (deleted OS runtimes) can waste many GB.
166
+ # Unavailable simulators (deleted OS runtimes) can waste many GB, but
167
+ # `simctl` ships only with full Xcode — not the Command Line Tools — so
168
+ # confirm it resolves before offering (else xcrun errors "unable to
169
+ # find utility simctl").
162
170
  if which("xcrun"):
163
- yield self.command_item(
164
- ["xcrun", "simctl", "delete", "unavailable"],
165
- "Delete unavailable/obsolete iOS simulators",
171
+ code, _out, _err = run_command(
172
+ ["xcrun", "--find", "simctl"], timeout=15
166
173
  )
174
+ if code == 0:
175
+ yield self.command_item(
176
+ ["xcrun", "simctl", "delete", "unavailable"],
177
+ "Delete unavailable/obsolete iOS simulators",
178
+ )
@@ -2,6 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ import os
5
6
  from pathlib import Path
6
7
  from typing import Iterable, Tuple
7
8
 
@@ -114,12 +115,23 @@ class MacSleepImageReporter(Cleaner):
114
115
  scope = SCOPE_SYSTEM
115
116
 
116
117
  def find_items(self) -> Iterable[CleanableItem]:
118
+ # /var is a symlink to /private/var on macOS, so both candidates resolve
119
+ # to the same file — report it once, keyed by its canonical path.
120
+ seen: set = set()
117
121
  for base in ("/private/var/vm/sleepimage", "/var/vm/sleepimage"):
118
122
  p = Path(base)
119
- if p.exists():
120
- item = self.report_item(
121
- p, "macOS sleep/hibernation image",
122
- hint="managed by pmset; remove only if you understand hibernation impact",
123
- )
124
- if item:
125
- yield item
123
+ if not p.exists():
124
+ continue
125
+ try:
126
+ real = os.path.realpath(p)
127
+ except OSError:
128
+ real = str(p)
129
+ if real in seen:
130
+ continue
131
+ seen.add(real)
132
+ item = self.report_item(
133
+ p, "macOS sleep/hibernation image",
134
+ hint="managed by pmset; remove only if you understand hibernation impact",
135
+ )
136
+ if item:
137
+ yield item
@@ -4,7 +4,8 @@ Subcommands:
4
4
  list show available cleaners
5
5
  scan analyze the system (read-only)
6
6
  clean remove junk (dry-run unless --execute; confirmation required)
7
- schedule install/uninstall/status of the systemd analysis timer
7
+ schedule install/uninstall/status of the periodic analysis job
8
+ (systemd timer on Linux/BSD, launchd agent on macOS)
8
9
  """
9
10
 
10
11
  from __future__ import annotations
@@ -606,15 +607,16 @@ def cmd_completion(args: argparse.Namespace, console: Console) -> int:
606
607
 
607
608
 
608
609
  def cmd_schedule(args: argparse.Namespace, console: Console) -> int:
609
- from cleanix.scheduler import systemd
610
+ from cleanix.scheduler import backend
610
611
 
612
+ sched = backend() # systemd on Linux/BSD, launchd on macOS
611
613
  try:
612
614
  if args.action == "install":
613
- console.print(systemd.install(args.frequency))
615
+ console.print(sched.install(args.frequency))
614
616
  elif args.action == "uninstall":
615
- console.print(systemd.uninstall())
617
+ console.print(sched.uninstall())
616
618
  else: # status
617
- console.print(systemd.status())
619
+ console.print(sched.status())
618
620
  except (RuntimeError, ValueError) as exc:
619
621
  console.print(f"[red]{exc}[/red]")
620
622
  return 1
@@ -62,6 +62,11 @@ class Config:
62
62
  # default because volumes can hold real data.
63
63
  docker_prune_volumes: bool = False
64
64
 
65
+ # By default only *dangling* (untagged) images are pruned — a truly safe
66
+ # leftover. Enable this to also remove tagged images not used by any
67
+ # container ("docker image prune -a"); it frees more but forces re-pulls.
68
+ docker_prune_all_images: bool = False
69
+
65
70
  # Offer removal of package-update leftovers (.rpmnew/.pacnew/.dpkg-old ...).
66
71
  remove_config_leftovers: bool = True
67
72
 
@@ -137,6 +142,7 @@ FIELD_HELP = {
137
142
  "browsers": "Browsers whose caches to clear",
138
143
  "symlink_scan_dirs": "Directories scanned for broken symlinks",
139
144
  "docker_prune_volumes": "Also prune unused Docker/Podman volumes",
145
+ "docker_prune_all_images": "Prune all unused images, not just dangling ones",
140
146
  "remove_config_leftovers": "Offer .rpmnew/.pacnew/.dpkg-old residue",
141
147
  "remove_apple_litter": "Remove .DS_Store / AppleDouble litter",
142
148
  "keep_backups": "AI CLI rolling backups to keep (newest N)",
@@ -0,0 +1,22 @@
1
+ """Scheduling support.
2
+
3
+ Picks the right OS-native backend: a **systemd user timer** on Linux/BSD and a
4
+ **launchd LaunchAgent** on macOS. Both expose the same
5
+ ``install/uninstall/status`` surface, so callers use :func:`backend` and stay
6
+ platform-agnostic.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from cleanix.core.platform import is_macos
12
+
13
+
14
+ def backend():
15
+ """Return the scheduling backend module for the current OS."""
16
+ if is_macos():
17
+ from cleanix.scheduler import launchd
18
+
19
+ return launchd
20
+ from cleanix.scheduler import systemd
21
+
22
+ return systemd