purger 0.2.0__tar.gz

purger-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nate Landau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

purger-0.2.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: purger
+Version: 0.2.0
+Summary: Find and clean rebuildable developer caches to free disk space.
+Keywords: cache,cleanup,cli,disk-space,docker,homebrew,uv,xcode
+Author: Nate Landau
+Author-email: Nate Landau <github@natenate.org>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Dist: cyclopts>=5.4.0,<6
+Requires-Dist: nclutils>=4.0.0,<5.0.0
+Requires-Dist: psutil>=7.0.0,<8
+Requires-Dist: rich>=15.0.0,<16
+Requires-Python: >=3.13
+Project-URL: Changelog, https://github.com/natelandau/purger/releases
+Project-URL: Homepage, https://github.com/natelandau/purger
+Project-URL: Issues, https://github.com/natelandau/purger/issues
+Project-URL: Repository, https://github.com/natelandau/purger
+Description-Content-Type: text/markdown
+
+# purger
+
+purger finds the caches that developer tools leave on your disk, shows how much space each cache uses, and removes the caches that you approve. It uses the cleanup command of each tool when the tool has one. It deletes a cache directory by hand only when no command exists, and only inside your home directory.
+
+Without `--dangerous` and your explicit confirmation, purger never deletes your files, your projects, or data that cannot be rebuilt.
+
+## What purger cleans
+
+purger runs on macOS and Linux. Each supported tool is a plugin, and each plugin has one or more cleanup actions.
+
+- `ansible` (macOS, Linux): temp folders left by interrupted runs and the Galaxy cache, in `~/.ansible` and `$ANSIBLE_HOME`. Skipped while an ansible command runs.
+- `apt` (Linux): downloaded package files. Both actions run with sudo.
+- `brew` (macOS, Linux): old formula versions, the download cache, and dependencies that nothing needs anymore.
+- `bun` (macOS, Linux): packages unused for 30 days, or the entire cache with `--dangerous`.
+- `cocoapods` (macOS): the pod download cache.
+- `conda` (macOS, Linux): downloaded package tarballs, packages that no environment uses, the index cache, and logs.
+- `corepack` (macOS, Linux): downloaded yarn, pnpm, and npm versions.
+- `dnf` (Linux): downloaded package files. Runs with sudo.
+- `docker` (macOS, Linux): the build cache, unused images, stopped containers, unused networks, and unused volumes.
+- `flatpak` (Linux): runtimes and extensions that no app uses, in your user installation and, with sudo, the system installation.
+- `go` (macOS, Linux): the build cache and the module download cache.
+- `macports` (macOS): build files, source archives, and inactive ports. Both actions run with sudo.
+- `maestro` (macOS, Linux): logs, screenshots, and local recordings of past `maestro test` runs. Skipped while Maestro runs.
+- `mise` (macOS, Linux): stale cache files and unused tool versions, or the entire cache with `--dangerous`.
+- `npm` (macOS, Linux): unneeded cache data and the npx cache, or the entire cache with `--dangerous`.
+- `pacman` (Linux): cached package versions beyond the newest 3, and every cached version of uninstalled packages. Needs `paccache` from pacman-contrib, and runs with sudo.
+- `pip` (macOS, Linux): the download and wheel cache, even when pip is no longer installed.
+- `playwright` (macOS, Linux): browser builds older than the newest of each browser.
+- `pnpm` (macOS, Linux): store packages that no project uses, and registry metadata in formats the installed pnpm can no longer read.
+- `podman` (macOS, Linux): unused images, stopped containers, pods, networks, and build cache, and unused volumes with `--dangerous`.
+- `pre-commit` (macOS, Linux): unused hook repos, or the entire cache with `--dangerous`.
+- `prek` (macOS, Linux): unused hook environments, or the entire cache with `--dangerous`.
+- `rip2` (macOS, Linux): the rip2 graveyard of deleted files. Runs only when `rip` on PATH is rip2.
+- `simulators` (macOS): simulator devices the installed Xcode cannot run.
+- `swiftpm` (macOS, Linux): cached package clones, manifests, and binary frameworks.
+- `thumbnails` (Linux): the desktop file thumbnail cache.
+- `trash` (macOS, Linux): everything in the Trash in your home folder. On macOS, the terminal needs Full Disk Access.
+- `uv` (macOS, Linux): unused cache entries, or the entire cache with `--dangerous`.
+- `xcode` (macOS): build products, device debug symbols, and app archives.
+- `yarn` (macOS, Linux): the global package cache, even when yarn is no longer installed.
+
+purger skips a plugin when its tool is not installed, is not running, or does not apply to your platform. Run `purger clean --dry-run` to see the actions that would run, with their risk tiers.
+
+## Install
+
+purger needs Python 3.13 or later.
+
+To install purger with uv, run this command:
+
+```bash
+uv tool install purger
+```
+
+To install purger with pip, run this command:
+
+```bash
+pip install purger
+```
+
+Run purger as your normal user. purger refuses to run as root. It asks for sudo only for the actions that need it, such as the `apt` and `macports` actions.
+
+## Quick start
+
+Start with `purger info`. It measures each cache and prints a table with one row for each tool: the size of its cache and a short description. A check in the `Partial purge` column means that a clean removes only part of that size. `purger info` deletes nothing.
+
+```bash
+purger info
+```
+
+Then run `purger clean`. It prints the same table, asks for confirmation, and runs the cleanups that you approve. At the end, it prints a table with the size of each cache before and after the clean, and the space that was freed.
+
+```bash
+purger clean
+```
+
+## Commands
+
+Both commands accept plugin names as arguments. Without names, a command uses every plugin.
+
+```bash
+purger info uv brew              # measure only the uv and Homebrew caches
+purger clean xcode --dry-run     # show what would be cleaned, change nothing
+purger clean docker --dangerous  # also offer to remove unused Docker volumes
+```
+
+These options apply to both commands:
+
+| Option        | Effect                                                                    |
+| ------------- | ------------------------------------------------------------------------- |
+| `--dangerous` | Include `dangerous` actions. Without it, purger hides them.               |
+| `--json`      | Print exactly one JSON document on stdout instead of tables and messages. |
+| `-v`, `-vv`   | Show more detail, such as the output of the tool commands.                |
+
+These options apply to `purger clean` only:
+
+| Option        | Effect                                                                               |
+| ------------- | ------------------------------------------------------------------------------------ |
+| `--dry-run`   | List the commands and paths that would run. purger asks nothing and changes nothing. |
+| `--yes`, `-y` | Skip the single prompt for `safe` actions.                                           |
+
+## Risk tiers
+
+Each cleanup action has one tier. The tier controls how purger asks for confirmation.
+
+| Tier        | Meaning                                                                               | Confirmation                                    |
+| ----------- | ------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `safe`      | The tool rebuilds the cache cheaply and automatically.                                | One prompt for all `safe` actions.              |
+| `caution`   | The cache can be rebuilt, but the rebuild is slow or a large download.                | One prompt for each action.                     |
+| `dangerous` | The action can destroy data that cannot be recreated, or it removes a complete cache. | Shown only with `--dangerous`. One prompt each. |
+
+The `--yes` flag skips only the prompt for `safe` actions. A `caution` or `dangerous` action never runs unless a person answers its prompt.
+
+> **Warning:** Docker `volumes` is a `dangerous` action. It deletes every volume that no container uses, which includes the data of local databases.
+
+## Use purger in scripts and agents
+
+Add `--json` to a command to get exactly one JSON document on stdout. Every document has `"schema_version": 1`, and every size is an integer number of bytes.
+
+```bash
+purger info --json
+purger clean --json --yes
+```
+
+`purger clean --json` never prompts. With `--yes`, it runs the `safe` actions only. It reports each `caution` and `dangerous` action as `declined`. Without a terminal, purger applies the same rules.
+
+The help pages give the full document shape and the status values:
+
+```bash
+purger info --help
+purger clean --help
+```
+
+## Exit codes
+
+Both commands use these exit codes:
+
+| Code  | Meaning                                                                 |
+| ----- | ----------------------------------------------------------------------- |
+| `0`   | Success. This includes a run where you declined every action.           |
+| `1`   | An action that you approved failed. Only `purger clean` uses this code. |
+| `2`   | A usage error, such as an unknown plugin name or a run as root.         |
+| `130` | You pressed Ctrl-C.                                                     |
+
+## Contributing
+
+To build purger, run the tests, or add a plugin, read [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+purger is available under the [MIT License](LICENSE).

purger-0.2.0/README.md

@@ -0,0 +1,150 @@
+# purger
+
+purger finds the caches that developer tools leave on your disk, shows how much space each cache uses, and removes the caches that you approve. It uses the cleanup command of each tool when the tool has one. It deletes a cache directory by hand only when no command exists, and only inside your home directory.
+
+Without `--dangerous` and your explicit confirmation, purger never deletes your files, your projects, or data that cannot be rebuilt.
+
+## What purger cleans
+
+purger runs on macOS and Linux. Each supported tool is a plugin, and each plugin has one or more cleanup actions.
+
+- `ansible` (macOS, Linux): temp folders left by interrupted runs and the Galaxy cache, in `~/.ansible` and `$ANSIBLE_HOME`. Skipped while an ansible command runs.
+- `apt` (Linux): downloaded package files. Both actions run with sudo.
+- `brew` (macOS, Linux): old formula versions, the download cache, and dependencies that nothing needs anymore.
+- `bun` (macOS, Linux): packages unused for 30 days, or the entire cache with `--dangerous`.
+- `cocoapods` (macOS): the pod download cache.
+- `conda` (macOS, Linux): downloaded package tarballs, packages that no environment uses, the index cache, and logs.
+- `corepack` (macOS, Linux): downloaded yarn, pnpm, and npm versions.
+- `dnf` (Linux): downloaded package files. Runs with sudo.
+- `docker` (macOS, Linux): the build cache, unused images, stopped containers, unused networks, and unused volumes.
+- `flatpak` (Linux): runtimes and extensions that no app uses, in your user installation and, with sudo, the system installation.
+- `go` (macOS, Linux): the build cache and the module download cache.
+- `macports` (macOS): build files, source archives, and inactive ports. Both actions run with sudo.
+- `maestro` (macOS, Linux): logs, screenshots, and local recordings of past `maestro test` runs. Skipped while Maestro runs.
+- `mise` (macOS, Linux): stale cache files and unused tool versions, or the entire cache with `--dangerous`.
+- `npm` (macOS, Linux): unneeded cache data and the npx cache, or the entire cache with `--dangerous`.
+- `pacman` (Linux): cached package versions beyond the newest 3, and every cached version of uninstalled packages. Needs `paccache` from pacman-contrib, and runs with sudo.
+- `pip` (macOS, Linux): the download and wheel cache, even when pip is no longer installed.
+- `playwright` (macOS, Linux): browser builds older than the newest of each browser.
+- `pnpm` (macOS, Linux): store packages that no project uses, and registry metadata in formats the installed pnpm can no longer read.
+- `podman` (macOS, Linux): unused images, stopped containers, pods, networks, and build cache, and unused volumes with `--dangerous`.
+- `pre-commit` (macOS, Linux): unused hook repos, or the entire cache with `--dangerous`.
+- `prek` (macOS, Linux): unused hook environments, or the entire cache with `--dangerous`.
+- `rip2` (macOS, Linux): the rip2 graveyard of deleted files. Runs only when `rip` on PATH is rip2.
+- `simulators` (macOS): simulator devices the installed Xcode cannot run.
+- `swiftpm` (macOS, Linux): cached package clones, manifests, and binary frameworks.
+- `thumbnails` (Linux): the desktop file thumbnail cache.
+- `trash` (macOS, Linux): everything in the Trash in your home folder. On macOS, the terminal needs Full Disk Access.
+- `uv` (macOS, Linux): unused cache entries, or the entire cache with `--dangerous`.
+- `xcode` (macOS): build products, device debug symbols, and app archives.
+- `yarn` (macOS, Linux): the global package cache, even when yarn is no longer installed.
+
+purger skips a plugin when its tool is not installed, is not running, or does not apply to your platform. Run `purger clean --dry-run` to see the actions that would run, with their risk tiers.
+
+## Install
+
+purger needs Python 3.13 or later.
+
+To install purger with uv, run this command:
+
+```bash
+uv tool install purger
+```
+
+To install purger with pip, run this command:
+
+```bash
+pip install purger
+```
+
+Run purger as your normal user. purger refuses to run as root. It asks for sudo only for the actions that need it, such as the `apt` and `macports` actions.
+
+## Quick start
+
+Start with `purger info`. It measures each cache and prints a table with one row for each tool: the size of its cache and a short description. A check in the `Partial purge` column means that a clean removes only part of that size. `purger info` deletes nothing.
+
+```bash
+purger info
+```
+
+Then run `purger clean`. It prints the same table, asks for confirmation, and runs the cleanups that you approve. At the end, it prints a table with the size of each cache before and after the clean, and the space that was freed.
+
+```bash
+purger clean
+```
+
+## Commands
+
+Both commands accept plugin names as arguments. Without names, a command uses every plugin.
+
+```bash
+purger info uv brew              # measure only the uv and Homebrew caches
+purger clean xcode --dry-run     # show what would be cleaned, change nothing
+purger clean docker --dangerous  # also offer to remove unused Docker volumes
+```
+
+These options apply to both commands:
+
+| Option        | Effect                                                                    |
+| ------------- | ------------------------------------------------------------------------- |
+| `--dangerous` | Include `dangerous` actions. Without it, purger hides them.               |
+| `--json`      | Print exactly one JSON document on stdout instead of tables and messages. |
+| `-v`, `-vv`   | Show more detail, such as the output of the tool commands.                |
+
+These options apply to `purger clean` only:
+
+| Option        | Effect                                                                               |
+| ------------- | ------------------------------------------------------------------------------------ |
+| `--dry-run`   | List the commands and paths that would run. purger asks nothing and changes nothing. |
+| `--yes`, `-y` | Skip the single prompt for `safe` actions.                                           |
+
+## Risk tiers
+
+Each cleanup action has one tier. The tier controls how purger asks for confirmation.
+
+| Tier        | Meaning                                                                               | Confirmation                                    |
+| ----------- | ------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `safe`      | The tool rebuilds the cache cheaply and automatically.                                | One prompt for all `safe` actions.              |
+| `caution`   | The cache can be rebuilt, but the rebuild is slow or a large download.                | One prompt for each action.                     |
+| `dangerous` | The action can destroy data that cannot be recreated, or it removes a complete cache. | Shown only with `--dangerous`. One prompt each. |
+
+The `--yes` flag skips only the prompt for `safe` actions. A `caution` or `dangerous` action never runs unless a person answers its prompt.
+
+> **Warning:** Docker `volumes` is a `dangerous` action. It deletes every volume that no container uses, which includes the data of local databases.
+
+## Use purger in scripts and agents
+
+Add `--json` to a command to get exactly one JSON document on stdout. Every document has `"schema_version": 1`, and every size is an integer number of bytes.
+
+```bash
+purger info --json
+purger clean --json --yes
+```
+
+`purger clean --json` never prompts. With `--yes`, it runs the `safe` actions only. It reports each `caution` and `dangerous` action as `declined`. Without a terminal, purger applies the same rules.
+
+The help pages give the full document shape and the status values:
+
+```bash
+purger info --help
+purger clean --help
+```
+
+## Exit codes
+
+Both commands use these exit codes:
+
+| Code  | Meaning                                                                 |
+| ----- | ----------------------------------------------------------------------- |
+| `0`   | Success. This includes a run where you declined every action.           |
+| `1`   | An action that you approved failed. Only `purger clean` uses this code. |
+| `2`   | A usage error, such as an unknown plugin name or a run as root.         |
+| `130` | You pressed Ctrl-C.                                                     |
+
+## Contributing
+
+To build purger, run the tests, or add a plugin, read [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+purger is available under the [MIT License](LICENSE).

purger-0.2.0/pyproject.toml

@@ -0,0 +1,199 @@
+[project]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: System :: Filesystems",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "cyclopts>=5.4.0,<6",
+    "nclutils>=4.0.0,<5.0.0",
+    "psutil>=7.0.0,<8",
+    "rich>=15.0.0,<16",
+]
+description = "Find and clean rebuildable developer caches to free disk space."
+keywords = [
+    "cache",
+    "cleanup",
+    "cli",
+    "disk-space",
+    "docker",
+    "homebrew",
+    "uv",
+    "xcode",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+name = "purger"
+readme = "README.md"
+requires-python = ">=3.13"
+version = "0.2.0"
+
+[[project.authors]]
+name = "Nate Landau"
+email = "github@natenate.org"
+
+[project.urls]
+Changelog = "https://github.com/natelandau/purger/releases"
+Homepage = "https://github.com/natelandau/purger"
+Issues = "https://github.com/natelandau/purger/issues"
+Repository = "https://github.com/natelandau/purger"
+
+[project.scripts]
+purger = "purger.cli:main"
+
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build>=0.13.0,<0.14"]
+
+[tool.uv.build-backend]
+module-name = "purger"
+
+[tool.commitizen]
+bump_message = "bump(release): v$current_version → v$new_version"
+changelog_merge_prerelease = true
+major_version_zero = true
+tag_format = "v$version"
+update_changelog_on_bump = true
+version_files = ["src/purger/__init__.py:__version__"]
+version_provider = "uv"
+
+[tool.coverage.report]
+exclude_lines = [
+    "def __repr__",
+    "if TYPE_CHECKING",
+    "pragma: no cover",
+]
+fail_under = 90
+show_missing = true
+skip_covered = true
+skip_empty = true
+
+[tool.coverage.run]
+branch = true
+command_line = "--module pytest"
+data_file = ".cache/coverage"
+omit = ["tests/*"]
+source = ["src"]
+
+[tool.coverage.xml]
+output = ".cache/coverage.xml"
+
+[tool.pytest.ini_options]
+addopts = "--color=yes --strict-config --strict-markers -n auto --dist loadfile"
+cache_dir = ".cache/pytest"
+filterwarnings = ["error"]
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.ruff]
+exclude = [
+    ".cache",
+    ".git",
+    ".venv",
+    "build",
+    "dist",
+]
+fix = true
+line-length = 100
+output-format = "grouped"
+src = [
+    "src",
+    "tests",
+]
+target-version = "py313"
+
+[tool.ruff.lint]
+ignore = [
+    "ANN002",
+    "ANN003",
+    "ANN204",
+    "COM812",
+    "CPY001",
+    "D107",
+    "E501",
+    "FIX002",
+    "PLC0415",
+    "TD001",
+    "TD002",
+    "TD003",
+]
+select = ["ALL"]
+unfixable = [
+    "ERA001",
+    "F401",
+    "F841",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "A002",
+    "A003",
+    "ANN001",
+    "ANN002",
+    "ANN003",
+    "ANN201",
+    "ARG001",
+    "ARG002",
+    "ARG005",
+    "D102",
+    "ERA001",
+    "FBT001",
+    "PGH003",
+    "PLC0415",
+    "PLR0913",
+    "PLR0917",
+    "PLR2004",
+    "PLW0108",
+    "S101",
+    "SLF001",
+]
+"src/purger/plugins/_template.py" = ["ERA001"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.pylint]
+max-args = 7
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true
+
+[tool.ruff.format]
+indent-style = "space"
+line-ending = "auto"
+quote-style = "double"
+skip-magic-trailing-comma = false
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[dependency-groups]
+dev = [
+    "commitizen>=4.19.3",
+    "coverage>=7.17.2",
+    "duty>=1.10.1",
+    "gate-cache>=0.6.0",
+    "prek>=0.5.10",
+    "pytest-clarity>=1.0.1",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.17.0",
+    "pytest-repeat>=0.9.4",
+    "pytest-sugar>=1.1.1",
+    "pytest-xdist>=3.8.0",
+    "pytest>=9.2.0",
+    "ruff>=0.17.4",
+    "shellcheck-py>=0.11.0.1",
+    "ty>=0.0.100",
+    "types-psutil>=7.2.2.20260906",
+    "typos>=1.52.0",
+    "yamllint>=1.38.0",
+]