portwiz 1.0.0

package/dist/__tests__/utils/ports.test.d.ts

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

package/dist/__tests__/utils/ports.test.js

@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest";
+import { createServer } from "node:net";
+import { validatePort, findNextFreePort, COMMON_DEV_PORTS } from "../../utils/ports.js";
+describe("validatePort", () => {
+    it("parses a valid port number", () => {
+        expect(validatePort("3000")).toBe(3000);
+        expect(validatePort("1")).toBe(1);
+        expect(validatePort("65535")).toBe(65535);
+        expect(validatePort("8080")).toBe(8080);
+    });
+    it("throws for non-numeric input", () => {
+        expect(() => validatePort("abc")).toThrow("Invalid port");
+        expect(() => validatePort("")).toThrow("Invalid port");
+        expect(() => validatePort("foo3000")).toThrow("Invalid port");
+    });
+    it("throws for out-of-range ports", () => {
+        expect(() => validatePort("0")).toThrow("Invalid port");
+        expect(() => validatePort("-1")).toThrow("Invalid port");
+        expect(() => validatePort("65536")).toThrow("Invalid port");
+        expect(() => validatePort("100000")).toThrow("Invalid port");
+    });
+    it("throws for floating point numbers", () => {
+        // parseInt("3.5") returns 3, which is valid — this is acceptable behavior
+        expect(validatePort("3.5")).toBe(3);
+    });
+});
+describe("findNextFreePort", () => {
+    it("returns the given port if it is free", async () => {
+        const port = await findNextFreePort(49152);
+        expect(port).toBeGreaterThanOrEqual(49152);
+        expect(port).toBeLessThanOrEqual(65535);
+    });
+    it("skips a port that is in use and finds the next one", async () => {
+        // Occupy a port
+        const server = createServer();
+        const occupiedPort = await new Promise((resolve) => {
+            server.listen(0, () => {
+                const addr = server.address();
+                if (addr && typeof addr !== "string") {
+                    resolve(addr.port);
+                }
+            });
+        });
+        try {
+            const freePort = await findNextFreePort(occupiedPort);
+            expect(freePort).toBeGreaterThan(occupiedPort);
+        }
+        finally {
+            server.close();
+        }
+    });
+});
+describe("COMMON_DEV_PORTS", () => {
+    it("contains well-known development ports", () => {
+        expect(COMMON_DEV_PORTS).toContain(3000);
+        expect(COMMON_DEV_PORTS).toContain(5173);
+        expect(COMMON_DEV_PORTS).toContain(8080);
+        expect(COMMON_DEV_PORTS.length).toBeGreaterThan(0);
+    });
+    it("contains only valid port numbers", () => {
+        for (const port of COMMON_DEV_PORTS) {
+            expect(port).toBeGreaterThanOrEqual(1);
+            expect(port).toBeLessThanOrEqual(65535);
+        }
+    });
+});

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { freePort } from "./commands/free.js";
+import { switchPort } from "./commands/switch.js";
+import { devMode } from "./commands/dev.js";
+import { doctor } from "./commands/doctor.js";
+import { error } from "./ui/output.js";
+const program = new Command();
+program
+    .name("portwiz")
+    .description("Fix port conflicts instantly and run your dev server without interruptions")
+    .version("1.0.0")
+    .enablePositionalOptions();
+// Default command: portwiz <port>
+program
+    .argument("[port]", "port number to check/free")
+    .option("-f, --force", "kill process without confirmation")
+    .option("-s, --switch", "find next available port instead of killing")
+    .action(async (port, options) => {
+    if (!port) {
+        program.help();
+        return;
+    }
+    try {
+        if (options.switch) {
+            await switchPort(port);
+        }
+        else {
+            await freePort(port, options);
+        }
+    }
+    catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+    }
+});
+// Dev command: portwiz dev <port> -- <cmd>
+program
+    .command("dev")
+    .description("free a port and start your dev server")
+    .argument("<port>", "port number to free")
+    .argument("<cmd...>", "command to run after freeing the port")
+    .option("-f, --force", "kill process without confirmation")
+    .passThroughOptions()
+    .action(async (port, cmd, options) => {
+    try {
+        await devMode(port, cmd, options);
+    }
+    catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+    }
+});
+// Doctor command: portwiz doctor
+program
+    .command("doctor")
+    .description("scan common dev ports and report status")
+    .option("-f, --force", "kill all busy processes without confirmation")
+    .option("--ports <list>", "custom comma-separated port list")
+    .action(async (options) => {
+    try {
+        await doctor(options);
+    }
+    catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+    }
+});
+program.parse();

package/dist/commands/dev.d.ts

@@ -0,0 +1,3 @@
+export declare function devMode(portStr: string, command: string[], options: {
+    force?: boolean;
+}): Promise<void>;

package/dist/commands/dev.js

@@ -0,0 +1,28 @@
+import { spawn } from "node:child_process";
+import { ensurePortFree } from "./free.js";
+import { info, error } from "../ui/output.js";
+import { validatePort } from "../utils/ports.js";
+export async function devMode(portStr, command, options) {
+    const port = validatePort(portStr);
+    const freed = await ensurePortFree(port, !!options.force);
+    if (!freed) {
+        error("Cannot start — port is still in use");
+        process.exitCode = 1;
+        return;
+    }
+    const cmd = command.join(" ");
+    info(`Starting: ${cmd}`);
+    const child = spawn(cmd, {
+        stdio: "inherit",
+        shell: true,
+        env: { ...process.env, PORT: String(port) },
+    });
+    const forwardSignal = (signal) => {
+        child.kill(signal);
+    };
+    process.on("SIGINT", forwardSignal);
+    process.on("SIGTERM", forwardSignal);
+    child.on("exit", (code) => {
+        process.exitCode = code ?? 1;
+    });
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,4 @@
+export declare function doctor(options: {
+    force?: boolean;
+    ports?: string;
+}): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,43 @@
+import { getPortStatuses } from "../platform/detector.js";
+import { killAndVerify } from "../platform/killer.js";
+import { info, success, warn, error, showPortTable } from "../ui/output.js";
+import { confirmKillAll } from "../ui/prompts.js";
+import { COMMON_DEV_PORTS } from "../utils/ports.js";
+export async function doctor(options) {
+    const ports = options.ports
+        ? options.ports.split(",").map((p) => parseInt(p.trim(), 10))
+        : COMMON_DEV_PORTS;
+    info("Scanning development ports...");
+    const statuses = await getPortStatuses(ports);
+    showPortTable(statuses);
+    const busy = statuses.filter((s) => s.inUse && s.process);
+    if (busy.length === 0) {
+        success("All ports are free");
+        return;
+    }
+    warn(`${busy.length} port${busy.length > 1 ? "s are" : " is"} in use`);
+    if (!options.force) {
+        const confirmed = await confirmKillAll(busy.length);
+        if (!confirmed) {
+            info("Aborted");
+            return;
+        }
+    }
+    let allFreed = true;
+    for (const s of busy) {
+        const proc = s.process;
+        info(`Killing ${proc.name} (PID ${proc.pid}) on port ${s.port}...`);
+        const freed = await killAndVerify(proc.pid, s.port, !!options.force);
+        if (!freed) {
+            error(`Failed to free port ${s.port}`);
+            allFreed = false;
+        }
+    }
+    if (allFreed) {
+        success("All ports are now free");
+    }
+    else {
+        warn("Some ports could not be freed. Try running with administrator/sudo privileges.");
+        process.exitCode = 1;
+    }
+}

package/dist/commands/free.d.ts

@@ -0,0 +1,5 @@
+export declare function freePort(portStr: string, options: {
+    force?: boolean;
+}): Promise<void>;
+/** Shared helper: free a port silently, returns true if freed or already free */
+export declare function ensurePortFree(port: number, force: boolean): Promise<boolean>;

package/dist/commands/free.js

@@ -0,0 +1,54 @@
+import { getProcessOnPort } from "../platform/detector.js";
+import { killAndVerify } from "../platform/killer.js";
+import { info, success, warn, error, showProcess } from "../ui/output.js";
+import { confirmKill } from "../ui/prompts.js";
+import { validatePort } from "../utils/ports.js";
+export async function freePort(portStr, options) {
+    const port = validatePort(portStr);
+    info(`Checking port ${port}...`);
+    const proc = await getProcessOnPort(port);
+    if (!proc) {
+        success(`Port ${port} is already free`);
+        return;
+    }
+    warn(`Port ${port} is in use`);
+    showProcess(proc);
+    if (!options.force) {
+        const confirmed = await confirmKill(proc.name, proc.pid);
+        if (!confirmed) {
+            info("Aborted");
+            return;
+        }
+    }
+    info(`Killing ${proc.name} (PID ${proc.pid})...`);
+    const freed = await killAndVerify(proc.pid, port, options.force);
+    if (freed) {
+        success(`Port ${port} is now free`);
+    }
+    else {
+        error(`Failed to free port ${port}. Try running with administrator/sudo privileges.`);
+        process.exitCode = 1;
+    }
+}
+/** Shared helper: free a port silently, returns true if freed or already free */
+export async function ensurePortFree(port, force) {
+    const proc = await getProcessOnPort(port);
+    if (!proc)
+        return true;
+    warn(`Port ${port} is in use by ${proc.name} (PID ${proc.pid})`);
+    if (!force) {
+        const confirmed = await confirmKill(proc.name, proc.pid);
+        if (!confirmed)
+            return false;
+    }
+    info(`Killing ${proc.name} (PID ${proc.pid})...`);
+    const freed = await killAndVerify(proc.pid, port, force);
+    if (freed) {
+        success(`Port ${port} is now free`);
+        return true;
+    }
+    else {
+        error(`Failed to free port ${port}`);
+        return false;
+    }
+}

package/dist/commands/switch.d.ts

@@ -0,0 +1 @@
+export declare function switchPort(portStr: string): Promise<void>;

package/dist/commands/switch.js

@@ -0,0 +1,14 @@
+import { getProcessOnPort } from "../platform/detector.js";
+import { info, success } from "../ui/output.js";
+import { validatePort, findNextFreePort } from "../utils/ports.js";
+export async function switchPort(portStr) {
+    const port = validatePort(portStr);
+    const proc = await getProcessOnPort(port);
+    if (!proc) {
+        success(`Port ${port} is already available`);
+        return;
+    }
+    info(`Port ${port} is in use by ${proc.name} (PID ${proc.pid})`);
+    const nextPort = await findNextFreePort(port + 1);
+    success(`Port ${nextPort} is available`);
+}

package/dist/platform/detector.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessInfo, PortStatus } from "./types.js";
+export declare function getProcessOnPort(port: number): Promise<ProcessInfo | null>;
+export declare function getPortStatuses(ports: number[]): Promise<PortStatus[]>;

package/dist/platform/detector.js

@@ -0,0 +1,96 @@
+import { run } from "../utils/exec.js";
+const platform = process.platform;
+async function getProcessOnPortWin32(port) {
+    const { stdout } = await run(`netstat -ano | findstr :${port}`);
+    if (!stdout.trim())
+        return null;
+    for (const line of stdout.trim().split("\n")) {
+        const parts = line.trim().split(/\s+/);
+        // Look for LISTENING state with our port in local address
+        if (parts.length < 5)
+            continue;
+        const localAddr = parts[1];
+        const state = parts[3];
+        if (state !== "LISTENING")
+            continue;
+        // localAddr is like 0.0.0.0:3000 or [::]:3000
+        const addrPort = localAddr.split(":").pop();
+        if (addrPort !== String(port))
+            continue;
+        const pid = parseInt(parts[4], 10);
+        if (isNaN(pid) || pid === 0)
+            continue;
+        const name = await getProcessNameWin32(pid);
+        return { pid, name, port, protocol: "tcp" };
+    }
+    return null;
+}
+async function getProcessNameWin32(pid) {
+    const { stdout } = await run(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`);
+    if (!stdout.trim())
+        return "unknown";
+    // Output: "name.exe","PID","Session Name","Session#","Mem Usage"
+    const match = stdout.match(/"([^"]+)"/);
+    return match ? match[1].replace(/\.exe$/i, "") : "unknown";
+}
+async function getProcessOnPortUnix(port) {
+    const { stdout } = await run(`lsof -iTCP:${port} -sTCP:LISTEN -n -P`);
+    if (!stdout.trim())
+        return null;
+    const lines = stdout.trim().split("\n");
+    // Skip header line
+    for (let i = 1; i < lines.length; i++) {
+        const parts = lines[i].trim().split(/\s+/);
+        if (parts.length < 2)
+            continue;
+        const name = parts[0];
+        const pid = parseInt(parts[1], 10);
+        if (isNaN(pid))
+            continue;
+        return { pid, name, port, protocol: "tcp" };
+    }
+    return null;
+}
+async function getProcessOnPortLinuxSs(port) {
+    const { stdout } = await run(`ss -tlnp sport = :${port}`);
+    if (!stdout.trim())
+        return null;
+    const lines = stdout.trim().split("\n");
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        // Match users:(("name",pid=1234,fd=5))
+        const match = line.match(/users:\(\("([^"]+)",pid=(\d+)/);
+        if (match) {
+            return { pid: parseInt(match[2], 10), name: match[1], port, protocol: "tcp" };
+        }
+    }
+    return null;
+}
+export async function getProcessOnPort(port) {
+    if (platform === "win32") {
+        return getProcessOnPortWin32(port);
+    }
+    // Try lsof first (macOS + Linux)
+    const result = await getProcessOnPortUnix(port);
+    if (result)
+        return result;
+    // Fallback to ss on Linux
+    if (platform === "linux") {
+        return getProcessOnPortLinuxSs(port);
+    }
+    return null;
+}
+export async function getPortStatuses(ports) {
+    const results = [];
+    // Run all checks in parallel
+    const checks = await Promise.all(ports.map((port) => getProcessOnPort(port)));
+    for (let i = 0; i < ports.length; i++) {
+        const proc = checks[i];
+        results.push({
+            port: ports[i],
+            inUse: proc !== null,
+            process: proc ?? undefined,
+        });
+    }
+    return results;
+}

package/dist/platform/killer.d.ts

@@ -0,0 +1,2 @@
+export declare function killProcess(pid: number, force?: boolean): Promise<boolean>;
+export declare function killAndVerify(pid: number, port: number, force?: boolean): Promise<boolean>;

package/dist/platform/killer.js

@@ -0,0 +1,36 @@
+import { run } from "../utils/exec.js";
+import { getProcessOnPort } from "./detector.js";
+const platform = process.platform;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function killProcess(pid, force = false) {
+    try {
+        if (platform === "win32") {
+            const flag = force ? " /F" : "";
+            const { stderr } = await run(`taskkill /PID ${pid}${flag}`);
+            return !stderr.includes("ERROR");
+        }
+        else {
+            const signal = force ? "SIGKILL" : "SIGTERM";
+            process.kill(pid, signal);
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+export async function killAndVerify(pid, port, force = false) {
+    const killed = await killProcess(pid, force);
+    if (!killed)
+        return false;
+    // Verify port is freed (retry up to 3 times)
+    for (let i = 0; i < 3; i++) {
+        await sleep(500);
+        const proc = await getProcessOnPort(port);
+        if (!proc)
+            return true;
+    }
+    return false;
+}

package/dist/platform/types.d.ts

@@ -0,0 +1,11 @@
+export interface ProcessInfo {
+    pid: number;
+    name: string;
+    port: number;
+    protocol: "tcp" | "udp";
+}
+export interface PortStatus {
+    port: number;
+    inUse: boolean;
+    process?: ProcessInfo;
+}

package/dist/platform/types.js

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

package/dist/ui/output.d.ts

@@ -0,0 +1,7 @@
+import type { ProcessInfo, PortStatus } from "../platform/types.js";
+export declare const info: (msg: string) => void;
+export declare const success: (msg: string) => void;
+export declare const warn: (msg: string) => void;
+export declare const error: (msg: string) => void;
+export declare function showProcess(p: ProcessInfo): void;
+export declare function showPortTable(statuses: PortStatus[]): void;

package/dist/ui/output.js

@@ -0,0 +1,29 @@
+import pc from "picocolors";
+export const info = (msg) => console.log(pc.cyan("i") + " " + msg);
+export const success = (msg) => console.log(pc.green("\u2714") + " " + msg);
+export const warn = (msg) => console.log(pc.yellow("!") + " " + msg);
+export const error = (msg) => console.error(pc.red("\u2716") + " " + msg);
+export function showProcess(p) {
+    console.log();
+    console.log(`  ${pc.dim("PID:")}     ${pc.bold(String(p.pid))}`);
+    console.log(`  ${pc.dim("Process:")} ${pc.bold(p.name)}`);
+    console.log();
+}
+export function showPortTable(statuses) {
+    console.log();
+    console.log(`  ${pc.bold(pad("PORT", 8))}${pc.bold(pad("STATUS", 10))}${pc.bold("PROCESS")}`);
+    for (const s of statuses) {
+        const port = pad(String(s.port), 8);
+        const status = s.inUse
+            ? pc.red(pad("in use", 10))
+            : pc.green(pad("free", 10));
+        const proc = s.process
+            ? `${s.process.name} (PID ${s.process.pid})`
+            : pc.dim("-");
+        console.log(`  ${port}${status}${proc}`);
+    }
+    console.log();
+}
+function pad(str, len) {
+    return str.padEnd(len);
+}

package/dist/ui/prompts.d.ts

@@ -0,0 +1,2 @@
+export declare function confirmKill(processName: string, pid: number): Promise<boolean>;
+export declare function confirmKillAll(count: number): Promise<boolean>;

package/dist/ui/prompts.js

@@ -0,0 +1,17 @@
+import confirm from "@inquirer/confirm";
+export async function confirmKill(processName, pid) {
+    if (!process.stdin.isTTY)
+        return false;
+    return confirm({
+        message: `Kill ${processName} (PID ${pid}) to free the port?`,
+        default: false,
+    });
+}
+export async function confirmKillAll(count) {
+    if (!process.stdin.isTTY)
+        return false;
+    return confirm({
+        message: `Free all ${count} busy port${count > 1 ? "s" : ""}?`,
+        default: false,
+    });
+}

package/dist/utils/exec.d.ts

@@ -0,0 +1,4 @@
+export declare function run(cmd: string): Promise<{
+    stdout: string;
+    stderr: string;
+}>;

package/dist/utils/exec.js

@@ -0,0 +1,12 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+export async function run(cmd) {
+    try {
+        return await execAsync(cmd, { timeout: 5000 });
+    }
+    catch (err) {
+        const e = err;
+        return { stdout: e.stdout ?? "", stderr: e.stderr ?? "" };
+    }
+}

package/dist/utils/ports.d.ts

@@ -0,0 +1,3 @@
+export declare const COMMON_DEV_PORTS: number[];
+export declare function validatePort(input: string): number;
+export declare function findNextFreePort(startFrom: number): Promise<number>;

package/dist/utils/ports.js

@@ -0,0 +1,28 @@
+import { createServer } from "node:net";
+export const COMMON_DEV_PORTS = [
+    3000, 3001, 4200, 5000, 5173, 5174, 8000, 8080, 8081, 8443, 9000, 9090,
+];
+export function validatePort(input) {
+    const port = parseInt(input, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid port: ${input}. Must be between 1 and 65535.`);
+    }
+    return port;
+}
+export function findNextFreePort(startFrom) {
+    return new Promise((resolve, reject) => {
+        const tryPort = (port) => {
+            if (port > 65535) {
+                reject(new Error("No free port found"));
+                return;
+            }
+            const server = createServer();
+            server.once("error", () => tryPort(port + 1));
+            server.once("listening", () => {
+                server.close(() => resolve(port));
+            });
+            server.listen(port);
+        };
+        tryPort(startFrom);
+    });
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "portwiz",
+  "version": "1.0.0",
+  "description": "Fix port conflicts instantly and run your dev server without interruptions",
+  "type": "module",
+  "bin": {
+    "portwiz": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "port",
+    "kill",
+    "process",
+    "cli",
+    "developer-tools",
+    "devtools",
+    "port-conflict",
+    "free-port",
+    "lsof",
+    "netstat"
+  ],
+  "author": "ashok1706",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashok1706/portwiz.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ashok1706/portwiz/issues"
+  },
+  "homepage": "https://github.com/ashok1706/portwiz#readme",
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/confirm": "^5.0.0",
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "eslint": "10.0.3",
+    "prettier": "3.8.1",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}