@dprrwt/ports 1.0.0

package/src/display.ts

@@ -0,0 +1,228 @@
+/**
+ * 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";
+import type { PortInfo } from "./scanner.js";
+
+// Well-known ports that developers care about
+const KNOWN_PORTS: Record<number, string> = {
+  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: string): (text: string) => string {
+  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: string): string {
+  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: number): string {
+  const label = KNOWN_PORTS[port];
+  return label ? chalk.dim(` (${label})`) : "";
+}
+
+/**
+ * Display a full port table
+ */
+export function displayPortTable(ports: PortInfo[], title?: string): void {
+  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: number, infos: PortInfo[]): void {
+  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: number, endPort: number, ports: PortInfo[]): void {
+  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: number | null, startPort: number): void {
+  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: number, pid: number, processName: string, success: boolean): void {
+  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(): void {
+  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/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @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/src/scanner.ts

@@ -0,0 +1,282 @@
+/**
+ * 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.
+ */
+
+import { execSync } from "node:child_process";
+import { platform } from "node:os";
+
+export interface PortInfo {
+  port: number;
+  pid: number;
+  protocol: "TCP" | "UDP";
+  state: string;
+  localAddress: string;
+  processName: string;
+}
+
+/**
+ * Get all listening ports on the system
+ */
+export function getListeningPorts(): PortInfo[] {
+  const os = platform();
+  if (os === "win32") {
+    return getPortsWindows();
+  }
+  return getPortsUnix();
+}
+
+/**
+ * Get info for a specific port
+ */
+export function getPortInfo(port: number): PortInfo[] {
+  return getListeningPorts().filter((p) => p.port === port);
+}
+
+/**
+ * Check if a port is in use
+ */
+export function isPortInUse(port: number): boolean {
+  return getPortInfo(port).length > 0;
+}
+
+/**
+ * Find the next free port starting from a given port
+ */
+export function findFreePort(startPort: number = 3000, endPort: number = 65535): number | null {
+  const usedPorts = new Set(getListeningPorts().map((p) => p.port));
+  for (let port = startPort; port <= endPort; port++) {
+    if (!usedPorts.has(port)) {
+      return port;
+    }
+  }
+  return null;
+}
+
+/**
+ * Scan a range of ports and return which are in use
+ */
+export function scanRange(startPort: number, endPort: number): PortInfo[] {
+  const allPorts = getListeningPorts();
+  return allPorts.filter((p) => p.port >= startPort && p.port <= endPort);
+}
+
+/**
+ * Kill a process by PID
+ */
+export function killProcess(pid: number, force: boolean = false): boolean {
+  try {
+    const os = platform();
+    if (os === "win32") {
+      execSync(`taskkill ${force ? "/F" : ""} /PID ${pid}`, { stdio: "pipe" });
+    } else {
+      execSync(`kill ${force ? "-9" : "-15"} ${pid}`, { stdio: "pipe" });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get process name by PID
+ */
+function getProcessName(pid: number): string {
+  if (pid === 0) return "System";
+  try {
+    const os = platform();
+    if (os === "win32") {
+      const result = execSync(
+        `powershell -Command "(Get-Process -Id ${pid} -ErrorAction SilentlyContinue).ProcessName"`,
+        { stdio: "pipe", encoding: "utf-8", timeout: 5000 }
+      ).trim();
+      return result || "unknown";
+    } else {
+      const result = execSync(`ps -p ${pid} -o comm= 2>/dev/null`, {
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 5000,
+      }).trim();
+      return result || "unknown";
+    }
+  } catch {
+    return "unknown";
+  }
+}
+
+// Cache process names to avoid repeated lookups
+const processNameCache = new Map<number, string>();
+
+function getCachedProcessName(pid: number): string {
+  if (processNameCache.has(pid)) {
+    return processNameCache.get(pid)!;
+  }
+  const name = getProcessName(pid);
+  processNameCache.set(pid, name);
+  return name;
+}
+
+/**
+ * Windows: Parse netstat -ano output
+ *
+ * Interesting: Windows netstat shows ALL connection states by default,
+ * while Unix ss needs flags. Different philosophies — Windows shows everything,
+ * Unix shows what you ask for.
+ */
+function getPortsWindows(): PortInfo[] {
+  try {
+    const output = execSync("netstat -ano -p TCP", {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: 10000,
+    });
+
+    const ports: PortInfo[] = [];
+    const lines = output.split("\n");
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("Active") || trimmed.startsWith("Proto")) {
+        continue;
+      }
+
+      // TCP    0.0.0.0:3000    0.0.0.0:0    LISTENING    1234
+      // TCP    127.0.0.1:8080  0.0.0.0:0    LISTENING    5678
+      const parts = trimmed.split(/\s+/);
+      if (parts.length < 5) continue;
+
+      const [proto, localAddr, , state, pidStr] = parts;
+      if (!proto || !localAddr || !state) continue;
+
+      // Only care about LISTENING and ESTABLISHED
+      if (state !== "LISTENING" && state !== "ESTABLISHED") continue;
+
+      const lastColon = localAddr.lastIndexOf(":");
+      if (lastColon === -1) continue;
+
+      const port = parseInt(localAddr.substring(lastColon + 1), 10);
+      const pid = parseInt(pidStr, 10);
+
+      if (isNaN(port) || isNaN(pid)) continue;
+
+      ports.push({
+        port,
+        pid,
+        protocol: proto.toUpperCase() as "TCP" | "UDP",
+        state,
+        localAddress: localAddr.substring(0, lastColon),
+        processName: getCachedProcessName(pid),
+      });
+    }
+
+    // Also grab UDP
+    try {
+      const udpOutput = execSync("netstat -ano -p UDP", {
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 10000,
+      });
+
+      for (const line of udpOutput.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("Active") || trimmed.startsWith("Proto")) continue;
+
+        const parts = trimmed.split(/\s+/);
+        if (parts.length < 4) continue;
+
+        const [proto, localAddr] = parts;
+        const pidStr = parts[parts.length - 1];
+
+        if (!proto?.toUpperCase().startsWith("UDP")) continue;
+
+        const lastColon = localAddr.lastIndexOf(":");
+        if (lastColon === -1) continue;
+
+        const port = parseInt(localAddr.substring(lastColon + 1), 10);
+        const pid = parseInt(pidStr, 10);
+
+        if (isNaN(port) || isNaN(pid)) continue;
+
+        ports.push({
+          port,
+          pid,
+          protocol: "UDP",
+          state: "*",
+          localAddress: localAddr.substring(0, lastColon),
+          processName: getCachedProcessName(pid),
+        });
+      }
+    } catch {
+      // UDP scan failed — not critical
+    }
+
+    return deduplicatePorts(ports);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Unix: Parse ss or lsof output
+ */
+function getPortsUnix(): PortInfo[] {
+  try {
+    // Try ss first (faster, more modern)
+    const output = execSync("ss -tlnp 2>/dev/null || netstat -tlnp 2>/dev/null", {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: 10000,
+    });
+
+    const ports: PortInfo[] = [];
+    const lines = output.split("\n");
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("State") || trimmed.startsWith("Proto")) continue;
+
+      // ss format: LISTEN  0  128  0.0.0.0:8080  0.0.0.0:*  users:(("node",pid=1234,fd=18))
+      const pidMatch = trimmed.match(/pid=(\d+)/);
+      const addrMatch = trimmed.match(/\s([\d.*:[\]]+):(\d+)\s/);
+
+      if (addrMatch && pidMatch) {
+        const port = parseInt(addrMatch[2], 10);
+        const pid = parseInt(pidMatch[1], 10);
+
+        if (!isNaN(port) && !isNaN(pid)) {
+          ports.push({
+            port,
+            pid,
+            protocol: "TCP",
+            state: "LISTEN",
+            localAddress: addrMatch[1],
+            processName: getCachedProcessName(pid),
+          });
+        }
+      }
+    }
+
+    return deduplicatePorts(ports);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Remove duplicate port entries (keep LISTENING over ESTABLISHED)
+ */
+function deduplicatePorts(ports: PortInfo[]): PortInfo[] {
+  const seen = new Map<string, PortInfo>();
+  for (const p of ports) {
+    const key = `${p.protocol}:${p.port}:${p.pid}`;
+    const existing = seen.get(key);
+    if (!existing || (p.state === "LISTENING" && existing.state !== "LISTENING")) {
+      seen.set(key, p);
+    }
+  }
+  return Array.from(seen.values()).sort((a, b) => a.port - b.port);
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}