ports-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pate Bryant
+
+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,108 @@
+<h1 align="center">ports-cli</h1>
+
+<p align="center">
+  Interactive TUI for viewing and killing listening TCP ports on macOS and Linux.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ports-cli"><img src="https://img.shields.io/npm/v/ports-cli.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/ports-cli"><img src="https://img.shields.io/npm/dm/ports-cli.svg" alt="monthly downloads"></a>
+  <a href="https://github.com/patebryant/ports-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="node version"></a>
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg" alt="platform">
+  <img src="https://img.shields.io/badge/coverage-100%25-brightgreen.svg" alt="coverage">
+</p>
+
+---
+
+## Demo
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/patebryant/ports-cli/main/demo.gif" alt="ports-cli demo" width="800">
+</p>
+
+## Quick Start
+
+Run it directly with npx -- no install required:
+
+```sh
+npx ports-cli
+```
+
+Or install globally:
+
+```sh
+npm install -g ports-cli
+```
+
+Then run:
+
+```sh
+ports
+```
+
+## Features
+
+- **Real-time monitoring** -- port list auto-refreshes every 2 seconds
+- **Interactive search** -- filter by port number, address, PID, or process name
+- **Kill processes** -- terminate processes with a confirmation prompt, or skip it with `ctrl+k`
+- **Vim-style navigation** -- `j`/`k` to move, `g`/`G` to jump to first/last
+- **IPv6 normalization** -- `[::1]` maps to `127.0.0.1`, `[::]` maps to `0.0.0.0`, deduplicating entries
+- **Viewport scrolling** -- adapts to terminal height, keeps selection visible
+- **Help overlay** -- press `?` for a full keybinding reference
+- **Zero config** -- no flags, no setup, just run it
+
+## Keybindings
+
+| Key            | Action                                    |
+| -------------- | ----------------------------------------- |
+| `↑` / `k`      | Move selection up                         |
+| `↓` / `j`      | Move selection down                       |
+| `g` / `G`      | Jump to first / last                      |
+| `enter` / `x`  | Kill selected process (with confirmation) |
+| `ctrl+k`       | Kill selected process (skip confirmation) |
+| `/`            | Enter search mode                         |
+| `ESC`          | Clear search / cancel                     |
+| `r` / `R`      | Refresh port list                         |
+| `?`            | Toggle help overlay                       |
+| `q` / `ctrl+c` | Quit                                      |
+
+## Options
+
+```
+ports --help, -h       Show help
+ports --version, -v    Show version
+```
+
+## How It Works
+
+`ports-cli` runs `lsof -iTCP -sTCP:LISTEN -nP` to discover all processes listening on TCP ports. The raw output is parsed, deduplicated, and normalized (converting IPv6 loopback and wildcard addresses to their IPv4 equivalents). The result is rendered as a full-screen terminal UI using [Ink](https://github.com/vadimdemedes/ink), a React renderer for the terminal. The list refreshes automatically every 2 seconds. Killing a process sends `SIGKILL` to the target PID.
+
+## Requirements
+
+- **macOS or Linux** -- requires `lsof` (pre-installed on macOS; install via `apt install lsof` or `dnf install lsof` on Linux)
+- **Node.js >= 18**
+
+## Contributing
+
+```sh
+git clone https://github.com/patebryant/ports-cli.git
+cd ports-cli
+npm install
+```
+
+Development commands:
+
+```sh
+npm run build        # Compile to dist/ports.js
+npm run typecheck    # TypeScript type checking
+npm run lint         # ESLint
+npm test             # Run test suite (189 tests)
+npm run coverage     # Run tests with coverage report
+```
+
+Built with TypeScript, React 18, Ink 4, esbuild, and Vitest.
+
+## License
+
+[MIT](LICENSE)

package/dist/ports.js

@@ -0,0 +1,585 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/components/SearchBar.tsx
+import { Box, Text } from "ink";
+import { jsx, jsxs } from "react/jsx-runtime";
+function SearchBar({ value, isActive }) {
+  return /* @__PURE__ */ jsxs(Box, { borderStyle: "round", borderColor: isActive ? "cyan" : value ? "yellow" : "gray", paddingX: 1, children: [
+    /* @__PURE__ */ jsx(Text, { bold: true, color: "cyan", children: "ports" }),
+    /* @__PURE__ */ jsx(Text, { color: isActive ? "cyan" : value ? "yellow" : "gray", children: "  / " }),
+    isActive ? value ? /* @__PURE__ */ jsxs(Text, { children: [
+      value,
+      /* @__PURE__ */ jsx(Text, { color: "cyan", children: CURSOR_CHAR })
+    ] }) : /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+      "type to filter...",
+      /* @__PURE__ */ jsx(Text, { color: "cyan", children: CURSOR_CHAR })
+    ] }) : value ? /* @__PURE__ */ jsx(Text, { color: "yellow", children: value }) : /* @__PURE__ */ jsx(Text, { dimColor: true, children: "to search" })
+  ] });
+}
+var CURSOR_CHAR;
+var init_SearchBar = __esm({
+  "src/components/SearchBar.tsx"() {
+    "use strict";
+    CURSOR_CHAR = "\u2588";
+  }
+});
+
+// src/components/PortRow.tsx
+import { Box as Box2, Text as Text2 } from "ink";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function PortRow({ port, isSelected, colProcess }) {
+  const portStr = String(port.port).padEnd(COL_PORT);
+  const processStr = port.process.slice(0, colProcess).padEnd(colProcess);
+  const userStr = port.user.slice(0, COL_USER).padEnd(COL_USER);
+  const pidStr = String(port.pid).padEnd(COL_PID);
+  const addressStr = port.address;
+  if (isSelected) {
+    return /* @__PURE__ */ jsxs2(HighlightBox, { backgroundColor: "blue", children: [
+      /* @__PURE__ */ jsx2(Text2, { color: "cyan", children: SELECTION_ARROW }),
+      /* @__PURE__ */ jsx2(Text2, { color: "cyan", children: portStr }),
+      /* @__PURE__ */ jsx2(Text2, { color: "cyan", children: processStr }),
+      /* @__PURE__ */ jsx2(Text2, { color: "cyan", children: userStr }),
+      /* @__PURE__ */ jsx2(Text2, { color: "cyan", children: pidStr }),
+      /* @__PURE__ */ jsx2(Text2, { color: "cyan", children: addressStr })
+    ] });
+  }
+  return /* @__PURE__ */ jsxs2(Box2, { children: [
+    /* @__PURE__ */ jsx2(Text2, { children: UNSELECTED_PREFIX }),
+    /* @__PURE__ */ jsx2(Text2, { children: portStr }),
+    /* @__PURE__ */ jsx2(Text2, { children: processStr }),
+    /* @__PURE__ */ jsx2(Text2, { dimColor: true, children: userStr }),
+    /* @__PURE__ */ jsx2(Text2, { children: pidStr }),
+    /* @__PURE__ */ jsx2(Text2, { dimColor: true, children: addressStr })
+  ] });
+}
+var COL_PORT, COL_PID, COL_USER, SELECTION_ARROW, UNSELECTED_PREFIX, HighlightBox;
+var init_PortRow = __esm({
+  "src/components/PortRow.tsx"() {
+    "use strict";
+    COL_PORT = 8;
+    COL_PID = 8;
+    COL_USER = 14;
+    SELECTION_ARROW = "\u25B6 ";
+    UNSELECTED_PREFIX = "  ";
+    HighlightBox = Box2;
+  }
+});
+
+// src/components/PortList.tsx
+import { Box as Box3, Text as Text3, useStdout } from "ink";
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+function calculateProcessColWidth(terminalWidth) {
+  const reserved = ROW_PREFIX_WIDTH + COL_PORT + COL_USER + COL_PID + ADDRESS_COL_MIN_WIDTH;
+  const available = terminalWidth - reserved;
+  return Math.min(MAX_PROCESS_COL_WIDTH, Math.max(MIN_PROCESS_COL_WIDTH, available));
+}
+function PortList({ ports, selectedIndex }) {
+  const { stdout } = useStdout();
+  const colProcess = calculateProcessColWidth(stdout?.columns ?? DEFAULT_TERMINAL_WIDTH);
+  const terminalRows = stdout?.rows ?? 24;
+  const maxVisiblePorts = Math.max(1, terminalRows - TOTAL_UI_OVERHEAD);
+  let startIndex = 0;
+  let endIndex = ports.length;
+  if (ports.length > maxVisiblePorts) {
+    const halfWindow = Math.floor(maxVisiblePorts / 2);
+    startIndex = Math.max(0, selectedIndex - halfWindow);
+    endIndex = startIndex + maxVisiblePorts;
+    if (endIndex > ports.length) {
+      endIndex = ports.length;
+      startIndex = Math.max(0, endIndex - maxVisiblePorts);
+    }
+  }
+  const visiblePorts = ports.slice(startIndex, endIndex);
+  const portHeader = "PORT".padEnd(COL_PORT);
+  const processHeader = "PROCESS".padEnd(colProcess);
+  const userHeader = "USER".padEnd(COL_USER);
+  const pidHeader = "PID".padEnd(COL_PID);
+  return /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsxs3(Box3, { paddingX: 1, children: [
+      /* @__PURE__ */ jsx3(Text3, { children: UNSELECTED_PREFIX }),
+      /* @__PURE__ */ jsx3(Text3, { bold: true, color: "gray", children: portHeader }),
+      /* @__PURE__ */ jsx3(Text3, { bold: true, color: "gray", children: processHeader }),
+      /* @__PURE__ */ jsx3(Text3, { bold: true, color: "gray", children: userHeader }),
+      /* @__PURE__ */ jsx3(Text3, { bold: true, color: "gray", children: pidHeader }),
+      /* @__PURE__ */ jsx3(Text3, { bold: true, color: "gray", children: "ADDRESS" })
+    ] }),
+    ports.length === 0 ? (
+      // Empty state: shown when the filtered or unfiltered port list is empty.
+      // Zero ports could mean no servers are currently listening, OR that
+      // lsof exited without output (e.g. insufficient permissions). Keeping
+      // the message generic avoids a false "no servers running" claim.
+      /* @__PURE__ */ jsx3(Box3, { paddingX: 1, children: /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: "No listening ports found." }) })
+    ) : visiblePorts.map((port, i) => {
+      const actualIndex = startIndex + i;
+      return /* @__PURE__ */ jsx3(
+        PortRow,
+        {
+          port,
+          isSelected: actualIndex === selectedIndex,
+          colProcess
+        },
+        `${port.pid}-${port.port}-${port.address}`
+      );
+    })
+  ] });
+}
+var DEFAULT_TERMINAL_WIDTH, ROW_PREFIX_WIDTH, ADDRESS_COL_MIN_WIDTH, MIN_PROCESS_COL_WIDTH, MAX_PROCESS_COL_WIDTH, SEARCH_BAR_HEIGHT, HEADER_ROW_HEIGHT, STATUS_BAR_HEIGHT, BUFFER_HEIGHT, TOTAL_UI_OVERHEAD;
+var init_PortList = __esm({
+  "src/components/PortList.tsx"() {
+    "use strict";
+    init_PortRow();
+    DEFAULT_TERMINAL_WIDTH = 80;
+    ROW_PREFIX_WIDTH = 2;
+    ADDRESS_COL_MIN_WIDTH = 20;
+    MIN_PROCESS_COL_WIDTH = 16;
+    MAX_PROCESS_COL_WIDTH = 40;
+    SEARCH_BAR_HEIGHT = 3;
+    HEADER_ROW_HEIGHT = 1;
+    STATUS_BAR_HEIGHT = 1;
+    BUFFER_HEIGHT = 1;
+    TOTAL_UI_OVERHEAD = SEARCH_BAR_HEIGHT + HEADER_ROW_HEIGHT + STATUS_BAR_HEIGHT + BUFFER_HEIGHT;
+  }
+});
+
+// src/components/StatusBar.tsx
+import { Box as Box4, Text as Text4 } from "ink";
+import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+function StatusBar({ mode, confirmKill, killMessage, selectedPort }) {
+  if (confirmKill && selectedPort) {
+    return /* @__PURE__ */ jsxs4(Box4, { paddingX: 1, children: [
+      /* @__PURE__ */ jsx4(Text4, { color: "red", children: "Kill " }),
+      /* @__PURE__ */ jsx4(Text4, { bold: true, children: selectedPort.process }),
+      /* @__PURE__ */ jsxs4(Text4, { color: "red", children: [
+        ":",
+        selectedPort.port,
+        "?  "
+      ] }),
+      /* @__PURE__ */ jsx4(Text4, { color: "green", children: "y " }),
+      /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: "confirm  " }),
+      /* @__PURE__ */ jsx4(Text4, { color: "gray", children: "ESC " }),
+      /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: "cancel" })
+    ] });
+  }
+  const rightContent = killMessage ? /* @__PURE__ */ jsx4(Text4, { color: killMessage.type === "success" ? "green" : "red", children: killMessage.text }) : selectedPort ? /* @__PURE__ */ jsxs4(Text4, { dimColor: true, children: [
+    selectedPort.process,
+    ":",
+    selectedPort.port
+  ] }) : null;
+  const hints = mode === "search" ? /* @__PURE__ */ jsxs4(Text4, { dimColor: true, children: [
+    "type to filter  ",
+    /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "\u2191\u2193/j k" }),
+    " navigate  ",
+    /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "enter" }),
+    " done  ",
+    /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "ESC" }),
+    " clear"
+  ] }) : /* @__PURE__ */ jsxs4(Text4, { dimColor: true, children: [
+    /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "\u2191\u2193/j k" }),
+    " navigate  ",
+    /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "/" }),
+    " search  ",
+    /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "enter" }),
+    " kill  ",
+    /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "r" }),
+    " refresh  ",
+    /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "?" }),
+    " help  ",
+    /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "q" }),
+    " quit"
+  ] });
+  return (
+    // justifyContent="space-between" pins hints to the left edge and status
+    // content to the right edge, making both scannable without crowding.
+    /* @__PURE__ */ jsxs4(Box4, { justifyContent: "space-between", paddingX: 1, children: [
+      /* @__PURE__ */ jsx4(Box4, { children: hints }),
+      /* @__PURE__ */ jsx4(Box4, { children: rightContent })
+    ] })
+  );
+}
+var init_StatusBar = __esm({
+  "src/components/StatusBar.tsx"() {
+    "use strict";
+  }
+});
+
+// src/components/HelpOverlay.tsx
+import { Box as Box5, Text as Text5 } from "ink";
+import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
+function HelpOverlay() {
+  return /* @__PURE__ */ jsxs5(Box5, { borderStyle: "round", borderColor: "cyan", flexDirection: "column", paddingX: 2, paddingY: 1, children: [
+    /* @__PURE__ */ jsx5(Text5, { bold: true, color: "cyan", children: "  Keybindings" }),
+    /* @__PURE__ */ jsx5(Text5, { children: " " }),
+    KEYBINDINGS.map(({ key, desc }) => /* @__PURE__ */ jsxs5(Text5, { children: [
+      /* @__PURE__ */ jsx5(Text5, { color: "cyan", bold: true, children: key.padEnd(maxKeyLen) }),
+      "  ",
+      desc
+    ] }, key)),
+    /* @__PURE__ */ jsx5(Text5, { children: " " }),
+    /* @__PURE__ */ jsx5(Text5, { dimColor: true, children: "Press any key to close" })
+  ] });
+}
+var KEYBINDINGS, maxKeyLen;
+var init_HelpOverlay = __esm({
+  "src/components/HelpOverlay.tsx"() {
+    "use strict";
+    KEYBINDINGS = [
+      { key: "\u2191 / k", desc: "Move up" },
+      { key: "\u2193 / j", desc: "Move down" },
+      { key: "enter", desc: "Kill selected port (with confirm)" },
+      { key: "ctrl+k", desc: "Kill selected port (no confirm)" },
+      { key: "/ + type", desc: "Filter by name, port, or address" },
+      { key: "ESC", desc: "Clear filter / exit search" },
+      { key: "r / R", desc: "Refresh port list" },
+      { key: "?", desc: "Toggle this help" },
+      { key: "q", desc: "Quit" },
+      { key: "ctrl+c", desc: "Quit" }
+    ];
+    maxKeyLen = Math.max(...KEYBINDINGS.map((b) => b.key.length));
+  }
+});
+
+// src/utils/getPorts.ts
+import { execSync } from "child_process";
+function getPorts() {
+  try {
+    const output = execSync("lsof -nP -iTCP -sTCP:LISTEN +c 0 2>/dev/null", {
+      encoding: "utf8",
+      timeout: LSOF_TIMEOUT_MS
+    });
+    const lines = output.trim().split("\n");
+    const dataLines = lines.slice(1);
+    const seen = /* @__PURE__ */ new Set();
+    const ports = [];
+    for (const line of dataLines) {
+      if (!line.trim()) continue;
+      const parts = line.trim().split(/\s+/);
+      if (parts.length < 9) continue;
+      const processName = parts[0];
+      const pid = parts[1];
+      const user = parts[2];
+      const addrPort = parts[8];
+      const lastColon = addrPort.lastIndexOf(":");
+      if (lastColon === -1) continue;
+      const rawAddr = addrPort.slice(0, lastColon);
+      const port = parseInt(addrPort.slice(lastColon + 1), 10);
+      if (isNaN(port)) continue;
+      let address = rawAddr;
+      if (address === "*" || address === "0.0.0.0" || address === "[::]" || address === "::") {
+        address = "0.0.0.0";
+      }
+      if (address === "[::1]" || address === "::1") {
+        address = "127.0.0.1";
+      }
+      const key = `${address}:${port}:${pid}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      ports.push({
+        port,
+        process: processName,
+        pid,
+        user,
+        address
+      });
+    }
+    ports.sort((a, b) => a.port - b.port);
+    return ports;
+  } catch {
+    return [];
+  }
+}
+var LSOF_TIMEOUT_MS;
+var init_getPorts = __esm({
+  "src/utils/getPorts.ts"() {
+    "use strict";
+    LSOF_TIMEOUT_MS = 5e3;
+  }
+});
+
+// src/utils/killPort.ts
+import { execSync as execSync2 } from "child_process";
+function killPort(pid) {
+  try {
+    const safePid = parseInt(pid, 10);
+    if (isNaN(safePid) || safePid <= 0) {
+      return { success: false, error: "Invalid PID" };
+    }
+    execSync2(`kill -9 ${safePid}`);
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+var init_killPort = __esm({
+  "src/utils/killPort.ts"() {
+    "use strict";
+  }
+});
+
+// src/utils/clampIndex.ts
+function clampIndex(index, maxIndex) {
+  return Math.min(Math.max(0, index), Math.max(0, maxIndex));
+}
+var init_clampIndex = __esm({
+  "src/utils/clampIndex.ts"() {
+    "use strict";
+  }
+});
+
+// src/hooks/useKeyboardInput.ts
+import { useInput } from "ink";
+function useKeyboardInput(props) {
+  const {
+    mode,
+    showHelp,
+    confirmKill,
+    searchQuery,
+    selectedPort,
+    exit,
+    executeKill,
+    toggleHelp,
+    closeHelp,
+    setConfirmKill,
+    setMode,
+    setSearchQuery,
+    moveUp,
+    moveDown,
+    refresh
+  } = props;
+  useInput((input, key) => {
+    if (key.ctrl && input === "c") {
+      exit();
+      return;
+    }
+    if (key.ctrl && input === "k") {
+      executeKill();
+      return;
+    }
+    if (input === "?" && mode === "navigate" && !confirmKill) {
+      toggleHelp();
+      return;
+    }
+    if (showHelp) {
+      closeHelp();
+      return;
+    }
+    if (confirmKill) {
+      if (input === "y") {
+        executeKill();
+        setConfirmKill(false);
+      } else if (key.escape || input === "n") {
+        setConfirmKill(false);
+      }
+      return;
+    }
+    if (mode === "navigate") {
+      if (key.upArrow || input === "k") {
+        moveUp();
+        return;
+      }
+      if (key.downArrow || input === "j") {
+        moveDown();
+        return;
+      }
+      if (input === "/") {
+        setMode("search");
+        return;
+      }
+      if (key.return) {
+        if (selectedPort) setConfirmKill(true);
+        return;
+      }
+      if (input === "r" || input === "R") {
+        refresh();
+        return;
+      }
+      if (key.escape) {
+        if (searchQuery) setSearchQuery("");
+        return;
+      }
+      if (input === "q") {
+        exit();
+        return;
+      }
+      return;
+    }
+    if (mode === "search") {
+      if (key.escape) {
+        setSearchQuery("");
+        setMode("navigate");
+        return;
+      }
+      if (key.backspace || key.delete) {
+        setSearchQuery((q) => q.slice(0, -1));
+        return;
+      }
+      if (key.upArrow) {
+        moveUp();
+        return;
+      }
+      if (key.downArrow) {
+        moveDown();
+        return;
+      }
+      if (key.return) {
+        setMode("navigate");
+        return;
+      }
+      if (key.ctrl || key.meta) return;
+      if (input) {
+        setSearchQuery((q) => q + input);
+      }
+    }
+  });
+}
+var init_useKeyboardInput = __esm({
+  "src/hooks/useKeyboardInput.ts"() {
+    "use strict";
+  }
+});
+
+// src/app.tsx
+var app_exports = {};
+__export(app_exports, {
+  App: () => App
+});
+import { useState, useEffect, useRef } from "react";
+import { Box as Box6, useApp } from "ink";
+import { jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
+function App({ _killMessageTimeoutMs = KILL_MESSAGE_TIMEOUT_MS }) {
+  const { exit } = useApp();
+  const [ports, setPorts] = useState(() => getPorts());
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [searchQuery, setSearchQuery] = useState("");
+  const [killMessage, setKillMessage] = useState(null);
+  const [mode, setMode] = useState("navigate");
+  const [showHelp, setShowHelp] = useState(false);
+  const killRefreshTimerRef = useRef(null);
+  const [confirmKill, setConfirmKill] = useState(false);
+  const query = searchQuery.toLowerCase();
+  const filteredPorts = ports.filter(
+    (p) => !searchQuery || [p.process, String(p.port), p.address].some(
+      (v) => v.toLowerCase().includes(query)
+    )
+  );
+  const clampedIndex = clampIndex(selectedIndex, filteredPorts.length - 1);
+  const selectedPort = filteredPorts[clampedIndex] ?? null;
+  useEffect(() => {
+    if (selectedIndex !== clampedIndex) {
+      setSelectedIndex(clampedIndex);
+    }
+  }, [clampedIndex, selectedIndex]);
+  useEffect(() => {
+    if (!killMessage) return;
+    const timer = setTimeout(() => setKillMessage(null), _killMessageTimeoutMs);
+    return () => clearTimeout(timer);
+  }, [killMessage, _killMessageTimeoutMs]);
+  const refresh = () => setPorts(getPorts());
+  useEffect(() => {
+    const id = setInterval(refresh, AUTO_REFRESH_INTERVAL_MS);
+    return () => clearInterval(id);
+  }, []);
+  const executeKill = () => {
+    if (!selectedPort) return;
+    const result = killPort(selectedPort.pid);
+    setKillMessage(
+      result.success ? { type: "success", text: `Killed ${selectedPort.process} (${selectedPort.pid})` } : { type: "error", text: `Failed: ${result.error}` }
+    );
+    if (killRefreshTimerRef.current !== null) clearTimeout(killRefreshTimerRef.current);
+    killRefreshTimerRef.current = setTimeout(refresh, POST_KILL_REFRESH_DELAY_MS);
+  };
+  useEffect(() => () => {
+    if (killRefreshTimerRef.current !== null) clearTimeout(killRefreshTimerRef.current);
+  }, []);
+  const moveUp = () => {
+    setSelectedIndex((i) => clampIndex(i - 1, filteredPorts.length - 1));
+  };
+  const moveDown = () => {
+    setSelectedIndex((i) => clampIndex(i + 1, filteredPorts.length - 1));
+  };
+  useKeyboardInput({
+    mode,
+    showHelp,
+    confirmKill,
+    searchQuery,
+    selectedPort,
+    exit,
+    executeKill,
+    toggleHelp: () => setShowHelp((s) => !s),
+    closeHelp: () => setShowHelp(false),
+    setConfirmKill,
+    setMode,
+    setSearchQuery,
+    moveUp,
+    moveDown,
+    refresh
+  });
+  return /* @__PURE__ */ jsxs6(Box6, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx6(SearchBar, { value: searchQuery, isActive: mode === "search" }),
+    /* @__PURE__ */ jsx6(PortList, { ports: filteredPorts, selectedIndex: clampedIndex }),
+    /* @__PURE__ */ jsx6(StatusBar, { mode, confirmKill, killMessage, selectedPort }),
+    showHelp && /* @__PURE__ */ jsx6(HelpOverlay, {})
+  ] });
+}
+var AUTO_REFRESH_INTERVAL_MS, KILL_MESSAGE_TIMEOUT_MS, POST_KILL_REFRESH_DELAY_MS;
+var init_app = __esm({
+  "src/app.tsx"() {
+    "use strict";
+    init_SearchBar();
+    init_PortList();
+    init_StatusBar();
+    init_HelpOverlay();
+    init_getPorts();
+    init_killPort();
+    init_clampIndex();
+    init_useKeyboardInput();
+    AUTO_REFRESH_INTERVAL_MS = 2e3;
+    KILL_MESSAGE_TIMEOUT_MS = 2e3;
+    POST_KILL_REFRESH_DELAY_MS = 300;
+  }
+});
+
+// bin/ports.tsx
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { jsx as jsx7 } from "react/jsx-runtime";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+var version = pkg.version;
+var args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`ports-cli v${version}
+
+Interactive TUI for viewing and killing listening TCP ports on macOS and Linux.
+
+Usage:
+  ports [options]
+
+Options:
+  -h, --help     Show this help message
+  -v, --version  Show version number
+
+Keybindings:
+  j/k, Up/Down    Navigate ports
+  /               Search/filter
+  x               Kill selected port
+  ?               Toggle help overlay
+  q               Quit`);
+  process.exit(0);
+}
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(version);
+  process.exit(0);
+}
+var { render } = await import("ink");
+var { App: App2 } = await Promise.resolve().then(() => (init_app(), app_exports));
+render(/* @__PURE__ */ jsx7(App2, {}));

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "ports-cli",
+  "version": "1.0.0",
+  "description": "Interactive TUI for viewing and killing listening TCP ports",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/patebryant/ports-cli.git"
+  },
+  "author": "patebryant",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/patebryant/ports-cli/issues"
+  },
+  "homepage": "https://github.com/patebryant/ports-cli#readme",
+  "os": ["darwin", "linux"],
+  "bin": {
+    "ports": "./dist/ports.js",
+    "ports-cli": "./dist/ports.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "esbuild bin/ports.tsx --bundle --platform=node --target=node18 --format=esm --jsx=automatic --loader:.ts=ts --loader:.tsx=tsx --loader:.js=jsx --loader:.jsx=jsx --outfile=dist/ports.js --banner:js='#!/usr/bin/env node' --external:react --external:ink && chmod +x dist/ports.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/ bin/",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ports",
+    "lsof",
+    "cli",
+    "tui",
+    "network",
+    "kill",
+    "process",
+    "tcp",
+    "macos",
+    "linux",
+    "terminal",
+    "interactive",
+    "ink"
+  ],
+  "dependencies": {
+    "ink": "^4",
+    "react": "^18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
+    "@vitest/coverage-v8": "^4.0.18",
+    "esbuild": "^0.27.3",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "ink-testing-library": "^4.0.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^4.0.18"
+  }
+}