portctl 0.5.4

portctl is a fast, cross-platform CLI to inspect ports, understand processes, and recover broken dev environments - built for real-world development workflows.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

# Contributing to portctl

Thanks for your interest in contributing to portctl! This guide will help you get started.

## Getting Started

```bash
git clone https://github.com/abhishekayu/portctl.git
cd portctl
cargo build
cargo test
```

Requires Rust 1.75+ (stable).

## Development

```bash
# Run in debug mode
cargo run -- scan
cargo run -- fix 3000

# Run tests
cargo test

# Run clippy
cargo clippy -- -D warnings

# Build release binary
cargo build --release
```

## Project Structure

```
src/
  models/       Data types (PortInfo, ProcessInfo, DevService)
  platform/     OS-specific adapters (macOS, Linux, Windows)
  scanner/      Port scanning with batch process resolution
  classifier/   Service identification (13+ categories)
  engine/       Fix engine with safety checks and strategies
  project/      Project type detection from filesystem
  docker/       Docker container awareness
  grouping/     Port role classification
  doctor/       Auto-diagnosis of dev environment issues
  history/      Persistent action history
  plugin/       Extensible service detector system
  cli/          Commands, output formatting, interactive TUI
```

## How to Contribute

### Report Bugs

Open a [GitHub Issue](https://github.com/abhishekayu/portctl/issues) with:

- Your OS and version
- portctl version (`portctl --version`)
- Steps to reproduce
- Expected vs actual behavior

### Suggest Features

Open an issue describing the use case and proposed solution.

### Submit Code

1. Fork the repo and create a branch from `main`
2. Make your changes
3. Add tests if applicable
4. Run `cargo test` and `cargo clippy`
5. Open a pull request

### Good First Contributions

- Add a new service classifier (e.g., Bun, Deno, Elixir)
- Improve an existing doctor diagnostic
- Add tests for edge cases
- Fix typos or improve documentation

## Code Style

- Follow standard Rust conventions (`cargo fmt`)
- Use `anyhow` for error handling in CLI code
- Use `thiserror` for library error types
- Keep functions focused and small
- Prefer returning `Result` over panicking

## License

By contributing, you agree that your contributions will be licensed under the MIT License.