Metadata-Version: 2.4
Name: junk-remover-cli
Version: 0.1.3
Summary: Universal cleanup executor - Automated deletion of unwanted files and directories
Project-URL: Homepage, https://github.com/AuraCulture/Junk
Project-URL: Bug Reports, https://github.com/AuraCulture/Junk/issues
Project-URL: Source, https://github.com/AuraCulture/Junk
Project-URL: Documentation, https://github.com/AuraCulture/Junk#readme
Author-email: Junk CLI <maintainer@junk-cli.dev>
License: MIT License
        
        Copyright (c) 2025 Junk CLI
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: automation,cleanup,cli,delete,devtools,files,junk,universal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown


# Junk - Universal Cleanup Executor

A zero-friction Python CLI tool for automated cleanup of unwanted files and directories.

## Problem Statement

Development repositories often accumulate unwanted files and directories:
- `/target/` build directories
- `*.log` files
- `__pycache__/` Python cache directories  
- `/temp/` temporary directories
- Build artifacts and cache files

Manual deletion of these files is time-consuming and error-prone. Organizations need an automated solution that works universally across different project types and environments.

## Solution Overview

**Junk** is a PyPI-distributed command-line tool that provides automated cleanup with zero user intervention required.

Execute with a single command:
```bash
junk
```

The tool operates by:
1. Locating a `junk.fat` configuration file in the current directory
2. Reading the specified list of files and directories for removal
3. Executing deletions as specified
4. Self-removing the configuration file upon successful completion

## Installation

Install from the Python Package Index:
```bash
pip install junk-remover-cli
```

The tool is immediately available system-wide:
```bash
junk
```

## Usage Instructions

### Step 1: Create Configuration File

Create a `junk.fat` file in your project root directory. List files and directories to be removed, one per line:

```
/target/
/Server/plotter/output/main.png
/Server/temp/arch.json
__pycache__/
*.log
node_modules/
.DS_Store
```

### Step 2: Execute Cleanup

Run the cleanup command:
```bash
junk
```

### Step 3: Verification

All specified items are removed, and the `junk.fat` configuration file is automatically deleted upon successful completion.

## Key Features

- **Zero User Interaction**: No confirmation prompts or manual intervention required
- **Universal Compatibility**: Functions in any directory containing a `junk.fat` configuration file
- **Self-Managing**: Automatically removes configuration file after successful execution
- **Error Handling**: Preserves configuration file when deletions fail for retry capability
- **Cross-Platform**: Compatible with Windows, macOS, and Linux environments
- **Encoding Support**: Handles multiple file encodings automatically

## Operational Behavior

### Success Case
When all specified items are successfully deleted, the `junk.fat` configuration file is automatically removed.

### Partial Failure Case  
When some items cannot be deleted, the `junk.fat` configuration file is preserved to allow for retry operations.

### Missing Configuration Case
When no `junk.fat` file is present, the tool exits gracefully with an informative status message.

## Integration with Development Workflows

This tool is designed for integration with automated development workflows:
- **Configuration Generation**: AI code assistants or scripts generate project-specific `junk.fat` files
- **Execution**: The junk tool executes cleanup operations without human intervention
- **Universal Application**: Consistent workflow across different programming languages and project types

## Configuration Examples

### Web Development Projects
```
node_modules/
dist/
.cache/
*.log
.DS_Store
```

### Python Projects
```
__pycache__/
*.pyc
.pytest_cache/
build/
*.egg-info/
```

### Java Projects
```
target/
*.class
*.jar
*.war
```

## Safety and Security

- Operations are limited to explicitly listed items in the configuration file
- No wildcard expansion or pattern matching beyond exact path specification
- Non-existent files and directories are gracefully ignored
- Comprehensive logging provides clear feedback on all operations performed

## License

This project is distributed under the MIT License. See the LICENSE file for complete terms and conditions.

## Contributing

Contributions are welcome through standard open-source channels. This tool maintains a focused scope centered on the core principle of zero-friction cleanup execution. Please ensure any proposed changes align with this fundamental design philosophy.

## Support

For issues, feature requests, or technical support, please utilize the project's issue tracking system on the source code repository.

---

**Junk CLI**: Making cleanup operations universal, automated, and reliable.