infinity-portpilot 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +463 -2
- package/cli.js +15 -0
- package/dist/cli/app.js +83 -0
- package/dist/cli/commands.js +275 -0
- package/dist/cli/prompt.js +66 -0
- package/dist/discovery/index.js +99 -0
- package/dist/discovery/lsof.js +131 -0
- package/dist/discovery/platforms/linux.js +196 -0
- package/dist/discovery/platforms/macos.js +89 -0
- package/dist/discovery/platforms/windows.js +170 -0
- package/dist/discovery/types.js +2 -0
- package/dist/process/inspector.js +196 -0
- package/dist/process/terminator.js +275 -0
- package/dist/types/index.js +2 -0
- package/dist/utils/exec.js +50 -0
- package/dist/utils/formatter.js +88 -0
- package/dist/utils/platform.js +15 -0
- package/dist/utils/validator.js +51 -0
- package/package.json +66 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Infinity™
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,464 @@
|
|
|
1
|
-
#
|
|
1
|
+
# PortPilot
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<p align="center">
|
|
4
|
+
<strong>Find out what owns a port. Free it only when it is safe.</strong>
|
|
5
|
+
<br />
|
|
6
|
+
A local-first CLI for inspecting TCP listeners and terminating the right process — with identity checks, not guesswork.
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://github.com/erfmollaey/infinite-toolbox/actions/workflows/portpilot.yml"><img src="https://github.com/erfmollaey/infinite-toolbox/actions/workflows/portpilot.yml/badge.svg?branch=main" alt="PortPilot CI" /></a>
|
|
11
|
+
<img src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white" alt="Node.js 18+" />
|
|
12
|
+
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey" alt="macOS, Linux, Windows" />
|
|
13
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License" /></a>
|
|
14
|
+
<img src="https://img.shields.io/badge/version-0.1.0-blue.svg" alt="Version 0.1.0" />
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p align="center">
|
|
18
|
+
<a href="#overview">Overview</a> ·
|
|
19
|
+
<a href="#commands">Commands</a> ·
|
|
20
|
+
<a href="#safe-termination-workflow">Safety</a> ·
|
|
21
|
+
<a href="#pid-reuse-protection">PID reuse</a> ·
|
|
22
|
+
<a href="#windows-cim-timeout-behavior">Windows</a> ·
|
|
23
|
+
<a href="#development">Development</a> ·
|
|
24
|
+
<a href="#license">License</a>
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Overview
|
|
30
|
+
|
|
31
|
+
You know the error:
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
Error: listen EADDRINUSE: address already in use :::3000
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Something owns port 3000. `lsof` output is noisy, a stale PID may point at a different process, and `kill -9` is a guess with consequences.
|
|
38
|
+
|
|
39
|
+
**PortPilot** reads real operating-system listener data, shows you the owning PID and process, and — only after explicit confirmation — terminates it. Before every signal it revalidates the process identity it captured during inspection, so a recycled PID is refused instead of killed.
|
|
40
|
+
|
|
41
|
+
No mock data. No network calls. No elevated privileges.
|
|
42
|
+
|
|
43
|
+
## Features
|
|
44
|
+
|
|
45
|
+
| | Feature | What it gives you |
|
|
46
|
+
| --- | --- | --- |
|
|
47
|
+
| 🔎 | **Port inspection** | PID, process name, protocol, local address, and details when the OS exposes them |
|
|
48
|
+
| 🧭 | **Native discovery** | `lsof`, `netstat`, `/proc`, and PowerShell providers per platform |
|
|
49
|
+
| 🛑 | **Guarded termination** | Explicit confirmation, graceful signal first, separate force confirmation |
|
|
50
|
+
| 🪪 | **PID reuse protection** | Start-time identity markers revalidated before every signal |
|
|
51
|
+
| 🖥️ | **Cross-platform** | macOS, Linux, and Windows implementations |
|
|
52
|
+
| 🔐 | **No escalation** | Never invokes `sudo`, UAC, or a shell; permission errors are reported |
|
|
53
|
+
| 📦 | **Zero runtime dependencies** | Node.js built-ins only; no native modules |
|
|
54
|
+
| 🤖 | **Script-friendly reads** | Non-interactive inspection exits without prompting; meaningful exit codes |
|
|
55
|
+
|
|
56
|
+
## Supported platforms
|
|
57
|
+
|
|
58
|
+
| Platform | Primary discovery | Fallback | Process details |
|
|
59
|
+
| --- | --- | --- | --- |
|
|
60
|
+
| 🍎 macOS | `lsof -nP -iTCP -sTCP:LISTEN` | `netstat -an -p tcp` | `ps` (user, parent PID, state, start time, command line) |
|
|
61
|
+
| 🐧 Linux | `lsof -nP -iTCP -sTCP:LISTEN` | `/proc/net/tcp`, `/proc/net/tcp6`, `/proc/<pid>/fd` | `ps` |
|
|
62
|
+
| 🪟 Windows | `netstat -ano` + `tasklist` | PowerShell `Get-NetTCPConnection -State Listen` | `tasklist`, plus `Get-CimInstance Win32_Process` when PowerShell is available |
|
|
63
|
+
|
|
64
|
+
Only **TCP listeners** are discovered. UDP ports are not listed.
|
|
65
|
+
|
|
66
|
+
## Requirements
|
|
67
|
+
|
|
68
|
+
- **Node.js 18 or newer**
|
|
69
|
+
- macOS, Linux, or Windows
|
|
70
|
+
- No native dependencies and no runtime npm packages
|
|
71
|
+
|
|
72
|
+
## Installation
|
|
73
|
+
|
|
74
|
+
PortPilot is version `0.1.0`.
|
|
75
|
+
|
|
76
|
+
### From this repository (pre-publication)
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
cd portpilot
|
|
80
|
+
npm ci
|
|
81
|
+
npm run build
|
|
82
|
+
node cli.js --help
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
To put the `portpilot` command on your `PATH` from this checkout:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
npm link
|
|
89
|
+
portpilot list
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### From npm (after the initial release)
|
|
93
|
+
|
|
94
|
+
Once PortPilot is published to npm as `infinity-portpilot`, install globally:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
npm install -g infinity-portpilot
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The package exposes a `portpilot` binary through its `bin` entry.
|
|
101
|
+
|
|
102
|
+
## Publishing
|
|
103
|
+
|
|
104
|
+
PortPilot is published to npm as `infinity-portpilot`.
|
|
105
|
+
|
|
106
|
+
### Initial release (manual bootstrap)
|
|
107
|
+
|
|
108
|
+
The first publication to npm must be performed manually. After the quality gates pass, run the publication steps locally:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
cd portpilot
|
|
112
|
+
npm ci
|
|
113
|
+
npm run typecheck
|
|
114
|
+
npm run lint
|
|
115
|
+
npm run format:check
|
|
116
|
+
npm test
|
|
117
|
+
npm pack --dry-run
|
|
118
|
+
npm publish --access public
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Once published, `npm install -g infinity-portpilot` becomes available worldwide.
|
|
122
|
+
|
|
123
|
+
### Subsequent releases (GitHub Actions, OIDC)
|
|
124
|
+
|
|
125
|
+
`.github/workflows/portpilot-publish.yml` automates publication for future releases:
|
|
126
|
+
|
|
127
|
+
- **Trigger**: A GitHub tag matching `portpilot-vX.Y.Z` triggers the publish workflow.
|
|
128
|
+
- **Manual publishing**: The workflow can also be triggered manually via `workflow_dispatch`, where you specify the existing release tag to publish.
|
|
129
|
+
- **Validation**: The workflow validates that the tag version exactly matches `portpilot/package.json` and that the package name is `infinity-portpilot`.
|
|
130
|
+
- **Process**: The tagged commit is checked out, dependencies are installed, type checks, lint, format checks, and tests all pass, then `npm pack --dry-run` is verified, and finally the package is published publicly via `npm publish --access public` using OIDC (npm Trusted Publishing).
|
|
131
|
+
|
|
132
|
+
Future releases use tags named `portpilot-vMAJOR.MINOR.PATCH` (e.g., `portpilot-v0.1.0`, `portpilot-v1.2.3`). The npm package automatically generates provenance metadata through Trusted Publishing.
|
|
133
|
+
|
|
134
|
+
## Quick start
|
|
135
|
+
|
|
136
|
+
```console
|
|
137
|
+
$ portpilot 3000
|
|
138
|
+
! Port 3000 is occupied by 1 process:
|
|
139
|
+
node (PID 1234)
|
|
140
|
+
TCP 127.0.0.1:3000
|
|
141
|
+
|
|
142
|
+
What would you like to do?
|
|
143
|
+
1) Inspect process details
|
|
144
|
+
2) Free the port
|
|
145
|
+
3) Cancel
|
|
146
|
+
>
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
In a non-interactive shell, `portpilot 3000` prints the listeners and exits without prompting. Use `portpilot inspect 3000` for read-only details or `portpilot free 3000` to run the guarded termination flow.
|
|
150
|
+
|
|
151
|
+
If the port is free:
|
|
152
|
+
|
|
153
|
+
```console
|
|
154
|
+
$ portpilot 3000
|
|
155
|
+
✓ Port 3000 is available.
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Commands
|
|
159
|
+
|
|
160
|
+
| Command | Purpose | Example |
|
|
161
|
+
| --- | --- | --- |
|
|
162
|
+
| `portpilot <port>` | Inspect a port and offer actions in a TTY | `portpilot 3000` |
|
|
163
|
+
| `portpilot list` | List every TCP listening endpoint | `portpilot list` |
|
|
164
|
+
| `portpilot find <port>` | Show the processes listening on one port | `portpilot find 3000` |
|
|
165
|
+
| `portpilot inspect <port>` | Read-only detailed process inspection | `portpilot inspect 3000` |
|
|
166
|
+
| `portpilot free <port>` | Run the guarded termination workflow | `portpilot free 3000` |
|
|
167
|
+
| `portpilot --help` | Show usage and examples | `portpilot -h` |
|
|
168
|
+
| `portpilot --version` | Print the installed version | `portpilot -v` |
|
|
169
|
+
|
|
170
|
+
### `portpilot list`
|
|
171
|
+
|
|
172
|
+
Lists every TCP listening endpoint found through the platform provider.
|
|
173
|
+
|
|
174
|
+
```console
|
|
175
|
+
$ portpilot list
|
|
176
|
+
|
|
177
|
+
TCP listeners
|
|
178
|
+
|
|
179
|
+
PORT PID PROCESS ADDRESS
|
|
180
|
+
───── ───── ──────── ───────────────
|
|
181
|
+
3000 1234 node 127.0.0.1:3000
|
|
182
|
+
5432 5678 postgres [::1]:5432
|
|
183
|
+
|
|
184
|
+
2 listening endpoints found.
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### `portpilot find <port>`
|
|
188
|
+
|
|
189
|
+
Shows the process or processes listening on one port, without the extra inspection lookup.
|
|
190
|
+
|
|
191
|
+
```console
|
|
192
|
+
$ portpilot find 3000
|
|
193
|
+
! Port 3000 is occupied by 1 process:
|
|
194
|
+
node (PID 1234)
|
|
195
|
+
TCP 127.0.0.1:3000
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Multiple sockets owned by the same PID are merged into one entry. If several distinct processes share the port, each is listed.
|
|
199
|
+
|
|
200
|
+
### `portpilot inspect <port>`
|
|
201
|
+
|
|
202
|
+
Read-only detailed inspection. Includes user, parent PID, executable, state, start time, and command line when the operating system exposes them.
|
|
203
|
+
|
|
204
|
+
```console
|
|
205
|
+
$ portpilot inspect 3000
|
|
206
|
+
! Port 3000 is occupied by 1 process:
|
|
207
|
+
|
|
208
|
+
Process 1234 (TCP 127.0.0.1:3000)
|
|
209
|
+
PID 1234
|
|
210
|
+
Process node
|
|
211
|
+
Port 3000
|
|
212
|
+
Protocol TCP
|
|
213
|
+
Local address 127.0.0.1:3000
|
|
214
|
+
User dev
|
|
215
|
+
Parent PID 1200
|
|
216
|
+
Status S
|
|
217
|
+
Started Fri Nov 20 19:36:26 2026
|
|
218
|
+
Command node server.js
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
`inspect` never signals a process.
|
|
222
|
+
|
|
223
|
+
### `portpilot free <port>`
|
|
224
|
+
|
|
225
|
+
Runs the guarded termination workflow described below. If the port is already free it exits successfully without touching anything.
|
|
226
|
+
|
|
227
|
+
```console
|
|
228
|
+
$ portpilot free 3000
|
|
229
|
+
|
|
230
|
+
Target: node (PID 1234)
|
|
231
|
+
PID 1234
|
|
232
|
+
...
|
|
233
|
+
Terminate node (PID 1234)? [y/N] y
|
|
234
|
+
✓ Process 1234 exited after a graceful termination request.
|
|
235
|
+
✓ Port 3000 is now free.
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## How process inspection works
|
|
239
|
+
|
|
240
|
+
1. **Discover listeners.** The platform provider enumerates TCP listening sockets and maps them to PIDs.
|
|
241
|
+
2. **Merge.** Multiple sockets owned by one PID become one process entry; a PID that cannot be resolved is shown as `?`.
|
|
242
|
+
3. **Inspect.** PortPilot runs platform-native, argument-array lookups — never a shell:
|
|
243
|
+
- macOS/Linux: `ps -p <pid> -o pid=,ppid=,user=,stat=,lstart=,comm=` and a second `ps` call for arguments.
|
|
244
|
+
- Windows: `tasklist` for the image name, plus `Get-CimInstance Win32_Process` for parent PID, executable, command line, and `CreationDate`.
|
|
245
|
+
4. **Present.** Missing fields are omitted rather than invented.
|
|
246
|
+
|
|
247
|
+
All discovery and inspection operations are read-only. Command-line strings are displayed only; they are never executed.
|
|
248
|
+
|
|
249
|
+
## Safe termination workflow
|
|
250
|
+
|
|
251
|
+
```mermaid
|
|
252
|
+
flowchart TD
|
|
253
|
+
A["portpilot free PORT"] --> B["Discover TCP listeners"]
|
|
254
|
+
B --> C{"Owning PID known?"}
|
|
255
|
+
C -- No --> R1["Refuse: cannot identify owner"]
|
|
256
|
+
C -- Yes --> D["Inspect process and capture start-time marker"]
|
|
257
|
+
D --> E{"Marker available?"}
|
|
258
|
+
E -- No --> R2["Refuse: identity unverifiable"]
|
|
259
|
+
E -- Yes --> F["Confirm termination"]
|
|
260
|
+
F -- No --> R3["Cancel: no signal sent"]
|
|
261
|
+
F -- Yes --> G["Revalidate marker and name"]
|
|
262
|
+
G --> H["Graceful signal<br/>SIGTERM or taskkill /PID"]
|
|
263
|
+
H --> I{"Exited?"}
|
|
264
|
+
I -- Yes --> OK["Report: port free"]
|
|
265
|
+
I -- No --> J["Explain and ask for force confirmation"]
|
|
266
|
+
J -- No --> R4["Leave running"]
|
|
267
|
+
J -- Yes --> K["Revalidate marker again"]
|
|
268
|
+
K --> L["Force signal<br/>SIGKILL or taskkill /PID /F"]
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
The guarantees behind that flow:
|
|
272
|
+
|
|
273
|
+
- **Explicit confirmation.** Termination requires an interactive terminal and a literal `y`/`yes`. Piped input, closed stdin, and non-TTY environments are treated as “no” — no prompt, no signal.
|
|
274
|
+
- **Confirmation before action, verification before signal.** The target is revalidated before the prompt and again immediately before each signal.
|
|
275
|
+
- **Graceful first.** PortPilot sends `SIGTERM` on macOS/Linux and a non-forced `taskkill /PID` on Windows, then waits for exit.
|
|
276
|
+
- **Separate force confirmation.** Force termination is only offered after the graceful attempt fails, is refused, or the process does not exit within the grace timeout — and it always needs a second explicit `[y/N]` answer.
|
|
277
|
+
- **Permission failures stop.** `EPERM`/`EACCES`/Windows “Access is denied” ends the workflow; escalation is never attempted.
|
|
278
|
+
- **Always refuse.** PID 1, PortPilot's own PID, and critical system process names (`launchd`, `systemd`, `init`, `csrss`, `lsass`, `svchost`, and others) are not eligible.
|
|
279
|
+
- **No guessing.** If the owning PID cannot be identified, `free` refuses.
|
|
280
|
+
|
|
281
|
+
## PID reuse protection
|
|
282
|
+
|
|
283
|
+
PIDs are recycled. The PID you inspected a second ago may belong to an unrelated process now.
|
|
284
|
+
|
|
285
|
+
PortPilot captures a **start-time marker** during inspection and stores it with the termination target:
|
|
286
|
+
|
|
287
|
+
| Platform | Marker source | Example shape |
|
|
288
|
+
| --- | --- | --- |
|
|
289
|
+
| macOS / Linux | `ps ... lstart=` | `Fri Nov 20 19:36:26 2026` |
|
|
290
|
+
| Windows | CIM `CreationDate` | WMI datetime string |
|
|
291
|
+
|
|
292
|
+
Before the confirmation prompt, before the graceful signal, and before the forced signal, PortPilot reads the current identity and compares:
|
|
293
|
+
|
|
294
|
+
- **Marker differs** → `PID <pid> has been reused by another process; refusing to terminate it`.
|
|
295
|
+
- **Marker missing from the fresh identity** → refused; the process name alone cannot prove identity.
|
|
296
|
+
- **No marker was captured for the target** → refused; there is nothing reliable to compare.
|
|
297
|
+
- **Name is incompatible** → refused as an additional check, never as the sole authorization.
|
|
298
|
+
|
|
299
|
+
Process names and PIDs are never sufficient on their own. A target that cannot carry a verifiable identity marker is not eligible for termination, even if its name matches.
|
|
300
|
+
|
|
301
|
+
## Windows CIM timeout behavior
|
|
302
|
+
|
|
303
|
+
Windows process details depend on PowerShell CIM (`Get-CimInstance Win32_Process`), which can be slow or unavailable. PortPilot treats CIM metadata as optional:
|
|
304
|
+
|
|
305
|
+
- **Inspection still works.** CIM is given a 20-second timeout. If it times out, the process name comes from `tasklist`; command line, executable, and parent PID are omitted rather than fabricated. `list`, `find`, `inspect`, and `portpilot <port>` all continue to work.
|
|
306
|
+
- **Termination is refused.** `tasklist` provides no creation time, so no start-time marker exists. Termination returns `refused` with an actionable message:
|
|
307
|
+
|
|
308
|
+
```text
|
|
309
|
+
Could not verify the identity of PID 1234: no start-time marker was captured
|
|
310
|
+
(the Windows CIM lookup may have timed out). Refusing to terminate it.
|
|
311
|
+
Stop the process manually, or re-run PortPilot once CIM is available.
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
This is deliberate: without a marker, PID reuse cannot be ruled out. Re-run inspection once CIM is responsive, or stop the process manually.
|
|
315
|
+
- **CIM answered, marker available.** Normal verification applies. Note that Windows often refuses a non-forced `taskkill` for console processes; PortPilot explains that failure and requires the second confirmation before `taskkill /F`.
|
|
316
|
+
|
|
317
|
+
## Permissions and safety limitations
|
|
318
|
+
|
|
319
|
+
- **No privilege escalation.** PortPilot never runs `sudo`, never requests UAC elevation, and never re-launches itself. Processes owned by another user may be unreadable or unkillable; PortPilot reports the limitation.
|
|
320
|
+
- **Unknown owners are never terminated.** A visible socket without a resolvable PID is shown with `?`, and `free` refuses to guess.
|
|
321
|
+
- **Read operations are shell-free.** `execFile` is used with fixed argument arrays and timeouts; no user input becomes a command.
|
|
322
|
+
- **TOCTOU remains.** A process can exit and a PID can be recycled between discovery, confirmation, and the signal. Revalidation shrinks that window but cannot make it atomic.
|
|
323
|
+
- **TCP only.** UDP listeners and non-listening sockets are out of scope.
|
|
324
|
+
- **Non-TTY means no termination.** Automation can inspect ports, but cannot confirm a kill.
|
|
325
|
+
- **Platform exposure varies.** On macOS, `ps` may hide arguments of other users' processes. On Linux, `/proc` entries for other users may be unreadable. On Windows without PowerShell, details are reduced to name and PID.
|
|
326
|
+
- **Windows verification status.** Discovery, parsing, inspection, and termination logic are implemented and covered by fixture tests. The previously tested commit passed the full cross-platform CI run ([`44809778797`](https://github.com/erfmollaey/infinite-toolbox/actions/runs/44809778797)) — 8/8 jobs, including Windows on Node 18 and Node 24.
|
|
327
|
+
|
|
328
|
+
## Exit codes
|
|
329
|
+
|
|
330
|
+
| Code | Meaning |
|
|
331
|
+
| --- | --- |
|
|
332
|
+
| `0` | Command completed and the requested state was reached — port available, port freed, inspection succeeded, or termination succeeded |
|
|
333
|
+
| `1` | Invalid input, incomplete discovery, unknown owner, refused/failed termination, no confirmation possible, or the port is still occupied afterwards |
|
|
334
|
+
|
|
335
|
+
User cancellation sends no signal. `free` still exits `1` if the port remains occupied after cancellation, so scripts can distinguish “freed” from “not freed”.
|
|
336
|
+
|
|
337
|
+
## Compatibility
|
|
338
|
+
|
|
339
|
+
| Requirement | Support |
|
|
340
|
+
| --- | --- |
|
|
341
|
+
| Node.js | 18 or newer (`engines.node >= 18.0.0`) |
|
|
342
|
+
| Operating systems | macOS (`darwin`), Linux, Windows (`win32`) |
|
|
343
|
+
| Module format | CommonJS |
|
|
344
|
+
| Runtime dependencies | None |
|
|
345
|
+
| Transport / protocol | Local OS commands; no network access |
|
|
346
|
+
| Port scope | TCP listeners |
|
|
347
|
+
| License | MIT |
|
|
348
|
+
|
|
349
|
+
## Development
|
|
350
|
+
|
|
351
|
+
```bash
|
|
352
|
+
cd portpilot
|
|
353
|
+
npm ci
|
|
354
|
+
|
|
355
|
+
npm run build # tsc → dist/
|
|
356
|
+
npm run typecheck # tsc --noEmit
|
|
357
|
+
npm run lint # ESLint
|
|
358
|
+
npm run format:check # Prettier
|
|
359
|
+
npm test # builds, then runs the full node --test suite
|
|
360
|
+
npm run test:unit
|
|
361
|
+
npm run test:integration
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
| Script | Purpose |
|
|
365
|
+
| --- | --- |
|
|
366
|
+
| `npm run build` | Compile TypeScript to `dist/` |
|
|
367
|
+
| `npm run typecheck` | Strict type check without emitting |
|
|
368
|
+
| `npm run lint` | ESLint over `src`, `tests`, and config |
|
|
369
|
+
| `npm run format` / `format:check` | Apply / verify Prettier formatting |
|
|
370
|
+
| `npm test` | Build and run all tests (`pretest` builds automatically) |
|
|
371
|
+
| `npm run test:unit` | Validator and parser tests |
|
|
372
|
+
| `npm run test:integration` | Discovery and termination tests |
|
|
373
|
+
| `npm start` | Run the CLI |
|
|
374
|
+
| `npm pack --dry-run` | Inspect the publishable tarball |
|
|
375
|
+
|
|
376
|
+
### Tests
|
|
377
|
+
|
|
378
|
+
The suite uses Node's built-in test runner and loads the compiled `dist/` output:
|
|
379
|
+
|
|
380
|
+
| File | Coverage |
|
|
381
|
+
| --- | --- |
|
|
382
|
+
| `validator.test.js` | Port/PID ranges, integers, malformed input |
|
|
383
|
+
| `parsers.test.js` | lsof, macOS/Windows netstat, tasklist CSV, PowerShell JSON, `/proc` |
|
|
384
|
+
| `prompt.test.js` | Non-TTY refusal, explicit yes/no, EOF |
|
|
385
|
+
| `discovery.test.js` | Real ephemeral loopback servers, PID lookup, free/occupied ports |
|
|
386
|
+
| `termination.test.js` | Guarded termination, cancellation, force confirmation, PID reuse, protected PIDs |
|
|
387
|
+
| `windows-identity.test.js` | CIM timeout fallback, missing start-time marker, fail-closed termination |
|
|
388
|
+
| `cli.test.js` | Help/version, invalid input, listing, non-interactive refusal |
|
|
389
|
+
|
|
390
|
+
Integration tests start their own child processes on ephemeral loopback ports and only signal those children. Platform-specific tests are skipped when the required OS feature is absent.
|
|
391
|
+
|
|
392
|
+
### CI
|
|
393
|
+
|
|
394
|
+
`.github/workflows/portpilot.yml` defines:
|
|
395
|
+
|
|
396
|
+
- a quality job (typecheck, lint, format check) on Node 24;
|
|
397
|
+
- a test matrix for Ubuntu, macOS, and Windows on Node 18 and 24 (the previously tested commit passed all 8 jobs in [run `44809778797`](https://github.com/erfmollaey/infinite-toolbox/actions/runs/44809778797));
|
|
398
|
+
- a packaged-CLI job that installs the tarball and exercises `--help`, `--version`, `list`, `find`, `inspect`, and non-interactive `free`.
|
|
399
|
+
|
|
400
|
+
## Project structure
|
|
401
|
+
|
|
402
|
+
```text
|
|
403
|
+
portpilot/
|
|
404
|
+
├── cli.js # Executable wrapper for dist/cli/app.js
|
|
405
|
+
├── src/
|
|
406
|
+
│ ├── cli/ # Argument dispatch, commands, TTY prompts
|
|
407
|
+
│ ├── discovery/ # Provider selection and platform discovery
|
|
408
|
+
│ │ └── platforms/ # macos.ts · linux.ts · windows.ts
|
|
409
|
+
│ ├── process/ # inspector.ts · terminator.ts
|
|
410
|
+
│ ├── types/ # Shared domain types
|
|
411
|
+
│ └── utils/ # exec, formatter, platform, validator
|
|
412
|
+
├── tests/ # node --test suites and fixtures
|
|
413
|
+
├── dist/ # Generated build output (shipped, gitignored)
|
|
414
|
+
├── BUILD.md # Build and packaging guide
|
|
415
|
+
├── package.json
|
|
416
|
+
└── tsconfig.json
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
See [BUILD.md](BUILD.md) for packaging details and troubleshooting.
|
|
420
|
+
|
|
421
|
+
## Limitations
|
|
422
|
+
|
|
423
|
+
- Only TCP listeners are supported.
|
|
424
|
+
- The initial release must be published manually from this repository; subsequent releases are published automatically by GitHub Actions using npm Trusted Publishing (OIDC).
|
|
425
|
+
- Windows support has fixture-test coverage and passed the full CI matrix, including Windows Node 18 and 24, on the previously tested commit.
|
|
426
|
+
- Processes owned by other users may not expose their PID or command line, and PortPilot will not elevate privileges to find out.
|
|
427
|
+
- Ports can change between discovery and termination; revalidation reduces, but cannot eliminate, that race.
|
|
428
|
+
- Platform command availability varies (`lsof`, `netstat`, `tasklist`, PowerShell). PortPilot reports incomplete discovery rather than claiming a port is free.
|
|
429
|
+
|
|
430
|
+
## Contributing
|
|
431
|
+
|
|
432
|
+
Issues and pull requests are welcome.
|
|
433
|
+
|
|
434
|
+
1. Open an issue describing the problem and the platform you observed it on.
|
|
435
|
+
2. Keep changes focused; include tests for behavior changes.
|
|
436
|
+
3. Run `npm test`, `npm run typecheck`, `npm run lint`, and `npm run format:check` before submitting.
|
|
437
|
+
4. Never weaken termination safety guarantees to make a workflow more convenient — fail closed is the design.
|
|
438
|
+
|
|
439
|
+
Repository: [erfmollaey/infinite-toolbox](https://github.com/erfmollaey/infinite-toolbox) · Issues: [github.com/erfmollaey/infinite-toolbox/issues](https://github.com/erfmollaey/infinite-toolbox/issues)
|
|
440
|
+
|
|
441
|
+
## License
|
|
442
|
+
|
|
443
|
+
PortPilot is released under the [MIT License](LICENSE).
|
|
444
|
+
|
|
445
|
+
Copyright © 2026 Infinity™.
|
|
446
|
+
|
|
447
|
+
## Part of Infinite Toolbox
|
|
448
|
+
|
|
449
|
+
PortPilot is part of **[Infinite Toolbox](https://github.com/erfmollaey/infinite-toolbox)** — an open-source collection of practical developer tools.
|
|
450
|
+
|
|
451
|
+
Explore the other tools:
|
|
452
|
+
|
|
453
|
+
- 🛡️ [EnvGuard](https://github.com/erfmollaey/infinite-toolbox/tree/main/envguard) — environment configuration checks
|
|
454
|
+
- 🧰 [Infinity MCP Toolbox](https://github.com/erfmollaey/infinite-toolbox/tree/main/mcp-tools) — read-only project context for AI assistants
|
|
455
|
+
- 🚢 [PortPilot](https://github.com/erfmollaey/infinite-toolbox/tree/main/portpilot) — this tool
|
|
456
|
+
- 📚 [Collection overview](https://github.com/erfmollaey/infinite-toolbox)
|
|
457
|
+
|
|
458
|
+
---
|
|
459
|
+
|
|
460
|
+
<p align="center">
|
|
461
|
+
<strong>Built with ❤️ by Infinity™</strong>
|
|
462
|
+
<br />
|
|
463
|
+
<sub>Tools that make development smarter.</sub>
|
|
464
|
+
</p>
|
package/cli.js
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
|
|
4
|
+
const { main } = require("./dist/cli/app.js");
|
|
5
|
+
|
|
6
|
+
main(process.argv.slice(2))
|
|
7
|
+
.then((code) => {
|
|
8
|
+
process.exitCode = code;
|
|
9
|
+
})
|
|
10
|
+
.catch((error) => {
|
|
11
|
+
console.error(
|
|
12
|
+
`Unexpected error: ${error && error.message ? error.message : error}`,
|
|
13
|
+
);
|
|
14
|
+
process.exitCode = 1;
|
|
15
|
+
});
|
package/dist/cli/app.js
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.printHelp = printHelp;
|
|
4
|
+
exports.printVersion = printVersion;
|
|
5
|
+
exports.main = main;
|
|
6
|
+
const node_fs_1 = require("node:fs");
|
|
7
|
+
const node_path_1 = require("node:path");
|
|
8
|
+
const commands_1 = require("./commands");
|
|
9
|
+
function getVersion() {
|
|
10
|
+
try {
|
|
11
|
+
const raw = (0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "..", "package.json"), "utf8");
|
|
12
|
+
const parsed = JSON.parse(raw);
|
|
13
|
+
return parsed.version ?? "0.0.0";
|
|
14
|
+
}
|
|
15
|
+
catch {
|
|
16
|
+
return "0.0.0";
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
function printHelp() {
|
|
20
|
+
console.log(`
|
|
21
|
+
PortPilot ${getVersion()} — inspect and free TCP ports
|
|
22
|
+
|
|
23
|
+
Usage:
|
|
24
|
+
portpilot <port> Inspect a port and choose an action
|
|
25
|
+
portpilot list List all TCP listening endpoints
|
|
26
|
+
portpilot find <port> Show processes listening on a port
|
|
27
|
+
portpilot inspect <port> Show detailed process information
|
|
28
|
+
portpilot free <port> Safely terminate processes on a port
|
|
29
|
+
|
|
30
|
+
Options:
|
|
31
|
+
-h, --help Show this help
|
|
32
|
+
-v, --version Show the version
|
|
33
|
+
|
|
34
|
+
Examples:
|
|
35
|
+
portpilot 3000
|
|
36
|
+
portpilot list
|
|
37
|
+
portpilot inspect 3000
|
|
38
|
+
portpilot free 3000
|
|
39
|
+
|
|
40
|
+
Termination is interactive and requires explicit confirmation. PortPilot
|
|
41
|
+
never escalates privileges and never kills a process it cannot revalidate.
|
|
42
|
+
`);
|
|
43
|
+
}
|
|
44
|
+
function printVersion() {
|
|
45
|
+
console.log(getVersion());
|
|
46
|
+
}
|
|
47
|
+
async function main(argv) {
|
|
48
|
+
const [command, ...rest] = argv;
|
|
49
|
+
if (command === undefined ||
|
|
50
|
+
command === "help" ||
|
|
51
|
+
command === "--help" ||
|
|
52
|
+
command === "-h") {
|
|
53
|
+
printHelp();
|
|
54
|
+
return 0;
|
|
55
|
+
}
|
|
56
|
+
if (command === "version" || command === "--version" || command === "-v") {
|
|
57
|
+
printVersion();
|
|
58
|
+
return 0;
|
|
59
|
+
}
|
|
60
|
+
try {
|
|
61
|
+
switch (command) {
|
|
62
|
+
case "list":
|
|
63
|
+
return await (0, commands_1.cmdList)();
|
|
64
|
+
case "find":
|
|
65
|
+
return await (0, commands_1.cmdFind)(rest[0]);
|
|
66
|
+
case "inspect":
|
|
67
|
+
return await (0, commands_1.cmdInspect)(rest[0]);
|
|
68
|
+
case "free":
|
|
69
|
+
return await (0, commands_1.cmdFree)(rest[0]);
|
|
70
|
+
default:
|
|
71
|
+
if (/^\d+$/.test(command)) {
|
|
72
|
+
return await (0, commands_1.cmdPort)(command);
|
|
73
|
+
}
|
|
74
|
+
console.error(`Unknown command: ${command}`);
|
|
75
|
+
printHelp();
|
|
76
|
+
return 1;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
catch (error) {
|
|
80
|
+
console.error(`Unexpected error: ${error.message}`);
|
|
81
|
+
return 1;
|
|
82
|
+
}
|
|
83
|
+
}
|