# 🚀 PortMan TUI

[![CI](https://github.com/sidgaikwad/portman/actions/workflows/ci.yml/badge.svg)](https://github.com/sidgaikwad/portman/actions/workflows/ci.yml)
[![npm version](https://badge.fury.io/js/portman.svg)](https://badge.fury.io/js/portman)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A beautiful, modern Terminal User Interface (TUI) for managing ports on your system. Kill processes, find free ports, and monitor active connections - all with a stunning interface.

![PortMan TUI Demo](https://via.placeholder.com/800x400?text=PortMan+TUI+Demo)

## ✨ Features

- 🎨 **Beautiful TUI** - Modern interface with gradients, animations, and smooth interactions
- 🔍 **Real-time Search** - Filter ports by number, process name, or PID
- ⚡ **Kill Processes** - Interactive process termination with confirmation
- 🔎 **Find Free Ports** - Quickly locate available ports in a range
- 🔄 **Auto-refresh** - Live monitoring of active ports
- 🌍 **Cross-platform** - Works on macOS, Linux (Ubuntu, Debian, Fedora, Arch), and Windows
- ⌨️ **Keyboard Navigation** - Full keyboard control for power users

## 📦 Installation

### Global Installation (Recommended)

```bash
npm install -g portman-tui
```

### Run without Installing

```bash
npx portman-tui
```

### Local Installation

```bash
npm install portman-tui
```

## 🚀 Usage

### Launch TUI

```bash
portman
```

### Quick Commands

```bash
# List all active ports
portman list

# Kill process on specific port
portman kill 3000

# Find available port
portman find

# Find port in specific range
portman find --range 3000-4000
```

## ⌨️ Keyboard Shortcuts

| Key     | Action                   |
| ------- | ------------------------ |
| `/`     | Enter search mode        |
| `↑` `↓` | Navigate port list       |
| `←` `→` | Toggle kill confirmation |
| `Enter` | Select/Confirm           |
| `ESC`   | Go back/Cancel           |
| `Q`     | Quit application         |

## 🎯 Use Cases

### Development

- Quickly find which process is using port 3000
- Free up ports when switching between projects
- Monitor multiple services running simultaneously

### DevOps

- Check port conflicts on servers
- Identify rogue processes
- Quick port management in CI/CD pipelines

### System Administration

- Monitor network services
- Troubleshoot port binding issues
- Clean up orphaned processes

## 🛠️ Requirements

- **Node.js** >= 18.0.0
- **Operating System**: macOS, Linux, or Windows
- **Permissions**: May require sudo/admin rights to kill certain processes

## 📋 Platform-Specific Notes

### macOS

Uses `lsof` command (pre-installed). No additional setup required.

### Linux (Ubuntu/Debian/Fedora/Arch)

Uses `lsof`, `ss`, or `netstat` (usually pre-installed). If not available:

```bash
# Ubuntu/Debian
sudo apt-get install lsof net-tools

# Fedora/RHEL
sudo dnf install lsof net-tools

# Arch
sudo pacman -S lsof net-tools
```

### Windows

Uses built-in `netstat` and `tasklist` commands. No additional setup required.

## 🏗️ Development

### Setup

```bash
# Clone repository
git clone https://github.com/sidgaikwad/portman.git
cd portman

# Install dependencies
npm install

# Run in development mode
npm run dev
```

### Scripts

```bash
npm run build        # Build TypeScript
npm run dev          # Run with tsx
npm run lint         # Run ESLint
npm run lint:fix     # Fix linting issues
npm run format       # Format code with Prettier
npm run format:check # Check formatting
npm run type-check   # TypeScript type checking
npm run clean        # Clean build directory
```

### Project Structure

```
portman/
├── src/
│   ├── cli.tsx              # CLI entry point
│   ├── components/
│   │   ├── App.tsx          # Main application component
│   │   ├── Header.tsx       # Header with branding
│   │   ├── PortList.tsx     # Port listing component
│   │   ├── SearchBar.tsx    # Search interface
│   │   ├── KillConfirmation.tsx  # Kill dialog
│   │   └── Footer.tsx       # Keyboard shortcuts footer
│   └── utils/
│       └── portUtils.ts     # Port management logic
├── .github/
│   └── workflows/
│       ├── ci.yml           # CI pipeline
│       └── release.yml      # Release automation
├── package.json
├── tsconfig.json
└── README.md
```

Contributions are welcome! Please follow these steps:

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

Please make sure to:

- Follow the existing code style
- Run `npm run lint` and `npm run format` before committing
- Add tests for new features
- Update documentation as needed

## 📝 License

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

## 🙏 Acknowledgments

- Built with [Ink](https://github.com/vadimdemedes/ink) - React for CLIs
- Inspired by modern TUI design principles
- Thanks to all contributors!

## 🐛 Issues

Found a bug? Have a feature request? Please [open an issue](https://github.com/sidgaikwad/portman/issues).

## 📧 Contact

Your Name - [@yourtwitter](https://twitter.com/yourtwitter) - your.email@example.com

Project Link: [https://github.com/sidgaikwad/portman](https://github.com/sidgaikwad/portman)

---

Made with ❤️ by [Your Name](https://github.com/yourusername)