port-reclaim 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 port-reclaim contributors
+
+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,72 @@
+# port-reclaim
+
+A zero-configuration, cross-platform CLI for safely reclaiming ports held by stale local development processes.
+
+## Install
+
+Run it once without installing:
+
+```sh
+npx port-reclaim 3000
+```
+
+Or install it globally:
+
+```sh
+npm install --global port-reclaim
+port-reclaim 3000
+```
+
+Requires Node.js 18 or newer. Supports macOS, Linux, Windows, WSL, PowerShell, and CMD.
+
+## How It Works
+
+```sh
+port-reclaim <PORT>
+```
+
+If the port is free, the command exits successfully. If the process working directory matches the current project, the process is terminated automatically. Processes from another directory, system services, and processes whose working directory cannot be read require explicit confirmation.
+
+The command uses a graceful termination signal first on Unix-like systems and falls back to a forceful signal if the process remains alive. Windows uses `taskkill`.
+
+If confirmation is required in a non-interactive environment, the command declines safely and exits with status `1`.
+
+## Script Integration
+
+Use it in a package script:
+
+```json
+{
+  "scripts": {
+    "dev": "port-reclaim 3000 && next dev"
+  }
+}
+```
+
+The same command can be used from Python, Ruby, Go, Make, or shell scripts.
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The port was free or was successfully released. |
+| `1` | The port is still in use, the user declined, or an operation failed. |
+| `2` | Invalid command-line input. |
+
+## Security Notes
+
+`port-reclaim` only acts on processes listening on the port you provide. It does not scan remote hosts or kill Docker containers directly. Review the process name and working directory before confirming a process from another project.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run build
+```
+
+Pull requests are tested on Ubuntu, macOS, and Windows with Node.js 18, 20, and 22.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/src/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import readline from "node:readline/promises";
+import process from "node:process";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createProcessRunner } from "./process.js";
+function usage() {
+    console.error("Usage: port-reclaim <PORT>");
+    process.exit(2);
+}
+function parsePort(value) {
+    if (!value || !/^\d+$/.test(value))
+        usage();
+    const port = Number(value);
+    if (port < 1 || port > 65535)
+        usage();
+    return port;
+}
+function sameDirectory(left, right) {
+    if (!left)
+        return false;
+    const normalizedLeft = path.normalize(path.resolve(left));
+    const normalizedRight = path.normalize(path.resolve(right));
+    return process.platform === "win32" ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase() : normalizedLeft === normalizedRight;
+}
+async function confirm(portProcess, port) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error(`Port ${port} is used by '${portProcess.name}'${portProcess.cwd ? ` in '${portProcess.cwd}'` : ""}. Use an interactive terminal to confirm termination.`);
+        return false;
+    }
+    const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await prompt.question(`Port ${port} is used by '${portProcess.name}'${portProcess.cwd ? ` in '${portProcess.cwd}'` : ""}. Kill it? (y/N) `);
+    prompt.close();
+    return /^y(es)?$/i.test(answer.trim());
+}
+export async function main(runner = createProcessRunner()) {
+    const port = parsePort(process.argv[2]);
+    const processes = await runner.discover(port);
+    if (processes.length === 0)
+        return 0;
+    const currentDirectory = process.cwd();
+    for (const portProcess of processes) {
+        const shouldTerminate = sameDirectory(portProcess.cwd, currentDirectory) || await confirm(portProcess, port);
+        if (!shouldTerminate)
+            return 1;
+        await runner.terminate(portProcess.pid);
+        console.log(`Released port ${port} from ${portProcess.name} (PID ${portProcess.pid}).`);
+    }
+    return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().then((code) => process.exit(code)).catch((error) => {
+        console.error(`port-reclaim: ${error.message}`);
+        process.exit(1);
+    });
+}

package/dist/src/process.js

@@ -0,0 +1,78 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import process from "node:process";
+import pidCwd from "pid-cwd";
+const execFileAsync = promisify(execFile);
+function parsePidList(output) {
+    return [...new Set(output.split(/\r?\n/).map((line) => Number(line.trim())).filter((pid) => Number.isInteger(pid) && pid > 0))];
+}
+export function parseWindowsPids(output) {
+    return parsePidList(output);
+}
+export function parseUnixLsof(output) {
+    return [...new Set([...output.matchAll(/^p(\d+)$/gm)].map((match) => Number(match[1])))];
+}
+async function run(command, args) {
+    try {
+        const result = await execFileAsync(command, args, { windowsHide: true, maxBuffer: 1024 * 1024 });
+        return result.stdout;
+    }
+    catch (error) {
+        const processError = error;
+        if (processError.stdout)
+            return processError.stdout;
+        if (processError.code === "ENOENT") {
+            throw new Error(`Required system command '${command}' was not found.`);
+        }
+        return "";
+    }
+}
+async function windowsPids(port) {
+    const script = `$ErrorActionPreference = 'SilentlyContinue'; Get-NetTCPConnection -LocalPort ${port} -State Listen | Select-Object -ExpandProperty OwningProcess`;
+    const output = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script]);
+    if (output.trim())
+        return parseWindowsPids(output);
+    const netstat = await run("netstat.exe", ["-ano", "-p", "TCP"]);
+    return parseWindowsPids(netstat.split(/\r?\n/).filter((line) => {
+        const columns = line.trim().split(/\s+/);
+        return columns[0]?.toUpperCase() === "TCP" && columns[1]?.endsWith(`:${port}`) && columns[3]?.toUpperCase() === "LISTENING";
+    }).map((line) => line.trim().split(/\s+/).at(-1)).join("\n"));
+}
+async function unixPids(port) {
+    const output = await run("lsof", ["-nP", "-a", "-iTCP:" + port, "-sTCP:LISTEN", "-Fp"]);
+    return parseUnixLsof(output);
+}
+async function processName(pid) {
+    if (process.platform === "win32") {
+        const output = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `(Get-Process -Id ${pid}).ProcessName`]);
+        return output.trim() || "unknown";
+    }
+    const output = await run("ps", ["-p", String(pid), "-o", "comm="]);
+    return output.trim() || "unknown";
+}
+async function processCwd(pid) {
+    return (await pidCwd(pid)) ?? undefined;
+}
+export function createProcessRunner() {
+    return {
+        async discover(port) {
+            const pids = process.platform === "win32" ? await windowsPids(port) : await unixPids(port);
+            return Promise.all(pids.map(async (pid) => ({ pid, name: await processName(pid), cwd: await processCwd(pid) })));
+        },
+        async terminate(pid) {
+            if (process.platform === "win32") {
+                await run("taskkill.exe", ["/PID", String(pid), "/T"]);
+                return;
+            }
+            process.kill(pid, "SIGTERM");
+            await new Promise((resolve) => setTimeout(resolve, 250));
+            try {
+                process.kill(pid, 0);
+                process.kill(pid, "SIGKILL");
+            }
+            catch {
+                // The process exited after SIGTERM.
+            }
+        }
+    };
+}

package/dist/tests/process.test.js

@@ -0,0 +1,9 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseUnixLsof, parseWindowsPids } from "../src/process.js";
+test("parses unique Windows PIDs", () => {
+    assert.deepEqual(parseWindowsPids("1234\r\n5678\r\n1234\r\n"), [1234, 5678]);
+});
+test("parses lsof PID records", () => {
+    assert.deepEqual(parseUnixLsof("p1234\ncnode\np5678\np1234\n"), [1234, 5678]);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "port-reclaim",
+  "version": "0.1.0",
+  "description": "Safely reclaim local ports from stale development processes.",
+  "author": "princegoel0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/princegoel0/port-reclaim.git"
+  },
+  "bugs": {
+    "url": "https://github.com/princegoel0/port-reclaim/issues"
+  },
+  "homepage": "https://github.com/princegoel0/port-reclaim#readme",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "port-reclaim": "dist/src/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test dist/tests/process.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "cli",
+    "port",
+    "process",
+    "developer-tools",
+    "cross-platform"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "pid-cwd": "^1.2.0"
+  }
+}