Metadata-Version: 2.4
Name: portforge
Version: 0.1.0
Summary: Find and free busy development ports in seconds.
Author: Asim Awdah
License-Expression: MIT
Project-URL: Homepage, https://github.com/asimawdah/portforge
Project-URL: Repository, https://github.com/asimawdah/portforge
Project-URL: Issues, https://github.com/asimawdah/portforge/issues
Keywords: ports,developer-tools,cli,process,debugging,localhost
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PortForge

Find and free busy development ports in seconds.

PortForge helps developers quickly answer the question: **what is using port 3000?** It shows the process, PID, command, and gives you a safe command when you want to free the port.

## Install

```bash
pip install portforge
```

The installed command is:

```bash
portforge
```

## Usage

Check one port:

```bash
portforge 3000
```

Scan common development ports:

```bash
portforge scan
```

Scan custom ports:

```bash
portforge scan -p 3000,5173,8000
```

Output JSON:

```bash
portforge 3000 --json
```

Write output to a file:

```bash
portforge 3000 -o ports.json --json
```

Free a busy port after confirmation:

```bash
portforge kill 3000 --yes
```

## Safety notes

- Review the displayed process name, PID, user, and command before killing anything.
- Prefer the normal kill command first; use `--force` only when a process does not stop cleanly.
- Avoid running kill commands against system services or processes you do not recognize.
- When using `--json` or `--output`, review files before sharing them because command paths can include local usernames or project names.

## Platform support

PortForge is designed for local development workflows on Unix-like systems where process and port inspection tools are available. Windows support is planned, but it may require different process lookup behavior.

## CLI shortcuts

- `-p`, `--ports`: comma-separated ports for scan
- `-j`, `--json`: output JSON
- `-o`, `--output`: write output to file
- `-y`, `--yes`: confirm port-freeing action
- `-f`, `--force`: use a stronger termination signal

## Example

```text
$ portforge 3000
Port 3000 is busy

PID      USER         NAME             COMMAND
18422    asim         node             npm run dev

Actions:
  portforge kill 3000
```

```text
$ portforge scan
PortForge scan

PORT     STATUS   PROCESS
3000     busy     node
3001     free     -
5173     free     -
8000     busy     python
```

## Development

```bash
python3 -m unittest discover -s tests -v
```

## Roadmap

- [x] Check a single port
- [x] Scan common development ports
- [x] JSON output
- [x] Safe port freeing with explicit confirmation
- [ ] Interactive confirmation
- [ ] Project directory detection from process cwd
- [ ] Windows support improvements
- [ ] Rich colored output

## License

MIT
