🧹 Sistema de Limpeza Inteligente 🧹

🚀 Libere espaço, organize arquivos e mantenha seu sistema limpo como nunca

📖 Índice

🤔 O que é isso?
✨ Funcionalidades
🏗️ Arquitetura
📦 Instalação
🎯 Como Usar
⚙️ Estrutura do Storage
🎨 Exemplos de Uso
🔧 Configuração
🤝 Contribuindo
📜 Licença

🤔 O que é isso?

Sabe aquele momento que você olha pro seu disco e tá 92% cheio de node_modules, caches e arquivos temporários que você nem lembra que existem? Pois é.

Este é um sistema completo de gerenciamento de arquivos para ambientes de desenvolvimento Linux. Ele não só limpa seu sistema, mas também:

🗄️ Arquiva arquivos antigos de forma inteligente
🗑️ Move para um "lixão" compactado (com tags bonitinhas)
🔄 Restaura tudo quando você precisar
📊 Organiza com políticas de retenção automatizadas
💾 Economiza espaço com compressão máxima

✨ Funcionalidades

🧹 Limpeza Tradicional

📦 Node Modules: Detecta e remove node_modules antigos ou inativos (>30 dias)
🐍 Cache Python: ⭐ NOVO! __pycache__, .pytest_cache, .mypy_cache, .ruff_cache, .tox, htmlcov, .pyc/.pyo/.pyd
🗂️ Arquivos Temporários: .tmp, .temp, .bak, .swp, ~, etc.
💾 Caches: .next, .nuxt, dist, build, .cache
📋 Logs Antigos: Arquivos .log com mais de 7 dias
🗑️ Lixeira do Sistema: Limpa ~/.local/share/Trash (apenas em --full)
🔒 Proteção Automática: Diretórios críticos (.config, .var, .vscode, etc.) são sempre protegidos

🗄️ Arquivamento Inteligente

O sistema implementa políticas de retenção automáticas que movem arquivos antigos para um storage dedicado:

Categoria	Política	Descrição
📊 Reports	15 dias	Mantém apenas 1 relatório por dia dos últimos 15 dias
💾 Backups	Top 2	Mantém apenas os 2 backups mais recentes por categoria
📋 Logs	7 dias	Move logs com mais de 7 dias
📦 Node Modules	30 dias	Arquiva projetos inativos há mais de 30 dias

Diferencial: Usa metadados do sistema de arquivos (mtime) em vez de nomenclatura, garantindo confiabilidade independente de como você nomeou seus arquivos.

🗑️ Lixão Compactado

Move arquivos para um "lixão" no storage com:

✅ Compressão máxima (nível 9)
🏷️ Tags organizadas: [OLD-REPORTS], [ARCHIVED], [NODE-MODULES], etc.
📊 Metadados completos de cada operação
🔍 Busca rápida sem precisar descompactar tudo

🔄 Sistema de Restauração

📋 Lista todos os archives e itens do lixão
🔍 Busca inteligente por arquivo específico
📂 Extração seletiva (não precisa restaurar tudo)
🎯 Destino personalizável

🏗️ Arquitetura

cleaning/
│
├── main.py                  # ⭐ Entry point (415 linhas)
│                            # - Parsing de argumentos com argparse
│                            # - Roteamento para managers (storage/archive/trash/restore)
│                            # - Importações absolutas para melhor manutenção
│
├── modules/
│   ├── __init__.py          # Package initialization com absolute imports
│   ├── cleaner.py           # ⭐ NOVO: LimpadorSistema (536 linhas)
│   │                        # - Lógica principal de limpeza
│   │                        # - Proteção de diretórios críticos
│   │                        # - Modo Python-only
│   ├── storage_manager.py   # Gerenciador do /mnt/storage
│   ├── archive_manager.py   # Sistema de arquivamento inteligente
│   ├── trash_manager.py     # Lixão compactado
│   └── restore_manager.py   # Restauração de arquivos
│
└── utils/                   # ⭐ NOVO: Utilitários reutilizáveis
    ├── __init__.py
    └── file_utils.py        # format_size, get_dir_size, is_old_file, is_old_or_inactive

Mudanças Arquiteturais (Dezembro 2025):

✅ Refatoração modular: main.py (845 linhas) → main.py (415 linhas) + modules/cleaner.py (536 linhas)
✅ Package utils/ criado para funções reutilizáveis
✅ Imports relativos → absolutos em todos os módulos (melhor IDE support e clareza)
✅ Redução de 52% no tamanho do arquivo principal

📁 Estrutura do Storage

O sistema cria e gerencia a seguinte estrutura em um disco de armazenamento:

/mnt/storage/                    # ← Pode ser configurado
│
├── archives/                    # Arquivos movidos com metadados
│   ├── moving-20241103-143022/
│   │   ├── reports/
│   │   └── backups/
│   └── index_archives.json      # Índice de todas operações
│
├── trash/                       # Lixão compactado
│   ├── compressed/              # .tar.gz files
│   │   └── [TAG]_nome_timestamp.tar.gz
│   ├── metadata/                # Metadados das compressões
│   └── manifest_trash.json      # Manifest do lixão
│
├── recovery/                    # Área temporária de restauração
│
└── .storage-config/             # Configurações e políticas
    ├── config.json
    ├── policies.json
    └── usage.json

📦 Instalação

Pré-requisitos

🐍 Python 3.6+
🐧 Sistema Linux
💾 Espaço em disco para o storage (recomendado: disco dedicado)

Instalação Rápida

# Clone o repositório
git clone https://github.com/montezuma-p/linux-storage-manager
cd linux-storage-manager

# Torna o script executável
chmod +x main.py

# (Opcional) Cria link simbólico para usar globalmente
sudo ln -s $(pwd)/main.py /usr/local/bin/cleaning

Configuração Inicial do Storage

# O sistema cria a estrutura automaticamente na primeira execução
# Por padrão usa /mnt/storage, mas pode ser configurado

# Teste a inicialização
python3 main.py --storage-info

🎯 Como Usar

Modo Limpeza Tradicional

1️⃣ Preview (Modo Seguro)

Mostra o que seria removido sem remover nada:

python3 main.py

2️⃣ Preview Detalhado

Mostra todos os arquivos (não só os 10 primeiros):

python3 main.py --details

3️⃣ Modo Interativo ⭐

Escolhe item por item o que limpar:

python3 main.py --interactive

Você verá algo assim:

🎯 MODO INTERATIVO - Escolha o que deseja limpar:
============================================================

📦 Node modules? 15 encontrados (2.3 GB)
   Limpar? (s/n): s

🗂️  Arquivos Temporários: 234 arquivos (45.2 MB)
   Limpar? (s/n): s

💾 Caches: 8 diretórios (567.8 MB)
   Limpar? (s/n): n

...

4️⃣ Execução Automática

Remove tudo de uma vez (cuidado! ⚠️):

python3 main.py --run

5️⃣ Limpeza de Node Modules Apenas

python3 main.py --only-nodes --run

6️⃣ Limpeza Python-Only ⭐ NOVO

Remove apenas cache Python (seguro para projetos ativos):

# Preview
python3 main.py --python-only

# Executar limpeza
python3 main.py --python-only --run

# Modo interativo focado em Python
python3 main.py --python-only --interactive

Remove:

__pycache__/ (bytecode compilado)
.pytest_cache/ (cache do pytest)
.mypy_cache/ (cache do mypy)
.ruff_cache/ (cache do Ruff linter)
.tox/ (ambientes de teste)
htmlcov/ (relatórios de cobertura)
*.pyc, *.pyo, *.pyd (arquivos compilados)

7️⃣ Limpeza Completa (inclui logs do sistema)

python3 main.py --run --full

Nota: Diretórios protegidos (.config, .var, .vscode, etc.) nunca são limpos, mesmo em modo --full.

Modo Arquivamento Inteligente

📊 Arquivamento Interativo

python3 main.py --move --interactive

Você escolhe quais categorias escanear:

📋 Escolha quais categorias escanear:
   [1] Relatórios (mantém últimos 15 dias)
   [2] Backups (mantém 2 mais recentes)
   [3] Ambos
   [0] Cancelar

📋 Política Específica

# Move apenas relatórios antigos
python3 main.py --move --policy reports

# Move apenas backups antigos
python3 main.py --move --policy backups

🔄 Modo Sinérgico (Aplica Todas as Políticas)

python3 main.py --move --synergic

Lixão Compactado

🗑️ Enviar para o Lixão

# Sintaxe básica
python3 main.py --trash /caminho/do/diretorio --tag NOME-DA-TAG

# Exemplos
python3 main.py --trash ~/old-project --tag OLD-PROJECTS
python3 main.py --trash ~/logs/antigos --tag OLD-LOGS

Tags disponíveis:

OLD-REPORTS
OLD-BACKUPS
ARCHIVED
NODE-MODULES
MOVED
LOGS
TEMP
CUSTOM

📋 Listar Conteúdo do Lixão

python3 main.py --list-trash

Saída:

🗑️  LIXÃO (12 arquivos compactados)
============================================================
 1. [OLD-REPORTS]_reports_20241103.tar.gz
    📅 2024-11-03 14:30 | 📊 145 itens | 💾 23.4 MB | 🗜️  87.3%
 2. [NODE-MODULES]_old-project_20241102.tar.gz
    📅 2024-11-02 10:15 | 📊 3421 itens | 💾 89.2 MB | 🗜️  94.1%
...

🔍 Buscar no Lixão

python3 main.py --search-trash "report_20241020"

Sistema de Restauração

📦 Listar Archives Disponíveis

python3 main.py --list-archives

🔄 Restaurar Archive Completo

python3 main.py --restore moving-20241103-143022

📄 Restaurar Arquivo Específico do Archive

python3 main.py --restore moving-20241103-143022 --item report.html

🗑️ Restaurar do Lixão

# Restaura tudo
python3 main.py --restore-trash "[OLD-REPORTS]_file.tar.gz"

# Restaura item específico
python3 main.py --restore-trash "[OLD-REPORTS]_file.tar.gz" --item report.html

🔍 Buscar nos Archives

python3 main.py --search "relatorio" --in-archives

🎯 Especificar Destino de Restauração

python3 main.py --restore moving-20241103 --to /home/user/restored/

⚙️ Estrutura do Storage

📊 Visualizar Informações do Storage

python3 main.py --storage-info

Mostra:

💾 Espaço usado/disponível
📦 Total de archives
🗑️ Total no lixão
📈 Estatísticas de uso
⚙️ Configurações ativas

🔧 Políticas de Retenção

As políticas estão definidas no código (modules/storage_manager.py):

self.default_policies = {
    "reports": {
        "keep_days": 15,
        "description": "Relatórios - mantém últimos 15 dias no sistema principal"
    },
    "backups": {
        "keep_count": 2,
        "description": "Backups - mantém apenas os 2 mais recentes de cada categoria"
    },
    "logs": {
        "keep_days": 7,
        "description": "Logs do sistema - mantém últimos 7 dias"
    },
    "node_modules": {
        "keep_days": 30,
        "description": "Node modules - move projetos inativos há mais de 30 dias"
    },
    "caches": {
        "action": "delete",
        "description": "Caches - deleta sempre (não arquiva)"
    }
}

🎨 Exemplos de Uso

🔥 Workflow Completo Semanal

# 1. Preview do que será limpo
python3 main.py --details

# 2. Limpa interativamente (você escolhe)
python3 main.py --interactive

# 3. Arquiva relatórios e backups antigos
python3 main.py --move --synergic

# 4. Verifica o storage
python3 main.py --storage-info

🚀 Limpeza de Emergência (Disco Cheio!)

# Remove node_modules imediatamente
python3 main.py --run --only-nodes

# Depois faz limpeza completa
python3 main.py --run --full

🗂️ Organização de Projeto Antigo

# Move projeto velho pro lixão
python3 main.py --trash ~/Projetos/projeto-antigo --tag OLD-PROJECTS

# Se precisar depois, restaura
python3 main.py --list-trash
python3 main.py --restore-trash "[OLD-PROJECTS]_projeto-antigo_20241103.tar.gz"

🔍 Procurar Aquele Arquivo que Você Arquivou

# Busca nos archives
python3 main.py --search "relatorio_importante" --in-archives

# Restaura quando encontrar
python3 main.py --restore archive-20241020 --item relatorio_importante.html

🔧 Configuração

Mudar Caminho do Storage

Edite storage_manager.py:

def __init__(self, storage_path: str = "/seu/caminho/personalizado"):
    self.storage_path = Path(storage_path)
    # ...

Ajustar Políticas de Retenção

Edite modules/storage_manager.py:

# Exemplo: Manter relatórios por 30 dias em vez de 15
self.default_policies = {
    "reports": {
        "keep_days": 30,  # ← Mudou aqui
        "description": "Relatórios - mantém últimos 30 dias no sistema principal"
    },
    # ... resto das políticas
}

Nível de Compressão

Para ajustar o nível de compressão (0-9), edite trash_manager.py:

# Na função _compress_path()
tar.add(path, arcname=path.name, compresslevel=9)  # ← Padrão: 9 (máxima)

Trade-off:

9 = Máxima compressão, mais lento
6 = Balanceado
1 = Rápido, menos compressão

🤝 Contribuindo

Contribuições são super bem-vindas! 🎉

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/MinhaFeature)
Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
Push para a branch (git push origin feature/MinhaFeature)
Abra um Pull Request

💡 Ideias para Contribuir

🔌 Adicionar mais políticas de retenção
📊 Dashboard web para visualizar estatísticas
🔔 Sistema de notificações quando disco está cheio
🗜️ Suporte para outros formatos de compressão (zstd, xz)
🐳 Dockerfile para rodar em container
📱 Integração com Telegram/Discord para alertas

📜 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

Feito com ☕ e 💻 por desenvolvedores cansados de disco cheio

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
modules		modules
utils		utils
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
main.py		main.py

License

montezuma-p/linux-storage-manager

Folders and files

Latest commit

History

Repository files navigation