portcleaner 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shubhashish Chakraborty
+
+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,306 @@
+# 🧹 Clean Ports (cleanports CLI)
+
+Instantly kill stuck development servers and free your ports.
+
+`cleanports` is a lightweight CLI tool that scans your system for running development servers (Node, Bun, Deno, Python, Docker proxies, etc.) and automatically releases the ports they are occupying.
+
+No more:
+
+```
+EADDRINUSE: address already in use :::3000
+```
+
+---
+
+## 📚 Table of Contents
+
+* [Why this exists](#why-this-exists)
+* [Features](#features)
+* [Supported Platforms](#supported-platforms)
+* [Quick Install (Automatic - Recommended)](#quick-install-automatic-recommended)
+* [Manual Installation (Local Development)](#manual-installation-local-development)
+* [Usage](#usage)
+* [Add to your project workflow](#add-to-your-project-workflow)
+* [Uninstall / Disable cleanports](#uninstall--disable-cleanports)
+* [Re-enable later](#re-enable-later)
+* [Requirements](#requirements)
+* [How it works](#how-it-works)
+* [Troubleshooting](#troubleshooting)
+* [Contributing](#contributing)
+* [License](#license)
+
+---
+
+## Why this exists
+
+During development, servers often **do not shut down properly**:
+
+* Next.js / React dev servers
+* Express / Fastify APIs
+* Prisma / WebSocket servers
+* Docker containers
+* AI coding agents
+
+Even after closing the terminal, the process continues running in the background and blocks ports.
+
+Developers repeatedly run:
+
+```
+lsof -i :3000
+kill -9 <PID>
+```
+
+This tool automates that entire process.
+
+---
+
+## ✨ Features
+
+* Detects active listening ports
+* Finds development servers automatically
+* Safely terminates only dev processes
+* Does NOT affect OS system services
+* Works globally from any directory
+* One-command cleanup
+
+---
+
+## 💻 Supported Platforms
+
+| OS                                 | Support        |
+| ---------------------------------- | -------------- |
+| macOS                              | ✅ Full support |
+| Linux (Ubuntu, Debian, Arch, etc.) | ✅ Full support |
+| Windows (WSL)                      | ✅ Supported    |
+| Windows (PowerShell / CMD native)  | ⚠️ Limited     |
+
+### Important for Windows users
+
+Windows does not include the `lsof` utility.
+Please run this tool inside:
+
+* WSL (recommended)
+* Git Bash
+
+---
+
+## 🚀 Quick Install (Automatic — Recommended)
+
+This is the **normal user method**.
+
+```
+npm install -g clean-ports
+```
+
+After installation, simply run:
+
+```
+cleanports
+```
+
+That’s it. No linking. No configuration.
+
+The installer automatically:
+
+* registers the CLI command
+* grants permissions
+* verifies environment
+
+---
+
+## 🛠 Manual Installation (Local Development)
+
+Use this if you cloned the repository.
+
+```
+git clone https://github.com/<your-username>/clean-ports.git
+cd clean-ports
+npm install
+npm link
+```
+
+Now the command works globally:
+
+```
+cleanports
+```
+
+---
+
+## ▶️ Usage
+
+Run:
+
+```
+cleanports
+```
+
+Example output:
+
+```
+🔍 Scanning for running dev servers...
+
+⚠️ Found running servers:
+
+• node running on port 3000 (PID 5542)
+• docker-proxy running on port 5432 (PID 8821)
+
+🧹 Cleaning ports...
+
+❌ Killed node on port 3000
+❌ Killed docker-proxy on port 5432
+
+🎉 All development ports cleaned!
+```
+
+---
+
+## 🔁 Add to your project workflow
+
+You can automatically clean ports before starting your app.
+
+Add inside any project's `package.json`:
+
+```
+"scripts": {
+  "dev": "cleanports && npm run start"
+}
+```
+
+or for Next.js:
+
+```
+"dev": "cleanports && next dev"
+```
+
+Now every time your project starts → ports are cleaned first.
+
+---
+
+## ❌ Uninstall / Disable cleanports
+
+If you no longer want the `cleanports` command on your system:
+
+### If installed globally (recommended install)
+
+```
+npm uninstall -g clean-ports
+```
+
+### If installed via `npm link`
+
+Inside the project folder:
+
+```
+npm unlink -g clean-ports
+```
+
+After uninstalling, running:
+
+```
+cleanports
+```
+
+will no longer work.
+
+---
+
+## 🔄 Re-enable later
+
+You can always reinstall:
+
+```
+npm install -g clean-ports
+```
+
+The command will immediately start working again.
+
+---
+
+## 📦 Requirements
+
+* Node.js v16 or newer
+* macOS or Linux (native support)
+* Windows requires WSL or Git Bash
+
+Check Node version:
+
+```
+node -v
+```
+
+---
+
+## ⚙️ How it works
+
+The CLI internally runs:
+
+```
+lsof -i -P -n | grep LISTEN
+```
+
+It filters only known development processes:
+
+* node
+* bun
+* deno
+* python
+* docker
+* docker-proxy
+
+Then safely terminates them using system signals.
+
+---
+
+## 🧯 Troubleshooting
+
+### `cleanports: command not found`
+
+Restart terminal or run:
+
+```
+source ~/.zshrc
+```
+
+---
+
+### Permission denied
+
+```
+chmod +x bin/cleanports.js
+```
+
+---
+
+### Nothing was killed
+
+Verify something is actually using a port:
+
+```
+lsof -i :3000
+```
+
+---
+
+## 🤝 Contributing
+
+Pull requests are welcome.
+
+Possible improvements:
+
+* interactive confirmation mode
+* port range filtering
+* Windows native support
+* database port exclusions (5432, 27017)
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 👨‍💻 Author
+
+Shubhashish Chakraborty

package/bin/cleanports.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+
+console.log("🔍 Scanning for running dev servers...\n");
+
+try {
+  const output = execSync("lsof -i -P -n | grep LISTEN", {
+    encoding: "utf8",
+  });
+
+  const lines = output.split("\n");
+
+  const targets = [];
+
+  lines.forEach((line) => {
+    if (!line.trim()) return;
+
+    const parts = line.trim().split(/\s+/);
+    const command = parts[0];
+    const pid = parts[1];
+    const portMatch = line.match(/:(\d+)\s/);
+
+    if (!portMatch) return;
+    const port = portMatch[1];
+
+    // Only kill development servers
+    const allowedProcesses = [
+      "node",
+      "bun",
+      "deno",
+      "docker",
+      "docker-proxy",
+      "python",
+      "python3",
+    ];
+
+    if (allowedProcesses.includes(command)) {
+      targets.push({ pid, port, command });
+    }
+  });
+
+  if (targets.length === 0) {
+    console.log("✅ No dev servers found. All ports clean.\n");
+    process.exit(0);
+  }
+
+  console.log("⚠️ Found running servers:\n");
+
+  targets.forEach((t) => {
+    console.log(`• ${t.command} running on port ${t.port} (PID ${t.pid})`);
+  });
+
+  console.log("\n🧹 Cleaning ports...\n");
+
+  targets.forEach((t) => {
+    try {
+      process.kill(t.pid, "SIGKILL");
+      console.log(`✅ Killed ${t.command} on port ${t.port}`);
+    } catch (err) {
+      console.log(`⚠️ Could not kill PID ${t.pid}`);
+    }
+  });
+
+  console.log("\n🎉 All development ports cleaned!\n");
+
+} catch (err) {
+  console.log("✅ No listening processes found.");
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "portcleaner",
+  "version": "1.0.0",
+  "description": "A CLI utility that detects and terminates stuck development servers to free ports.",
+  "main": "index.js",
+  "preferGlobal": true,
+  "bin": {
+    "cleanports": "./bin/cleanports.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": ["ports", "kill-port", "dev-tools", "node", "cli"],
+  "author": "Shubhashish Chakraborty",
+  "license": "MIT",
+  "type": "commonjs"
+}