@dprrwt/ports 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deepankar Rawat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# ⚡ ports
+
+> Beautiful port manager CLI — because `netstat -ano | findstr :3000` is a crime against developer experience.
+
+See what's running. Kill by port. Scan ranges. Find free ports. All with colors and sanity.
+
+## Install
+
+```bash
+npm install -g @dprrwt/ports
+```
+
+Or use without installing:
+
+```bash
+npx @dprrwt/ports
+```
+
+## Usage
+
+### List all listening ports
+
+```bash
+ports
+```
+
+```
+  ⚡ ports — what's running on your machine
+
+  Listening Ports
+┌──────────────────────┬───────┬───────┬──────────┬───────────┬───────────┐
+│ Port                 │ Proto │ PID   │ Process  │ State     │ Address   │
+├──────────────────────┼───────┼───────┼──────────┼───────────┼───────────┤
+│ 3000 (Dev Server)    │ TCP   │ 12345 │ node     │ LISTENING │ 0.0.0.0   │
+├──────────────────────┼───────┼───────┼──────────┼───────────┼───────────┤
+│ 5432 (PostgreSQL)    │ TCP   │ 6789  │ postgres │ LISTENING │ 127.0.0.1 │
+├──────────────────────┼───────┼───────┼──────────┼───────────┼───────────┤
+│ 8080 (HTTP Alt)      │ TCP   │ 4567  │ java     │ LISTENING │ 0.0.0.0   │
+└──────────────────────┴───────┴───────┴──────────┴───────────┴───────────┘
+  3 ports found
+
+  Legend:
+    ■ JS Runtime  ■ Python  ■ Java  ■ Container  ■ Database  ■ System  ■ Unknown
+```
+
+### Check a specific port
+
+```bash
+ports 3000
+# or
+ports check 3000
+```
+
+```
+  Port 3000 (Dev Server)
+
+  Process:  node (PID 12345)
+  Proto:    TCP
+  State:    LISTENING
+  Address:  0.0.0.0:3000
+```
+
+### Kill a process by port
+
+```bash
+ports kill 3000           # asks for confirmation
+ports kill 3000 --yes     # skip confirmation
+ports kill 3000 -f --yes  # force kill (SIGKILL)
+```
+
+### Scan a port range
+
+```bash
+ports scan 3000-4000
+```
+
+```
+  Scanning ports 3000-4000
+  2 in use  ·  999 free  ·  1001 total
+
+┌──────┬───────┬──────┬─────────┬───────────┬─────────┐
+│ Port │ Proto │ PID  │ Process │ State     │ Address │
+├──────┼───────┼──────┼─────────┼───────────┼─────────┤
+│ 3000 │ TCP   │ 1234 │ node    │ LISTENING │ 0.0.0.0 │
+├──────┼───────┼──────┼─────────┼───────────┼─────────┤
+│ 3306 │ TCP   │ 5678 │ mysqld  │ LISTENING │ 0.0.0.0 │
+└──────┴───────┴──────┴─────────┴───────────┴─────────┘
+```
+
+### Find next free port
+
+```bash
+ports free         # starts from 3000
+ports free 8000    # starts from 8000
+```
+
+```
+  ✓ Next free port: 3000
+```
+
+## Features
+
+- 🎨 **Color-coded processes** — JS runtimes (green), Python (blue), Java (yellow), databases (magenta), system (gray), unknown (red)
+- 🏷️ **Smart port labels** — recognizes 30+ common ports (PostgreSQL, Redis, Vite, Django, etc.)
+- 🛡️ **Safety warnings** — warns before killing critical processes
+- 📊 **JSON output** — `--json` flag on any command for scripting
+- 🖥️ **Cross-platform** — Windows (netstat) + macOS/Linux (ss/lsof)
+- ⚡ **Fast** — process name caching, no unnecessary lookups
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON (works on all commands) |
+| `--tcp` | Show only TCP ports (list command) |
+| `--udp` | Show only UDP ports (list command) |
+| `-a, --all` | Show all states, not just LISTENING |
+| `-f, --force` | Force kill (SIGKILL / taskkill /F) |
+| `-y, --yes` | Skip confirmation prompts |
+
+## Programmatic API
+
+```typescript
+import { getListeningPorts, isPortInUse, findFreePort, killProcess } from "@dprrwt/ports";
+
+// Get all listening ports
+const ports = getListeningPorts();
+
+// Check if a port is in use
+if (isPortInUse(3000)) {
+  console.log("Port 3000 is taken!");
+}
+
+// Find next free port
+const free = findFreePort(3000); // → 3001
+
+// Kill a process
+killProcess(12345, true); // force = true
+```
+
+## Why?
+
+Every developer has done this dance:
+
+1. "Port 3000 is already in use"
+2. Google "how to find what's using port 3000"
+3. Copy-paste some arcane `netstat` or `lsof` incantation
+4. Parse the output with your eyes
+5. Find the PID
+6. Google "how to kill process by PID"
+7. Finally kill it
+8. Repeat next week because you forgot the commands
+
+**`ports` makes this a one-liner.** See what's running, kill what you need, move on with your life.
+
+## License
+
+MIT © [Deepankar Rawat](https://dprrwt.me)

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * ports — A beautiful port manager CLI
+ *
+ * Because `netstat -ano | findstr :3000` is a crime against developer experience.
+ *
+ * Usage:
+ *   ports              List all listening ports
+ *   ports <port>       Check what's on a specific port
+ *   ports kill <port>  Kill whatever's on that port
+ *   ports scan <range> Scan a port range (e.g. 3000-4000)
+ *   ports free [start] Find next available port
+ *
+ * @author Deepankar Rawat <dprrwt@gmail.com>
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * ports — A beautiful port manager CLI
+ *
+ * Because `netstat -ano | findstr :3000` is a crime against developer experience.
+ *
+ * Usage:
+ *   ports              List all listening ports
+ *   ports <port>       Check what's on a specific port
+ *   ports kill <port>  Kill whatever's on that port
+ *   ports scan <range> Scan a port range (e.g. 3000-4000)
+ *   ports free [start] Find next available port
+ *
+ * @author Deepankar Rawat <dprrwt@gmail.com>
+ */
+import { Command } from "commander";
+import chalk from "chalk";
+import { getListeningPorts, getPortInfo, killProcess, scanRange, findFreePort, } from "./scanner.js";
+import { displayPortTable, displayPortDetail, displayScanRange, displayFreePort, displayKillResult, displayLegend, } from "./display.js";
+const program = new Command();
+program
+    .name("ports")
+    .description("Beautiful port manager — see, kill, scan, find")
+    .version("1.0.0")
+    .option("--json", "Output as JSON")
+    .option("--no-legend", "Hide color legend");
+// Default command: list all ports
+program
+    .command("list", { isDefault: true })
+    .description("List all listening ports")
+    .option("-a, --all", "Show all states (not just LISTENING)")
+    .option("--tcp", "Show only TCP ports")
+    .option("--udp", "Show only UDP ports")
+    .option("--json", "Output as JSON")
+    .action((opts) => {
+    let ports = getListeningPorts();
+    if (!opts.all) {
+        ports = ports.filter((p) => p.state === "LISTENING" || p.state === "LISTEN" || p.state === "*");
+    }
+    if (opts.tcp) {
+        ports = ports.filter((p) => p.protocol === "TCP");
+    }
+    if (opts.udp) {
+        ports = ports.filter((p) => p.protocol === "UDP");
+    }
+    if (opts.json || program.opts().json) {
+        console.log(JSON.stringify(ports, null, 2));
+        return;
+    }
+    console.log(chalk.bold.cyan("\n  ⚡ ports") + chalk.dim(" — what's running on your machine\n"));
+    displayPortTable(ports, "Listening Ports");
+    displayLegend();
+});
+// Check specific port
+program
+    .command("check <port>")
+    .description("Check what's using a specific port")
+    .option("--json", "Output as JSON")
+    .action((portStr, opts) => {
+    const port = parseInt(portStr, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+        console.error(chalk.red(`\n  ✗ Invalid port: ${portStr} (must be 1-65535)\n`));
+        process.exit(1);
+    }
+    const infos = getPortInfo(port);
+    if (opts.json || program.opts().json) {
+        console.log(JSON.stringify(infos, null, 2));
+        return;
+    }
+    displayPortDetail(port, infos);
+});
+// Kill process on port
+program
+    .command("kill <port>")
+    .description("Kill the process using a port")
+    .option("-f, --force", "Force kill (SIGKILL / taskkill /F)")
+    .option("-y, --yes", "Skip confirmation")
+    .option("--json", "Output as JSON")
+    .action(async (portStr, opts) => {
+    const port = parseInt(portStr, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+        console.error(chalk.red(`\n  ✗ Invalid port: ${portStr}\n`));
+        process.exit(1);
+    }
+    const infos = getPortInfo(port);
+    if (infos.length === 0) {
+        console.log(chalk.yellow(`\n  Nothing is running on port ${port}\n`));
+        return;
+    }
+    // Safety check: warn about system processes
+    const systemPorts = [18791, 18800]; // OpenClaw
+    if (systemPorts.includes(port)) {
+        console.log(chalk.red.bold(`\n  ⚠ Port ${port} is used by OpenClaw — killing it may break your agent system!`));
+        if (!opts.yes) {
+            console.log(chalk.dim("  Use --yes to confirm\n"));
+            return;
+        }
+    }
+    for (const info of infos) {
+        if (!opts.yes) {
+            console.log(chalk.yellow(`\n  Kill ${chalk.bold(info.processName)} (PID ${info.pid}) on port ${port}?`));
+            console.log(chalk.dim("  Use --yes to skip confirmation\n"));
+            return;
+        }
+        const success = killProcess(info.pid, opts.force);
+        if (opts.json || program.opts().json) {
+            console.log(JSON.stringify({ port, pid: info.pid, processName: info.processName, killed: success }));
+        }
+        else {
+            displayKillResult(port, info.pid, info.processName, success);
+        }
+    }
+});
+// Scan port range
+program
+    .command("scan <range>")
+    .description("Scan a port range (e.g. 3000-4000)")
+    .option("--json", "Output as JSON")
+    .action((range, opts) => {
+    const match = range.match(/^(\d+)-(\d+)$/);
+    if (!match) {
+        console.error(chalk.red(`\n  ✗ Invalid range: ${range} (use format: 3000-4000)\n`));
+        process.exit(1);
+    }
+    const startPort = parseInt(match[1], 10);
+    const endPort = parseInt(match[2], 10);
+    if (startPort > endPort || startPort < 1 || endPort > 65535) {
+        console.error(chalk.red(`\n  ✗ Invalid range: ${startPort}-${endPort}\n`));
+        process.exit(1);
+    }
+    if (endPort - startPort > 10000) {
+        console.log(chalk.yellow(`\n  Scanning ${endPort - startPort + 1} ports — this may take a moment...\n`));
+    }
+    const ports = scanRange(startPort, endPort);
+    if (opts.json || program.opts().json) {
+        console.log(JSON.stringify(ports, null, 2));
+        return;
+    }
+    displayScanRange(startPort, endPort, ports);
+});
+// Find free port
+program
+    .command("free [startPort]")
+    .description("Find the next available port")
+    .option("--json", "Output as JSON")
+    .action((startStr, opts) => {
+    const startPort = startStr ? parseInt(startStr, 10) : 3000;
+    if (isNaN(startPort) || startPort < 1 || startPort > 65535) {
+        console.error(chalk.red(`\n  ✗ Invalid start port: ${startStr}\n`));
+        process.exit(1);
+    }
+    const freePort = findFreePort(startPort);
+    if (opts.json || program.opts().json) {
+        console.log(JSON.stringify({ freePort, startedFrom: startPort }));
+        return;
+    }
+    displayFreePort(freePort, startPort);
+});
+// Handle bare port number: `ports 3000` → `ports check 3000`
+const args = process.argv.slice(2);
+if (args.length > 0 && /^\d+$/.test(args[0])) {
+    // Rewrite `ports 3000` → `ports check 3000`
+    process.argv.splice(2, 0, "check");
+}
+program.parse();

package/dist/display.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Display Layer — Making port data beautiful
+ *
+ * netstat is powerful but ugly. The information is there — it just needs
+ * a human-friendly presentation. Like Da Vinci's anatomical drawings:
+ * the same body everyone could see, but rendered with clarity and beauty.
+ */
+import type { PortInfo } from "./scanner.js";
+/**
+ * Display a full port table
+ */
+export declare function displayPortTable(ports: PortInfo[], title?: string): void;
+/**
+ * Display compact port info (for single port lookup)
+ */
+export declare function displayPortDetail(port: number, infos: PortInfo[]): void;
+/**
+ * Display scan range results
+ */
+export declare function displayScanRange(startPort: number, endPort: number, ports: PortInfo[]): void;
+/**
+ * Display free port result
+ */
+export declare function displayFreePort(port: number | null, startPort: number): void;
+/**
+ * Display kill result
+ */
+export declare function displayKillResult(port: number, pid: number, processName: string, success: boolean): void;
+/**
+ * Display legend
+ */
+export declare function displayLegend(): void;

package/dist/display.js

@@ -0,0 +1,205 @@
+/**
+ * Display Layer — Making port data beautiful
+ *
+ * netstat is powerful but ugly. The information is there — it just needs
+ * a human-friendly presentation. Like Da Vinci's anatomical drawings:
+ * the same body everyone could see, but rendered with clarity and beauty.
+ */
+import chalk from "chalk";
+import Table from "cli-table3";
+// Well-known ports that developers care about
+const KNOWN_PORTS = {
+    80: "HTTP",
+    443: "HTTPS",
+    3000: "Dev Server",
+    3001: "Dev Server",
+    3333: "Dev Server",
+    4000: "Dev Server",
+    4200: "Angular",
+    5000: "Flask/Vite",
+    5173: "Vite",
+    5174: "Vite",
+    5432: "PostgreSQL",
+    5500: "Live Server",
+    6379: "Redis",
+    8000: "Django/FastAPI",
+    8080: "HTTP Alt",
+    8443: "HTTPS Alt",
+    8888: "Jupyter",
+    9000: "PHP-FPM",
+    9090: "Prometheus",
+    9229: "Node Debug",
+    18791: "OpenClaw",
+    18800: "OpenClaw Browser",
+    27017: "MongoDB",
+    2960: "Mission Control",
+};
+// Process name to color category
+function getProcessColor(name) {
+    const lower = name.toLowerCase();
+    if (lower.includes("node") || lower.includes("deno") || lower.includes("bun")) {
+        return chalk.green; // JS runtimes — green (your dev servers)
+    }
+    if (lower.includes("python") || lower.includes("flask") || lower.includes("django")) {
+        return chalk.blue; // Python
+    }
+    if (lower.includes("java") || lower.includes("gradle") || lower.includes("maven")) {
+        return chalk.yellow; // Java
+    }
+    if (lower.includes("docker") || lower.includes("containerd")) {
+        return chalk.cyan; // Containers
+    }
+    if (lower.includes("postgres") || lower.includes("mysql") || lower.includes("mongo") || lower.includes("redis")) {
+        return chalk.magenta; // Databases
+    }
+    if (lower === "system" || lower === "svchost" || lower.includes("system")) {
+        return chalk.gray; // System processes
+    }
+    if (lower === "unknown") {
+        return chalk.red; // Unknown — potential concern
+    }
+    return chalk.white; // Everything else
+}
+function getStateColor(state) {
+    switch (state) {
+        case "LISTENING":
+            return chalk.green(state);
+        case "ESTABLISHED":
+            return chalk.cyan(state);
+        case "TIME_WAIT":
+            return chalk.gray(state);
+        case "CLOSE_WAIT":
+            return chalk.yellow(state);
+        default:
+            return chalk.white(state);
+    }
+}
+function getPortLabel(port) {
+    const label = KNOWN_PORTS[port];
+    return label ? chalk.dim(` (${label})`) : "";
+}
+/**
+ * Display a full port table
+ */
+export function displayPortTable(ports, title) {
+    if (ports.length === 0) {
+        console.log(chalk.yellow("\n  No ports found.\n"));
+        return;
+    }
+    if (title) {
+        console.log(chalk.bold(`\n  ${title}`));
+    }
+    const table = new Table({
+        head: [
+            chalk.bold.white("Port"),
+            chalk.bold.white("Proto"),
+            chalk.bold.white("PID"),
+            chalk.bold.white("Process"),
+            chalk.bold.white("State"),
+            chalk.bold.white("Address"),
+        ],
+        style: {
+            head: [],
+            border: ["gray"],
+        },
+        chars: {
+            top: "─",
+            "top-mid": "┬",
+            "top-left": "┌",
+            "top-right": "┐",
+            bottom: "─",
+            "bottom-mid": "┴",
+            "bottom-left": "└",
+            "bottom-right": "┘",
+            left: "│",
+            "left-mid": "├",
+            mid: "─",
+            "mid-mid": "┼",
+            right: "│",
+            "right-mid": "┤",
+            middle: "│",
+        },
+    });
+    for (const p of ports) {
+        const colorFn = getProcessColor(p.processName);
+        table.push([
+            chalk.bold.white(String(p.port)) + getPortLabel(p.port),
+            p.protocol === "UDP" ? chalk.yellow(p.protocol) : chalk.cyan(p.protocol),
+            chalk.dim(String(p.pid)),
+            colorFn(p.processName),
+            getStateColor(p.state),
+            chalk.dim(p.localAddress),
+        ]);
+    }
+    console.log(table.toString());
+    console.log(chalk.dim(`  ${ports.length} port${ports.length === 1 ? "" : "s"} found\n`));
+}
+/**
+ * Display compact port info (for single port lookup)
+ */
+export function displayPortDetail(port, infos) {
+    if (infos.length === 0) {
+        console.log(chalk.green(`\n  ✓ Port ${port} is free\n`));
+        return;
+    }
+    console.log(chalk.bold(`\n  Port ${port}`) + getPortLabel(port));
+    console.log();
+    for (const info of infos) {
+        const colorFn = getProcessColor(info.processName);
+        console.log(`  ${chalk.dim("Process:")}  ${colorFn(info.processName)} ${chalk.dim(`(PID ${info.pid})`)}`);
+        console.log(`  ${chalk.dim("Proto:")}    ${info.protocol}`);
+        console.log(`  ${chalk.dim("State:")}    ${getStateColor(info.state)}`);
+        console.log(`  ${chalk.dim("Address:")}  ${info.localAddress}:${port}`);
+        if (infos.indexOf(info) < infos.length - 1) {
+            console.log(chalk.dim("  ─────────────────────────"));
+        }
+    }
+    console.log();
+}
+/**
+ * Display scan range results
+ */
+export function displayScanRange(startPort, endPort, ports) {
+    const total = endPort - startPort + 1;
+    const used = new Set(ports.map((p) => p.port)).size;
+    const free = total - used;
+    console.log(chalk.bold(`\n  Scanning ports ${startPort}-${endPort}`));
+    console.log(`  ${chalk.red(String(used))} in use  ·  ${chalk.green(String(free))} free  ·  ${chalk.dim(String(total) + " total")}`);
+    if (ports.length > 0) {
+        displayPortTable(ports);
+    }
+    else {
+        console.log(chalk.green(`\n  ✓ All ${total} ports are free\n`));
+    }
+}
+/**
+ * Display free port result
+ */
+export function displayFreePort(port, startPort) {
+    if (port === null) {
+        console.log(chalk.red(`\n  ✗ No free ports found starting from ${startPort}\n`));
+    }
+    else {
+        console.log(chalk.green(`\n  ✓ Next free port: ${chalk.bold.white(String(port))}\n`));
+    }
+}
+/**
+ * Display kill result
+ */
+export function displayKillResult(port, pid, processName, success) {
+    if (success) {
+        console.log(chalk.green(`\n  ✓ Killed ${processName} (PID ${pid}) on port ${port}\n`));
+    }
+    else {
+        console.log(chalk.red(`\n  ✗ Failed to kill ${processName} (PID ${pid}) on port ${port}`));
+        console.log(chalk.dim("    Try running with --force or as administrator\n"));
+    }
+}
+/**
+ * Display legend
+ */
+export function displayLegend() {
+    console.log(chalk.dim("  Legend:"));
+    console.log(`    ${chalk.green("■")} JS Runtime  ${chalk.blue("■")} Python  ${chalk.yellow("■")} Java  ${chalk.cyan("■")} Container  ${chalk.magenta("■")} Database  ${chalk.gray("■")} System  ${chalk.red("■")} Unknown`);
+    console.log();
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @dprrwt/ports — Programmatic API
+ *
+ * Use the CLI for interactive use, or import these functions
+ * for programmatic port management in your Node.js scripts.
+ */
+export { getListeningPorts, getPortInfo, isPortInUse, findFreePort, scanRange, killProcess, type PortInfo, } from "./scanner.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @dprrwt/ports — Programmatic API
+ *
+ * Use the CLI for interactive use, or import these functions
+ * for programmatic port management in your Node.js scripts.
+ */
+export { getListeningPorts, getPortInfo, isPortInUse, findFreePort, scanRange, killProcess, } from "./scanner.js";

package/dist/scanner.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Port Scanner — Cross-platform port detection
+ *
+ * Da Vinci's curiosity: How do operating systems track network connections?
+ * Windows uses netstat, macOS/Linux use ss/lsof. Different tools, same truth.
+ * The abstraction layer here unifies them — like translating between languages
+ * to find the same underlying meaning.
+ */
+export interface PortInfo {
+    port: number;
+    pid: number;
+    protocol: "TCP" | "UDP";
+    state: string;
+    localAddress: string;
+    processName: string;
+}
+/**
+ * Get all listening ports on the system
+ */
+export declare function getListeningPorts(): PortInfo[];
+/**
+ * Get info for a specific port
+ */
+export declare function getPortInfo(port: number): PortInfo[];
+/**
+ * Check if a port is in use
+ */
+export declare function isPortInUse(port: number): boolean;
+/**
+ * Find the next free port starting from a given port
+ */
+export declare function findFreePort(startPort?: number, endPort?: number): number | null;
+/**
+ * Scan a range of ports and return which are in use
+ */
+export declare function scanRange(startPort: number, endPort: number): PortInfo[];
+/**
+ * Kill a process by PID
+ */
+export declare function killProcess(pid: number, force?: boolean): boolean;