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.
- bekas-0.1.0/.github/workflows/publish.yml +39 -0
- bekas-0.1.0/.gitignore +123 -0
- bekas-0.1.0/.pre-commit-config.yaml +22 -0
- bekas-0.1.0/LICENSE +21 -0
- bekas-0.1.0/PKG-INFO +303 -0
- bekas-0.1.0/README.md +280 -0
- bekas-0.1.0/bekas_PRD.md +1043 -0
- bekas-0.1.0/pyproject.toml +85 -0
- bekas-0.1.0/src/bekas/__init__.py +11 -0
- bekas-0.1.0/src/bekas/clean.py +191 -0
- bekas-0.1.0/src/bekas/cli.py +450 -0
- bekas-0.1.0/src/bekas/config.py +201 -0
- bekas-0.1.0/src/bekas/database.py +231 -0
- bekas-0.1.0/src/bekas/formatters.py +137 -0
- bekas-0.1.0/src/bekas/models.py +242 -0
- bekas-0.1.0/src/bekas/plugin.py +152 -0
- bekas-0.1.0/src/bekas/plugins/docker_containers.py +110 -0
- bekas-0.1.0/src/bekas/plugins/docker_images.py +277 -0
- bekas-0.1.0/src/bekas/plugins/dotfiles_backups.py +132 -0
- bekas-0.1.0/src/bekas/plugins/downloads.py +117 -0
- bekas-0.1.0/src/bekas/plugins/git_branches.py +192 -0
- bekas-0.1.0/src/bekas/plugins/node_modules.py +259 -0
- bekas-0.1.0/src/bekas/plugins/python_cache.py +147 -0
- bekas-0.1.0/src/bekas/plugins/python_venvs.py +203 -0
- bekas-0.1.0/src/bekas/plugins/rust_target.py +172 -0
- bekas-0.1.0/src/bekas/plugins/screenshots.py +136 -0
- bekas-0.1.0/src/bekas/plugins/system_tmp.py +99 -0
- bekas-0.1.0/src/bekas/quarantine.py +126 -0
- bekas-0.1.0/src/bekas/runner.py +117 -0
- bekas-0.1.0/src/bekas/safety.py +191 -0
- bekas-0.1.0/src/bekas/signing.py +66 -0
- bekas-0.1.0/src/bekas/tui.py +119 -0
- bekas-0.1.0/tests/integration/__init__.py +1 -0
- bekas-0.1.0/tests/integration/test_plugins_integration.py +223 -0
- bekas-0.1.0/tests/test_clean.py +157 -0
- bekas-0.1.0/tests/test_cli.py +189 -0
- bekas-0.1.0/tests/test_config.py +26 -0
- bekas-0.1.0/tests/test_database.py +95 -0
- bekas-0.1.0/tests/test_formatters.py +114 -0
- bekas-0.1.0/tests/test_models.py +39 -0
- bekas-0.1.0/tests/test_quarantine.py +116 -0
- bekas-0.1.0/tests/test_runner.py +39 -0
- bekas-0.1.0/tests/test_safety.py +25 -0
- bekas-0.1.0/tests/test_safety_advanced.py +95 -0
- 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
|