⚡ CleanStack

Limpiador y optimizador de espacio en disco de alto rendimiento y grado profesional enfocado a entornos de desarrollo de software y contenedores Docker.

Características • Arquitectura • Capas de Seguridad • Instalación • Uso CLI • Interfaz Gráfica • Docker • Compilación

---

📖 Visión General

Durante el ciclo de desarrollo diario con múltiples pilas tecnológicas (Node.js, Python, Java/Kotlin, Rust, Go, C/C++, .NET y Docker), los entornos de compilación y los gestores de paquetes acumulan decenas o cientos de gigabytes en artefactos prescindibles (node_modules, .venv, target/, cachés de compilación, contenedores huérfanos...).

CleanStack ha sido diseñado desde cero por Luis Lázaro Pimentel como una solución nativa, rápida y ante todo segura:

• Rendimiento extremo: Escaneo multihilo (ThreadPoolExecutor) optimizado para SSDs NVMe y CPUs multinúcleo con paralelismo en el cómputo de tamaños.
• Seguridad integral: Verificación del estado de Git (git status --porcelain), protección de rutas críticas del sistema y uso de la Papelera de Reciclaje (send2trash) para evitar borrados irreversibles accidentales.
• Experiencia dual: Potente CLI con tablas y barras de progreso interactivas con Rich, o GUI moderna en modo oscuro nativo con CustomTkinter.
• Zero-Spam & Anti-Falsos Positivos: Carpetas ambiguas como target/ o dist/ solo se consideran prescindibles si existen marcadores probatorios en el proyecto (ej. Cargo.toml, package.json o pom.xml).

---

🏛 Arquitectura Técnica

CleanStack adopta una arquitectura desacoplada en capas donde el núcleo del motor (Engine Core) es totalmente independiente de la interfaz gráfica y de la consola:

graph TD
    subgraph UI_Layer ["Capa de Presentación"]
        CLI["CLI (Rich Console & Tables)"]
        GUI["GUI (CustomTkinter Dark Slate/Indigo)"]
    end

    subgraph Core_Engine ["Engine Core (Backend)"]
        Scanner["Multi-Threaded Scanner<br/>(ThreadPoolExecutor + Work-Stealing)"]
        RuleSet["Rules & Marker Engine<br/>(Node, Python, Java, Rust, Docker...)"]
        GitCheck["Git Safety Checker<br/>(git status & ls-files porcelain)"]
        Cleaner["Safe Purge Engine<br/>(send2trash + Path Protection)"]
        DockerClean["Docker Engine SDK<br/>(Containers, Images, Cache, Volumes)"]
    end

    subgraph Config_Utils ["Utilidades & Configuración"]
        Config["Cascada YAML & .cleanignore"]
        Formatters["Formatters (Bytes, Tiempos, Rutas)"]
    end

    CLI --> Scanner
    CLI --> Cleaner
    CLI --> DockerClean
    GUI --> Scanner
    GUI --> Cleaner
    GUI --> DockerClean

    Scanner --> RuleSet
    Scanner --> Config
    Cleaner --> GitCheck
    Cleaner --> Config

Loading

---

🛡 Capas de Seguridad Obligatorias

1. Modo Simulación (--dry-run): Calcula con exactitud quirúrgica los bytes liberables, archivos afectados y tiempos sin realizar ninguna modificación en disco.
2. Borrado Seguro (send2trash): En lugar de un rmtree destructivo e irreversible, los elementos se trasladan a la Papelera de Reciclaje del sistema operativo. Si la ruta pertenece a una unidad de red o WSL sin soporte de papelera, CleanStack bloquea la operación y solicita confirmación de borrado permanente.
3. Git Safety Check (GitPython / subprocess): Comprueba automáticamente git status --porcelain en el proyecto y git ls-files. Si el proyecto tiene cambios pendientes no commiteados o si el artefacto está versionado en el repositorio, se marca en alerta roja y se omite de la purga a menos que se use --force.
4. Reglas Anti-Falsos Positivos (Markers): Carpetas con nombres estándar (target, build, bin, dist) no se tocan a menos que en el directorio exista el archivo de manifiesto correspondiente (Cargo.toml para Rust, package.json para Node, pom.xml para Java, CMakeLists.txt para C++).
5. Protección de Rutas del Sistema: Raíces de unidad (C:\, /), directorios de usuario base (%USERPROFILE%), carpetas de Windows y directorios del sistema operativo están protegidos en el núcleo.
6. Soporte de Exclusiones (.cleanignore & YAML): Reglas globales y por proyecto para proteger carpetas sensibles utilizando la sintaxis estándar tipo .gitignore.

---

📦 Ecosistemas Soportados

Ecosistema	Artefactos Detectados	Marcador de Verificación Requerido	Riesgo
Node.js / Web	node_modules, .next, .nuxt, .cache, build, dist	package.json	Medio / Alto
Python	.venv, venv, __pycache__, .pytest_cache, .mypy_cache, *.pyc, build, *.egg-info	pyvenv.cfg, setup.py, pyproject.toml	Bajo / Medio
Java / Kotlin	target/, .gradle/, build/, .out/, out/	pom.xml, build.gradle, *.iml	Bajo / Medio
Rust	target/	Cargo.toml	Medio
Go	bin/	go.mod	Alto
.NET	bin/, obj/	*.csproj, *.fsproj, *.sln	Medio
C / C++	bin/, obj/, cmake-build-*, *.o, *.exe, *.dll, *.so	CMakeLists.txt, Makefile, *.vcxproj	Medio / Alto
Docker	Contenedores detenidos, imágenes huérfanas (dangling), build cache, volúmenes sin usar	Docker Daemon API	Configurable

---

🚀 Instalación y Requisitos

Requisitos

• Python 3.11, 3.12 o 3.13 (64-bit).
• Windows 11 / WSL2 o Linux.
• Opcional: Docker Desktop en ejecución para las funcionalidades de Docker.

Instalación en Entorno Virtual

# 1. Clonar el repositorio o situarse en la carpeta
cd CleanStack

# 2. Crear y activar el entorno virtual
python -m venv .venv
.\.venv\Scripts\activate

# 3. Instalar dependencias
pip install -r requirements.txt

---

💻 Guía de Uso CLI

CleanStack incorpora una interfaz de línea de comandos ultrarrápida impulsada por Rich.

1. Escanear espacio recuperable

Analiza el directorio actual o las rutas indicadas sin modificar nada:

# Escaneo de la carpeta actual
python -m src.main scan

# Escaneo de una o varias rutas de proyectos
python -m src.main scan C:\Users\Luis\dev D:\Workspace

# Filtrar por un ecosistema concreto y tamaño mínimo
python -m src.main scan ~/dev -e node -e python --min-size 50MB

# Agrupar el reporte por proyecto en lugar de por artefacto
python -m src.main scan ~/dev --by-project

# Salida estructurada en JSON para automatizaciones
python -m src.main scan ~/dev --json

2. Purga segura (Papelera de reciclaje)

# Modo Simulación (Dry-Run): calcula exactamente qué se liberaría
python -m src.main purge ~/dev --dry-run

# Purga segura interactiva (los elementos van a la Papelera de Reciclaje)
python -m src.main purge ~/dev

# Purgar sin confirmación interactiva (los artefactos con riesgo Git se omiten)
python -m src.main purge ~/dev -y

# Forzar la inclusión de proyectos con cambios pendientes en Git
python -m src.main purge ~/dev --force

3. Consultar reglas activas o configuración

# Ver todas las reglas y marcadores activos
python -m src.main rules

# Ver la configuración efectiva actual
python -m src.main config --show

# Crear el fichero de configuración de usuario en %APPDATA%/CleanStack/cleanstack.yaml
python -m src.main config --init

---

🐳 Optimización de Docker

CleanStack se comunica de forma nativa con el socket o named pipe del daemon de Docker (docker system df y endpoints de prune):

# Analizar espacio recuperable en Docker (modo simulación)
python -m src.main docker -n

# Purgar contenedores parados, imágenes huérfanas y build cache
python -m src.main docker

# Ver detalle individual de cada contenedor o imagen
python -m src.main docker --details

# Incluir volúmenes sin usar (¡precaución con bases de datos persistentes!)
python -m src.main docker --volumes

---

🖥 Interfaz Gráfica (GUI CustomTkinter)

Para iniciar la interfaz de escritorio en Dark Mode:

python -m src.main gui
# O simplemente:
python -m src.main

Características de la GUI

• Dashboard Métrico: Indicadores de GB recuperables, total de artefactos y capacidad disponible en disco en tiempo real.
• Barra de Distribución: Gráfico segmentado por colores representativos de cada tecnología (Node en verde, Python en amarillo, Docker en azul, etc.).
• Filtros Dinámicos: Búsqueda en vivo por texto y selector de stack tecnológico.
• Selección Selectiva: Checkboxes independientes para cada artefacto, con botones de "Seleccionar Todo" y "Deseleccionar".
• Acceso Directo: Botón 📂 para abrir de inmediato la carpeta del artefacto en el Explorador de Windows.
• Modal de Confirmación: Diálogo informativo previo a cualquier purga con advertencias de repositorios Git sucios.
• Pestaña Docker: Tarjetas con switches individuales para purgar contenedores, imágenes huérfanas, caché de build y volúmenes.

---

🧪 Pruebas Unitarias

La suite de pruebas automatizadas garantiza la integridad del escáner multihilo, el motor de reglas y la seguridad de borrado:

.\.venv\Scripts\python -m pytest tests/ -v

Resultado:

tests/test_cleaner.py::test_cleaner_dry_run PASSED
tests/test_cleaner.py::test_cleaner_trash_mode PASSED
tests/test_cleaner.py::test_cleaner_git_safety_blocks_dirty_project PASSED
tests/test_cleaner.py::test_cleaner_protected_paths PASSED
tests/test_cleaner.py::test_docker_cleaner_analysis_with_mock PASSED
tests/test_config.py::test_formatters PASSED
tests/test_config.py::test_shorten_path PASSED
tests/test_config.py::test_default_config_loading PASSED
tests/test_config.py::test_config_merge_with_explicit_yaml PASSED
tests/test_config.py::test_config_invalid_file PASSED
tests/test_config.py::test_cleanignore_patterns PASSED
tests/test_scanner.py::test_scanner_node_project PASSED
tests/test_scanner.py::test_scanner_rust_marker_protection PASSED
tests/test_scanner.py::test_scanner_python_venv_and_pycache PASSED
tests/test_scanner.py::test_scanner_with_cleanignore PASSED
tests/test_scanner.py::test_scanner_min_size_filter PASSED
tests/test_scanner.py::test_scanner_cancellation PASSED
============================== 17 passed in 0.15s ==============================

---

🔨 Empaquetado a Ejecutable (.exe)

CleanStack incluye un script de compilación automatizado basado en PyInstaller:

# 1. Compilar binario autónomo para Windows sin consola auxiliar (Windowed GUI)
python build.py

# 2. Compilar binario con soporte de consola CLI
python build.py --console

# 3. Generar distribución en directorio (arranque instantáneo)
python build.py --onedir

El ejecutable final se genera en la carpeta dist/CleanStack.exe, completamente empaquetado con todos los recursos de configuración y temas de CustomTkinter incluidos.

---

📄 Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.

Autor: Luis Lázaro Pimentel (Software & Systems Developer)