portwiz 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 portwiz
+
+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,221 @@
+# 🚀 portwiz
+
+**Fix port conflicts instantly and run your dev server without interruptions.**
+
+```bash
+npx portwiz 3000
+```
+
+---
+
+## 😩 The Problem
+
+Every developer has seen this:
+
+```
+Error: EADDRINUSE: address already in use :::3000
+```
+
+Then you:
+
+* Search for the process using the port
+* Run `lsof` / `netstat`
+* Kill processes manually
+* Repeat again tomorrow 😑
+
+👉 It breaks your flow.
+
+---
+
+## ⚡ The Solution
+
+**portwiz** handles everything in one command:
+
+```bash
+npx portwiz 3000
+```
+
+* Detects what’s using the port
+* Shows the process clearly
+* Frees it instantly
+
+No guesswork. No manual steps.
+
+---
+
+## 📦 Installation
+
+```bash
+# Run instantly (recommended)
+npx portwiz 3000
+
+# Or install globally
+npm install -g portwiz
+```
+
+**Requirements:** Node.js 18+
+
+---
+
+## 🧪 Usage
+
+---
+
+### 🔧 Free a port
+
+```bash
+portwiz 3000
+```
+
+```
+ℹ Checking port 3000...
+⚠ Port 3000 is in use
+
+  PID:     1234
+  Process: node
+
+? Kill this process to free port 3000? (y/N) y
+✔ Port 3000 is now free
+```
+
+---
+
+### ⚡ Force mode
+
+Skip confirmation:
+
+```bash
+portwiz 3000 --force
+```
+
+---
+
+### 🔀 Smart switch
+
+Find the next available port instead of killing:
+
+```bash
+portwiz 3000 --switch
+```
+
+```
+ℹ Port 3000 is in use by node (PID 1234)
+✔ Port 3001 is available
+```
+
+---
+
+### 🔥 Dev mode (run + fix in one command)
+
+```bash
+portwiz dev 3000 -- npm run dev
+```
+
+```
+⚠ Port 3000 is in use by node (PID 1234)
+? Kill node (PID 1234)? (y/N) y
+✔ Port 3000 is now free
+
+ℹ Starting: npm run dev
+```
+
+👉 Automatically sets the `PORT` environment variable.
+
+---
+
+### 🧠 Doctor mode
+
+Scan common development ports:
+
+```bash
+portwiz doctor
+```
+
+```
+ℹ Scanning development ports...
+
+  PORT    STATUS    PROCESS
+  3000    in use    node (PID 1234)
+  3001    free      -
+  4200    free      -
+  5000    in use    python3 (PID 5678)
+  5173    free      -
+  8080    in use    java (PID 9012)
+
+⚠ 3 ports are in use
+
+? Free all 3 busy ports? (y/N) y
+✔ All ports are now free
+```
+
+Custom ports:
+
+```bash
+portwiz doctor --ports 4000,4001,4002
+```
+
+---
+
+## 📖 Commands
+
+| Command                       | Description               |
+| ----------------------------- | ------------------------- |
+| `portwiz <port>`              | Detect and free a port    |
+| `portwiz <port> --switch`     | Find next available port  |
+| `portwiz dev <port> -- <cmd>` | Free port and run command |
+| `portwiz doctor`              | Scan common dev ports     |
+
+---
+
+## ⚙️ Options
+
+| Flag             | Short | Description                            |
+| ---------------- | ----- | -------------------------------------- |
+| `--force`        | `-f`  | Kill without confirmation              |
+| `--switch`       | `-s`  | Find next free port instead of killing |
+| `--ports <list>` | —     | Custom ports (doctor mode)             |
+| `--version`      | `-V`  | Show version                           |
+| `--help`         | `-h`  | Show help                              |
+
+---
+
+## 🌍 Cross-platform
+
+Works out of the box on all major platforms:
+
+| Platform | Detection              | Kill                |
+| -------- | ---------------------- | ------------------- |
+| Windows  | `netstat` + `tasklist` | `taskkill`          |
+| macOS    | `lsof`                 | `SIGTERM / SIGKILL` |
+| Linux    | `lsof` / `ss`          | `SIGTERM / SIGKILL` |
+
+---
+
+## 🎯 Use Cases
+
+* React / Vite / Next.js dev servers
+* Node.js / Express apps
+* Full-stack local development
+* Docker port conflicts
+* Multi-service environments
+
+---
+
+## 💡 Why portwiz?
+
+* ⚡ Zero setup
+* 🧠 Smart defaults
+* 🔥 Dev-friendly workflow
+* ⏱ Saves time every day
+
+---
+
+## 🚀 One-line Pitch
+
+> Stop fixing ports. Start building.
+
+---
+
+## 📄 License
+
+MIT

package/dist/__tests__/commands/dev.test.d.ts

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

package/dist/__tests__/commands/dev.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+vi.mock("../../commands/free.js", () => ({
+    ensurePortFree: vi.fn(),
+}));
+vi.mock("../../ui/output.js", () => ({
+    info: vi.fn(),
+    error: vi.fn(),
+}));
+// Mock child_process.spawn
+const mockSpawn = vi.fn();
+vi.mock("node:child_process", () => ({
+    spawn: (...args) => mockSpawn(...args),
+}));
+import { devMode } from "../../commands/dev.js";
+import { ensurePortFree } from "../../commands/free.js";
+import { info, error } from "../../ui/output.js";
+const mockEnsureFree = vi.mocked(ensurePortFree);
+beforeEach(() => {
+    vi.clearAllMocks();
+    process.exitCode = undefined;
+    // Default spawn mock: returns an EventEmitter-like object
+    mockSpawn.mockReturnValue({
+        kill: vi.fn(),
+        on: vi.fn(),
+    });
+});
+describe("devMode", () => {
+    it("frees port and spawns the command", async () => {
+        mockEnsureFree.mockResolvedValue(true);
+        await devMode("3000", ["npm", "run", "dev"], {});
+        expect(mockEnsureFree).toHaveBeenCalledWith(3000, false);
+        expect(info).toHaveBeenCalledWith(expect.stringContaining("Starting: npm run dev"));
+        expect(mockSpawn).toHaveBeenCalledWith("npm run dev", expect.objectContaining({
+            stdio: "inherit",
+            shell: true,
+        }));
+    });
+    it("sets PORT env variable", async () => {
+        mockEnsureFree.mockResolvedValue(true);
+        await devMode("4000", ["node", "server.js"], {});
+        const spawnCall = mockSpawn.mock.calls[0];
+        expect(spawnCall[1].env.PORT).toBe("4000");
+    });
+    it("errors when port cannot be freed", async () => {
+        mockEnsureFree.mockResolvedValue(false);
+        await devMode("3000", ["npm", "start"], {});
+        expect(error).toHaveBeenCalledWith(expect.stringContaining("port is still in use"));
+        expect(process.exitCode).toBe(1);
+        expect(mockSpawn).not.toHaveBeenCalled();
+    });
+    it("passes force option through", async () => {
+        mockEnsureFree.mockResolvedValue(true);
+        await devMode("3000", ["npm", "start"], { force: true });
+        expect(mockEnsureFree).toHaveBeenCalledWith(3000, true);
+    });
+});

package/dist/__tests__/commands/doctor.test.d.ts

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

package/dist/__tests__/commands/doctor.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+vi.mock("../../platform/detector.js", () => ({
+    getPortStatuses: vi.fn(),
+}));
+vi.mock("../../platform/killer.js", () => ({
+    killAndVerify: vi.fn(),
+}));
+vi.mock("../../ui/prompts.js", () => ({
+    confirmKillAll: vi.fn(),
+}));
+vi.mock("../../ui/output.js", () => ({
+    info: vi.fn(),
+    success: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    showPortTable: vi.fn(),
+}));
+import { doctor } from "../../commands/doctor.js";
+import { getPortStatuses } from "../../platform/detector.js";
+import { killAndVerify } from "../../platform/killer.js";
+import { confirmKillAll } from "../../ui/prompts.js";
+import { success, warn, error } from "../../ui/output.js";
+const mockGetStatuses = vi.mocked(getPortStatuses);
+const mockKillAndVerify = vi.mocked(killAndVerify);
+const mockConfirmAll = vi.mocked(confirmKillAll);
+beforeEach(() => {
+    vi.clearAllMocks();
+    process.exitCode = undefined;
+});
+describe("doctor", () => {
+    it("reports all ports free when nothing is busy", async () => {
+        mockGetStatuses.mockResolvedValue([
+            { port: 3000, inUse: false },
+            { port: 8080, inUse: false },
+        ]);
+        await doctor({});
+        expect(success).toHaveBeenCalledWith(expect.stringContaining("All ports are free"));
+    });
+    it("shows busy ports and prompts to kill", async () => {
+        mockGetStatuses.mockResolvedValue([
+            { port: 3000, inUse: true, process: { pid: 1234, name: "node", port: 3000, protocol: "tcp" } },
+            { port: 8080, inUse: false },
+        ]);
+        mockConfirmAll.mockResolvedValue(true);
+        mockKillAndVerify.mockResolvedValue(true);
+        await doctor({});
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("1 port is in use"));
+        expect(mockKillAndVerify).toHaveBeenCalledWith(1234, 3000, false);
+        expect(success).toHaveBeenCalledWith(expect.stringContaining("All ports are now free"));
+    });
+    it("aborts when user declines", async () => {
+        mockGetStatuses.mockResolvedValue([
+            { port: 3000, inUse: true, process: { pid: 1234, name: "node", port: 3000, protocol: "tcp" } },
+        ]);
+        mockConfirmAll.mockResolvedValue(false);
+        await doctor({});
+        expect(mockKillAndVerify).not.toHaveBeenCalled();
+    });
+    it("force-kills without prompting", async () => {
+        mockGetStatuses.mockResolvedValue([
+            { port: 3000, inUse: true, process: { pid: 1234, name: "node", port: 3000, protocol: "tcp" } },
+            { port: 5173, inUse: true, process: { pid: 5678, name: "vite", port: 5173, protocol: "tcp" } },
+        ]);
+        mockKillAndVerify.mockResolvedValue(true);
+        await doctor({ force: true });
+        expect(mockConfirmAll).not.toHaveBeenCalled();
+        expect(mockKillAndVerify).toHaveBeenCalledTimes(2);
+        expect(success).toHaveBeenCalledWith(expect.stringContaining("All ports are now free"));
+    });
+    it("uses custom port list when provided", async () => {
+        mockGetStatuses.mockResolvedValue([
+            { port: 4000, inUse: false },
+            { port: 4001, inUse: false },
+        ]);
+        await doctor({ ports: "4000,4001" });
+        expect(mockGetStatuses).toHaveBeenCalledWith([4000, 4001]);
+    });
+    it("sets exitCode when some kills fail", async () => {
+        mockGetStatuses.mockResolvedValue([
+            { port: 3000, inUse: true, process: { pid: 1234, name: "node", port: 3000, protocol: "tcp" } },
+        ]);
+        mockKillAndVerify.mockResolvedValue(false);
+        await doctor({ force: true });
+        expect(error).toHaveBeenCalledWith(expect.stringContaining("Failed"));
+        expect(process.exitCode).toBe(1);
+    });
+});

package/dist/__tests__/commands/free.test.d.ts

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

package/dist/__tests__/commands/free.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+// Mock modules before importing the command
+vi.mock("../../platform/detector.js", () => ({
+    getProcessOnPort: vi.fn(),
+}));
+vi.mock("../../platform/killer.js", () => ({
+    killAndVerify: vi.fn(),
+}));
+vi.mock("../../ui/prompts.js", () => ({
+    confirmKill: vi.fn(),
+}));
+vi.mock("../../ui/output.js", () => ({
+    info: vi.fn(),
+    success: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    showProcess: vi.fn(),
+}));
+import { freePort, ensurePortFree } from "../../commands/free.js";
+import { getProcessOnPort } from "../../platform/detector.js";
+import { killAndVerify } from "../../platform/killer.js";
+import { confirmKill } from "../../ui/prompts.js";
+import { success, error } from "../../ui/output.js";
+const mockGetProcess = vi.mocked(getProcessOnPort);
+const mockKillAndVerify = vi.mocked(killAndVerify);
+const mockConfirmKill = vi.mocked(confirmKill);
+beforeEach(() => {
+    vi.clearAllMocks();
+    process.exitCode = undefined;
+});
+describe("freePort", () => {
+    it("reports port is free when nothing is using it", async () => {
+        mockGetProcess.mockResolvedValue(null);
+        await freePort("3000", {});
+        expect(success).toHaveBeenCalledWith(expect.stringContaining("already free"));
+    });
+    it("kills process with --force without prompting", async () => {
+        mockGetProcess.mockResolvedValue({ pid: 1234, name: "node", port: 3000, protocol: "tcp" });
+        mockKillAndVerify.mockResolvedValue(true);
+        await freePort("3000", { force: true });
+        expect(mockConfirmKill).not.toHaveBeenCalled();
+        expect(mockKillAndVerify).toHaveBeenCalledWith(1234, 3000, true);
+        expect(success).toHaveBeenCalledWith(expect.stringContaining("now free"));
+    });
+    it("prompts for confirmation and aborts when declined", async () => {
+        mockGetProcess.mockResolvedValue({ pid: 1234, name: "node", port: 3000, protocol: "tcp" });
+        mockConfirmKill.mockResolvedValue(false);
+        await freePort("3000", {});
+        expect(mockKillAndVerify).not.toHaveBeenCalled();
+    });
+    it("prompts for confirmation and kills when accepted", async () => {
+        mockGetProcess.mockResolvedValue({ pid: 1234, name: "node", port: 3000, protocol: "tcp" });
+        mockConfirmKill.mockResolvedValue(true);
+        mockKillAndVerify.mockResolvedValue(true);
+        await freePort("3000", {});
+        expect(mockKillAndVerify).toHaveBeenCalledWith(1234, 3000, undefined);
+        expect(success).toHaveBeenCalledWith(expect.stringContaining("now free"));
+    });
+    it("sets exitCode when kill fails", async () => {
+        mockGetProcess.mockResolvedValue({ pid: 1234, name: "node", port: 3000, protocol: "tcp" });
+        mockKillAndVerify.mockResolvedValue(false);
+        await freePort("3000", { force: true });
+        expect(error).toHaveBeenCalledWith(expect.stringContaining("Failed"));
+        expect(process.exitCode).toBe(1);
+    });
+    it("throws for invalid port", async () => {
+        await expect(freePort("abc", {})).rejects.toThrow("Invalid port");
+    });
+});
+describe("ensurePortFree", () => {
+    it("returns true when port is already free", async () => {
+        mockGetProcess.mockResolvedValue(null);
+        const result = await ensurePortFree(3000, false);
+        expect(result).toBe(true);
+    });
+    it("returns false when user declines kill", async () => {
+        mockGetProcess.mockResolvedValue({ pid: 1234, name: "node", port: 3000, protocol: "tcp" });
+        mockConfirmKill.mockResolvedValue(false);
+        const result = await ensurePortFree(3000, false);
+        expect(result).toBe(false);
+    });
+    it("force-kills without prompting", async () => {
+        mockGetProcess.mockResolvedValue({ pid: 1234, name: "node", port: 3000, protocol: "tcp" });
+        mockKillAndVerify.mockResolvedValue(true);
+        const result = await ensurePortFree(3000, true);
+        expect(result).toBe(true);
+        expect(mockConfirmKill).not.toHaveBeenCalled();
+    });
+});

package/dist/__tests__/commands/switch.test.d.ts

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

package/dist/__tests__/commands/switch.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+vi.mock("../../platform/detector.js", () => ({
+    getProcessOnPort: vi.fn(),
+}));
+vi.mock("../../ui/output.js", () => ({
+    info: vi.fn(),
+    success: vi.fn(),
+}));
+vi.mock("../../utils/ports.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        findNextFreePort: vi.fn(),
+    };
+});
+import { switchPort } from "../../commands/switch.js";
+import { getProcessOnPort } from "../../platform/detector.js";
+import { info, success } from "../../ui/output.js";
+import { findNextFreePort } from "../../utils/ports.js";
+const mockGetProcess = vi.mocked(getProcessOnPort);
+const mockFindNext = vi.mocked(findNextFreePort);
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+describe("switchPort", () => {
+    it("reports port is available when not in use", async () => {
+        mockGetProcess.mockResolvedValue(null);
+        await switchPort("3000");
+        expect(success).toHaveBeenCalledWith(expect.stringContaining("already available"));
+    });
+    it("finds next free port when port is busy", async () => {
+        mockGetProcess.mockResolvedValue({ pid: 1234, name: "node", port: 3000, protocol: "tcp" });
+        mockFindNext.mockResolvedValue(3001);
+        await switchPort("3000");
+        expect(info).toHaveBeenCalledWith(expect.stringContaining("in use"));
+        expect(mockFindNext).toHaveBeenCalledWith(3001);
+        expect(success).toHaveBeenCalledWith(expect.stringContaining("3001"));
+    });
+});

package/dist/__tests__/platform/detector.test.d.ts

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

package/dist/__tests__/platform/detector.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import { createServer } from "node:net";
+import { getProcessOnPort, getPortStatuses } from "../../platform/detector.js";
+describe("getProcessOnPort", () => {
+    it("returns null for a port that is not in use", async () => {
+        // Use a high ephemeral port unlikely to be in use
+        const result = await getProcessOnPort(59999);
+        expect(result).toBeNull();
+    });
+    it("detects a process listening on a port", async () => {
+        const server = createServer();
+        const port = await new Promise((resolve) => {
+            server.listen(0, () => {
+                const addr = server.address();
+                if (addr && typeof addr !== "string") {
+                    resolve(addr.port);
+                }
+            });
+        });
+        try {
+            const result = await getProcessOnPort(port);
+            expect(result).not.toBeNull();
+            expect(result.port).toBe(port);
+            expect(result.pid).toBe(process.pid);
+            expect(result.protocol).toBe("tcp");
+            expect(typeof result.name).toBe("string");
+            expect(result.name.length).toBeGreaterThan(0);
+        }
+        finally {
+            server.close();
+        }
+    });
+});
+describe("getPortStatuses", () => {
+    it("returns statuses for multiple ports", async () => {
+        const server = createServer();
+        const busyPort = await new Promise((resolve) => {
+            server.listen(0, () => {
+                const addr = server.address();
+                if (addr && typeof addr !== "string") {
+                    resolve(addr.port);
+                }
+            });
+        });
+        try {
+            const statuses = await getPortStatuses([busyPort, 59998]);
+            expect(statuses).toHaveLength(2);
+            const busyStatus = statuses.find((s) => s.port === busyPort);
+            expect(busyStatus.inUse).toBe(true);
+            expect(busyStatus.process).toBeDefined();
+            expect(busyStatus.process.pid).toBe(process.pid);
+            const freeStatus = statuses.find((s) => s.port === 59998);
+            expect(freeStatus.inUse).toBe(false);
+            expect(freeStatus.process).toBeUndefined();
+        }
+        finally {
+            server.close();
+        }
+    });
+    it("returns empty array for empty input", async () => {
+        const statuses = await getPortStatuses([]);
+        expect(statuses).toHaveLength(0);
+    });
+});

package/dist/__tests__/platform/killer.test.d.ts

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

package/dist/__tests__/platform/killer.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import { fork } from "node:child_process";
+import { killProcess, killAndVerify } from "../../platform/killer.js";
+function spawnDummyServer(port) {
+    return new Promise((resolve, reject) => {
+        const child = fork("-e", [`require("net").createServer().listen(${port}, () => process.send("ready"))`], { execArgv: [], stdio: ["pipe", "pipe", "pipe", "ipc"] });
+        child.on("message", (msg) => {
+            if (msg === "ready") {
+                resolve({
+                    pid: child.pid,
+                    cleanup: () => {
+                        try {
+                            child.kill("SIGKILL");
+                        }
+                        catch { }
+                    },
+                });
+            }
+        });
+        child.on("error", reject);
+        setTimeout(() => reject(new Error("Timed out waiting for child server")), 5000);
+    });
+}
+describe("killProcess", () => {
+    it("kills a running process", async () => {
+        const child = fork("-e", ["setTimeout(() => {}, 60000)"], {
+            execArgv: [],
+            stdio: "pipe",
+        });
+        // Give it a moment to start
+        await new Promise((r) => setTimeout(r, 200));
+        const result = await killProcess(child.pid, true);
+        expect(result).toBe(true);
+        // Verify the process is gone
+        await new Promise((r) => setTimeout(r, 500));
+        let alive = true;
+        try {
+            process.kill(child.pid, 0);
+        }
+        catch {
+            alive = false;
+        }
+        expect(alive).toBe(false);
+    });
+    it("returns false for a non-existent PID", async () => {
+        const result = await killProcess(999999, true);
+        expect(result).toBe(false);
+    });
+});
+describe("killAndVerify", () => {
+    it("kills a process and verifies the port is freed", async () => {
+        const port = 49321;
+        let helper = null;
+        try {
+            helper = await spawnDummyServer(port);
+            const result = await killAndVerify(helper.pid, port, true);
+            expect(result).toBe(true);
+        }
+        finally {
+            if (helper)
+                helper.cleanup();
+        }
+    });
+});

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

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

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

@@ -0,0 +1,22 @@
+import { describe, it, expect } from "vitest";
+import { run } from "../../utils/exec.js";
+describe("run", () => {
+    it("executes a simple command and returns stdout", async () => {
+        const { stdout } = await run("echo hello");
+        expect(stdout.trim()).toBe("hello");
+    });
+    it("returns stderr on error without throwing", async () => {
+        const result = await run("node -e \"process.stderr.write('oops'); process.exit(1)\"");
+        expect(result.stderr).toContain("oops");
+    });
+    it("returns empty strings for a command that produces no output", async () => {
+        const result = await run("node -e \"\"");
+        expect(result.stdout).toBe("");
+    });
+    it("handles non-existent commands gracefully", async () => {
+        const result = await run("nonexistentcommand12345");
+        // Should not throw, returns empty or error output
+        expect(result).toHaveProperty("stdout");
+        expect(result).toHaveProperty("stderr");
+    });
+});