cleanix-cli 1.0.1__py3-none-any.whl

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 (64) hide show
  1. cleanix/__init__.py +4 -0
  2. cleanix/__main__.py +6 -0
  3. cleanix/cleaners/__init__.py +269 -0
  4. cleanix/cleaners/ai_cli.py +193 -0
  5. cleanix/cleaners/ai_tools.py +224 -0
  6. cleanix/cleaners/app_cruft.py +201 -0
  7. cleanix/cleaners/apple_litter.py +41 -0
  8. cleanix/cleaners/apps.py +89 -0
  9. cleanix/cleaners/apt.py +70 -0
  10. cleanix/cleaners/base.py +173 -0
  11. cleanix/cleaners/broken_symlinks.py +51 -0
  12. cleanix/cleaners/browsers.py +68 -0
  13. cleanix/cleaners/bsd.py +108 -0
  14. cleanix/cleaners/containers.py +82 -0
  15. cleanix/cleaners/coredumps.py +32 -0
  16. cleanix/cleaners/desktop_extras.py +42 -0
  17. cleanix/cleaners/dev_caches.py +57 -0
  18. cleanix/cleaners/distro_pkg.py +127 -0
  19. cleanix/cleaners/dnf.py +56 -0
  20. cleanix/cleaners/editor_litter.py +115 -0
  21. cleanix/cleaners/font_cache.py +29 -0
  22. cleanix/cleaners/ide.py +87 -0
  23. cleanix/cleaners/kernels.py +115 -0
  24. cleanix/cleaners/lang_caches.py +70 -0
  25. cleanix/cleaners/linux_extras.py +77 -0
  26. cleanix/cleaners/localizations.py +70 -0
  27. cleanix/cleaners/logs.py +80 -0
  28. cleanix/cleaners/macos.py +166 -0
  29. cleanix/cleaners/macos_extra.py +125 -0
  30. cleanix/cleaners/memory.py +110 -0
  31. cleanix/cleaners/more_pkg.py +168 -0
  32. cleanix/cleaners/npm_cache.py +36 -0
  33. cleanix/cleaners/packaging_extras.py +140 -0
  34. cleanix/cleaners/pacman.py +63 -0
  35. cleanix/cleaners/pip_cache.py +27 -0
  36. cleanix/cleaners/snapshots.py +126 -0
  37. cleanix/cleaners/sys_extras.py +109 -0
  38. cleanix/cleaners/temp_files.py +48 -0
  39. cleanix/cleaners/thumbnails.py +31 -0
  40. cleanix/cleaners/trash.py +47 -0
  41. cleanix/cleaners/user_cache.py +69 -0
  42. cleanix/cleaners/virtualization.py +76 -0
  43. cleanix/cli.py +810 -0
  44. cleanix/completion.py +131 -0
  45. cleanix/config.py +225 -0
  46. cleanix/core/__init__.py +1 -0
  47. cleanix/core/context.py +147 -0
  48. cleanix/core/engine.py +155 -0
  49. cleanix/core/history.py +55 -0
  50. cleanix/core/models.py +141 -0
  51. cleanix/core/platform.py +117 -0
  52. cleanix/core/quarantine.py +147 -0
  53. cleanix/core/registry.py +58 -0
  54. cleanix/core/report.py +130 -0
  55. cleanix/core/safety.py +166 -0
  56. cleanix/core/utils.py +244 -0
  57. cleanix/reset.py +328 -0
  58. cleanix/scheduler/__init__.py +1 -0
  59. cleanix/scheduler/systemd.py +160 -0
  60. cleanix_cli-1.0.1.dist-info/METADATA +436 -0
  61. cleanix_cli-1.0.1.dist-info/RECORD +64 -0
  62. cleanix_cli-1.0.1.dist-info/WHEEL +5 -0
  63. cleanix_cli-1.0.1.dist-info/entry_points.txt +2 -0
  64. cleanix_cli-1.0.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,201 @@
1
+ """Bloat that miscellaneous desktop apps scatter across the home directory.
2
+
3
+ Electron apps in particular drop rebuildable HTTP/GPU/code caches into their
4
+ config dirs; GPU drivers, Steam, and JetBrains IDEs keep large regenerable
5
+ caches. We only ever touch caches that the app recreates on demand — never
6
+ session/login stores (Local Storage, IndexedDB, Service Worker, cookies).
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ from pathlib import Path
13
+ from typing import Iterable
14
+
15
+ from cleanix.cleaners.base import Cleaner
16
+ from cleanix.core.models import CleanableItem
17
+ from cleanix.core.platform import LINUX, MACOS, XDG_PLATFORMS
18
+ from cleanix.core.utils import config_dir
19
+ from cleanix.core.utils import home, iter_children, path_size
20
+
21
+ # Electron/Chromium cache subdirs that are always safe to delete — the runtime
22
+ # rebuilds them. Deliberately EXCLUDES Service Worker, IndexedDB, Local/Session
23
+ # Storage, Cookies and other persistent site/session data.
24
+ _SAFE_ELECTRON_CACHES = (
25
+ "Cache",
26
+ "Code Cache",
27
+ "GPUCache",
28
+ "CachedData",
29
+ "DawnCache",
30
+ "DawnGraphiteCache",
31
+ "DawnWebGPUCache",
32
+ "GrShaderCache",
33
+ "ShaderCache",
34
+ "component_crx_cache",
35
+ "Crashpad",
36
+ "blob_storage",
37
+ )
38
+
39
+ # Browser config dirs are owned by the dedicated browser cleaner; skip them here
40
+ # to avoid offering the same cache twice.
41
+ _SKIP_APPS = {
42
+ "google-chrome", "chromium", "BraveSoftware", "vivaldi",
43
+ "microsoft-edge", "opera", "google-chrome-beta", "chromium-dev",
44
+ }
45
+
46
+
47
+ class ElectronCacheCleaner(Cleaner):
48
+ id = "electron_cache"
49
+ name = "Electron/Chromium app caches"
50
+ description = "Rebuildable Cache/GPUCache/Code Cache from Electron apps"
51
+ requires_root = False
52
+ platforms = XDG_PLATFORMS
53
+
54
+ def _config_roots(self) -> Iterable[Path]:
55
+ cfg = config_dir()
56
+ if cfg.is_dir():
57
+ for app in iter_children(cfg):
58
+ if app.is_dir() and app.name not in _SKIP_APPS:
59
+ yield app
60
+ # Flatpak-packaged Electron apps keep config under ~/.var/app/<id>/config.
61
+ var = home() / ".var" / "app"
62
+ if var.is_dir():
63
+ for app in iter_children(var):
64
+ conf = app / "config"
65
+ if conf.is_dir():
66
+ for sub in iter_children(conf):
67
+ if sub.is_dir():
68
+ yield sub
69
+
70
+ def find_items(self) -> Iterable[CleanableItem]:
71
+ for app_dir in self._config_roots():
72
+ for cache_name in _SAFE_ELECTRON_CACHES:
73
+ target = app_dir / cache_name
74
+ if target.is_dir() and path_size(target) > 0:
75
+ item = self.path_item(
76
+ target, f"{app_dir.name}: {cache_name}"
77
+ )
78
+ if item:
79
+ yield item
80
+
81
+
82
+ class FlatpakAppCacheCleaner(Cleaner):
83
+ id = "flatpak_cache"
84
+ name = "Flatpak app caches"
85
+ description = "Per-app cache dirs under ~/.var/app/*/cache"
86
+ requires_root = False
87
+ platforms = (LINUX,)
88
+
89
+ def find_items(self) -> Iterable[CleanableItem]:
90
+ var = home() / ".var" / "app"
91
+ if not var.is_dir():
92
+ return
93
+ for app in iter_children(var):
94
+ cache = app / "cache"
95
+ if not cache.is_dir():
96
+ continue
97
+ for child in iter_children(cache):
98
+ # A flatpak's own fontconfig cache etc. — all safe.
99
+ item = self.path_item(child, f"{app.name} cache: {child.name}")
100
+ if item:
101
+ yield item
102
+
103
+
104
+ class GpuShaderCacheCleaner(Cleaner):
105
+ id = "gpu_shader_cache"
106
+ name = "GPU shader caches"
107
+ description = "Mesa/NVIDIA/RADV shader caches (rebuilt after driver changes)"
108
+ requires_root = False
109
+ platforms = (LINUX,)
110
+
111
+ def _candidates(self):
112
+ h = home()
113
+ cache = h / ".cache"
114
+ yield cache / "mesa_shader_cache", "Mesa shader cache"
115
+ yield cache / "mesa_shader_cache_db", "Mesa shader cache (db)"
116
+ yield h / ".nv" / "GLCache", "NVIDIA GL shader cache"
117
+ yield cache / "nvidia" / "GLCache", "NVIDIA GL shader cache"
118
+ yield cache / "radv_builtin_shaders64", "RADV builtin shaders"
119
+ yield cache / "AMD" / "VkCache", "AMD Vulkan pipeline cache"
120
+
121
+ def find_items(self) -> Iterable[CleanableItem]:
122
+ seen = set()
123
+ for path, label in self._candidates():
124
+ if path in seen or not path.exists() or path_size(path) <= 0:
125
+ continue
126
+ seen.add(path)
127
+ item = self.path_item(path, label)
128
+ if item:
129
+ yield item
130
+
131
+
132
+ class SteamCleaner(Cleaner):
133
+ id = "steam"
134
+ name = "Steam caches"
135
+ description = "Shader cache, partial downloads, and HTTP cache"
136
+ requires_root = False
137
+ platforms = (LINUX,)
138
+
139
+ def _steam_root(self) -> Path:
140
+ for candidate in (
141
+ home() / ".local" / "share" / "Steam",
142
+ home() / ".steam" / "steam",
143
+ ):
144
+ if candidate.is_dir():
145
+ return candidate
146
+ return home() / ".local" / "share" / "Steam"
147
+
148
+ def find_items(self) -> Iterable[CleanableItem]:
149
+ root = self._steam_root()
150
+ if not root.is_dir():
151
+ return
152
+ apps = root / "steamapps"
153
+ # Per-game shader caches.
154
+ for child in iter_children(apps / "shadercache"):
155
+ item = self.path_item(child, f"Steam shader cache: {child.name}")
156
+ if item:
157
+ yield item
158
+ # Interrupted downloads and temp staging.
159
+ for rel in ("downloading", "temp"):
160
+ target = apps / rel
161
+ if target.is_dir() and path_size(target) > 0:
162
+ item = self.path_item(target, f"Steam {rel}")
163
+ if item:
164
+ yield item
165
+ # HTTP cache.
166
+ httpcache = root / "appcache" / "httpcache"
167
+ if httpcache.is_dir() and path_size(httpcache) > 0:
168
+ item = self.path_item(httpcache, "Steam HTTP cache")
169
+ if item:
170
+ yield item
171
+
172
+
173
+ class JetBrainsCleaner(Cleaner):
174
+ id = "jetbrains"
175
+ name = "JetBrains IDE caches"
176
+ description = "Caches, logs, and indexes for IntelliJ/PyCharm/etc."
177
+ requires_root = False
178
+ platforms = (LINUX, MACOS, *XDG_PLATFORMS)
179
+
180
+ def _roots(self) -> Iterable[Path]:
181
+ # Linux/BSD: ~/.cache/JetBrains/<Product>/{caches,log,index,...}
182
+ yield home() / ".cache" / "JetBrains"
183
+ # macOS: ~/Library/Caches/JetBrains and ~/Library/Logs/JetBrains
184
+ yield home() / "Library" / "Caches" / "JetBrains"
185
+ yield home() / "Library" / "Logs" / "JetBrains"
186
+
187
+ def find_items(self) -> Iterable[CleanableItem]:
188
+ for root in self._roots():
189
+ if not root.is_dir():
190
+ continue
191
+ for product in iter_children(root):
192
+ if not product.is_dir():
193
+ continue
194
+ for sub in ("caches", "log", "logs", "index", "tmp"):
195
+ target = product / sub
196
+ if target.is_dir() and path_size(target) > 0:
197
+ item = self.path_item(
198
+ target, f"JetBrains {product.name}: {sub}"
199
+ )
200
+ if item:
201
+ yield item
@@ -0,0 +1,41 @@
1
+ """``.DS_Store`` and AppleDouble (``._*``) litter.
2
+
3
+ macOS scatters ``.DS_Store`` directory-metadata files and ``._name``
4
+ AppleDouble resource-fork files across any filesystem it touches — including
5
+ network shares and USB drives that later get read on Linux/BSD. They are pure
6
+ metadata and safe to delete anywhere. Runs on every platform for that reason.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ from pathlib import Path
13
+ from typing import Iterable
14
+
15
+ from cleanix.cleaners.base import Cleaner
16
+ from cleanix.core.models import CleanableItem
17
+ from cleanix.core.utils import home, walk_pruned
18
+
19
+
20
+ class AppleLitterCleaner(Cleaner):
21
+ id = "apple_litter"
22
+ name = ".DS_Store / AppleDouble"
23
+ description = "macOS .DS_Store and ._* metadata litter in your home tree"
24
+ requires_root = False
25
+
26
+ def available(self):
27
+ if not self.config.remove_apple_litter:
28
+ return "disabled in config (remove_apple_litter=false)"
29
+ return None
30
+
31
+ def find_items(self) -> Iterable[CleanableItem]:
32
+ root = home()
33
+ for dirpath, _dirs, files in walk_pruned(root):
34
+ for name in files:
35
+ if name == ".DS_Store" or (
36
+ name.startswith("._") and len(name) > 2
37
+ ):
38
+ p = os.path.join(dirpath, name)
39
+ item = self.path_item(p, f"Apple litter: {p}")
40
+ if item:
41
+ yield item
@@ -0,0 +1,89 @@
1
+ """Leftovers from a broad set of desktop applications.
2
+
3
+ Focuses on app-specific logs, crash reports, temp and launcher caches that live
4
+ *outside* ~/.cache (which the generic cache cleaner already handles) — so there
5
+ is no double-coverage. User data (chat history, saves, documents) is untouched.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from pathlib import Path
11
+ from typing import Iterable, Tuple
12
+
13
+ from cleanix.cleaners.base import Cleaner
14
+ from cleanix.core.models import CleanableItem
15
+ from cleanix.core.platform import XDG_PLATFORMS
16
+ from cleanix.core.utils import home, iter_children, path_size
17
+
18
+ # (relative-to-home path, label) — logs / crash reports / temp / launcher caches.
19
+ _TARGETS: Tuple[Tuple[str, str], ...] = (
20
+ # Gaming & launchers
21
+ (".minecraft/logs", "Minecraft logs"),
22
+ (".minecraft/crash-reports", "Minecraft crash reports"),
23
+ (".local/share/PrismLauncher/logs", "PrismLauncher logs"),
24
+ (".local/share/multimc/logs", "MultiMC logs"),
25
+ (".local/share/Steam/logs", "Steam logs"),
26
+ (".config/heroic/store_cache", "Heroic store cache"),
27
+ (".local/share/lutris/coverart", "Lutris cover-art cache"),
28
+ (".local/share/bottles/temp", "Bottles temp"),
29
+ (".PlayOnLinux/tmp", "PlayOnLinux temp"),
30
+ # Communication / meetings
31
+ (".zoom/logs", "Zoom logs"),
32
+ (".config/skypeforlinux/logs", "Skype logs"),
33
+ (".config/Ferdium/logs", "Ferdium logs"),
34
+ (".config/Rambox/logs", "Rambox logs"),
35
+ # Media / creative
36
+ (".config/obs-studio/logs", "OBS Studio logs"),
37
+ (".config/obs-studio/crashes", "OBS Studio crash reports"),
38
+ (".kodi/temp", "Kodi temp/logs"),
39
+ # Cloud storage
40
+ (".config/Nextcloud/logs", "Nextcloud logs"),
41
+ (".dropbox/logs", "Dropbox logs"),
42
+ (".config/insync/log", "Insync logs"),
43
+ # Browser crash reports (caches live under ~/.cache, handled elsewhere)
44
+ (".mozilla/firefox/Crash Reports", "Firefox crash reports"),
45
+ (".thunderbird/Crash Reports", "Thunderbird crash reports"),
46
+ (".config/google-chrome/Crash Reports", "Chrome crash reports"),
47
+ # Virtualization app logs
48
+ (".config/VirtualBox/VBoxSVC.log", "VirtualBox service log"),
49
+ # Dev / misc
50
+ (".expo", "Expo cache"),
51
+ (".node-gyp", "node-gyp headers"),
52
+ )
53
+
54
+
55
+ class AppLeftoverCleaner(Cleaner):
56
+ id = "app_leftovers"
57
+ name = "Application leftovers"
58
+ description = "Logs, crash reports and temp from many desktop apps"
59
+ requires_root = False
60
+ platforms = XDG_PLATFORMS
61
+
62
+ def find_items(self) -> Iterable[CleanableItem]:
63
+ h = home()
64
+ for rel, label in _TARGETS:
65
+ path = h / rel
66
+ if path.exists() and path_size(path) > 0:
67
+ item = self.path_item(path, label)
68
+ if item:
69
+ yield item
70
+
71
+
72
+ class SnapAppCacheCleaner(Cleaner):
73
+ id = "snap_app_cache"
74
+ name = "Snap per-app caches"
75
+ description = "Cache dirs inside ~/snap/*/{current,common}"
76
+ requires_root = False
77
+ platforms = XDG_PLATFORMS
78
+
79
+ def find_items(self) -> Iterable[CleanableItem]:
80
+ snap = home() / "snap"
81
+ if not snap.is_dir():
82
+ return
83
+ for app in iter_children(snap):
84
+ for rev in ("current", "common"):
85
+ cache = app / rev / ".cache"
86
+ if cache.is_dir() and path_size(cache) > 0:
87
+ item = self.path_item(cache, f"snap {app.name}/{rev}: cache")
88
+ if item:
89
+ yield item
@@ -0,0 +1,70 @@
1
+ """APT (Debian/Ubuntu) — package cache, orphaned deps, residual configs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+ from typing import Iterable
7
+
8
+ from cleanix.cleaners.base import Cleaner, SCOPE_SYSTEM
9
+ from cleanix.core.models import CleanableItem
10
+ from cleanix.core.platform import LINUX
11
+ from cleanix.core.utils import path_size, run_command, which
12
+
13
+
14
+ class AptCleaner(Cleaner):
15
+ id = "apt"
16
+ scope = SCOPE_SYSTEM
17
+ name = "APT cache & orphans"
18
+ description = "Downloaded .deb archives, orphaned deps, residual configs"
19
+ requires_root = True
20
+ platforms = (LINUX,)
21
+
22
+ def available(self):
23
+ if not which("apt-get") or not which("dpkg"):
24
+ return "apt-get/dpkg not found (not a Debian/Ubuntu system)"
25
+ return None
26
+
27
+ def find_items(self) -> Iterable[CleanableItem]:
28
+ # 1) Downloaded .deb archives.
29
+ archives = Path("/var/cache/apt/archives")
30
+ cached = sum(path_size(deb) for deb in archives.glob("*.deb")) if archives.exists() else 0
31
+ if cached > 0:
32
+ yield self.command_item(
33
+ ["apt-get", "clean"],
34
+ "Remove downloaded .deb package archives",
35
+ size=cached,
36
+ )
37
+
38
+ # 2) Orphaned dependencies (autoremovable).
39
+ code, out, _err = run_command(["apt-get", "-s", "autoremove"], timeout=60)
40
+ if code == 0 and out:
41
+ removals = [ln for ln in out.splitlines() if ln.startswith("Remv ")]
42
+ if removals:
43
+ yield self.command_item(
44
+ ["apt-get", "-y", "autoremove", "--purge"],
45
+ f"Autoremove {len(removals)} orphaned package(s)",
46
+ )
47
+
48
+ # 3) Residual configs — packages removed but not purged (dpkg "rc").
49
+ code, out, _err = run_command(["dpkg", "-l"], timeout=60)
50
+ if code == 0 and out:
51
+ rc = [
52
+ ln.split()[1]
53
+ for ln in out.splitlines()
54
+ if ln.startswith("rc ") and len(ln.split()) > 1
55
+ ]
56
+ if rc:
57
+ yield self.command_item(
58
+ ["apt-get", "-y", "purge", *rc],
59
+ f"Purge {len(rc)} leftover package config(s) (dpkg 'rc' state)",
60
+ )
61
+
62
+ # 4) deborphan — libraries no longer required by anything.
63
+ if which("deborphan"):
64
+ code, out, _err = run_command(["deborphan"], timeout=60)
65
+ if code == 0 and out.strip():
66
+ orphans = [ln.strip() for ln in out.splitlines() if ln.strip()]
67
+ yield self.command_item(
68
+ ["apt-get", "-y", "purge", *orphans],
69
+ f"Purge {len(orphans)} orphaned librar(y/ies) (deborphan)",
70
+ )
@@ -0,0 +1,173 @@
1
+ """The :class:`Cleaner` abstract base class.
2
+
3
+ A cleaner knows how to *find* junk (``scan``) and describes itself with class
4
+ attributes. It never deletes anything directly — the engine owns removal so
5
+ that the safety guard and dry-run logic live in exactly one place.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import abc
11
+ from pathlib import Path
12
+ from typing import Iterable, List, Optional
13
+
14
+ from cleanix.config import Config
15
+ from cleanix.core.context import get_target_users, use_user
16
+ from cleanix.core.models import CleanableItem, CleanerReport, ItemKind
17
+ from cleanix.core.platform import ALL, supports
18
+ from cleanix.core.utils import path_size
19
+
20
+ # Cleaner scope:
21
+ # SCOPE_USER — operates within a home directory; runs once per target user
22
+ # (all users when root, else just the invoker).
23
+ # SCOPE_SYSTEM — operates on system-wide, absolute paths; runs once.
24
+ SCOPE_USER = "user"
25
+ SCOPE_SYSTEM = "system"
26
+
27
+
28
+ class Cleaner(abc.ABC):
29
+ """Base class for all cleaners.
30
+
31
+ Subclasses set :attr:`id`, :attr:`name`, :attr:`description`,
32
+ :attr:`requires_root`, and :attr:`platforms`, then implement
33
+ :meth:`find_items`.
34
+ """
35
+
36
+ id: str = ""
37
+ name: str = ""
38
+ description: str = ""
39
+ requires_root: bool = False
40
+ # Platform tokens this cleaner applies to (see cleanix.core.platform).
41
+ # Default: every platform.
42
+ platforms: tuple = (ALL,)
43
+ # Whether this cleaner is per-user (default) or system-wide.
44
+ scope: str = SCOPE_USER
45
+ # If False, the cleaner is excluded from a normal scan/clean and only runs
46
+ # when explicitly requested via ``--only`` (e.g. the memory cleaners, whose
47
+ # effect is transient and shouldn't happen on every run).
48
+ default_enabled: bool = True
49
+
50
+ def __init__(self, config: Config):
51
+ self.config = config
52
+
53
+ def supported(self) -> bool:
54
+ """True if this cleaner applies to the current operating system."""
55
+ return supports(self.platforms)
56
+
57
+ # -- subclass hook -------------------------------------------------------
58
+ @abc.abstractmethod
59
+ def find_items(self) -> Iterable[CleanableItem]:
60
+ """Yield the removable items this cleaner found. Read-only."""
61
+
62
+ def available(self) -> Optional[str]:
63
+ """Return ``None`` if the cleaner can run, else a skip reason.
64
+
65
+ Override to declare tool/OS prerequisites (e.g. "apt not installed").
66
+ """
67
+ return None
68
+
69
+ # -- helpers for subclasses ---------------------------------------------
70
+ def path_item(
71
+ self,
72
+ path: str | Path,
73
+ description: str,
74
+ *,
75
+ requires_root: Optional[bool] = None,
76
+ ) -> Optional[CleanableItem]:
77
+ """Build a PATH item for ``path`` if it exists and is non-empty."""
78
+ p = Path(path)
79
+ if not p.exists() and not p.is_symlink():
80
+ return None
81
+ size = path_size(p)
82
+ return CleanableItem(
83
+ cleaner_id=self.id,
84
+ description=description,
85
+ size=size,
86
+ kind=ItemKind.PATH,
87
+ path=str(p),
88
+ requires_root=self.requires_root
89
+ if requires_root is None
90
+ else requires_root,
91
+ )
92
+
93
+ def report_item(
94
+ self,
95
+ path: str | Path,
96
+ description: str,
97
+ *,
98
+ hint: str,
99
+ requires_root: Optional[bool] = None,
100
+ ) -> Optional[CleanableItem]:
101
+ """Build a *report-only* PATH item (surfaced with size, never deleted)."""
102
+ p = Path(path)
103
+ if not p.exists() and not p.is_symlink():
104
+ return None
105
+ return CleanableItem(
106
+ cleaner_id=self.id,
107
+ description=description,
108
+ size=path_size(p),
109
+ kind=ItemKind.PATH,
110
+ path=str(p),
111
+ requires_root=self.requires_root
112
+ if requires_root is None
113
+ else requires_root,
114
+ report_only=True,
115
+ hint=hint,
116
+ )
117
+
118
+ def command_item(
119
+ self,
120
+ command: List[str],
121
+ description: str,
122
+ *,
123
+ size: int = 0,
124
+ requires_root: Optional[bool] = None,
125
+ ) -> CleanableItem:
126
+ """Build a COMMAND item."""
127
+ return CleanableItem(
128
+ cleaner_id=self.id,
129
+ description=description,
130
+ size=size,
131
+ kind=ItemKind.COMMAND,
132
+ command=command,
133
+ requires_root=self.requires_root
134
+ if requires_root is None
135
+ else requires_root,
136
+ )
137
+
138
+ # -- engine entry point --------------------------------------------------
139
+ def scan(self) -> CleanerReport:
140
+ """Produce a report. Catches cleaner errors so one bad cleaner cannot
141
+ abort the whole scan."""
142
+ report = CleanerReport(
143
+ cleaner_id=self.id, name=self.name, description=self.description
144
+ )
145
+ reason = self.available()
146
+ if reason:
147
+ report.skipped_reason = reason
148
+ return report
149
+ try:
150
+ if self.scope == SCOPE_SYSTEM:
151
+ report.items = [i for i in self.find_items() if i is not None]
152
+ else:
153
+ report.items = self._scan_all_users()
154
+ except Exception as exc: # noqa: BLE001 - defensive: never crash a scan
155
+ report.skipped_reason = f"error while scanning: {exc}"
156
+ return report
157
+
158
+ 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."""
161
+ items: List[CleanableItem] = []
162
+ seen: set = set()
163
+ for user in get_target_users():
164
+ with use_user(user):
165
+ for item in self.find_items():
166
+ if item is None:
167
+ continue
168
+ if item.path is not None:
169
+ if item.path in seen:
170
+ continue
171
+ seen.add(item.path)
172
+ items.append(item)
173
+ return items
@@ -0,0 +1,51 @@
1
+ """Dangling (broken) symlinks — a classic leftover from removed software.
2
+
3
+ When a package or manually-installed tool is deleted, symlinks pointing into it
4
+ (in ``~/.local/bin``, ``/usr/local/bin``, menu entries, ...) are frequently left
5
+ behind pointing at nothing. These are always safe to remove.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import os
11
+ from pathlib import Path
12
+ from typing import Iterable
13
+
14
+ from cleanix.cleaners.base import Cleaner
15
+ from cleanix.core.models import CleanableItem
16
+ from cleanix.core.utils import expand
17
+ from cleanix.core.utils import home, is_broken_symlink, iter_children
18
+
19
+
20
+ class BrokenSymlinkCleaner(Cleaner):
21
+ id = "broken_symlinks"
22
+ name = "Broken symlinks"
23
+ description = "Dangling symlinks left behind by uninstalled software"
24
+ requires_root = False # per-item; system paths flagged individually
25
+
26
+ def find_items(self) -> Iterable[CleanableItem]:
27
+ home_str = str(home())
28
+ seen = set()
29
+ for raw in self.config.symlink_scan_dirs:
30
+ base = expand(raw)
31
+ if not base.is_dir():
32
+ continue
33
+ for child in iter_children(base):
34
+ key = str(child)
35
+ if key in seen:
36
+ continue
37
+ seen.add(key)
38
+ if not is_broken_symlink(child):
39
+ continue
40
+ try:
41
+ target = os.readlink(child)
42
+ except OSError:
43
+ target = "?"
44
+ needs_root = not key.startswith(home_str)
45
+ yield CleanableItem(
46
+ cleaner_id=self.id,
47
+ description=f"Broken symlink: {child} -> {target}",
48
+ size=0,
49
+ path=str(child),
50
+ requires_root=needs_root,
51
+ )