zport 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dogita
+
+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,99 @@
+# zport
+
+Kill processes running on specified ports. Fast, zero-dependency, cross-platform.
+
+## Why zport?
+
+Existing tools like `kill-port` shell out to `lsof -i -P` and parse the entire connection table with a loose regex — which means they miss processes, false-match adjacent port numbers, and fail silently on Linux when `lsof` isn't installed.
+
+**zport** fixes all of that:
+
+- **Linux** — uses `fuser` (fast, exact match) → falls back to `ss` → then `lsof`
+- **macOS** — uses `lsof -ti` with exact port + LISTEN filter
+- **Windows** — uses `netstat -ano` with exact port + LISTENING match → `taskkill`
+- **Zero dependencies** — just Node.js `child_process.execFile`, no shell spawning
+- **TypeScript** — fully typed, ships with declarations
+
+## Install
+
+```bash
+npm i -g zport
+```
+
+Or run directly without installing:
+
+```bash
+npx zport 3000
+bunx zport 3000
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Kill a single port
+zport 3000
+
+# Kill multiple ports
+zport 3000 3001 8080
+
+# Comma-separated
+zport 3000,3001,8080
+
+# UDP instead of TCP
+zport 5353 --method udp
+zport 5353 -m udp
+```
+
+Output:
+
+```
+✔ :3000 — killed pid 12345
+✔ :3001 — killed pids 12346, 12347
+✘ :8080 — No process on this port
+```
+
+### Programmatic
+
+```ts
+import { kill } from "zport";
+
+const result = await kill(3000);
+// { port: 3000, pids: [12345], killed: true }
+
+const result2 = await kill(9999);
+// { port: 9999, pids: [], killed: false, error: "No process on this port" }
+```
+
+#### `kill(port, method?)`
+
+| Param    | Type             | Default | Description            |
+| -------- | ---------------- | ------- | ---------------------- |
+| `port`   | `number`         | —       | Port number (1–65535)  |
+| `method` | `"tcp" \| "udp"` | `"tcp"` | Protocol to match      |
+
+Returns `Promise<KillResult>`:
+
+```ts
+interface KillResult {
+  port: number;
+  pids: number[];
+  killed: boolean;
+  error?: string;
+}
+```
+
+## How it works
+
+| OS      | Find PIDs                                      | Kill           |
+| ------- | ---------------------------------------------- | -------------- |
+| Linux   | `fuser {port}/tcp` → `ss -tlnp` → `lsof -ti`  | `SIGKILL`      |
+| macOS   | `lsof -iTCP:{port} -t -sTCP:LISTEN`            | `SIGKILL`      |
+| Windows | `netstat -ano` (exact port + LISTENING)         | `taskkill /F`  |
+
+On Linux, `fuser` is tried first because it directly queries the kernel's socket table — no parsing, no regex, no false matches. If `fuser` isn't available (minimal containers), it falls back to `ss`, then `lsof`.
+
+## License
+
+MIT

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { kill } from "./index.js";
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+    console.log(`
+  zport — kill processes on ports, fast
+
+  Usage
+    $ zport <port> [port ...]
+    $ zport 3000
+    $ zport 3000 3001 8080
+
+  Options
+    --method, -m   Protocol: tcp (default) or udp
+    --help, -h     Show this help
+    --version, -v  Show version
+`);
+    process.exit(0);
+}
+if (args.includes("--version") || args.includes("-v")) {
+    console.log("1.0.0");
+    process.exit(0);
+}
+let method = "tcp";
+const ports = [];
+for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--method" || arg === "-m") {
+        const next = args[++i];
+        if (next === "udp")
+            method = "udp";
+        continue;
+    }
+    if (arg.startsWith("-"))
+        continue;
+    // Support comma-separated: 3000,3001
+    for (const part of arg.split(",")) {
+        const n = parseInt(part, 10);
+        if (n > 0 && n <= 65535)
+            ports.push(n);
+    }
+}
+if (ports.length === 0) {
+    console.error("No valid ports provided");
+    process.exit(1);
+}
+const results = await Promise.all(ports.map((p) => kill(p, method)));
+let hasError = false;
+for (const r of results) {
+    if (r.killed) {
+        const pidStr = r.pids.length > 1 ? `pids ${r.pids.join(", ")}` : `pid ${r.pids[0]}`;
+        console.log(`✔ :${r.port} — killed ${pidStr}`);
+    }
+    else {
+        console.log(`✘ :${r.port} — ${r.error}`);
+        hasError = true;
+    }
+}
+process.exit(hasError && results.every((r) => !r.killed) ? 1 : 0);

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export interface KillResult {
+    port: number;
+    pids: number[];
+    killed: boolean;
+    error?: string;
+}
+export declare function kill(port: number, method?: "tcp" | "udp"): Promise<KillResult>;

package/dist/index.js

@@ -0,0 +1,176 @@
+import { execFile } from "node:child_process";
+function exec(cmd, args) {
+    return new Promise((resolve, reject) => {
+        execFile(cmd, args, { timeout: 5000 }, (err, stdout, stderr) => {
+            if (err) {
+                if ("stdout" in err) {
+                    resolve({ stdout: stdout || "", stderr: stderr || "" });
+                }
+                else {
+                    reject(err);
+                }
+            }
+            else {
+                resolve({ stdout: stdout || "", stderr: stderr || "" });
+            }
+        });
+    });
+}
+function parsePids(raw) {
+    const seen = new Set();
+    for (const token of raw.split(/[\s,]+/)) {
+        const n = parseInt(token, 10);
+        if (n > 0)
+            seen.add(n);
+    }
+    return [...seen];
+}
+async function findPidsLinux(port, method) {
+    // Try fuser first — fast, reliable, works even when lsof doesn't
+    try {
+        const proto = method === "udp" ? "udp" : "tcp";
+        const { stdout } = await exec("fuser", [`${port}/${proto}`]);
+        const pids = parsePids(stdout);
+        if (pids.length > 0)
+            return pids;
+    }
+    catch {
+        // fuser not available or no match, fall through
+    }
+    // Fallback: ss + awk to find pids from socket listing
+    try {
+        const flag = method === "udp" ? "-ulnp" : "-tlnp";
+        const { stdout } = await exec("ss", [flag, "sport", "=", `:${port}`]);
+        const pids = [];
+        const pidRegex = /pid=(\d+)/g;
+        let match;
+        while ((match = pidRegex.exec(stdout)) !== null) {
+            const n = parseInt(match[1], 10);
+            if (n > 0)
+                pids.push(n);
+        }
+        if (pids.length > 0)
+            return [...new Set(pids)];
+    }
+    catch {
+        // ss not available, fall through
+    }
+    // Last resort: lsof with exact port match
+    try {
+        const proto = method === "udp" ? "UDP" : "TCP";
+        const { stdout } = await exec("lsof", [
+            `-i${proto}:${port}`,
+            "-t",
+            "-sTCP:LISTEN",
+        ]);
+        return parsePids(stdout);
+    }
+    catch {
+        return [];
+    }
+}
+async function findPidsDarwin(port, method) {
+    try {
+        const proto = method === "udp" ? "UDP" : "TCP";
+        const { stdout } = await exec("lsof", [
+            `-i${proto}:${port}`,
+            "-t",
+            "-sTCP:LISTEN",
+        ]);
+        return parsePids(stdout);
+    }
+    catch {
+        return [];
+    }
+}
+async function findPidsWindows(port, method) {
+    try {
+        const { stdout } = await exec("netstat", ["-ano"]);
+        const proto = method === "udp" ? "UDP" : "TCP";
+        const pids = new Set();
+        for (const line of stdout.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed.startsWith(proto))
+                continue;
+            // Match exact port — columns: Proto LocalAddr ForeignAddr State PID
+            const parts = trimmed.split(/\s+/);
+            if (parts.length < 5)
+                continue;
+            const localAddr = parts[1];
+            const localPort = localAddr.split(":").pop();
+            if (localPort !== String(port))
+                continue;
+            const state = parts[3];
+            if (method === "tcp" && state !== "LISTENING")
+                continue;
+            const pid = parseInt(parts[parts.length - 1], 10);
+            if (pid > 0)
+                pids.add(pid);
+        }
+        return [...pids];
+    }
+    catch {
+        return [];
+    }
+}
+async function killPids(pids) {
+    if (pids.length === 0)
+        return;
+    if (process.platform === "win32") {
+        const args = pids.flatMap((pid) => ["/F", "/PID", String(pid)]);
+        await exec("taskkill", args);
+    }
+    else {
+        // SIGKILL — force kill, don't wait for graceful shutdown
+        for (const pid of pids) {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch {
+                // already dead, fine
+            }
+        }
+    }
+}
+export async function kill(port, method = "tcp") {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return { port, pids: [], killed: false, error: "Invalid port number" };
+    }
+    let pids;
+    try {
+        switch (process.platform) {
+            case "win32":
+                pids = await findPidsWindows(port, method);
+                break;
+            case "darwin":
+                pids = await findPidsDarwin(port, method);
+                break;
+            default:
+                pids = await findPidsLinux(port, method);
+                break;
+        }
+    }
+    catch {
+        return {
+            port,
+            pids: [],
+            killed: false,
+            error: "Failed to find processes",
+        };
+    }
+    if (pids.length === 0) {
+        return { port, pids: [], killed: false, error: "No process on this port" };
+    }
+    try {
+        await killPids(pids);
+        return { port, pids, killed: true };
+    }
+    catch {
+        return {
+            port,
+            pids,
+            killed: false,
+            error: "Failed to kill processes",
+        };
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "zport",
+  "version": "1.0.0",
+  "description": "Kill processes running on specified ports. Fast, zero-dependency, cross-platform.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "zport": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "port",
+    "kill",
+    "process",
+    "kill-port",
+    "free-port",
+    "zport",
+    "cli",
+    "cross-platform"
+  ],
+  "author": "Dogita",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/itorz7/zport.git"
+  },
+  "homepage": "https://github.com/itorz7/zport",
+  "bugs": "https://github.com/itorz7/zport/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "typescript": "^5.8.0"
+  }
+}