bekas 0.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 (45) hide show
  1. bekas-0.1.0/.github/workflows/publish.yml +39 -0
  2. bekas-0.1.0/.gitignore +123 -0
  3. bekas-0.1.0/.pre-commit-config.yaml +22 -0
  4. bekas-0.1.0/LICENSE +21 -0
  5. bekas-0.1.0/PKG-INFO +303 -0
  6. bekas-0.1.0/README.md +280 -0
  7. bekas-0.1.0/bekas_PRD.md +1043 -0
  8. bekas-0.1.0/pyproject.toml +85 -0
  9. bekas-0.1.0/src/bekas/__init__.py +11 -0
  10. bekas-0.1.0/src/bekas/clean.py +191 -0
  11. bekas-0.1.0/src/bekas/cli.py +450 -0
  12. bekas-0.1.0/src/bekas/config.py +201 -0
  13. bekas-0.1.0/src/bekas/database.py +231 -0
  14. bekas-0.1.0/src/bekas/formatters.py +137 -0
  15. bekas-0.1.0/src/bekas/models.py +242 -0
  16. bekas-0.1.0/src/bekas/plugin.py +152 -0
  17. bekas-0.1.0/src/bekas/plugins/docker_containers.py +110 -0
  18. bekas-0.1.0/src/bekas/plugins/docker_images.py +277 -0
  19. bekas-0.1.0/src/bekas/plugins/dotfiles_backups.py +132 -0
  20. bekas-0.1.0/src/bekas/plugins/downloads.py +117 -0
  21. bekas-0.1.0/src/bekas/plugins/git_branches.py +192 -0
  22. bekas-0.1.0/src/bekas/plugins/node_modules.py +259 -0
  23. bekas-0.1.0/src/bekas/plugins/python_cache.py +147 -0
  24. bekas-0.1.0/src/bekas/plugins/python_venvs.py +203 -0
  25. bekas-0.1.0/src/bekas/plugins/rust_target.py +172 -0
  26. bekas-0.1.0/src/bekas/plugins/screenshots.py +136 -0
  27. bekas-0.1.0/src/bekas/plugins/system_tmp.py +99 -0
  28. bekas-0.1.0/src/bekas/quarantine.py +126 -0
  29. bekas-0.1.0/src/bekas/runner.py +117 -0
  30. bekas-0.1.0/src/bekas/safety.py +191 -0
  31. bekas-0.1.0/src/bekas/signing.py +66 -0
  32. bekas-0.1.0/src/bekas/tui.py +119 -0
  33. bekas-0.1.0/tests/integration/__init__.py +1 -0
  34. bekas-0.1.0/tests/integration/test_plugins_integration.py +223 -0
  35. bekas-0.1.0/tests/test_clean.py +157 -0
  36. bekas-0.1.0/tests/test_cli.py +189 -0
  37. bekas-0.1.0/tests/test_config.py +26 -0
  38. bekas-0.1.0/tests/test_database.py +95 -0
  39. bekas-0.1.0/tests/test_formatters.py +114 -0
  40. bekas-0.1.0/tests/test_models.py +39 -0
  41. bekas-0.1.0/tests/test_quarantine.py +116 -0
  42. bekas-0.1.0/tests/test_runner.py +39 -0
  43. bekas-0.1.0/tests/test_safety.py +25 -0
  44. bekas-0.1.0/tests/test_safety_advanced.py +95 -0
  45. bekas-0.1.0/tests/test_signing.py +28 -0
@@ -0,0 +1,39 @@
1
+ name: Test, Build & Publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ test-build-publish:
10
+ runs-on: ubuntu-latest
11
+
12
+ steps:
13
+ - name: Checkout repository
14
+ uses: actions/checkout@v4
15
+
16
+ - name: Set up Python
17
+ uses: actions/setup-python@v5
18
+ with:
19
+ python-version: "3.9"
20
+
21
+ - name: Install dependencies
22
+ run: |
23
+ python -m pip install --upgrade pip
24
+ pip install .[dev]
25
+ pip install pytest build twine
26
+
27
+ - name: Run tests
28
+ run: pytest -v
29
+
30
+ - name: Build package
31
+ if: success()
32
+ run: python -m build
33
+
34
+ - name: Publish to PyPI
35
+ if: success()
36
+ env:
37
+ TWINE_USERNAME: __token__
38
+ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
39
+ run: twine upload dist/*
bekas-0.1.0/.gitignore ADDED
@@ -0,0 +1,123 @@
1
+ # Created by https://www.gitignore.io/api/python
2
+ # Edit at https://www.gitignore.io/?templates=python
3
+
4
+ # internal
5
+ log/*
6
+
7
+ ### Python ###
8
+ # Byte-compiled / optimized / DLL files
9
+ __pycache__/
10
+ *.py[cod]
11
+ *$py.class
12
+
13
+ # C extensions
14
+ *.so
15
+
16
+ # Distribution / packaging
17
+ .Python
18
+ build/
19
+ jars/
20
+ develop-eggs/
21
+ dist/
22
+ downloads/
23
+ eggs/
24
+ .eggs/
25
+ lib/
26
+ lib64/
27
+ parts/
28
+ sdist/
29
+ var/
30
+ wheels/
31
+ pip-wheel-metadata/
32
+ share/python-wheels/
33
+ *.egg-info/
34
+ .installed.cfg
35
+ *.egg
36
+ MANIFEST
37
+
38
+ # PyInstaller
39
+ # Usually these files are written by a python script from a template
40
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
41
+ *.manifest
42
+ *.spec
43
+
44
+ # Installer logs
45
+ pip-log.txt
46
+ pip-delete-this-directory.txt
47
+
48
+ # Unit test / coverage reports
49
+ htmlcov/
50
+ .tox/
51
+ .nox/
52
+ .coverage.*
53
+ .cache
54
+ nosetests.xml
55
+ coverage.xml
56
+ *.cover
57
+ .hypothesis/
58
+ .pytest_cache/
59
+
60
+ # Translations
61
+ *.mo
62
+ *.pot
63
+
64
+ # Sphinx documentation
65
+ docs/_build/
66
+
67
+ # PyBuilder
68
+ target/
69
+
70
+ # Jupyter Notebook
71
+ .ipynb_checkpoints
72
+
73
+ # IPython
74
+ profile_default/
75
+ ipython_config.py
76
+
77
+ # pyenv
78
+ .python-version
79
+
80
+ # pipenv
81
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
82
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
83
+ # having no cross-platform support, pipenv may install dependencies that don’t work, or not
84
+ # install all needed dependencies.
85
+ #Pipfile.lock
86
+
87
+ # celery beat schedule file
88
+ celerybeat-schedule
89
+
90
+ # SageMath parsed files
91
+ *.sage.py
92
+
93
+ # Environments
94
+ .env
95
+ .venv
96
+ env/
97
+ venv/
98
+ ENV/
99
+ env.bak/
100
+ venv.bak/
101
+
102
+ # Spyder project settings
103
+ .spyderproject
104
+ .spyproject
105
+
106
+ # Rope project settings
107
+ .ropeproject
108
+
109
+ # mkdocs documentation
110
+ /site
111
+
112
+ # End of https://www.gitignore.io/api/python
113
+
114
+ build/*
115
+ test/data/demand_forecaster/save_model.model
116
+ condaenv.t1e302om.requirements.txt
117
+
118
+ *.env
119
+ *.aes
120
+
121
+ # local IDE stuffs
122
+ .idea/*
123
+ .coverage
@@ -0,0 +1,22 @@
1
+ # .pre-commit-config.yaml
2
+
3
+ repos:
4
+ - repo: https://github.com/pre-commit/pre-commit-hooks
5
+ rev: v4.5.0
6
+ hooks:
7
+ - id: check-merge-conflict
8
+ - id: no-commit-to-branch
9
+ args: [--branch, main]
10
+ - id: trailing-whitespace
11
+ - id: end-of-file-fixer
12
+ - id: check-added-large-files
13
+
14
+ # Ruff for both linting and formatting
15
+ - repo: https://github.com/astral-sh/ruff-pre-commit
16
+ rev: v0.6.8
17
+ hooks:
18
+ - id: ruff
19
+ args: [--fix]
20
+ types: [python]
21
+ - id: ruff-format
22
+ types: [python]
bekas-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ragil Prasetyo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
bekas-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,303 @@
1
+ Metadata-Version: 2.4
2
+ Name: bekas
3
+ Version: 0.1.0
4
+ Summary: A CLI utility that audits your local machine for stuff you forgot and helps you safely reclaim disk space.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.11
8
+ Requires-Dist: click>=8.0
9
+ Requires-Dist: platformdirs>=4.0
10
+ Requires-Dist: psutil>=5.9
11
+ Requires-Dist: pydantic>=2.0
12
+ Requires-Dist: pyyaml>=6.0
13
+ Requires-Dist: rich>=13.0
14
+ Requires-Dist: textual>=0.50
15
+ Provides-Extra: dev
16
+ Requires-Dist: mypy>=1.0; extra == 'dev'
17
+ Requires-Dist: pytest-cov>=4.0; extra == 'dev'
18
+ Requires-Dist: pytest>=7.0; extra == 'dev'
19
+ Requires-Dist: ruff>=0.1.0; extra == 'dev'
20
+ Requires-Dist: types-psutil; extra == 'dev'
21
+ Requires-Dist: types-pyyaml; extra == 'dev'
22
+ Description-Content-Type: text/markdown
23
+
24
+ # bekas
25
+
26
+ One audit. Every kind of forgotten thing. Nothing deleted you cared about.
27
+
28
+ `bekas` is a CLI utility that audits your local machine for stuff you forgot — orphaned Docker images, unused git branches, old `node_modules`, dangling Python venvs, stale downloads, screenshots from years ago — and helps you safely reclaim disk space. Every destructive action is logged to an SQLite undo log and can be quarantined before permanent deletion.
29
+
30
+ ---
31
+
32
+ ## Table of Contents
33
+
34
+ - [Installation](#installation)
35
+ - [Quick Start](#quick-start)
36
+ - [Commands](#commands)
37
+ - [`audit`](#bekas-audit)
38
+ - [`plan`](#bekas-plan)
39
+ - [`clean`](#bekas-clean)
40
+ - [`inspect`](#bekas-inspect)
41
+ - [`history` / `undo`](#bekas-history--undo)
42
+ - [`quarantine`](#bekas-quarantine)
43
+ - [`plugins`](#bekas-plugins)
44
+ - [`config`](#bekas-config)
45
+ - [`tui`](#bekas-tui)
46
+ - [Plugins](#plugins)
47
+ - [Configuration](#configuration)
48
+ - [Safety Model](#safety-model)
49
+ - [Architecture & File Structure](#architecture--file-structure)
50
+ - [License](#license)
51
+
52
+ ---
53
+
54
+ ## Installation
55
+
56
+ ```bash
57
+ pip install bekas
58
+ ```
59
+
60
+ Requires **Python 3.11+**. Some plugins (e.g. Docker, Git) require the corresponding CLI tools to be installed.
61
+
62
+ ---
63
+
64
+ ## Quick Start
65
+
66
+ ```bash
67
+ # 1. Run a read-only audit
68
+ bekas audit
69
+
70
+ # 2. Preview what a clean would remove
71
+ bekas plan
72
+
73
+ # 3. Clean only the safest items (dry-run by default)
74
+ bekas clean --apply --safe-only
75
+ ```
76
+
77
+ ---
78
+
79
+ ## Commands
80
+
81
+ ### `bekas audit`
82
+
83
+ Runs a read-only scan across all available plugins and prints candidates.
84
+
85
+ ```bash
86
+ bekas audit # Human-readable output
87
+ bekas audit --json # JSON output
88
+ bekas audit --plugin docker # Only run Docker plugins
89
+ bekas audit --serial # Run plugins one at a time
90
+ ```
91
+
92
+ ### `bekas plan`
93
+
94
+ Converts the latest audit into a concrete removal plan. You can save a cryptographically signed plan to disk and apply it later.
95
+
96
+ ```bash
97
+ bekas plan # Preview in human-readable format
98
+ bekas plan --safe-only # Only SAFE-tier items
99
+ bekas plan --include-review # Include REVIEW-tier items
100
+ bekas plan --save plan.json # Save a signed plan file
101
+ ```
102
+
103
+ ### `bekas clean`
104
+
105
+ The only command that actually removes files. **Dry-run by default** — you must pass `--apply` to delete anything.
106
+
107
+ ```bash
108
+ bekas clean --apply --safe-only # Auto-clean safe items
109
+ bekas clean --apply --yes-all # Skip per-category prompts
110
+ bekas clean --apply --non-interactive \
111
+ --accept-categories "docker,tmp" # CI-friendly mode
112
+ bekas clean --apply --plan-file plan.json # Apply a signed plan
113
+ ```
114
+
115
+ Options:
116
+
117
+ - `--apply` — Actually delete (default is dry-run).
118
+ - `--safe-only` — Only include `SAFE`-tier candidates.
119
+ - `--review` / `--include-review` — Include `REVIEW`-tier candidates.
120
+ - `--yes-all` — Skip all interactive prompts.
121
+ - `--non-interactive` — Requires `--accept-categories`.
122
+ - `--accept-categories` — Comma-separated category whitelist for non-interactive runs.
123
+ - `--plan-file` — Apply a previously saved signed plan instead of re-auditing.
124
+
125
+ ### `bekas inspect <id>`
126
+
127
+ Show full metadata and reasoning for a single candidate.
128
+
129
+ ```bash
130
+ bekas inspect ss:Screenshot_2023-01-01.png
131
+ ```
132
+
133
+ ### `bekas history` / `bekas undo`
134
+
135
+ Every `clean --apply` is persisted to an SQLite undo log.
136
+
137
+ ```bash
138
+ bekas history # List past runs
139
+ bekas history <run_id> # Show details for one run
140
+ bekas undo # Undo the most recent run
141
+ bekas undo <run_id> # Undo a specific run
142
+ ```
143
+
144
+ ### `bekas quarantine`
145
+
146
+ Files removed by plugins that support quarantine are moved to a quarantine directory instead of being permanently deleted. You can restore them later.
147
+
148
+ ```bash
149
+ bekas quarantine list # Show quarantined items
150
+ bekas quarantine restore <quarantine_id> # Restore to original path
151
+ bekas quarantine purge # Empty quarantine immediately
152
+ ```
153
+
154
+ ### `bekas plugins`
155
+
156
+ List, enable, or disable plugins.
157
+
158
+ ```bash
159
+ bekas plugins list # Show installed plugins and availability
160
+ bekas plugins enable <name> # Enable a plugin (edit config)
161
+ bekas plugins disable <name> # Disable a plugin (edit config)
162
+ ```
163
+
164
+ ### `bekas config`
165
+
166
+ Print the current effective configuration.
167
+
168
+ ```bash
169
+ bekas config
170
+ ```
171
+
172
+ ### `bekas tui`
173
+
174
+ Launch an interactive Textual TUI for browsing candidates and cleaning interactively.
175
+
176
+ ```bash
177
+ bekas tui
178
+ ```
179
+
180
+ ---
181
+
182
+ ## Plugins
183
+
184
+ | Plugin | Category | What it finds | Needs `docker` / `git` |
185
+ |---|---|---|---|
186
+ | `docker.images` | `docker.image.*` | Dangling & unused Docker images | docker |
187
+ | `docker.containers` | `docker.container.*` | Stopped containers | docker |
188
+ | `python.venvs` | `python.venv` | Orphaned Python virtual environments | — |
189
+ | `python.cache` | `python.cache` | `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache` | — |
190
+ | `node.modules` | `node.modules` | Old `node_modules` directories | — |
191
+ | `rust.target` | `rust.target` | Old `target/` build directories | — |
192
+ | `git.branches` | `git.branch` | Fully-merged local branches | git |
193
+ | `downloads` | `downloads.file` | Old files in `~/Downloads` | — |
194
+ | `screenshots` | `screenshots.file` | Old screenshots (Desktop / Pictures) | — |
195
+ | `system.tmp` | `system.tmp` | Old temp files owned by you | — |
196
+ | `dotfiles.backups` | `dotfiles.backups` | Backup files like `.zshrc.bak` | — |
197
+
198
+ Plugins are auto-discovered via `entry_points` in `pyproject.toml`. You can write your own by subclassing `bekas.plugin.Plugin`.
199
+
200
+ ---
201
+
202
+ ## Configuration
203
+
204
+ The first time you run `bekas`, a config file is created at the platform-specific config directory (e.g. `~/.config/bekas/config.yaml` on Linux).
205
+
206
+ Example:
207
+
208
+ ```yaml
209
+ version: "0.1.0"
210
+ active_profile: default
211
+ profiles:
212
+ default:
213
+ enabled_plugins: ["*"]
214
+ quarantine_enabled: true
215
+ # Per-plugin thresholds
216
+ plugin_settings:
217
+ screenshots:
218
+ min_age_days: 90
219
+ downloads:
220
+ min_age_days: 180
221
+ python.venvs:
222
+ min_idle_days: 90
223
+ node.modules:
224
+ min_idle_days: 180
225
+ rust.target:
226
+ min_idle_days: 60
227
+ python.cache:
228
+ min_idle_days: 90
229
+ system.tmp:
230
+ min_age_days: 30
231
+ git.branches:
232
+ min_idle_days: 90
233
+ # Repositories for the git.branches plugin
234
+ git_repos:
235
+ - ~/code
236
+ - ~/projects
237
+ ```
238
+
239
+ ---
240
+
241
+ ## Safety Model
242
+
243
+ - **Read-only by default** — `audit` and `plan` never touch the filesystem.
244
+ - **Dry-run by default** — `clean` without `--apply` only prints a preview.
245
+ - **Confidence tiers** — Every candidate is classified as:
246
+ - `SAFE` — Low risk (e.g. dangling Docker image, no project nearby).
247
+ - `REVIEW` — Medium risk (e.g. old download, active project but untouched).
248
+ - `MANUAL` — High risk (e.g. branch on an active project, container in use).
249
+ - **Hard exclusions** — System paths and sensitive files are automatically excluded.
250
+ - **Quarantine** — Deletable files are moved to a quarantine folder so you can `restore` them later.
251
+ - **Undo log** — Every `clean --apply` is recorded in SQLite with per-candidate results and undo tokens.
252
+ - **Signed plans** — Saved plan files include a signature to detect tampering.
253
+
254
+ ---
255
+
256
+ ## Architecture & File Structure
257
+
258
+ ```
259
+ bekas/
260
+ ├── src/bekas/
261
+ │ ├── __init__.py # Package metadata
262
+ │ ├── cli.py # Click CLI entry point & commands
263
+ │ ├── models.py # Core dataclasses: Candidate, Plan, AuditReport, etc.
264
+ │ ├── plugin.py # Plugin base class & discovery
265
+ │ ├── runner.py # Orchestrates plugin discovery and runs audits
266
+ │ ├── clean.py # Applies a Plan: removes, quarantines, logs
267
+ │ ├── safety.py # Exclusion engine (path safety, pattern matching)
268
+ │ ├── config.py # Config file I/O and profile resolution
269
+ │ ├── formatters.py # Human, JSON, Markdown output formatters
270
+ │ ├── database.py # SQLite undo log & quarantine registry
271
+ │ ├── quarantine.py # Move / restore / purge quarantined items
272
+ │ ├── signing.py # Plan file signing & verification
273
+ │ ├── tui.py # Textual interactive UI
274
+ │ └── plugins/
275
+ │ ├── docker_images.py # Dangling & unused Docker images
276
+ │ ├── docker_containers.py # Stopped containers
277
+ │ ├── python_venvs.py # Orphaned Python virtual environments
278
+ │ ├── python_cache.py # __pycache__ & tool caches
279
+ │ ├── node_modules.py # Old node_modules directories
280
+ │ ├── rust_target.py # Rust target/ directories
281
+ │ ├── git_branches.py # Stale merged local branches
282
+ │ ├── downloads.py # Old files in ~/Downloads
283
+ │ ├── screenshots.py # Old screenshots
284
+ │ ├── system_tmp.py # Old temp files
285
+ │ └── dotfiles_backups.py # Dotfile backup files
286
+ ├── tests/ # pytest test suite
287
+ ├── pyproject.toml # Project metadata, deps, entry points
288
+ └── README.md # This file
289
+ ```
290
+
291
+ ### Key design principles
292
+
293
+ - **Plugin architecture** — Every scanner is a `Plugin`. The runner loads them via `entry_points`, so third-party plugins can be added without touching core code.
294
+ - **Context-driven** — Each plugin receives a `Context` carrying the active profile, dry-run flag, and verbosity. This keeps plugins stateless and testable.
295
+ - **Immutable models** — `Candidate`, `Plan`, `RemovalResult`, etc. are dataclasses with strong typing. `AuditReport` uses Pydantic for JSON serialization.
296
+ - **Quarantine-first** — Plugins that support quarantine (`supports_quarantine() -> True`) move items to a staging area instead of deleting immediately. The CLI controls whether quarantine is enabled per profile.
297
+ - **Audit trail** — `database.py` writes every run to an SQLite DB; `undo` reads it back and restores quarantined items via their undo tokens.
298
+
299
+ ---
300
+
301
+ ## License
302
+
303
+ MIT