process-killer-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MD Milon
+
+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,260 @@
+# Port Killer CLI ⚡
+
+> A fast, cross-platform utility to safely kill processes using specific ports on Windows, macOS, and Linux.
+
+![npm version](https://img.shields.io/badge/version-1.0.0-blue)
+![license](https://img.shields.io/badge/license-MIT-green)
+![node version](https://img.shields.io/badge/node->=12.0.0-brightgreen)
+
+## 🎯 Features
+
+✨ **Cross-Platform** - Works on Windows, macOS, and Linux  
+🎯 **Interactive Menu** - Easy OS selection (no need to memorize commands)  
+🛡️ **Safe** - Always asks for confirmation before killing processes  
+⚙️ **Zero Dependencies** - Uses only Node.js built-in modules  
+🚀 **Fast** - Kills ports instantly  
+🎨 **Beautiful UI** - Colorized output with Unicode borders  
+📊 **Developer Info** - Shows package info on success
+
+## 📦 Installation
+
+```bash
+npm install -g port-killer-cli
+```
+
+## 🚀 Quick Start
+
+```bash
+port-killer
+```
+
+Then follow the prompts:
+
+1. **Select OS** - Choose your operating system (1=Windows, 2=macOS, 3=Linux)
+2. **Enter Port** - Type the port number (e.g., 3001, 8080, 5000)
+3. **Confirm** - Review the process info and confirm
+4. **Done!** - Port is freed and ready to use
+
+## 💡 Common Use Cases
+
+### Kill Node.js Server
+
+```bash
+$ port-killer
+
+Select your Operating System:
+  1) Windows
+  2) macOS
+  3) Linux
+
+Enter your choice (1, 2, or 3): 2
+✓ macOS selected
+
+Enter the port number you want to stop (e.g., 8087): 3000
+
+➜ Searching for processes using port 3000...
+
+Found process with PID: 12345 using port 3000
+Process Name: node
+Port: 3000
+PID: 12345
+
+Do you want to kill this process? (y/n): y
+
+✓ Port 3000 has been killed!
+
+You can now start your backend server on this port.
+
+```
+
+### Kill Java Application (Port 8080)
+
+```bash
+$ port-killer
+...
+Enter the port number you want to stop: 8080
+✓ Port 8080 has been killed!
+```
+
+### Kill Python Flask (Port 5000)
+
+```bash
+$ port-killer
+...
+Enter the port number you want to stop: 5000
+✓ Port 5000 has been killed!
+```
+
+## 🖥️ Supported Operating Systems
+
+| OS          | Status             | Notes                                  |
+| ----------- | ------------------ | -------------------------------------- |
+| **Windows** | ✅ Fully Supported | Uses `netstat`, `tasklist`, `taskkill` |
+| **macOS**   | ✅ Fully Supported | Uses `lsof`, `ps`, `fuser`             |
+| **Linux**   | ✅ Fully Supported | Uses `lsof`, `ps`, `fuser`             |
+
+## 📋 Requirements
+
+- **Node.js** >= 12.0.0
+- **npm** or **yarn**
+
+## 🔧 How It Works
+
+### Windows
+
+- Uses `netstat -ano` to find process by port
+- Uses `tasklist` to get process name
+- Uses `taskkill /PID X /F` to terminate process
+
+### macOS & Linux
+
+- Uses `lsof -ti:PORT` to find process by port
+- Uses `ps` to get process name
+- Uses `fuser -k PORT/tcp` to terminate process
+
+## ⚠️ Troubleshooting
+
+### Port Still Shows as In Use
+
+Some ports enter TIME_WAIT state. Wait 30-60 seconds and try again.
+
+### Permission Denied (macOS/Linux)
+
+The tool may need elevated privileges:
+
+```bash
+sudo port-killer
+```
+
+### Process Not Found
+
+Verify the port number is correct using:
+
+**Windows:**
+
+```bash
+netstat -ano | findstr :3000
+```
+
+**macOS/Linux:**
+
+```bash
+lsof -i :3000
+```
+
+### Port Command Not Found
+
+Make sure you installed it globally:
+
+```bash
+npm install -g port-killer-cli
+```
+
+## 🗑️ Uninstall
+
+```bash
+npm uninstall -g port-killer-cli
+```
+
+## 📚 Advanced Usage
+
+### Manual Port Killing (Without Tool)
+
+**Windows:**
+
+```powershell
+netstat -ano | findstr :3000
+taskkill /PID 12345 /F
+```
+
+**macOS/Linux:**
+
+```bash
+lsof -i :3000
+sudo kill -9 12345
+# OR
+sudo fuser -k 3000/tcp
+```
+
+## 🔄 Update to Latest Version
+
+```bash
+npm install -g port-killer-cli@latest
+```
+
+## 📝 What's New in v1.0.0
+
+- ✨ Initial release
+- 🎨 Beautiful colorized UI with Unicode borders
+- 🌍 Cross-platform support (Windows, macOS, Linux)
+- 📋 Interactive OS selection menu
+- 🎯 Safe operation with confirmation
+- 📊 Developer information display
+- ⚡ Zero external dependencies
+
+## 🤝 Contributing
+
+Contributions are welcome! Feel free to:
+
+- Report bugs
+- Suggest features
+- Submit pull requests
+
+[Visit GitHub Repository](https://github.com/devmilon923/port-killer-cli)
+
+## 📄 License
+
+MIT © Milon
+
+This project is open source and available under the MIT License.
+
+## 👨‍💻 Author
+
+**Milon Mia**
+
+- GitHub: [@devmilon923](https://github.com/devmilon923)
+- npm: [port-killer-cli](https://www.npmjs.com/package/port-killer-cli)
+- Email: dev.milon923@gmail.com
+
+## 🙏 Support
+
+If you found this tool helpful, please:
+
+- ⭐ Star on GitHub
+- 📢 Share with friends
+- 🐛 Report issues
+- 💡 Suggest improvements
+
+## FAQ
+
+**Q: Is it safe to use?**  
+A: Yes! The tool always asks for confirmation before killing any process.
+
+**Q: Can I use this on Windows?**  
+A: Yes! Full native Windows support without WSL.
+
+**Q: Do I need to remember commands?**  
+A: No! Interactive menu guides you through every step.
+
+**Q: What if I kill the wrong process?**  
+A: The tool shows process details before killing, so you can verify.
+
+**Q: Can I use this in scripts?**  
+A: This tool is interactive. For automation, use OS-specific commands directly.
+
+## 🎓 Learn More
+
+- [Node.js Documentation](https://nodejs.org/en/docs/)
+- [npm Documentation](https://docs.npmjs.com/)
+- [Port Management Guide](https://www.howtouselinux.com/linux/lsof-command)
+
+## 📞 Feedback
+
+Have questions or suggestions? Open an issue on GitHub:
+[GitHub Issues](https://github.com/devmilon923/port-killer-cli/issues)
+
+---
+
+**Made with ❤️ for Backend Developers**
+
+Happy coding! 🚀

package/bin/port-killer.js

@@ -0,0 +1,554 @@
+#!/usr/bin/env node
+
+import { execSync } from "child_process";
+import readline from "readline";
+import process from "process";
+
+// ============================================================================
+// Colors & Styling
+// ============================================================================
+
+const colors = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  bgRed: "\x1b[41m",
+  bgGreen: "\x1b[42m",
+  bgYellow: "\x1b[43m",
+  bgBlue: "\x1b[44m",
+  bgCyan: "\x1b[46m",
+};
+
+function c(text, color) {
+  return `${color}${text}${colors.reset}`;
+}
+
+function box(text, color = colors.cyan, width = 50) {
+  const padding = Math.max(0, width - text.length - 2);
+  const leftPad = Math.floor(padding / 2);
+  const rightPad = padding - leftPad;
+  return (
+    c(`┌${"─".repeat(width)}┐`, color) +
+    "\n" +
+    c(`│`, color) +
+    " ".repeat(leftPad) +
+    text +
+    " ".repeat(rightPad) +
+    c(`│`, color) +
+    "\n" +
+    c(`└${"─".repeat(width)}┘`, color)
+  );
+}
+
+function section(title, color = colors.cyan) {
+  return (
+    c(`╔${"═".repeat(title.length + 2)}╗`, color) +
+    "\n" +
+    c(`║ ${title} ║`, color) +
+    "\n" +
+    c(`╚${"═".repeat(title.length + 2)}╝`, color)
+  );
+}
+
+function line(color = colors.cyan, width = 54) {
+  return c(`${"─".repeat(width)}`, color);
+}
+
+function header() {
+  console.clear();
+  console.log("");
+  console.log(
+    c("╔═══════════════════════════════════════════════════════╗", colors.cyan),
+  );
+  console.log(
+    c("               PORT KILLER UTILITY v1.0.0", colors.bold + colors.cyan),
+  );
+  //   console.log(c("               Tool By Milon", colors.yellow));
+  console.log(
+    c("╚═══════════════════════════════════════════════════════╝", colors.cyan),
+  );
+  console.log("");
+}
+
+function info(text, icon = "➜") {
+  console.log(c(icon, colors.blue) + " " + text);
+}
+
+function success(text, icon = "✓") {
+  console.log(c(icon, colors.green) + " " + c(text, colors.green));
+}
+
+function error(text, icon = "✗") {
+  console.log(c(icon, colors.red) + " " + c(text, colors.red));
+}
+
+function warning(text, icon = "⚠") {
+  console.log(c(icon, colors.yellow) + " " + c(text, colors.yellow));
+}
+
+// ============================================================================
+// Display Functions
+// ============================================================================
+
+function showIntro() {
+  console.log(
+    c(
+      "┌─ INFORMATION ─────────────────────────────────────────┐",
+      colors.magenta,
+    ),
+  );
+  console.log(
+    c("│", colors.magenta) + " Common scenarios when you need this tool:",
+  );
+  console.log(
+    c("│", colors.magenta) +
+      " 1. Port 8087 already in use error during development",
+  );
+  console.log(
+    c("│", colors.magenta) +
+      " 2. Spring Boot application didn't shutdown properly",
+  );
+  console.log(
+    c("│", colors.magenta) + " 3. Multiple instances running on same port",
+  );
+  console.log(
+    c("│", colors.magenta) +
+      " 4. Clean up ports before starting new server instances",
+  );
+  console.log(
+    c(
+      "└───────────────────────────────────────────────────────┘",
+      colors.magenta,
+    ),
+  );
+  console.log("");
+}
+
+function showDevInfo() {
+  console.log("");
+  console.log(
+    c("╔═══════════════════════════════════════════════════════╗", colors.cyan),
+  );
+  console.log(
+    c("║", colors.cyan) +
+      c(
+        "               ✨ DEVELOPER INFORMATION ✨",
+        colors.bold + colors.green,
+      ),
+  );
+  console.log(
+    c("╠═══════════════════════════════════════════════════════║", colors.cyan),
+  );
+  console.log(
+    c("║", colors.cyan) +
+      c(" Developer         Milon Mia", colors.yellow).padEnd(54),
+  );
+  console.log(
+    c("║", colors.cyan) +
+      c(" Tool              Port Killer CLI", colors.yellow).padEnd(54),
+  );
+  console.log(
+    c("║", colors.cyan) +
+      c(" Version           1.0.0", colors.yellow).padEnd(54),
+  );
+  console.log(
+    c("║", colors.cyan) + c(" License           MIT", colors.yellow).padEnd(54),
+  );
+  console.log(
+    c("║", colors.cyan) +
+      c(" GitHub            github.com/devmilon923", colors.green).padEnd(54),
+  );
+  console.log(
+    c("║", colors.cyan) +
+      c(" LinkedIn          linkedin.com/in/devmilon", colors.green).padEnd(54),
+  );
+  console.log(
+    c("╚═══════════════════════════════════════════════════════╝", colors.cyan),
+  );
+  console.log("");
+}
+
+function showNotFound(port) {
+  console.log("");
+  warning(`No process found listening on port ${port}`);
+  console.log("");
+  console.log(
+    c(
+      "┌─ TROUBLESHOOTING ─────────────────────────────────────┐",
+      colors.yellow,
+    ),
+  );
+  console.log(c("│", colors.yellow) + " Try manually:");
+  console.log(c("│", colors.yellow));
+  console.log(c("│", colors.yellow) + c(" Windows:", colors.white));
+  console.log(c("│", colors.yellow) + "   netstat -ano | findstr :" + port);
+  console.log(c("│", colors.yellow) + "   taskkill /PID <PID> /F");
+  console.log(c("│", colors.yellow));
+  console.log(c("│", colors.yellow) + c(" Linux/macOS:", colors.white));
+  console.log(c("│", colors.yellow) + "   lsof -i :" + port);
+  console.log(c("│", colors.yellow) + "   sudo fuser -k " + port + "/tcp");
+  console.log(
+    c(
+      "└───────────────────────────────────────────────────────┘",
+      colors.yellow,
+    ),
+  );
+}
+
+function showOSMenu() {
+  console.log("");
+  console.log(
+    c("┌─ SELECT YOUR OPERATING SYSTEM ────────────────────────┐", colors.cyan),
+  );
+  console.log(c("│", colors.blue));
+  console.log(c("│", colors.blue) + c("  1) Windows", colors.yellow));
+  console.log(c("│", colors.blue) + c("  2) macOS", colors.yellow));
+  console.log(c("│", colors.blue) + c("  3) Linux", colors.yellow));
+  console.log(c("│", colors.blue));
+  console.log(
+    c("└───────────────────────────────────────────────────────┘", colors.cyan),
+  );
+  console.log("");
+}
+
+function showProcessInfo(pid, port, name) {
+  console.log("");
+  console.log(
+    c(
+      "╔─ PROCESS FOUND ───────────────────────────────────────╗",
+      colors.green,
+    ),
+  );
+  console.log(
+    c("║", colors.green) + ` PID:          ${String(pid).padEnd(45)}`,
+  );
+  console.log(
+    c("║", colors.green) + ` Port:         ${String(port).padEnd(45)}`,
+  );
+  console.log(
+    c("║", colors.green) + ` Process Name: ${String(name).padEnd(45)}`,
+  );
+  console.log(
+    c(
+      "╚───────────────────────────────────────────────────────╝",
+      colors.green,
+    ),
+  );
+  console.log("");
+}
+
+// ============================================================================
+// Windows Functions
+// ============================================================================
+
+function findProcessWindows(port) {
+  try {
+    const output = execSync("netstat -ano", { encoding: "utf-8" });
+    const lines = output.split("\n");
+
+    for (const line of lines) {
+      if (line.includes(`:${port}`) && line.includes("LISTENING")) {
+        const parts = line.trim().split(/\s+/);
+        return parts[parts.length - 1];
+      }
+    }
+    return null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function getProcessNameWindows(pid) {
+  try {
+    const output = execSync(`tasklist /FI "PID eq ${pid}" /FO table /NH`, {
+      encoding: "utf-8",
+    }).trim();
+
+    if (output && output.length > 0) {
+      return output.split(/\s+/)[0] || "Unknown";
+    }
+    return "Unknown";
+  } catch (e) {
+    return "Unknown";
+  }
+}
+
+function killPortWindows(pid) {
+  try {
+    execSync(`taskkill /PID ${pid} /F`, { stdio: "pipe" });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+// ============================================================================
+// Unix (Linux/macOS) Functions
+// ============================================================================
+
+function findProcessUnix(port) {
+  try {
+    const result = execSync(`lsof -ti:${port}`, { encoding: "utf-8" }).trim();
+    return result.split("\n")[0];
+  } catch (e) {
+    return null;
+  }
+}
+
+function getProcessNameUnix(pid) {
+  try {
+    return (
+      execSync(`ps -p ${pid} -o comm=`, { encoding: "utf-8" }).trim() ||
+      "Unknown"
+    );
+  } catch (e) {
+    return "Unknown";
+  }
+}
+
+function killPortUnix(port) {
+  try {
+    execSync(`fuser -k ${port}/tcp`, { stdio: "pipe" });
+    return true;
+  } catch (e1) {
+    try {
+      execSync(`sudo fuser -k ${port}/tcp`, { stdio: "pipe" });
+      return true;
+    } catch (e2) {
+      return false;
+    }
+  }
+}
+
+// ============================================================================
+// User Input
+// ============================================================================
+
+function getInput(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+function askConfirm(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+    });
+  });
+}
+
+// ============================================================================
+// OS Selection
+// ============================================================================
+
+async function selectOS() {
+  let osChoice;
+
+  while (true) {
+    showOSMenu();
+    osChoice = await getInput(c("Select option (e,g. 1,2,3): ", colors.cyan));
+
+    if (osChoice === "1") {
+      success("Windows selected");
+      console.log("");
+      return "windows";
+    } else if (osChoice === "2") {
+      success("macOS selected");
+      console.log("");
+      return "macos";
+    } else if (osChoice === "3") {
+      success("Linux selected");
+      console.log("");
+      return "linux";
+    } else {
+      error("Invalid choice! Please enter 1, 2, or 3.");
+      console.log("");
+    }
+  }
+}
+
+// ============================================================================
+// Main Logic by OS
+// ============================================================================
+
+async function runWindows(port) {
+  info(`Searching for processes using port ${port}...`);
+  console.log("");
+
+  const pid = findProcessWindows(port);
+
+  if (!pid) {
+    showNotFound(port);
+    return;
+  }
+
+  const name = getProcessNameWindows(pid);
+  showProcessInfo(pid, port, name);
+
+  const confirmed = await askConfirm(
+    c("Do you want to kill this process? (y/n): ", colors.cyan),
+  );
+
+  if (!confirmed) {
+    warning("Operation cancelled by user.");
+    console.log("");
+    return;
+  }
+
+  console.log("");
+  info("Terminating process...");
+  console.log("");
+
+  if (killPortWindows(pid)) {
+    success(`Port ${port} has been killed!`);
+    console.log("");
+    info("You can now start your backend server on this port.");
+    showDevInfo();
+  } else {
+    error(`Failed to kill the port! (PID: ${pid})`);
+    console.log("");
+    console.log(
+      c(
+        "┌─ SOLUTION ─────────────────────────────────────────────┐",
+        colors.red,
+      ),
+    );
+    console.log(c("│", colors.red) + " Try manually:");
+    console.log(c("│", colors.red));
+    console.log(
+      c("│", colors.red) + c(`  taskkill /PID ${pid} /F`, colors.white),
+    );
+    console.log(c("│", colors.red));
+    console.log(
+      c(
+        "└────────────────────────────────────────────────────────┘",
+        colors.red,
+      ),
+    );
+    console.log("");
+  }
+}
+
+async function runUnix(port) {
+  info(`Searching for processes using port ${port}...`);
+  console.log("");
+
+  const pid = findProcessUnix(port);
+
+  if (!pid) {
+    showNotFound(port);
+    return;
+  }
+
+  const name = getProcessNameUnix(pid);
+  showProcessInfo(pid, port, name);
+
+  const confirmed = await askConfirm(
+    c("Do you want to kill this process? (y/n): ", colors.cyan),
+  );
+
+  if (!confirmed) {
+    warning("Operation cancelled by user.");
+    console.log("");
+    return;
+  }
+
+  console.log("");
+  info("Terminating process...");
+  console.log("");
+
+  if (killPortUnix(port)) {
+    success(`Port ${port} has been killed!`);
+    console.log("");
+    info("You can now start your backend server on this port.");
+    showDevInfo();
+  } else {
+    error(`Failed to kill the port! (PID: ${pid})`);
+    console.log("");
+    console.log(
+      c(
+        "┌─ SOLUTION ─────────────────────────────────────────────┐",
+        colors.red,
+      ),
+    );
+    console.log(c("│", colors.red) + " Try manually:");
+    console.log(c("│", colors.red));
+    console.log(c("│", colors.red) + c(`  sudo kill -9 ${pid}`, colors.white));
+    console.log(
+      c("│", colors.red) + c(`  sudo fuser -k ${port}/tcp`, colors.white),
+    );
+    console.log(c("│", colors.red));
+    console.log(
+      c(
+        "└────────────────────────────────────────────────────────┘",
+        colors.red,
+      ),
+    );
+    console.log("");
+  }
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  header();
+  showIntro();
+
+  // Step 1: Select OS
+  const selectedOS = await selectOS();
+
+  // Step 2: Get port
+  let portInput = await getInput(
+    c("Enter the port number (e.g., 8087): ", colors.cyan),
+  );
+
+  if (!portInput.trim()) {
+    error("Please enter a port number!");
+    console.log("");
+    return;
+  }
+
+  const port = parseInt(portInput);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    error("Invalid port number! Port must be between 1 and 65535.");
+    console.log("");
+    return;
+  }
+
+  console.log("");
+
+  // Step 3: Run based on selected OS
+  if (selectedOS === "windows") {
+    await runWindows(port);
+  } else if (selectedOS === "macos" || selectedOS === "linux") {
+    await runUnix(port);
+  }
+}
+
+main().catch((err) => {
+  error("Error: " + err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "process-killer-cli",
+  "version": "1.0.0",
+  "description": "A utility to safely find and kill processes using specific ports on Linux/macOS. Perfect for backend developers dealing with port conflicts.",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "port-killer": "./bin/port-killer.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "port",
+    "kill",
+    "process",
+    "backend",
+    "development",
+    "utility",
+    "nodejs",
+    "spring-boot",
+    "port-conflict"
+  ],
+  "author": "Milon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/port-killer-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/port-killer-cli/issues"
+  },
+  "homepage": "https://github.com/yourusername/port-killer-cli#readme",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "preferGlobal": true,
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ]
+}