empty-folder-manager/webui/README.md

Interactive CLI tool for analyzing and removing empty folders from filesystem with .gitignore support and custom glob patterns

# 🗂️ Empty Folder Manager - Web UI

A beautiful, modern web interface for the Empty Folder Manager CLI tool. Clean up your filesystem with an intuitive graphical interface!

## Features

- 🎨 **Beautiful Interface**: Modern, responsive design with smooth animations
- 📊 **Real-time Progress**: Live updates during analysis with progress bars
- 🔧 **Easy Configuration**: Simple forms for path, speed, and filtering options
- 🎯 **Advanced Filtering**: Support for .gitignore files and custom glob patterns
- 🔍 **Dry Run Mode**: Preview what would be removed before making changes
- 📈 **Detailed Statistics**: Comprehensive analysis results with folder counts
- 💾 **Persistent Settings**: Your configuration is saved between sessions
- 📱 **Mobile Friendly**: Responsive design works on all devices

## Quick Start

1. **Install dependencies:**
   ```bash
   cd webui
   npm install
   ```

2. **Start the web server:**
   ```bash
   npm start
   ```

3. **Open your browser:**
   Navigate to `http://localhost:3000`

4. **Configure and analyze:**
   - Enter the directory path you want to analyze
   - Choose your preferred processing speed
   - Set up filtering options (optional)
   - Click "Run Analysis" to find empty folders
   - Review results and remove folders as needed

## Configuration Options

### 📁 Directory Path
Enter the full path to the directory you want to analyze:
- **Linux/Mac**: `/home/user/Documents` or `/Users/user/Documents`
- **Windows**: `C:\Users\User\Documents`

### ⚡ Processing Speed
Choose from 5 speed presets:
- **🚀 Turbo**: Fastest processing, no delays
- **⚡ Fast**: Quick processing with minimal delays
- **🐢 Normal**: Balanced speed and system friendliness (default)
- **🌱 Gentle**: Slower processing, easier on your disk
- **🐌 Ultra Gentle**: Very slow, maximum safety for old systems

### 🎯 Filtering Options
- **GitIgnore Support**: Automatically respect .gitignore files
- **Custom Patterns**: Add your own ignore patterns using glob syntax

#### Example Custom Patterns:
```
node_modules/
*.log
.git/
build/
dist/
temp*
!important.log
```

## API Endpoints

The web UI communicates with a REST API:

### `POST /api/analyze`
Analyze a directory for empty folders.

**Request Body:**
```json
{
  "path": "/path/to/analyze",
  "speed": "normal",
  "gitignoreEnabled": true,
  "customPatterns": ["node_modules/", "*.log"]
}
```

**Response:** Streaming JSON with progress updates and final results.

### `POST /api/remove`
Remove empty folders (with dry-run option).

**Request Body:**
```json
{
  "folders": ["/path/to/empty/folder1", "/path/to/empty/folder2"],
  "dryRun": false,
  "speed": "normal"
}
```

**Response:**
```json
{
  "removedCount": 5,
  "errorCount": 0
}
```

### `GET /api/health`
Health check endpoint.

**Response:**
```json
{
  "status": "ok",
  "timestamp": "2024-01-01T12:00:00.000Z"
}
```

## Safety Features

- ✅ **Dry Run Mode**: Preview changes before making them
- ✅ **Confirmation Dialogs**: Multiple confirmations for destructive actions
- ✅ **Real-time Validation**: Path validation before analysis
- ✅ **Error Handling**: Graceful handling of permission errors
- ✅ **Progress Tracking**: Monitor analysis progress in real-time
- ✅ **Persistent Logs**: Activity log shows all operations

## Browser Compatibility

- ✅ Chrome 80+
- ✅ Firefox 75+
- ✅ Safari 13+
- ✅ Edge 80+

## Development

### Project Structure
```
webui/
├── public/           # Frontend files
│   ├── index.html   # Main HTML page
│   ├── styles.css   # CSS styling
│   └── app.js       # Frontend JavaScript
├── src/             # Backend files
│   └── server.js    # Express server
├── package.json     # Dependencies
└── README.md        # This file
```

### Running in Development Mode
```bash
cd webui
npm install
npm run dev
```

The server will start on `http://localhost:3000` with automatic restart on file changes.

## Customization

### Styling
Edit `public/styles.css` to customize the appearance. The design uses:
- CSS Grid and Flexbox for layout
- CSS custom properties for theming
- Smooth transitions and animations
- Responsive design principles

### Functionality
Edit `public/app.js` to modify frontend behavior or `src/server.js` for backend changes.

## Troubleshooting

### Common Issues

**"Path does not exist" error:**
- Ensure the path is correct and accessible
- Check file permissions
- Use forward slashes (/) even on Windows

**Analysis takes too long:**
- Try a faster speed preset
- Add more ignore patterns to skip unnecessary directories
- Ensure the path isn't too large (like entire system drives)

**Server won't start:**
- Check if port 3000 is already in use
- Ensure Node.js 14+ is installed
- Run `npm install` to install dependencies

### Performance Tips

- **Large directories**: Start with "Gentle" speed and increase if needed
- **Network drives**: Use "Ultra Gentle" for best reliability
- **SSD users**: "Turbo" or "Fast" speeds work well
- **HDD users**: Stick with "Normal" or "Gentle" speeds

## Contributing

Contributions are welcome! The web UI is built with:
- **Frontend**: Vanilla JavaScript, CSS3, HTML5
- **Backend**: Node.js, Express.js
- **No build process**: Simple, dependency-light architecture

## License

MIT License - same as the main Empty Folder Manager project.

---

**Enjoy cleaning up your filesystem with style! 🚀**