Metadata-Version: 2.4
Name: clutterctrl
Version: 1.0.1
Summary: A lightweight terminal file organizer with dry-run previews, per-run audit logs, and 1-click rollback.
Author: az1213-dev
License-Expression: MIT
Project-URL: Homepage, https://github.com/az1213-dev/clutter-ctrl
Project-URL: Documentation, https://github.com/az1213-dev/clutter-ctrl#readme
Project-URL: Repository, https://github.com/az1213-dev/clutter-ctrl.git
Project-URL: Issues, https://github.com/az1213-dev/clutter-ctrl/issues
Keywords: clutterctrl,file-organizer,filesystem,cli,terminal,automation,cleaner,rollback,productivity
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: watcher
Requires-Dist: watchdog>=4.0.0; extra == "watcher"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# ClutterCtrl

<p align="left">
  <a href="https://www.python.org"><img src="https://img.shields.io/badge/Python-3.9+-3776AB.svg?style=flat-square&logo=python&logoColor=white" alt="Python 3.9+" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" alt="License: MIT" /></a>
  <a href="https://github.com/az1213-dev/clutter-ctrl/actions"><img src="https://img.shields.io/github/actions/workflow/status/az1213-dev/clutter-ctrl/ci.yml?style=flat-square&label=CI" alt="CI Status" /></a>
  <a href="pyproject.toml"><img src="https://img.shields.io/badge/Dependencies-0%20Mandatory-brightgreen.svg?style=flat-square" alt="Zero Mandatory Dependencies" /></a>
</p>

A fast, lightweight terminal file organizer. It cleans up cluttered folders (like your Downloads or Desktop), sorts files into organized directories by type, lets you preview changes before touching anything, and keeps a dedicated log of every run so you can undo changes with a single command.

Written in pure Python with standard library modules, so you can run it immediately without installing any third-party packages.

---

## <img src="https://api.iconify.design/lucide:sparkles.svg?color=%2306b6d4" width="20" height="20" align="center" /> Features

- **Zero-Dependency CLI**: Runs directly in Windows Command Prompt, PowerShell, macOS Terminal, or Linux using standard Python.
- **Dedicated Run Logs**: Every organization run creates its own log file (`run_YYYY-MM-DD_HH-MM-SS_<id>.log`) recording the exact before and after paths for every file moved.
- **1-Click Undo**: Revert any previous run instantly via `clutterctrl undo <Run ID>` or through the interactive menu.
- **Dry Run Previews**: Check file lists, categories, destination paths, and sizes in a clean table before anything gets moved.
- **Background Folder Watcher**: Optionally watch folders like Downloads to auto-sort new files as they arrive, with built-in debounce so it never touches partial downloads.
- **Standard and Deep Scans**: Choose between organizing top-level files or scanning entire folder trees recursively while cleaning up empty folders.
- **Safe Renaming**: Never overwrites existing files. If a file with the same name exists, it automatically adds a counter (like `photo_1.png`).
- **Stats & History**: View your past runs and see a visual bar chart of how your storage is organized across categories.

### Supported Categories

**Images** · **Videos** · **Audio** · **Documents** · **Code & Web** · **Projects & Creative** · **Data & Databases** · **Archives** · **Executables** · **Fonts** · **Misc**

---

## <img src="https://api.iconify.design/lucide:terminal.svg?color=%2306b6d4" width="20" height="20" align="center" /> Quickstart

### 1. Run Directly (No Setup Needed)
You can clone the repo and run ClutterCtrl right away:

```bash
git clone https://github.com/az1213-dev/clutter-ctrl.git
cd clutter-ctrl

# Run in Windows CMD or PowerShell
python clutterctrl/main.py
```

### 2. Install as a Global Command
If you want to use the `clutterctrl` command anywhere in your terminal, install it in editable mode:

```bash
pip install -e .

# Or with pipx
pipx install .
```

Now you can run `clutterctrl` from any directory.

---

## <img src="https://api.iconify.design/lucide:command.svg?color=%2306b6d4" width="20" height="20" align="center" /> CLI Commands

You can run ClutterCtrl with subcommands or launch the interactive menu by running `clutterctrl` with no arguments:

```bash
# Open the interactive terminal menu
clutterctrl

# Preview what will be moved in Downloads without changing anything
clutterctrl scan "C:\Users\Username\Downloads"

# Preview a folder recursively (Deep Scan)
clutterctrl scan "D:\Projects" --deep

# Clean and organize Downloads right away
clutterctrl clean "C:\Users\Username\Downloads"

# Clean an entire directory tree recursively
clutterctrl clean "D:\MessyFolder" --deep

# Watch a folder in the background and sort files as they arrive
clutterctrl watch "C:\Users\Username\Downloads"

# View past organization runs
clutterctrl history

# Undo the most recent run
clutterctrl undo

# Undo a specific run by ID
clutterctrl undo run_2026-08-31_13-52-17_aad725

# View storage statistics and category distribution
clutterctrl stats

# View extension mapping rules
clutterctrl rules
```

---

## <img src="https://api.iconify.design/lucide:file-text.svg?color=%2306b6d4" width="20" height="20" align="center" /> Run Logs and Undo

ClutterCtrl creates a dedicated log file for every run inside the repository:
- **Log Path**: `clutterctrl/logs/run_*.log`

### What a Run Log Looks Like
```text
Run ID: run_2026-08-31_13-52-17_aad725
Run started: 2026-08-31T13:52:17.123456
Target: C:\Users\Username\Downloads
Deep Scan: False
Mode: clean
Status: ACTIVE

--- OPERATIONS ---
MOVED: C:\Users\Username\Downloads\photo.png -> C:\Users\Username\Downloads\Images\photo.png | Category: Images | Size: 1048576
MOVED: C:\Users\Username\Downloads\report.pdf -> C:\Users\Username\Downloads\Documents\report.pdf | Category: Documents | Size: 524288

--- SUMMARY ---
Total files moved: 2
Images: 1
Documents: 1
Total bytes: 1572864
Run completed: 2026-08-31T13:52:17.456789
Status: COMPLETED
```

When you undo a run, ClutterCtrl reads the operations in reverse, puts all files back in their original folders, and marks the log as `UNDONE`.

---

## <img src="https://api.iconify.design/lucide:flask-conical.svg?color=%2306b6d4" width="20" height="20" align="center" /> Running Tests

You can run the test suite with `pytest`:

```bash
pytest -v
```

---

## <img src="https://api.iconify.design/lucide:scale.svg?color=%2306b6d4" width="20" height="20" align="center" /> License

This project is open source and available under the MIT License. See [LICENSE](LICENSE) for details.
