# DevPort CLI

A command-line tool for managing development server ports across multiple projects.

## Overview

When working on multiple development projects, port conflicts are a common issue. DevPort CLI helps you track and manage which ports are being used by which projects, making it easy to avoid conflicts and organize your development environment.

## Features

- 🚀 **Simple port registration**: Register ports with project names and descriptions
- 📋 **List all registered ports**: View all ports in use across your projects
- 🔍 **Find port information**: Quickly check what's using a specific port
- 💡 **Smart port suggestions**: Get suggestions for available ports
- 🗑️ **Easy removal**: Remove port registrations when projects are no longer active
- 🏠 **Local storage**: All data stored locally in your home directory

## Installation

### Global installation via npm

```bash
npm install -g devport-cli
```

### Local development

```bash
git clone https://github.com/uehara/devport-cli.git
cd devport-cli
npm install
npm link
```

## Usage

### Add a port registration

```bash
devport add 3000 my-react-app
devport add 3001 my-api-server --description "Express.js API server"
```

### List all registered ports

```bash
devport list
# or
devport ls
```

### Find information about a specific port

```bash
devport find 3000
```

### Get a suggestion for an available port

```bash
devport suggest
devport suggest --start 4000
```

### Scan directory and auto-register ports

```bash
# Scan current directory
devport scan

# Scan specific directory
devport scan ~/projects

# Scan with custom depth (default: 3)
devport scan ~/projects --depth 5

# Preview what would be registered (dry run)
devport scan ~/projects --dry-run

# Include low-confidence matches
devport scan ~/projects --all
```

This command automatically scans your project directories and detects ports from:
- package.json scripts (Next.js, Vite, React, etc.)
- .env files
- Configuration files (vite.config.js, next.config.js, etc.)
- Docker compose files
- Server files (server.js, app.js, etc.)

### Remove a port registration

```bash
devport remove 3000
# or
devport rm 3000
```

### Kill a process using a specific port

```bash
devport kill 3000
```

This command will find and terminate the process that is currently using the specified port. This is useful when you have a stuck development server or process that didn't shut down properly.

### Kill all processes for a specific project

```bash
devport kill-project my-react-app
```

This command will find and terminate all processes using ports registered to the specified project name.

### Kill all processes for all registered ports

```bash
devport kill-all
```

This command will find and terminate all processes using any of your registered ports. Useful for cleaning up all development servers at once.

### Clear all registrations

```bash
devport clear
```

### View help

```bash
devport --help
devport <command> --help
```

## Commands

| Command                 | Alias | Description                                         |
| ----------------------- | ----- | --------------------------------------------------- |
| `add <port> <project>`  | -     | Register a port for a project                       |
| `remove <port>`         | `rm`  | Remove a port registration                          |
| `list`                  | `ls`  | List all registered ports                           |
| `find <port>`           | -     | Find information about a specific port              |
| `suggest`               | -     | Suggest an available port                           |
| `scan [directory]`      | -     | Scan directory and auto-detect/register ports       |
| `kill <port>`           | -     | Kill the process using the specified port           |
| `kill-project <name>`   | -     | Kill all processes for the specified project        |
| `kill-all`              | -     | Kill all processes for all registered ports         |
| `clear`                 | -     | Clear all port registrations                        |

## Options

### add command

- `-d, --description <desc>`: Add a description for the project

### suggest command

- `-s, --start <port>`: Starting port number for suggestions (default: 3000)

### scan command

- `-d, --depth <levels>`: Maximum directory depth to scan (default: 3)
- `--all`: Include low-confidence port matches
- `--dry-run`: Preview what would be registered without actually registering

## Data Storage

DevPort CLI stores all port registrations locally in:

- **macOS/Linux**: `~/.devport/ports.json`
- **Windows**: `%USERPROFILE%\.devport\ports.json`

## Use Cases

### Daily Development

```bash
# Auto-detect ports in your projects directory
devport scan ~/projects

# Starting a new React project
devport add 3000 my-new-app --description "React development server"

# Need a port for API server
devport suggest --start 3001
# Returns: Suggested available port: 3001
devport add 3001 my-api

# Check what's using port 3000
devport find 3000

# View all active projects
devport list
```

### AI Integration

```bash
# Get an available port for AI to use
AVAILABLE_PORT=$(devport suggest)
devport add $AVAILABLE_PORT "ai-generated-project" --description "Auto-generated by AI"
```

### Project Cleanup

```bash
# Kill stuck React development server on specific port
devport kill 3000

# Kill all processes for a specific project
devport kill-project my-react-app

# Kill all registered development servers at once
devport kill-all

# Remove port when project is done
devport remove 3000

# Clean slate
devport clear
```

## Requirements

- Node.js 14.0.0 or higher
- npm or yarn

## Contributing

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.

## AI Assistant Instructions

**For AI Assistants (Claude, ChatGPT, etc.):**

When users are developing projects and need port management, use the `devport` CLI tool:

### Essential Commands:

- `devport scan <directory>` - Auto-detect and register ports from project files
- `devport suggest` - Get available port suggestion before starting new projects
- `devport add <port> <project-name> --description "<desc>"` - Register port usage
- `devport list` - Show all registered ports to avoid conflicts
- `devport find <port>` - Check what's using a specific port
- `devport kill <port>` - Kill process using the specified port (useful for stuck servers)
- `devport kill-project <name>` - Kill all processes for a specific project
- `devport kill-all` - Kill all processes for all registered ports
- `devport remove <port>` - Clean up when project ends

### AI Workflow Integration:

1. **When working with existing projects**: Run `devport scan <directory>` to auto-detect all ports
2. **Before starting any development server**: Run `devport suggest` to get available port
3. **When creating projects**: Always register the port with `devport add`
4. **When port conflicts occur**: Use `devport list` and `devport find` to troubleshoot, or `devport kill` to terminate stuck processes
5. **In automation scripts**: Use `AVAILABLE_PORT=$(devport suggest)` for dynamic port allocation

### Best Practices for AI:

- Always check port availability before suggesting specific ports to users
- Register ports immediately when setting up development environments
- Include port cleanup in project completion instructions
- Use descriptive project names and descriptions for better port management

## Support

If you encounter any problems or have suggestions, please [open an issue](https://github.com/uehara/devport-cli/issues) on GitHub.
