modscan/README.md

A CLI tool to scan and manage node_modules directories

# ModScan

<div align="center">

[![npm version](https://img.shields.io/npm/v/modscan.svg)](https://www.npmjs.com/package/modscan)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/KaizoKonpaku/modscan/blob/main/LICENSE)
[![X](https://img.shields.io/badge/X-@KaizoKonpakuu-black)](https://x.com/KaizoKonpakuu)

A powerful CLI tool to scan, analyze, and manage `node_modules` directories with an interactive terminal UI.

![ModScan Demo](preview/preview.gif)

</div>

## ✨ Features

- 🔍 **Smart Scanning**: Scan local or global directories for `node_modules` folders
- 📊 **Interactive UI**: Beautiful terminal interface with detailed statistics
- 📈 **Flexible Sorting**: Sort modules by size, date, name, or path
- 🗑️ **Easy Cleanup**: Delete unnecessary `node_modules` directories
- 🎯 **Smart Filtering**: Filter modules by status, size, or age
- 💾 **Space Tracking**: Monitor space freed after deletion
- 🚀 **Performance**: Fast and efficient scanning
- ⌨️ **Keyboard First**: Intuitive keyboard navigation

## 🚀 Quick Start

```bash
# Install globally
npm install -g modscan

# Or use npx
npx modscan
```

## 📖 Usage

```bash
# Scan current directory
modscan

# Scan entire system
modscan -g

# Show help
modscan --help
```

## ⌨️ Keyboard Controls

| Key | Action |
|-----|--------|
| `↑/↓` | Navigate entries |
| `ENTER` or `R` | Start/restart scan |
| `D` or `dd` | Delete selected directory |
| `S` | Sort modules |
| `F` | Filter modules |
| `Q` or `q` | Quit application |

## 🛠️ Development

```bash
# Clone the repository
git clone https://github.com/KaizoKonpaku/modscan.git
cd modscan

# Install dependencies
npm install

# Start development
npm start

# Run linting
npm run lint

# Format code
npm run format
```

## 📋 Requirements

- Node.js >= 10.0.0
- Terminal with Unicode support

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [blessed](https://github.com/chjj/blessed) - Terminal UI library