port-patrol 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 mifwar
+
+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,77 @@
+# Port Patrol
+
+[![npm](https://img.shields.io/npm/v/port-patrol)](https://www.npmjs.com/package/port-patrol)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+
+A terminal UI to inspect listening ports and terminate the owning process.
+
+Built with [Ink](https://github.com/vadimdemedes/ink) + [React](https://react.dev).
+
+## Features
+
+- **List all listening ports** with process info
+- **Search/filter** by port number or process name
+- **Kill processes** with optional force kill (SIGKILL)
+- **Sort** by port, PID, or process name
+- **Color-coded ports** (system < 1024, registered < 10000, dynamic)
+- **Cross-platform** (macOS, Linux, Windows)
+
+## Installation
+
+```bash
+# Run directly
+npx port-patrol
+
+# Or install globally
+npm install -g port-patrol
+pp
+```
+
+## Usage
+
+```bash
+# Open TUI
+pp
+
+# Quick search for port 3000
+pp 3000
+```
+
+### Keyboard Shortcuts
+
+| Key       | Action                    |
+| --------- | ------------------------- |
+| `j / ↓`   | Move down                 |
+| `k / ↑`   | Move up                   |
+| `g`       | Jump to top               |
+| `G`       | Jump to bottom            |
+| `/ or f`  | Search/filter             |
+| `Enter`   | Kill selected process     |
+| `K`       | Force kill (SIGKILL)      |
+| `r`       | Refresh list              |
+| `s`       | Toggle sort field         |
+| `o`       | Toggle sort order         |
+| `Esc`     | Clear search / Close      |
+| `?`       | Show help                 |
+| `q`       | Quit                      |
+
+### Port Colors
+
+- **Red** - System ports (< 1024) - usually need sudo to bind
+- **Yellow** - Registered ports (< 10000)
+- **Green** - Dynamic/private ports (>= 10000)
+
+## Development
+
+```bash
+npm install
+npm run dev
+
+# Build
+npm run build
+```
+
+## License
+
+MIT

package/dist/App.d.ts

@@ -0,0 +1,6 @@
+interface Props {
+    onExit: () => void;
+    initialPort?: number;
+}
+export declare function App({ onExit, initialPort }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/App.js

@@ -0,0 +1,276 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect, useCallback, useMemo, useReducer } from "react";
+import { Box, Text, useInput, useStdout } from "ink";
+import Fuse from "fuse.js";
+import { Header } from "./components/Header.js";
+import { ProcessList } from "./components/ProcessList.js";
+import { KillConfirm } from "./components/KillConfirm.js";
+import { SearchInput } from "./components/SearchInput.js";
+import { HelpModal } from "./components/HelpModal.js";
+import { ProcessDetails } from "./components/ProcessDetails.js";
+import { StatusBar } from "./components/StatusBar.js";
+import { getListeningPorts, getProcessDetails, killProcess } from "./utils/process.js";
+function uiReducer(state, action) {
+    switch (action.type) {
+        case "navigate": {
+            const { direction, listLength, maxVisible } = action;
+            if (listLength === 0)
+                return state;
+            const nextIndex = direction === "down"
+                ? Math.min(state.selectedIndex + 1, listLength - 1)
+                : Math.max(state.selectedIndex - 1, 0);
+            // Keep selected item visible with some padding
+            let nextScroll = state.scrollOffset;
+            if (nextIndex < nextScroll) {
+                nextScroll = nextIndex;
+            }
+            else if (nextIndex >= nextScroll + maxVisible) {
+                nextScroll = nextIndex - maxVisible + 1;
+            }
+            nextScroll = Math.max(0, Math.min(nextScroll, listLength - maxVisible));
+            return { ...state, selectedIndex: nextIndex, scrollOffset: nextScroll };
+        }
+        case "jumpTop":
+            return { ...state, selectedIndex: 0, scrollOffset: 0 };
+        case "jumpBottom": {
+            const { listLength, maxVisible } = action;
+            const lastIndex = Math.max(0, listLength - 1);
+            return {
+                ...state,
+                selectedIndex: lastIndex,
+                scrollOffset: Math.max(0, listLength - maxVisible)
+            };
+        }
+        case "setViewMode":
+            return { ...state, viewMode: action.mode };
+        case "setSearch":
+            return { ...state, searchQuery: action.query, selectedIndex: 0, scrollOffset: 0 };
+        case "appendSearch":
+            return {
+                ...state,
+                searchQuery: state.searchQuery + action.char,
+                selectedIndex: 0,
+                scrollOffset: 0
+            };
+        case "backspaceSearch":
+            return {
+                ...state,
+                searchQuery: state.searchQuery.slice(0, -1),
+                selectedIndex: 0,
+                scrollOffset: 0
+            };
+        case "clearSearch":
+            return { ...state, searchQuery: "", viewMode: "list", selectedIndex: 0, scrollOffset: 0 };
+        case "toggleSort": {
+            const fields = ["port", "pid", "name"];
+            const currentIdx = fields.indexOf(state.sortField);
+            const nextField = fields[(currentIdx + 1) % fields.length];
+            return { ...state, sortField: nextField, selectedIndex: 0, scrollOffset: 0 };
+        }
+        case "toggleSortOrder":
+            return {
+                ...state,
+                sortOrder: state.sortOrder === "asc" ? "desc" : "asc",
+                selectedIndex: 0,
+                scrollOffset: 0
+            };
+        case "reset":
+            return { ...state, selectedIndex: 0, scrollOffset: 0, viewMode: "list" };
+        default:
+            return state;
+    }
+}
+export function App({ onExit, initialPort }) {
+    const { stdout } = useStdout();
+    const width = stdout?.columns || 100;
+    const height = stdout?.rows || 24;
+    const [processes, setProcesses] = useState([]);
+    const [isLoading, setIsLoading] = useState(true);
+    const [message, setMessage] = useState(null);
+    const [ui, dispatch] = useReducer(uiReducer, {
+        selectedIndex: 0,
+        scrollOffset: 0,
+        viewMode: "list",
+        searchQuery: initialPort ? String(initialPort) : "",
+        sortField: "port",
+        sortOrder: "asc"
+    });
+    const headerHeight = ui.searchQuery || ui.viewMode === "search" ? 4 : 3;
+    const footerHeight = 2;
+    const listHeaderHeight = 2;
+    const modalHeight = ui.viewMode !== "list" && ui.viewMode !== "search" ? 12 : 0;
+    const refresh = useCallback(() => {
+        setIsLoading(true);
+        const ports = getListeningPorts();
+        setProcesses(ports);
+        setIsLoading(false);
+    }, []);
+    useEffect(() => {
+        refresh();
+    }, [refresh]);
+    const showMessage = useCallback((text, type = "info") => {
+        setMessage({ text, type });
+        setTimeout(() => setMessage(null), 3000);
+    }, []);
+    const fuse = useMemo(() => new Fuse(processes, {
+        keys: ["port", "processName", "command", "user", "cwd"],
+        threshold: 0.4,
+        ignoreLocation: true,
+        findAllMatches: true
+    }), [processes]);
+    const filteredProcesses = useMemo(() => {
+        let result = processes;
+        if (ui.searchQuery) {
+            // Check if it's a port number search
+            const portNum = parseInt(ui.searchQuery, 10);
+            if (!isNaN(portNum)) {
+                result = processes.filter((p) => String(p.port).includes(ui.searchQuery));
+            }
+            else {
+                result = fuse.search(ui.searchQuery).map((r) => r.item);
+            }
+        }
+        // Sort
+        result = [...result].sort((a, b) => {
+            let cmp = 0;
+            switch (ui.sortField) {
+                case "port":
+                    cmp = a.port - b.port;
+                    break;
+                case "pid":
+                    cmp = a.pid - b.pid;
+                    break;
+                case "name":
+                    cmp = a.processName.localeCompare(b.processName);
+                    break;
+            }
+            return ui.sortOrder === "asc" ? cmp : -cmp;
+        });
+        return result;
+    }, [processes, ui.searchQuery, ui.sortField, ui.sortOrder, fuse]);
+    const baseMaxVisible = Math.max(1, height - headerHeight - footerHeight - listHeaderHeight - modalHeight);
+    const showScrollIndicators = filteredProcesses.length > baseMaxVisible;
+    const maxVisible = Math.max(1, baseMaxVisible - (showScrollIndicators ? 2 : 0));
+    const selectedProcess = filteredProcesses[ui.selectedIndex];
+    const selectedDetails = useMemo(() => {
+        if (ui.viewMode !== "details" || !selectedProcess)
+            return "";
+        return getProcessDetails(selectedProcess.pid);
+    }, [ui.viewMode, selectedProcess?.pid]);
+    const handleKill = useCallback((force) => {
+        if (!selectedProcess)
+            return;
+        dispatch({ type: "setViewMode", mode: "list" });
+        const result = killProcess(selectedProcess.pid, force);
+        if (result.success) {
+            showMessage(`Killed process ${selectedProcess.pid} (port ${selectedProcess.port})`, "success");
+            setTimeout(refresh, 500);
+        }
+        else {
+            showMessage(result.error || "Failed to kill process", "error");
+        }
+    }, [selectedProcess, refresh, showMessage]);
+    useInput((input, key) => {
+        // Search mode input handling
+        if (ui.viewMode === "search") {
+            if (key.escape) {
+                if (ui.searchQuery) {
+                    dispatch({ type: "clearSearch" });
+                }
+                else {
+                    dispatch({ type: "setViewMode", mode: "list" });
+                }
+            }
+            else if (key.return) {
+                dispatch({ type: "setViewMode", mode: "list" });
+            }
+            else if (key.backspace || key.delete) {
+                dispatch({ type: "backspaceSearch" });
+            }
+            else if (input && input.length === 1 && !key.ctrl && !key.meta) {
+                dispatch({ type: "appendSearch", char: input });
+            }
+            return;
+        }
+        // Modal open - ignore other inputs
+        if (ui.viewMode === "kill" || ui.viewMode === "help" || ui.viewMode === "details")
+            return;
+        // Normal mode
+        if (input === "q" || (input === "c" && key.ctrl)) {
+            onExit();
+            return;
+        }
+        if (key.escape) {
+            if (ui.searchQuery) {
+                dispatch({ type: "clearSearch" });
+            }
+            return;
+        }
+        if (input === "/" || input === "f") {
+            dispatch({ type: "setViewMode", mode: "search" });
+            return;
+        }
+        if (input === "j" || key.downArrow) {
+            dispatch({
+                type: "navigate",
+                direction: "down",
+                listLength: filteredProcesses.length,
+                maxVisible
+            });
+        }
+        else if (input === "k" || key.upArrow) {
+            dispatch({
+                type: "navigate",
+                direction: "up",
+                listLength: filteredProcesses.length,
+                maxVisible
+            });
+        }
+        else if (input === "g") {
+            dispatch({ type: "jumpTop" });
+        }
+        else if (input === "G") {
+            dispatch({ type: "jumpBottom", listLength: filteredProcesses.length, maxVisible });
+        }
+        else if (key.return) {
+            if (selectedProcess) {
+                dispatch({ type: "setViewMode", mode: "kill" });
+            }
+        }
+        else if (input === "K") {
+            // Quick force kill
+            if (selectedProcess) {
+                const result = killProcess(selectedProcess.pid, true);
+                if (result.success) {
+                    showMessage(`Force killed ${selectedProcess.pid} (port ${selectedProcess.port})`, "success");
+                    setTimeout(refresh, 500);
+                }
+                else {
+                    showMessage(result.error || "Failed to kill", "error");
+                }
+            }
+        }
+        else if (input === "r") {
+            refresh();
+            showMessage("Refreshed", "success");
+        }
+        else if (input === "s") {
+            dispatch({ type: "toggleSort" });
+        }
+        else if (input === "o") {
+            dispatch({ type: "toggleSortOrder" });
+        }
+        else if (input === "?") {
+            dispatch({ type: "setViewMode", mode: "help" });
+        }
+        else if (input === "i") {
+            if (selectedProcess) {
+                dispatch({ type: "setViewMode", mode: "details" });
+            }
+        }
+    });
+    if (isLoading && processes.length === 0) {
+        return (_jsx(Box, { padding: 2, children: _jsx(Text, { color: "#60a5fa", children: "Scanning ports..." }) }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", width: width, height: height, children: [_jsx(Header, { totalPorts: filteredProcesses.length, filterQuery: ui.searchQuery }), ui.viewMode === "search" && _jsx(SearchInput, { value: ui.searchQuery }), _jsxs(Box, { flexGrow: 1, flexDirection: "column", marginTop: 1, children: [(ui.viewMode === "list" || ui.viewMode === "search") && (_jsx(ProcessList, { processes: filteredProcesses, selectedIndex: ui.selectedIndex, scrollOffset: ui.scrollOffset, maxVisible: maxVisible, showScrollIndicators: showScrollIndicators })), ui.viewMode === "kill" && selectedProcess && (_jsx(Box, { paddingX: 1, children: _jsx(KillConfirm, { process: selectedProcess, onConfirm: handleKill, onCancel: () => dispatch({ type: "setViewMode", mode: "list" }) }) })), ui.viewMode === "help" && (_jsx(Box, { paddingX: 1, children: _jsx(HelpModal, { onClose: () => dispatch({ type: "setViewMode", mode: "list" }) }) })), ui.viewMode === "details" && selectedProcess && (_jsx(Box, { paddingX: 1, children: _jsx(ProcessDetails, { process: selectedProcess, details: selectedDetails, onClose: () => dispatch({ type: "setViewMode", mode: "list" }) }) }))] }), _jsx(StatusBar, { message: message?.text, messageType: message?.type, sortField: ui.sortField, sortOrder: ui.sortOrder })] }));
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { run } from "./index.js";
+// Parse CLI args for quick port lookup
+const args = process.argv.slice(2);
+let initialPort;
+if (args.length > 0) {
+    const portArg = parseInt(args[0], 10);
+    if (!isNaN(portArg)) {
+        initialPort = portArg;
+    }
+}
+run(initialPort);

package/dist/components/Header.d.ts

@@ -0,0 +1,6 @@
+interface Props {
+    totalPorts: number;
+    filterQuery: string;
+}
+export declare function Header({ totalPorts, filterQuery }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Header.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+export function Header({ totalPorts, filterQuery }) {
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderBottom: true, borderTop: false, borderLeft: false, borderRight: false, borderColor: "#3b3b3b", paddingX: 1, children: [_jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { children: [_jsx(Text, { color: "#f87171", bold: true, children: "Port Patrol" }), _jsx(Text, { color: "#6b7280", children: " - Who's using my ports?" })] }), _jsxs(Text, { color: "#6b7280", children: [totalPorts, " listening ", totalPorts === 1 ? "port" : "ports"] })] }), filterQuery && (_jsxs(Box, { children: [_jsx(Text, { color: "#6b7280", children: "Filter: " }), _jsxs(Text, { color: "#fbbf24", children: ["\"", filterQuery, "\""] })] }))] }));
+}

package/dist/components/HelpModal.d.ts

@@ -0,0 +1,5 @@
+interface Props {
+    onClose: () => void;
+}
+export declare function HelpModal({ onClose }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/HelpModal.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text, useInput } from "ink";
+const KEYBINDINGS = [
+    { key: "j / ↓", action: "Move down" },
+    { key: "k / ↑", action: "Move up" },
+    { key: "g", action: "Jump to top" },
+    { key: "G", action: "Jump to bottom" },
+    { key: "/ or f", action: "Search/filter" },
+    { key: "Enter", action: "Kill selected process" },
+    { key: "i", action: "Show process details" },
+    { key: "K", action: "Force kill (SIGKILL)" },
+    { key: "r", action: "Refresh list" },
+    { key: "s", action: "Toggle sort (port/pid/name)" },
+    { key: "o", action: "Toggle sort order" },
+    { key: "Esc", action: "Clear search / Close modal" },
+    { key: "?", action: "Show this help" },
+    { key: "q", action: "Quit" }
+];
+export function HelpModal({ onClose }) {
+    useInput((input, key) => {
+        if (key.escape || input === "?" || input === "q") {
+            onClose();
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "#60a5fa", paddingX: 2, paddingY: 1, children: [_jsx(Text, { color: "#60a5fa", bold: true, children: "Keyboard Shortcuts" }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: KEYBINDINGS.map(({ key, action }) => (_jsxs(Box, { children: [_jsx(Box, { width: 14, children: _jsx(Text, { color: "#fbbf24", children: key }) }), _jsx(Text, { color: "#9ca3af", children: action })] }, key))) }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "#6b7280", dimColor: true, children: ["Port colors: ", _jsx(Text, { color: "#f87171", children: "system (<1024)" }), " ", _jsx(Text, { color: "#fbbf24", children: "registered (<10000)" }), " ", _jsx(Text, { color: "#22c55e", children: "dynamic (10000+)" })] }) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "#6b7280", dimColor: true, children: "Press ? or Esc to close" }) })] }));
+}

package/dist/components/KillConfirm.d.ts

@@ -0,0 +1,8 @@
+import type { PortProcess } from "../types/index.js";
+interface Props {
+    process: PortProcess;
+    onConfirm: (force: boolean) => void;
+    onCancel: () => void;
+}
+export declare function KillConfirm({ process, onConfirm, onCancel }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/KillConfirm.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Box, Text, useInput } from "ink";
+export function KillConfirm({ process, onConfirm, onCancel }) {
+    const [forceMode, setForceMode] = useState(false);
+    useInput((input, key) => {
+        if (key.escape || input === "n") {
+            onCancel();
+            return;
+        }
+        if (input === "y" || key.return) {
+            onConfirm(forceMode);
+        }
+        if (input === "f") {
+            setForceMode((v) => !v);
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "#f87171", paddingX: 2, paddingY: 1, children: [_jsx(Text, { color: "#f87171", bold: true, children: "Kill Process" }), _jsxs(Box, { marginTop: 1, flexDirection: "column", paddingLeft: 1, children: [_jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "Port: " }), _jsx(Text, { color: "#fbbf24", children: process.port })] }), _jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "PID: " }), _jsx(Text, { color: "#60a5fa", children: process.pid })] }), _jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "Process: " }), _jsx(Text, { children: process.processName })] }), process.command && (_jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "Command: " }), _jsx(Text, { dimColor: true, children: process.command.slice(0, 60) })] }))] }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "Force kill (SIGKILL): " }), _jsx(Text, { color: forceMode ? "#f87171" : "#22c55e", children: forceMode ? "YES" : "no" }), _jsx(Text, { color: "#6b7280", children: " (press f to toggle)" })] }) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "#6b7280", dimColor: true, children: "y/Enter confirm | n/Esc cancel | f toggle force" }) })] }));
+}

package/dist/components/ProcessDetails.d.ts

@@ -0,0 +1,8 @@
+import type { PortProcess } from "../types/index.js";
+interface Props {
+    process: PortProcess;
+    details: string;
+    onClose: () => void;
+}
+export declare function ProcessDetails({ process, details, onClose }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ProcessDetails.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text, useInput } from "ink";
+export function ProcessDetails({ process, details, onClose }) {
+    useInput((input, key) => {
+        if (key.escape || input === "i" || input === "q") {
+            onClose();
+        }
+    });
+    const detailLines = details ? details.split("\n") : [];
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "#22c55e", paddingX: 2, paddingY: 1, children: [_jsx(Text, { color: "#22c55e", bold: true, children: "Process Details" }), _jsxs(Box, { marginTop: 1, flexDirection: "column", paddingLeft: 1, children: [_jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "Port: " }), _jsx(Text, { color: "#fbbf24", children: process.port }), _jsxs(Text, { color: "#6b7280", children: [" (", process.protocol, ")"] })] }), _jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "PID: " }), _jsx(Text, { color: "#60a5fa", children: process.pid })] }), _jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "Process: " }), _jsx(Text, { children: process.processName })] }), process.user && (_jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "User: " }), _jsx(Text, { children: process.user })] })), _jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "Address: " }), _jsx(Text, { children: process.address })] }), process.command && (_jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "Command: " }), _jsx(Text, { dimColor: true, children: process.command })] })), process.cwd && (_jsxs(Text, { children: [_jsx(Text, { color: "#6b7280", children: "CWD: " }), _jsx(Text, { dimColor: true, children: process.cwd })] }))] }), detailLines.length > 0 && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "#6b7280", children: "ps output:" }), _jsx(Box, { marginTop: 1, flexDirection: "column", paddingLeft: 1, children: detailLines.map((line, idx) => (_jsx(Text, { dimColor: true, children: line }, `${process.pid}:${idx}`))) })] })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "#6b7280", dimColor: true, children: "Press i or Esc to close" }) })] }));
+}

package/dist/components/ProcessList.d.ts

@@ -0,0 +1,10 @@
+import type { PortProcess } from "../types/index.js";
+interface Props {
+    processes: PortProcess[];
+    selectedIndex: number;
+    scrollOffset: number;
+    maxVisible: number;
+    showScrollIndicators: boolean;
+}
+export declare function ProcessList({ processes, selectedIndex, scrollOffset, maxVisible, showScrollIndicators }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ProcessList.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+function truncate(str, len) {
+    if (str.length <= len)
+        return str;
+    return str.slice(0, len - 1) + "…";
+}
+function formatCwd(cwd) {
+    const home = process.env.HOME || "";
+    if (cwd.startsWith(home)) {
+        return "~" + cwd.slice(home.length);
+    }
+    return cwd;
+}
+function getDisplayCommand(proc) {
+    // For node/interpreters, show cwd (project path) if available
+    if (proc.cwd) {
+        return formatCwd(proc.cwd);
+    }
+    // Otherwise show the command
+    return proc.command || proc.processName;
+}
+function ProcessRow({ proc, isSelected }) {
+    const portColor = proc.port < 1024 ? "#f87171" : proc.port < 10000 ? "#fbbf24" : "#22c55e";
+    const displayCmd = getDisplayCommand(proc);
+    const colGap = 1;
+    return (_jsxs(Box, { paddingX: 1, children: [_jsx(Box, { width: 2, marginRight: colGap, children: _jsx(Text, { color: isSelected ? "#fbbf24" : "#6b7280", children: isSelected ? "▸" : " " }) }), _jsx(Box, { width: 7, marginRight: colGap, children: _jsx(Text, { color: portColor, bold: isSelected, children: proc.port }) }), _jsx(Box, { width: 5, marginRight: colGap, children: _jsx(Text, { color: "#6b7280", children: proc.protocol }) }), _jsx(Box, { width: 8, marginRight: colGap, children: _jsx(Text, { color: isSelected ? "#9ca3af" : "#6b7280", children: proc.pid }) }), _jsx(Box, { width: 20, marginRight: colGap, children: _jsx(Text, { color: "#60a5fa", bold: isSelected, children: truncate(proc.processName, 19) }) }), _jsx(Box, { width: 9, marginRight: colGap, children: _jsx(Text, { color: "#6b7280", children: truncate(proc.user || "-", 8) }) }), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { color: isSelected ? "#22c55e" : "#6b7280", dimColor: !isSelected, children: proc.cwd ? truncate(displayCmd, 60) : truncate(displayCmd, 50) }) })] }));
+}
+export function ProcessList({ processes, selectedIndex, scrollOffset, maxVisible, showScrollIndicators }) {
+    const colGap = 1;
+    const visible = processes.slice(scrollOffset, scrollOffset + maxVisible);
+    const showScrollUp = scrollOffset > 0;
+    const showScrollDown = scrollOffset + maxVisible < processes.length;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { paddingX: 1, marginBottom: 1, children: [_jsx(Box, { width: 2, marginRight: colGap, children: _jsx(Text, { children: " " }) }), _jsx(Box, { width: 7, marginRight: colGap, children: _jsx(Text, { color: "#6b7280", bold: true, children: "PORT" }) }), _jsx(Box, { width: 5, marginRight: colGap, children: _jsx(Text, { color: "#6b7280", bold: true, children: "PROTO" }) }), _jsx(Box, { width: 8, marginRight: colGap, children: _jsx(Text, { color: "#6b7280", bold: true, children: "PID" }) }), _jsx(Box, { width: 20, marginRight: colGap, children: _jsx(Text, { color: "#6b7280", bold: true, children: "NAME" }) }), _jsx(Box, { width: 9, marginRight: colGap, children: _jsx(Text, { color: "#6b7280", bold: true, children: "USER" }) }), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { color: "#6b7280", bold: true, children: "COMMAND" }) })] }), showScrollIndicators && (_jsx(Box, { paddingX: 1, children: _jsx(Text, { color: "#6b7280", children: showScrollUp ? `↑ ${scrollOffset} more above` : " " }) })), visible.map((proc, i) => (_jsx(ProcessRow, { proc: proc, isSelected: scrollOffset + i === selectedIndex }, `${proc.pid}:${proc.port}:${proc.protocol}`))), showScrollIndicators && (_jsx(Box, { paddingX: 1, children: _jsx(Text, { color: "#6b7280", children: showScrollDown
+                        ? `↓ ${processes.length - scrollOffset - maxVisible} more below`
+                        : " " }) })), processes.length === 0 && (_jsx(Box, { paddingX: 1, children: _jsx(Text, { color: "#6b7280", children: "No listening ports found" }) }))] }));
+}

package/dist/components/SearchInput.d.ts

@@ -0,0 +1,6 @@
+interface Props {
+    value: string;
+    placeholder?: string;
+}
+export declare function SearchInput({ value, placeholder }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/SearchInput.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+export function SearchInput({ value, placeholder = "Search by port or process name..." }) {
+    return (_jsxs(Box, { paddingX: 1, borderStyle: "single", borderBottom: true, borderTop: false, borderLeft: false, borderRight: false, borderColor: "#3b3b3b", children: [_jsx(Text, { color: "#60a5fa", children: "/" }), _jsx(Text, { color: "#6b7280", children: " " }), value ? (_jsx(Text, { color: "#e5e7eb", children: value })) : (_jsx(Text, { color: "#6b7280", dimColor: true, children: placeholder })), _jsx(Text, { color: "#60a5fa", children: "\u258B" })] }));
+}

package/dist/components/StatusBar.d.ts

@@ -0,0 +1,9 @@
+import type { SortField, SortOrder } from "../types/index.js";
+interface Props {
+    message?: string | null;
+    messageType?: "info" | "success" | "error";
+    sortField: SortField;
+    sortOrder: SortOrder;
+}
+export declare function StatusBar({ message, messageType, sortField, sortOrder }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/StatusBar.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+export function StatusBar({ message, messageType = "info", sortField, sortOrder }) {
+    const messageColor = messageType === "success" ? "#22c55e" : messageType === "error" ? "#f87171" : "#60a5fa";
+    const sortLabel = `${sortField} ${sortOrder === "asc" ? "↑" : "↓"}`;
+    return (_jsxs(Box, { borderStyle: "single", borderTop: true, borderBottom: false, borderLeft: false, borderRight: false, borderColor: "#3b3b3b", paddingX: 1, justifyContent: "space-between", children: [_jsx(Text, { color: "#6b7280", children: "j/k: nav | /: search | Enter: kill | i: details | r: refresh | s: sort | ?: help | q: quit" }), _jsx(Box, { children: message ? (_jsx(Text, { color: messageColor, children: message })) : (_jsxs(Text, { color: "#6b7280", children: ["sort: ", sortLabel] })) })] }));
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function run(initialPort?: number): void;

package/dist/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from "ink";
+import { App } from "./App.js";
+export function run(initialPort) {
+    const { unmount, waitUntilExit } = render(_jsx(App, { onExit: () => {
+            unmount();
+            process.exit(0);
+        }, initialPort: initialPort }));
+    waitUntilExit().catch(() => { });
+}

package/dist/types/index.d.ts

@@ -0,0 +1,14 @@
+export interface PortProcess {
+    pid: number;
+    port: number;
+    protocol: "TCP" | "UDP" | "BOTH";
+    state: string;
+    address: string;
+    processName: string;
+    command?: string;
+    user?: string;
+    cwd?: string;
+}
+export type ViewMode = "list" | "kill" | "help" | "search" | "details";
+export type SortField = "port" | "pid" | "name";
+export type SortOrder = "asc" | "desc";

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/process.d.ts

@@ -0,0 +1,8 @@
+import type { PortProcess } from "../types/index.js";
+export declare function getListeningPorts(): PortProcess[];
+export declare function killProcess(pid: number, force?: boolean): {
+    success: boolean;
+    error?: string;
+};
+export declare function findProcessByPort(port: number): PortProcess | undefined;
+export declare function getProcessDetails(pid: number): string;

package/dist/utils/process.js

@@ -0,0 +1,207 @@
+import { execSync } from "child_process";
+function run(cmd) {
+    try {
+        return execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function getProcessCwd(pid) {
+    // macOS: use lsof to get cwd
+    const output = run(`lsof -p ${pid} 2>/dev/null | grep cwd`);
+    if (output) {
+        const parts = output.split(/\s+/);
+        // cwd line format: COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
+        const cwdPath = parts.slice(8).join(" ");
+        if (cwdPath && cwdPath !== "/") {
+            return cwdPath;
+        }
+    }
+    return undefined;
+}
+function normalizeProcessName(name) {
+    return name.replace(/\\x20/g, " ");
+}
+export function getListeningPorts() {
+    const platform = process.platform;
+    if (platform === "darwin" || platform === "linux") {
+        return getPortsUnix();
+    }
+    else if (platform === "win32") {
+        return getPortsWindows();
+    }
+    return [];
+}
+function getPortsUnix() {
+    const output = run("lsof -i -P -n -sTCP:LISTEN +c 0 2>/dev/null");
+    if (!output)
+        return [];
+    const lines = output.split("\n").slice(1); // Skip header
+    const processes = [];
+    const seen = new Set();
+    for (const line of lines) {
+        const parts = line.split(/\s+/);
+        if (parts.length < 9)
+            continue;
+        const [rawProcessName, pidStr, user, , , , , , addressPort] = parts;
+        const processName = normalizeProcessName(rawProcessName);
+        const pid = parseInt(pidStr, 10);
+        // Parse address:port
+        const lastColon = addressPort.lastIndexOf(":");
+        if (lastColon === -1)
+            continue;
+        const address = addressPort.slice(0, lastColon);
+        const port = parseInt(addressPort.slice(lastColon + 1), 10);
+        if (isNaN(port))
+            continue;
+        const key = `${pid}:${port}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        // Get full command
+        const command = run(`ps -p ${pid} -o command= 2>/dev/null`);
+        // Get cwd for interpreters (node, python, ruby, etc.) to show project path
+        let cwd;
+        const interpreters = ["node", "python", "ruby", "php", "java", "deno", "bun"];
+        if (interpreters.some((i) => processName.toLowerCase().includes(i))) {
+            cwd = getProcessCwd(pid);
+        }
+        processes.push({
+            pid,
+            port,
+            protocol: "TCP",
+            state: "LISTEN",
+            address: address === "*" ? "0.0.0.0" : address,
+            processName,
+            command: command || processName,
+            user,
+            cwd
+        });
+    }
+    // Also get UDP
+    const udpOutput = run("lsof -i UDP -P -n +c 0 2>/dev/null");
+    if (udpOutput) {
+        const udpLines = udpOutput.split("\n").slice(1);
+        for (const line of udpLines) {
+            const parts = line.split(/\s+/);
+            if (parts.length < 9)
+                continue;
+            const [rawProcessName, pidStr, user, , , , , , addressPort] = parts;
+            const processName = normalizeProcessName(rawProcessName);
+            const pid = parseInt(pidStr, 10);
+            const lastColon = addressPort.lastIndexOf(":");
+            if (lastColon === -1)
+                continue;
+            const address = addressPort.slice(0, lastColon);
+            const port = parseInt(addressPort.slice(lastColon + 1), 10);
+            if (isNaN(port))
+                continue;
+            const key = `${pid}:${port}:udp`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const command = run(`ps -p ${pid} -o command= 2>/dev/null`).slice(0, 100);
+            processes.push({
+                pid,
+                port,
+                protocol: "UDP",
+                state: "OPEN",
+                address: address === "*" ? "0.0.0.0" : address,
+                processName,
+                command: command || processName,
+                user
+            });
+        }
+    }
+    // Merge TCP and UDP entries for same port+pid
+    const merged = new Map();
+    for (const proc of processes) {
+        const key = `${proc.port}:${proc.pid}`;
+        const existing = merged.get(key);
+        if (existing) {
+            if (existing.protocol !== proc.protocol) {
+                existing.protocol = "BOTH";
+            }
+        }
+        else {
+            merged.set(key, { ...proc });
+        }
+    }
+    return Array.from(merged.values()).sort((a, b) => a.port - b.port);
+}
+function getPortsWindows() {
+    const output = run("netstat -ano -p TCP");
+    if (!output)
+        return [];
+    const lines = output.split("\n").slice(4); // Skip headers
+    const processes = [];
+    const seen = new Set();
+    for (const line of lines) {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length < 5)
+            continue;
+        const [, localAddress, , state, pidStr] = parts;
+        if (state !== "LISTENING")
+            continue;
+        const lastColon = localAddress.lastIndexOf(":");
+        if (lastColon === -1)
+            continue;
+        const address = localAddress.slice(0, lastColon);
+        const port = parseInt(localAddress.slice(lastColon + 1), 10);
+        const pid = parseInt(pidStr, 10);
+        if (isNaN(port) || isNaN(pid))
+            continue;
+        const key = `${pid}:${port}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        // Get process name
+        const tasklistOutput = run(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`);
+        const processName = tasklistOutput.split(",")[0]?.replace(/"/g, "") || "unknown";
+        processes.push({
+            pid,
+            port,
+            protocol: "TCP",
+            state: "LISTENING",
+            address,
+            processName,
+            command: processName
+        });
+    }
+    return processes.sort((a, b) => a.port - b.port);
+}
+export function killProcess(pid, force = false) {
+    try {
+        const platform = process.platform;
+        let cmd;
+        if (platform === "win32") {
+            cmd = force ? `taskkill /PID ${pid} /F` : `taskkill /PID ${pid}`;
+        }
+        else {
+            cmd = force ? `kill -9 ${pid}` : `kill ${pid}`;
+        }
+        execSync(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+        return { success: true };
+    }
+    catch (err) {
+        const error = err;
+        return { success: false, error: error.message };
+    }
+}
+export function findProcessByPort(port) {
+    const processes = getListeningPorts();
+    return processes.find((p) => p.port === port);
+}
+export function getProcessDetails(pid) {
+    const platform = process.platform;
+    if (platform === "darwin" || platform === "linux") {
+        const info = run(`ps -p ${pid} -o pid,ppid,user,%cpu,%mem,etime,command 2>/dev/null`);
+        return info || "Process not found";
+    }
+    else if (platform === "win32") {
+        const info = run(`tasklist /FI "PID eq ${pid}" /V /FO LIST`);
+        return info || "Process not found";
+    }
+    return "Unsupported platform";
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "port-patrol",
+  "version": "1.0.0",
+  "description": "TUI to inspect listening ports and terminate the owning process.",
+  "type": "module",
+  "license": "MIT",
+  "author": "mifwar",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mifwar/port-patrol.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mifwar/port-patrol/issues"
+  },
+  "homepage": "https://github.com/mifwar/port-patrol#readme",
+  "keywords": [
+    "tui",
+    "terminal",
+    "ports",
+    "network",
+    "process",
+    "cli",
+    "ink"
+  ],
+  "bin": {
+    "port-patrol": "dist/cli.js",
+    "pp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "npx tsx src/cli.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "postbuild": "chmod +x dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check"
+  },
+  "dependencies": {
+    "fuse.js": "^7.0.0",
+    "ink": "^5.1.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.0",
+    "prettier": "^3.3.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}