winclean-manager

KO | EN

gitlite — search

#javascript #python #hacktoberfest #typescript #android #machine-learning #linux #nodejs #cli #kubernetes #awesome-list #pytorch #security #open-source

winclean-manager

(★ 13)

No description available.

winclean-manager Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

"""README for WinClean Manager."""

# WinClean Manager 🧹

A safe Windows desktop application for cleaning up installed applications, packages, and leftover files.

## Features

- **Installed Apps Dashboard**: View all installed applications from winget, Windows Registry, pip, and npm
- **Safe Uninstaller**: Uninstall applications and packages with confirmation dialogs
- **Leftover Cleanup**: Scan for and quarantine leftover files from uninstalled apps
- **Quarantine System**: Safely move files to quarantine instead of permanent deletion
- **Restore Capability**: Restore files from quarantine if needed
- **Permanent Delete**: Securely delete quarantined items when ready
- **Clean Dark UI**: Modern PySide6/Qt interface

## Requirements

- Python 3.12 or later (3.14+ recommended)
- Windows 10/11
- Administrator privileges for some operations

## Installation

### 1. Clone/Download the project

```bash
cd winclean-manager
```

### 2. Create Virtual Environment

```bash
python -m venv .venv
.venv\Scripts\activate
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

### 4. Run the Application

```bash
python main.py
```

## Usage

1. **Click "Scan System"** to perform a full system scan
   - Detects installed apps from winget and Windows Registry
   - Lists Python (pip) and Node.js (npm) packages
   - Scans for leftover files from uninstalled applications

2. **Installed Apps Page**: View and uninstall applications
   - Search by app name
   - Shows version, publisher, and source
   - Click "Uninstall" to remove apps

3. **Packages Page**: Manage Python and npm packages
   - Separate tabs for pip and npm
   - Search functionality
   - Uninstall packages with confirmation

4. **Cleanup Page**: Find and quarantine leftovers
   - High confidence items auto-selected
   - Shows path, size, and reason for detection
   - Move selected items to quarantine

5. **Quarantine Page**: Manage quarantined items
   - View all quarantined files
   - Restore to original location
   - Permanently delete when ready

## Safety Features

✅ **Never auto-deletes files** - Always moves to quarantine first
✅ **Confirmation dialogs** - All destructive actions require user confirmation
✅ **Dry-run mode** - Scan results before any changes
✅ **Restore capability** - Recover files from quarantine
✅ **System protection** - Won't allow deletion of critical system paths

## Database

SQLite database stored in: `%APPDATA%\WinClean Manager\winclean.db`
- Scan history
- Installed items
- Cleanup candidates
- Quarantine items
- Action log

## Logs

Application logs stored in: `%APPDATA%\WinClean Manager\Logs\`

## Packaging (PyInstaller)

To create a standalone .exe file:

```bash
pyinstaller --noconfirm --windowed --name "WinClean Manager" main.py
```

The executable will be in: `dist/WinClean Manager/`

## Project Structure

```
winclean-manager/
├── main.py                      # Entry point
├── requirements.txt             # Dependencies
├── app/
│   ├── config.py               # Configuration & constants
│   ├── models.py               # Data models
│   ├── ui/                     # UI Components (PySide6)
│   │   ├── main_window.py      # Main window & navigation
│   │   ├── dashboard_page.py   # Dashboard summary
│   │   ├── apps_page.py        # Installed apps
│   │   ├── packages_page.py    # Pip & npm packages
│   │   ├── cleanup_page.py     # Leftover cleanup
│   │   └── quarantine_page.py  # Quarantine management
│   ├── core/                   # Business logic
│   │   ├── command_runner.py   # Execute system commands
│   │   ├── database.py         # SQLite database
│   │   ├── scanner_service.py  # System scanning
│   │   ├── cleanup_service.py  # Leftover detection
│   │   ├── quarantine_service.py # File quarantine
│   │   ├── uninstall_service.py # App uninstallation
│   │   └── safety.py           # Safety checks
│   ├── providers/              # System integrations
│   │   ├── winget_provider.py  # Windows package manager
│   │   ├── pip_provider.py     # Python packages
│   │   ├── npm_provider.py     # Node.js packages
│   │   ├── registry_provider.py # Windows Registry apps
│   │   └── startup_provider.py # Startup items
│   └── utils/                  # Utilities
│       ├── logging.py          # Logging setup
│       ├── paths.py            # Path utilities
│       ├── admin.py            # Admin operations
│       └── hashing.py          # Hash utilities
└── tests/                      # Unit tests
    └── test_basic.py
```

## Troubleshooting

### "Winget not found"
- Install [Windows Package Manager](https://github.com/microsoft/winget-cli)
- Or use via Microsoft Store

### "Npm not found"
- Install [Node.js](https://nodejs.org/) which includes npm

### Permission errors
- Some operations require administrator privileges
- Right-click application → Run as administrator
- Or rebuild with UAC elevation support

### Database locked
- Close all instances of the application
- Delete or backup `%APPDATA%\WinClean Manager\winclean.db`

## Architecture

### Scanning (Background Thread)
- `ScannerService` runs in QThread to prevent UI freeze
- Aggregates data from multiple providers
- Saves results to SQLite for history

### Safety System
- `SafetyCheck` validates paths before deletion
- `QuarantineService` moves files instead of deleting
- Timestamped backups in quarantine folder

### Database
- `Database` class provides SQLite ORM-like interface
- Indexed tables for performance
- Action logging for audit trail

## Development

### Adding New Providers
1. Create provider class in `app/providers/`
2. Inherit from base command execution pattern
3. Return standardized data models
4. Add to `ScannerService`

### Adding New UI Pages
1. Create page class in `app/ui/`
2. Inherit from `QWidget`
3. Connect to main window navigation
4. Implement `update_data()` method

### Testing
```bash
python -m pytest tests/
# or
python -m unittest tests.test_basic
```

## Configuration

Edit `app/config.py` to customize:
- Cleanup paths to scan
- UI styling and colors
- App directories and logging

## License

MIT License - See LICENSE file

## Support

- Report issues on GitHub
- Check logs in `%APPDATA%\WinClean Manager\Logs\`
- Quarantine folder: `%APPDATA%\WinClean Manager\Quarantine\`

## Changelog

### v1.0.0
- Initial release
- Winget, pip, npm, and registry scanning
- Leftover cleanup and quarantine
- Safe uninstall functionality

---

**Always keep a backup before cleaning your system!**

winclean-manager

winclean-manager Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

winclean-manager

winclean-manager Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README