empty-folder-manager/knowledge.md

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

# Empty Folder Manager Project

## Overview
This project provides both a CLI tool and web UI for analyzing and removing empty folders from filesystems. It includes advanced filtering with .gitignore support and custom glob patterns.

## Project Structure
- `remove-empty-folders.js` - Main CLI application with interactive menu and UI launch capability
- `webui/` - Web interface built with Express.js and vanilla JavaScript
  - `public/` - Frontend files (HTML, CSS, JS)
  - `src/server.js` - Express backend API
- `desktop/` - Tauri-based desktop application
- `kill-webui.js` - Utility script to kill orphaned web UI processes
- `package.json` - CLI tool dependencies and metadata

## Key Features
- **Speed Control**: 5 presets from Turbo to Ultra Gentle for different system capabilities
- **Advanced Filtering**: .gitignore file support + custom glob patterns
- **Safety Features**: Dry-run mode, confirmation prompts, error handling
- **Progress Tracking**: Real-time updates during analysis
- **Persistent Configuration**: Settings saved between sessions
- **Multiple Interfaces**: CLI, Web UI, and Desktop app

## UI Launch Options
The CLI tool now supports launching the web UI in multiple ways:

### Command Line Arguments
- `empty-folder-manager --ui` or `empty-folder-manager -u` - Launch web UI directly
- `npm run ui` or `npm run web` - Launch web UI via npm scripts

### CLI Menu Option
- Option 7 in the interactive CLI menu launches the web UI
- Automatically installs web UI dependencies if needed
- Gracefully transitions from CLI to web interface

### Process Management
- Proper cleanup of readline interface when launching from CLI menu
- Graceful shutdown handling for web server
- Port conflict detection and helpful error messages
- Utility script (`npm run kill-webui`) to clean up orphaned processes

## Development Notes
- The web UI extends the CLI tool's EmptyFolderCLI class for consistency
- Uses streaming responses for real-time progress updates
- All file operations use Node.js fs.promises for async handling
- Browser localStorage used for configuration persistence
- CLI automatically handles web UI dependency installation
- Process groups used to prevent orphaned processes

## Running the Project
- CLI: `node remove-empty-folders.js` or `npm start`
- Web UI: `node remove-empty-folders.js --ui` or `npm run ui`
- Web UI (manual): `cd webui && npm start` (runs on http://localhost:3000)
- Desktop: `cd desktop && npm run tauri dev`
- Cleanup: `npm run kill-webui` (kills orphaned web UI processes)

## Troubleshooting
- **Port conflicts**: Use `npm run kill-webui` to clean up orphaned processes
- **Readline errors**: Fixed by proper interface cleanup in CLI menu launch
- **Orphaned processes**: Prevented by using process groups and proper signal handling

## Safety Considerations
- Always validate paths before analysis
- Use dry-run mode for testing
- Respect .gitignore files to avoid removing important directories
- Implement proper error handling for permission issues