port-reclaim 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +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.
+MIT License
+
+Copyright (c) 2026 Prince Goel
+
+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

@@ -1,72 +1,134 @@
-# 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).
+# 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> [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. Confirmation prompts show the process name, working directory, and uptime.
+
+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 /F`.
+
+If confirmation is required in a non-interactive environment, the command declines safely and exits with status `1` (rerun with `--yes` to override).
+
+Ports held by Docker processes (for example `docker-proxy` or Docker Desktop) are never killed. The tool explains that the port looks like Docker and suggests stopping the container instead.
+
+Both TCP and UDP listeners are discovered.
+
+### Options
+
+| Flag | Meaning |
+| --- | --- |
+| `-l`, `--list` | Report what is using each port without killing anything. |
+| `-y`, `--yes` | Terminate processes from other directories without prompting. |
+| `-h`, `--help` | Show the help message. |
+| `-v`, `--version` | Show the installed version. |
+
+## Configuration
+
+Ports can be declared once so scripts can run plain `port-reclaim` with no arguments. Add a `port-reclaim` key to `package.json`:
+
+```json
+{
+  "port-reclaim": {
+    "ports": [3000, 5173],
+    "ignore": [5432]
+  }
+}
+```
+
+Ports in `ignore` are skipped with a notice. A `.reclaimignore` file in the project root protects ports the same way — one port per line, `#` starts a comment:
+
+```text
+# databases
+5432
+6379
+```
+
+## Script Integration
+
+Use it in a package script:
+
+```json
+{
+  "scripts": {
+    "dev": "port-reclaim 3000 && next dev"
+  }
+}
+```
+
+Or rely on configured ports:
+
+```json
+{
+  "scripts": {
+    "dev": "port-reclaim && next dev"
+  },
+  "port-reclaim": { "ports": [3000] }
+}
+```
+
+The same command can be used from Python, Ruby, Go, Make, or shell scripts.
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The port was free, listed with `--list`, or successfully released. |
+| `1` | The port is still in use, the user declined, or an operation failed. |
+| `2` | Invalid command-line input. |
+
+## Programmatic Use
+
+The process runner is exported for use in other tools:
+
+```js
+import { createProcessRunner } from "port-reclaim";
+
+const runner = createProcessRunner();
+const found = await runner.discover(3000);
+for (const process of found) {
+  console.log(process.name, process.cwd, process.ageMs);
+}
+if (found.length > 0) {
+  await runner.terminate(found[0].pid);
+}
+```
+
+## Security Notes
+
+`port-reclaim` only acts on processes listening on the port you provide. It does not scan remote hosts, and it refuses to kill Docker processes — stop those containers yourself. Ports protected by `.reclaimignore` or the `ignore` config are always skipped. Review the process name and working directory before confirming a process from another project. UDP matches are heuristic: a UDP socket on a port can belong to a client as well as a server.
+
+## 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/args.d.ts

@@ -0,0 +1,8 @@
+export interface CliOptions {
+    ports: number[];
+    help: boolean;
+    version: boolean;
+    yes: boolean;
+    list: boolean;
+}
+export declare function parseArgs(argv: string[]): CliOptions | undefined;

package/dist/src/args.js

@@ -0,0 +1,35 @@
+const HELP_FLAGS = new Set(["--help", "-h"]);
+const VERSION_FLAGS = new Set(["--version", "-v"]);
+const YES_FLAGS = new Set(["--yes", "-y", "--force", "-f"]);
+const LIST_FLAGS = new Set(["--list", "-l"]);
+function parsePort(value) {
+    if (!/^\d+$/.test(value))
+        return undefined;
+    const port = Number(value);
+    return port >= 1 && port <= 65535 ? port : undefined;
+}
+export function parseArgs(argv) {
+    const options = { ports: [], help: false, version: false, yes: false, list: false };
+    for (const arg of argv) {
+        if (HELP_FLAGS.has(arg)) {
+            options.help = true;
+        }
+        else if (VERSION_FLAGS.has(arg)) {
+            options.version = true;
+        }
+        else if (YES_FLAGS.has(arg)) {
+            options.yes = true;
+        }
+        else if (LIST_FLAGS.has(arg)) {
+            options.list = true;
+        }
+        else {
+            const port = parsePort(arg);
+            if (port === undefined)
+                return undefined;
+            if (!options.ports.includes(port))
+                options.ports.push(port);
+        }
+    }
+    return options;
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { type ProcessRunner } from "./process.js";
+export declare function main(argv?: string[], runner?: ProcessRunner): Promise<number>;

package/dist/src/cli.js

@@ -2,19 +2,26 @@
 import readline from "node:readline/promises";
 import process from "node:process";
 import path from "node:path";
+import { readFile } from "node:fs/promises";
 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;
+import { parseArgs } from "./args.js";
+import { loadConfig } from "./config.js";
+const USAGE = `Usage: port-reclaim [options] <PORT ...>
+
+Safely reclaim local ports held by stale development processes.
+
+Options:
+  -l, --list     Report what is using each port without killing anything.
+  -y, --yes      Terminate processes from other directories without prompting.
+  -h, --help     Show this help message.
+  -v, --version  Show the installed version.
+
+Ports may also come from the "port-reclaim" key in package.json:
+  "port-reclaim": { "ports": [3000, 5173], "ignore": [5432] }
+Ports listed in .reclaimignore (one per line, '#' starts a comment) are never touched.`;
+function printUsage() {
+    console.error(USAGE);
 }
 function sameDirectory(left, right) {
     if (!left)
@@ -23,30 +30,113 @@ function sameDirectory(left, right) {
     const normalizedRight = path.normalize(path.resolve(right));
     return process.platform === "win32" ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase() : normalizedLeft === normalizedRight;
 }
+function formatAge(ageMs) {
+    const totalSeconds = Math.floor(ageMs / 1000);
+    const days = Math.floor(totalSeconds / 86400);
+    const hours = Math.floor((totalSeconds % 86400) / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    if (days > 0)
+        return `${days}d ${hours}h`;
+    if (hours > 0)
+        return `${hours}h ${minutes}m`;
+    if (minutes > 0)
+        return `${minutes}m ${totalSeconds % 60}s`;
+    return `${totalSeconds}s`;
+}
+function describe(portProcess) {
+    const details = [`PID ${portProcess.pid}`];
+    if (portProcess.cwd)
+        details.push(`'${portProcess.cwd}'`);
+    if (portProcess.ageMs !== undefined)
+        details.push(`up ${formatAge(portProcess.ageMs)}`);
+    if (portProcess.protocol === "udp")
+        details.push("udp");
+    return `'${portProcess.name}' (${details.join(", ")})`;
+}
 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.`);
+        console.error(`Port ${port} is used by ${describe(portProcess)}. Use an interactive terminal to confirm termination, or rerun with --yes.`);
         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) `);
+    const answer = await prompt.question(`Port ${port} is used by ${describe(portProcess)}. 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;
+async function version() {
+    try {
+        const pkg = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+async function reclaimPort(port, runner, options) {
+    const portProcesses = await runner.discover(port);
+    if (portProcesses.length === 0) {
+        if (options.list)
+            console.log(`Port ${port} is free.`);
+        return true;
+    }
+    let free = true;
     const currentDirectory = process.cwd();
-    for (const portProcess of processes) {
-        const shouldTerminate = sameDirectory(portProcess.cwd, currentDirectory) || await confirm(portProcess, port);
-        if (!shouldTerminate)
-            return 1;
+    for (const portProcess of portProcesses) {
+        if (options.list) {
+            const origin = sameDirectory(portProcess.cwd, currentDirectory)
+                ? "matches the current directory"
+                : portProcess.cwd ? `'${portProcess.cwd}'` : "an unreadable working directory";
+            const docker = portProcess.docker ? " [docker]" : "";
+            console.log(`Port ${port} is used by ${describe(portProcess)}${docker} — ${origin}.`);
+            continue;
+        }
+        if (portProcess.docker) {
+            console.error(`Port ${port} is used by ${describe(portProcess)}, which appears to be a Docker process. Refusing to kill it — stop the container instead (for example 'docker stop <container>').`);
+            free = false;
+            continue;
+        }
+        const shouldTerminate = sameDirectory(portProcess.cwd, currentDirectory) || options.yes || await confirm(portProcess, port);
+        if (!shouldTerminate) {
+            free = false;
+            continue;
+        }
         await runner.terminate(portProcess.pid);
         console.log(`Released port ${port} from ${portProcess.name} (PID ${portProcess.pid}).`);
     }
-    return 0;
+    return free;
+}
+export async function main(argv = process.argv.slice(2), runner = createProcessRunner()) {
+    const options = parseArgs(argv);
+    if (!options) {
+        printUsage();
+        return 2;
+    }
+    if (options.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (options.version) {
+        console.log(await version());
+        return 0;
+    }
+    const config = await loadConfig(process.cwd());
+    const ignored = new Set(config.ignore);
+    const ports = options.ports.length > 0 ? options.ports : config.ports;
+    if (ports.length === 0) {
+        printUsage();
+        return 2;
+    }
+    let exitCode = 0;
+    for (const port of ports) {
+        if (ignored.has(port)) {
+            console.log(`Port ${port} is protected by .reclaimignore or config — skipped.`);
+            continue;
+        }
+        const free = await reclaimPort(port, runner, options);
+        if (!free)
+            exitCode = 1;
+    }
+    return exitCode;
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     main().then((code) => process.exit(code)).catch((error) => {

package/dist/src/config.d.ts

@@ -0,0 +1,7 @@
+export interface ReclaimConfig {
+    ports: number[];
+    ignore: number[];
+}
+export declare function parseReclaimignore(content: string): number[];
+export declare function parsePackageConfig(json: unknown): ReclaimConfig;
+export declare function loadConfig(cwd: string): Promise<ReclaimConfig>;

package/dist/src/config.js

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+function toPortList(value) {
+    if (!Array.isArray(value))
+        return [];
+    const ports = [];
+    for (const entry of value) {
+        const port = typeof entry === "number" ? entry : typeof entry === "string" && /^\d+$/.test(entry) ? Number(entry) : NaN;
+        if (Number.isInteger(port) && port >= 1 && port <= 65535 && !ports.includes(port))
+            ports.push(port);
+    }
+    return ports;
+}
+export function parseReclaimignore(content) {
+    const ports = [];
+    for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const port = Number(trimmed);
+        if (Number.isInteger(port) && port >= 1 && port <= 65535 && !ports.includes(port))
+            ports.push(port);
+    }
+    return ports;
+}
+export function parsePackageConfig(json) {
+    if (typeof json !== "object" || json === null)
+        return { ports: [], ignore: [] };
+    const key = json["port-reclaim"];
+    if (typeof key !== "object" || key === null)
+        return { ports: [], ignore: [] };
+    const config = key;
+    return { ports: toPortList(config.ports), ignore: toPortList(config.ignore) };
+}
+export async function loadConfig(cwd) {
+    let ports = [];
+    let ignore = [];
+    try {
+        const pkg = JSON.parse(await readFile(path.join(cwd, "package.json"), "utf8"));
+        const config = parsePackageConfig(pkg);
+        ports = config.ports;
+        ignore = config.ignore;
+    }
+    catch {
+        // No readable package.json or no usable config key.
+    }
+    try {
+        const extra = parseReclaimignore(await readFile(path.join(cwd, ".reclaimignore"), "utf8"));
+        ignore = [...new Set([...ignore, ...extra])];
+    }
+    catch {
+        // No .reclaimignore file.
+    }
+    return { ports, ignore };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export { createProcessRunner, parseEtime, parseNetstatPids, parseUnixLsof, parseWindowsPids } from "./process.js";
+export type { NetstatPid, PortProcess, ProcessRunner, Protocol } from "./process.js";
+export { loadConfig, parsePackageConfig, parseReclaimignore } from "./config.js";
+export type { ReclaimConfig } from "./config.js";
+export { parseArgs } from "./args.js";
+export type { CliOptions } from "./args.js";

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export { createProcessRunner, parseEtime, parseNetstatPids, parseUnixLsof, parseWindowsPids } from "./process.js";
+export { loadConfig, parsePackageConfig, parseReclaimignore } from "./config.js";
+export { parseArgs } from "./args.js";

package/dist/src/process.d.ts

@@ -0,0 +1,22 @@
+export type Protocol = "tcp" | "udp";
+export interface PortProcess {
+    pid: number;
+    name: string;
+    cwd?: string;
+    protocol?: Protocol;
+    ageMs?: number;
+    docker?: boolean;
+}
+export interface ProcessRunner {
+    discover(port: number): Promise<PortProcess[]>;
+    terminate(pid: number): Promise<void>;
+}
+export declare function parseWindowsPids(output: string): number[];
+export declare function parseUnixLsof(output: string): number[];
+export declare function parseEtime(value: string): number | undefined;
+export interface NetstatPid {
+    pid: number;
+    protocol: Protocol;
+}
+export declare function parseNetstatPids(output: string, port: number): NetstatPid[];
+export declare function createProcessRunner(): ProcessRunner;

package/dist/src/process.js

@@ -3,6 +3,10 @@ import { promisify } from "node:util";
 import process from "node:process";
 import pidCwd from "pid-cwd";
 const execFileAsync = promisify(execFile);
+const DOCKER_PROCESS = /docker|vpnkit/i;
+function isDockerProcess(name) {
+    return DOCKER_PROCESS.test(name);
+}
 function parsePidList(output) {
     return [...new Set(output.split(/\r?\n/).map((line) => Number(line.trim())).filter((pid) => Number.isInteger(pid) && pid > 0))];
 }
@@ -12,7 +16,49 @@ export function parseWindowsPids(output) {
 export function parseUnixLsof(output) {
     return [...new Set([...output.matchAll(/^p(\d+)$/gm)].map((match) => Number(match[1])))];
 }
-async function run(command, args) {
+export function parseEtime(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    const dayParts = trimmed.split("-");
+    const days = dayParts.length === 2 ? Number(dayParts[0]) : 0;
+    const units = (dayParts.length === 2 ? dayParts[1] : dayParts[0]).split(":");
+    if (dayParts.length > 2 || (units.length !== 2 && units.length !== 3) || units.some((unit) => !/^\d+$/.test(unit)) || !Number.isInteger(days)) {
+        return undefined;
+    }
+    const numbers = units.map(Number);
+    let hours = 0;
+    let minutes = 0;
+    let seconds = 0;
+    if (numbers.length === 3) {
+        [hours, minutes, seconds] = numbers;
+    }
+    else {
+        [minutes, seconds] = numbers;
+    }
+    return (((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
+}
+export function parseNetstatPids(output, port) {
+    const results = [];
+    const seen = new Set();
+    for (const line of output.split(/\r?\n/)) {
+        const columns = line.trim().split(/\s+/);
+        const protocol = columns[0]?.toUpperCase();
+        if (protocol !== "TCP" && protocol !== "UDP")
+            continue;
+        if (columns[1]?.split(":").at(-1) !== String(port))
+            continue;
+        if (protocol === "TCP" && columns[3]?.toUpperCase() !== "LISTENING")
+            continue;
+        const pid = Number(columns.at(-1));
+        if (Number.isInteger(pid) && pid > 0 && !seen.has(pid)) {
+            seen.add(pid);
+            results.push({ pid, protocol: protocol.toLowerCase() });
+        }
+    }
+    return results;
+}
+async function run(command, args, checked = false) {
     try {
         const result = await execFileAsync(command, args, { windowsHide: true, maxBuffer: 1024 * 1024 });
         return result.stdout;
@@ -24,31 +70,59 @@ async function run(command, args) {
         if (processError.code === "ENOENT") {
             throw new Error(`Required system command '${command}' was not found.`);
         }
+        if (checked) {
+            const detail = processError.stderr?.trim() || processError.message;
+            throw new Error(`Command '${command}' failed: ${detail}`);
+        }
         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 unixPortProcesses(port) {
+    const merged = new Map();
+    const udp = await run("lsof", ["-nP", "-iUDP:" + port, "-Fp"]);
+    for (const pid of parseUnixLsof(udp))
+        merged.set(pid, "udp");
+    const tcp = await run("lsof", ["-nP", "-a", "-iTCP:" + port, "-sTCP:LISTEN", "-Fp"]);
+    for (const pid of parseUnixLsof(tcp))
+        merged.set(pid, "tcp");
+    return merged;
 }
-async function unixPids(port) {
-    const output = await run("lsof", ["-nP", "-a", "-iTCP:" + port, "-sTCP:LISTEN", "-Fp"]);
-    return parseUnixLsof(output);
+async function windowsPortProcesses(port) {
+    const merged = new Map();
+    const tcpScript = `$ErrorActionPreference = 'SilentlyContinue'; Get-NetTCPConnection -LocalPort ${port} -State Listen | Select-Object -ExpandProperty OwningProcess`;
+    for (const pid of parseWindowsPids(await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", tcpScript]))) {
+        merged.set(pid, "tcp");
+    }
+    const udpScript = `$ErrorActionPreference = 'SilentlyContinue'; Get-NetUDPConnection -LocalPort ${port} | Select-Object -ExpandProperty OwningProcess`;
+    for (const pid of parseWindowsPids(await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", udpScript]))) {
+        if (!merged.has(pid))
+            merged.set(pid, "udp");
+    }
+    if (merged.size > 0)
+        return merged;
+    const netstat = await run("netstat.exe", ["-ano"]);
+    for (const entry of parseNetstatPids(netstat, port)) {
+        if (!merged.has(entry.pid))
+            merged.set(entry.pid, entry.protocol);
+    }
+    return merged;
 }
-async function processName(pid) {
+async function processInfo(pid) {
     if (process.platform === "win32") {
-        const output = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `(Get-Process -Id ${pid}).ProcessName`]);
-        return output.trim() || "unknown";
+        const script = `$ErrorActionPreference = 'SilentlyContinue'; $p = Get-Process -Id ${pid}; if ($p) { $p.ProcessName; if ($p.StartTime) { [DateTime]::UtcNow.Subtract($p.StartTime).TotalMilliseconds } }`;
+        const output = await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script]);
+        const [name, age] = output.split(/\r?\n/);
+        const ageMs = Number(age?.trim());
+        return { name: name?.trim() || "unknown", ageMs: Number.isFinite(ageMs) && ageMs > 0 ? ageMs : undefined };
     }
-    const output = await run("ps", ["-p", String(pid), "-o", "comm="]);
-    return output.trim() || "unknown";
+    const output = await run("ps", ["-p", String(pid), "-o", "comm=", "-o", "etime="]);
+    const trimmed = output.trim();
+    if (!trimmed)
+        return { name: "unknown" };
+    const match = /^(.*?)\s+(\S+)$/.exec(trimmed);
+    if (!match)
+        return { name: trimmed };
+    return { name: match[1].trim(), ageMs: parseEtime(match[2]) };
 }
 async function processCwd(pid) {
     return (await pidCwd(pid)) ?? undefined;
@@ -56,12 +130,23 @@ async function processCwd(pid) {
 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) })));
+            const entries = process.platform === "win32" ? await windowsPortProcesses(port) : await unixPortProcesses(port);
+            return Promise.all([...entries].map(async ([pid, protocol]) => {
+                const info = await processInfo(pid);
+                return {
+                    pid,
+                    name: info.name,
+                    protocol,
+                    cwd: await processCwd(pid),
+                    ageMs: info.ageMs,
+                    docker: isDockerProcess(info.name),
+                };
+            }));
         },
         async terminate(pid) {
             if (process.platform === "win32") {
-                await run("taskkill.exe", ["/PID", String(pid), "/T"]);
+                // Without /F, taskkill cannot end console processes such as node dev servers.
+                await run("taskkill.exe", ["/F", "/PID", String(pid), "/T"], true);
                 return;
             }
             process.kill(pid, "SIGTERM");

package/dist/tests/args.test.d.ts

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

package/dist/tests/args.test.js

@@ -0,0 +1,25 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseArgs } from "../src/args.js";
+test("parses multiple ports and deduplicates", () => {
+    assert.deepEqual(parseArgs(["3000", "5173", "3000"]), {
+        ports: [3000, 5173],
+        help: false,
+        version: false,
+        yes: false,
+        list: false,
+    });
+});
+test("parses flags", () => {
+    assert.deepEqual(parseArgs(["-l", "--yes"]), { ports: [], help: false, version: false, yes: true, list: true });
+    assert.deepEqual(parseArgs(["--list", "-y", "-f"]), { ports: [], help: false, version: false, yes: true, list: true });
+    assert.deepEqual(parseArgs(["--help"]), { ports: [], help: true, version: false, yes: false, list: false });
+    assert.deepEqual(parseArgs(["-v"]), { ports: [], help: false, version: true, yes: false, list: false });
+});
+test("rejects invalid input", () => {
+    assert.equal(parseArgs(["abc"]), undefined);
+    assert.equal(parseArgs(["0"]), undefined);
+    assert.equal(parseArgs(["65536"]), undefined);
+    assert.equal(parseArgs(["3000", "--nope"]), undefined);
+    assert.equal(parseArgs(["-1"]), undefined);
+});

package/dist/tests/cli.test.d.ts

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

package/dist/tests/cli.test.js

@@ -0,0 +1,144 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import process from "node:process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { main } from "../src/cli.js";
+function fakeRunner(byPort) {
+    const calls = { discovered: [], terminated: [] };
+    return {
+        calls,
+        runner: {
+            async discover(port) {
+                calls.discovered.push(port);
+                return byPort[port] ?? [];
+            },
+            async terminate(pid) {
+                calls.terminated.push(pid);
+            },
+        },
+    };
+}
+function capture() {
+    const log = [];
+    const error = [];
+    const originalLog = console.log;
+    const originalError = console.error;
+    console.log = (...args) => log.push(args.join(" "));
+    console.error = (...args) => error.push(args.join(" "));
+    return {
+        log,
+        error,
+        restore: () => {
+            console.log = originalLog;
+            console.error = originalError;
+        },
+    };
+}
+test("exits 0 when all ports are free", async () => {
+    const { runner, calls } = fakeRunner({});
+    const output = capture();
+    try {
+        assert.equal(await main(["3000", "5173"], runner), 0);
+        assert.deepEqual(calls.discovered, [3000, 5173]);
+        assert.deepEqual(calls.terminated, []);
+    }
+    finally {
+        output.restore();
+    }
+});
+test("terminates processes from the current directory without prompting", async () => {
+    const { runner, calls } = fakeRunner({ 3000: [{ pid: 42, name: "node", cwd: process.cwd() }] });
+    const output = capture();
+    try {
+        assert.equal(await main(["3000"], runner), 0);
+        assert.deepEqual(calls.terminated, [42]);
+    }
+    finally {
+        output.restore();
+    }
+});
+test("declines foreign processes when not interactive", async () => {
+    const { runner, calls } = fakeRunner({ 3000: [{ pid: 7, name: "node", cwd: "/somewhere/else" }] });
+    const output = capture();
+    try {
+        assert.equal(await main(["3000"], runner), 1);
+        assert.deepEqual(calls.terminated, []);
+        assert.match(output.error.join("\n"), /interactive terminal/);
+    }
+    finally {
+        output.restore();
+    }
+});
+test("--yes terminates foreign processes across multiple ports", async () => {
+    const { runner, calls } = fakeRunner({
+        3000: [{ pid: 7, name: "node", cwd: "/somewhere/else" }],
+        5173: [{ pid: 8, name: "node", cwd: "/elsewhere" }],
+    });
+    const output = capture();
+    try {
+        assert.equal(await main(["3000", "5173", "--yes"], runner), 0);
+        assert.deepEqual(calls.terminated, [7, 8]);
+    }
+    finally {
+        output.restore();
+    }
+});
+test("--list reports without terminating", async () => {
+    const { runner, calls } = fakeRunner({
+        3000: [{ pid: 7, name: "node", cwd: "/somewhere/else", ageMs: 93784000, protocol: "tcp" }],
+    });
+    const output = capture();
+    try {
+        assert.equal(await main(["--list", "3000"], runner), 0);
+        assert.deepEqual(calls.terminated, []);
+        assert.match(output.log.join("\n"), /PID 7/);
+        assert.match(output.log.join("\n"), /up 1d 2h/);
+        assert.match(output.log.join("\n"), /\/somewhere\/else/);
+    }
+    finally {
+        output.restore();
+    }
+});
+test("refuses to kill Docker processes even with --yes", async () => {
+    const { runner, calls } = fakeRunner({ 3000: [{ pid: 9, name: "docker-proxy", docker: true }] });
+    const output = capture();
+    try {
+        assert.equal(await main(["3000", "--yes"], runner), 1);
+        assert.deepEqual(calls.terminated, []);
+        assert.match(output.error.join("\n"), /Docker/);
+    }
+    finally {
+        output.restore();
+    }
+});
+test("skips ports protected by .reclaimignore in the current directory", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "port-reclaim-"));
+    const originalCwd = process.cwd();
+    const { runner, calls } = fakeRunner({ 5432: [{ pid: 1, name: "postgres", cwd: "/var/lib/postgresql" }] });
+    const output = capture();
+    try {
+        await writeFile(path.join(dir, ".reclaimignore"), "5432\n");
+        process.chdir(dir);
+        assert.equal(await main(["5432"], runner), 0);
+        assert.deepEqual(calls.discovered, []);
+        assert.match(output.log.join("\n"), /protected/);
+    }
+    finally {
+        process.chdir(originalCwd);
+        await rm(dir, { recursive: true, force: true });
+        output.restore();
+    }
+});
+test("invalid input exits 2", async () => {
+    const { runner } = fakeRunner({});
+    const output = capture();
+    try {
+        assert.equal(await main(["nope"], runner), 2);
+        assert.match(output.error.join("\n"), /Usage: port-reclaim/);
+    }
+    finally {
+        output.restore();
+    }
+});

package/dist/tests/config.test.d.ts

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

package/dist/tests/config.test.js

@@ -0,0 +1,37 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { loadConfig, parsePackageConfig, parseReclaimignore } from "../src/config.js";
+test("parses .reclaimignore with comments and invalid lines", () => {
+    const content = "# databases\n5432\n\n  6379  \nnot-a-port\n70000\n5432\n";
+    assert.deepEqual(parseReclaimignore(content), [5432, 6379]);
+});
+test("parses the package.json config key", () => {
+    assert.deepEqual(parsePackageConfig({ "port-reclaim": { ports: [3000, "5173"], ignore: [5432] } }), { ports: [3000, 5173], ignore: [5432] });
+    assert.deepEqual(parsePackageConfig({}), { ports: [], ignore: [] });
+    assert.deepEqual(parsePackageConfig({ "port-reclaim": "nope" }), { ports: [], ignore: [] });
+    assert.deepEqual(parsePackageConfig(null), { ports: [], ignore: [] });
+});
+test("loadConfig merges package.json key and .reclaimignore", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "port-reclaim-"));
+    try {
+        await writeFile(path.join(dir, "package.json"), JSON.stringify({ name: "demo", "port-reclaim": { ports: [3000, "5173"], ignore: [5432] } }));
+        await writeFile(path.join(dir, ".reclaimignore"), "# db\n5432\n6379\n");
+        const config = await loadConfig(dir);
+        assert.deepEqual(config, { ports: [3000, 5173], ignore: [5432, 6379] });
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("loadConfig returns an empty config when nothing is configured", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "port-reclaim-"));
+    try {
+        assert.deepEqual(await loadConfig(dir), { ports: [], ignore: [] });
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});

package/dist/tests/process.test.d.ts

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

package/dist/tests/process.test.js

@@ -1,9 +1,35 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { parseUnixLsof, parseWindowsPids } from "../src/process.js";
+import { parseEtime, parseNetstatPids, 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]);
 });
+test("parses ps etime durations", () => {
+    assert.equal(parseEtime("45"), undefined);
+    assert.equal(parseEtime("34:56"), 2096000);
+    assert.equal(parseEtime("12:34:56"), 45296000);
+    assert.equal(parseEtime("1-02:03:04"), 93784000);
+    assert.equal(parseEtime(""), undefined);
+    assert.equal(parseEtime("abc"), undefined);
+    assert.equal(parseEtime("1:2:3:4"), undefined);
+});
+test("parses netstat TCP listeners and UDP sockets for an exact port", () => {
+    const output = [
+        "Active Connections",
+        "",
+        "  Proto  Local Address          Foreign Address        State           PID",
+        "  TCP    0.0.0.0:135            0.0.0.0:0              LISTENING       1111",
+        "  TCP    0.0.0.0:3000           0.0.0.0:0              LISTENING       2222",
+        "  TCP    0.0.0.0:13000          0.0.0.0:0              LISTENING       3333",
+        "  TCP    127.0.0.1:3000         127.0.0.1:51234        ESTABLISHED     4444",
+        "  UDP    0.0.0.0:3000           *:*                                    5555",
+        "  UDP    [::]:5353             *:*                                    6666",
+    ].join("\r\n");
+    assert.deepEqual(parseNetstatPids(output, 3000), [
+        { pid: 2222, protocol: "tcp" },
+        { pid: 5555, protocol: "udp" },
+    ]);
+});

package/package.json

@@ -1,46 +1,54 @@
-{
-  "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"
-  }
-}
+{
+  "name": "port-reclaim",
+  "version": "0.2.0",
+  "description": "Safely reclaim local ports from stale development processes.",
+  "author": "princegoel0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/princegoel0/port-reclaim.git"
+  },
+  "bugs": {
+    "url": "https://github.com/princegoel0/port-reclaim/issues"
+  },
+  "homepage": "https://github.com/princegoel0/port-reclaim#readme",
+  "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 dist/tests/args.test.js dist/tests/config.test.js dist/tests/cli.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"
+  }
+}