port-nuker 1.0.0 → 1.0.1

package/README.md

@@ -26,11 +26,20 @@ npx port-nuker 3000
 ## Usage
 
 ```bash
+# Kill process on specific port
 nuke <PORT>
+
+# Kill and wait until port is actually free
+nuke <PORT> --wait
+
+# List all active ports and select one to kill interactively
+nuke list
 ```
 
 ### Examples
 
+**Direct Port Killing:**
+
 ```bash
 # Kill process on port 3000
 nuke 3000
@@ -42,12 +51,48 @@ nuke 8080
 npx port-nuker 3000
 ```
 
+**Interactive Port Selection:**
+
+```bash
+# List all active ports with details
+nuke list
+
+# You'll see a table like this:
+# ┌──────┬──────────┬──────────┬──────────────────────────────┬───────────────┬────────────┐
+# │ Port │ PID      │ Protocol │ Command                      │ User          │ Memory     │
+# ├──────┼──────────┼──────────┼──────────────────────────────┼───────────────┼────────────┤
+# │ 3000 │ 12345    │ TCP      │ node.exe                     │ username      │ 45,232 K   │
+# │ 8080 │ 67890    │ TCP      │ java.exe                     │ username      │ 128,456 K  │
+# └──────┴──────────┴──────────┴──────────────────────────────┴───────────────┴────────────┘
+#
+# Use arrow keys to select a process and press Enter to kill it
+```
+
+**Wait Mode (Command Chaining):**
+
+```bash
+# Kill and wait for port to be released (polls every 500ms)
+nuke 3000 --wait
+
+# Chain commands - start dev server only after port is free
+nuke 3000 --wait && npm run dev
+
+# Works with stubborn processes that take time to release sockets
+nuke 8080 --wait && docker-compose up
+
+# Timeout after 30 seconds if port isn't released
+nuke 5000 --wait && echo "Port is free!"
+```
+
 ## Features
 
 - **Cross-Platform**: Works on Windows (using `netstat` + `taskkill`) and Unix-like systems (Linux/macOS using `lsof` + `kill`)
+- **Interactive Mode**: Browse all active ports with `nuke list` and select which one to kill
+- **Wait Mode**: Block until port is actually released with `--wait` flag for safe command chaining
+- **Detailed Process Info**: See PID, command name, user, memory usage, and protocol for each port
 - **Fast**: Instantly frees up your port
-- **Safe**: Checks if the port matches exactly to avoid killing wrong processes (e.g., `nuke 80` won't kill `8080`)
-- **Zero Dependencies**: No external packages required
+- **Safe**: Confirmation prompt before killing processes in interactive mode
+- **Exact Port Matching**: `nuke 80` won't kill processes on `8080`
 - **Simple**: Just one command to remember
 
 ## Common Use Cases

package/index.js

@@ -1,21 +1,346 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const { exec } = require('child_process');
 const os = require('os');
+const inquirer = require('inquirer');
+const Table = require('cli-table3');
 
-const port = process.argv[2];
+const args = process.argv.slice(2);
 
-if (!port) {
-  console.error('Please specify a port to nuke. Usage: nuke <PORT>');
+// Parse arguments
+let port = null;
+let shouldWait = false;
+let command = null;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--wait') {
+    shouldWait = true;
+  } else if (args[i] === 'list') {
+    command = 'list';
+  } else if (!isNaN(args[i])) {
+    port = args[i];
+  }
+}
+
+// Handle different commands
+if (command === 'list') {
+  listPorts();
+} else if (port) {
+  // nuke <PORT> [--wait]
+  nukePort(port, shouldWait);
+} else {
+  console.error('Usage:');
+  console.error('  nuke <PORT>           Kill process on specific port');
+  console.error('  nuke <PORT> --wait    Kill process and wait until port is free');
+  console.error('  nuke list             List all active ports and select one to kill');
   process.exit(1);
 }
 
-console.log(`Searching for process holding port ${port}...`);
+// List all active ports with process details
+function listPorts() {
+  const platform = os.platform();
+  let listCommand;
+  
+  if (platform === 'win32') {
+    // Get network connections and process details
+    listCommand = 'netstat -ano';
+  } else {
+    // Unix-like: get detailed process info
+    listCommand = 'lsof -i -P -n';
+  }
+
+  console.log('Scanning for active ports...\n');
+
+  exec(listCommand, (error, stdout, stderr) => {
+    if (error) {
+      console.error(`Error scanning ports: ${error.message}`);
+      process.exit(1);
+    }
+
+    const processes = parseProcessList(stdout, platform);
+
+    if (processes.length === 0) {
+      console.log('No active ports found.');
+      process.exit(0);
+    }
+
+    displayPortsTable(processes);
+    promptKillProcess(processes);
+  });
+}
+
+// Parse process list based on platform
+function parseProcessList(output, platform) {
+  const processMap = new Map();
+
+  if (platform === 'win32') {
+    const lines = output.trim().split('\n');
+    
+    lines.forEach(line => {
+      const parts = line.trim().split(/\s+/);
+      // Proto Local-Address Foreign-Address State PID
+      // TCP 0.0.0.0:3000 0.0.0.0:0 LISTENING 1234
+      
+      if (parts.length >= 5 && (parts[0] === 'TCP' || parts[0] === 'UDP')) {
+        const localAddress = parts[1];
+        const state = parts[3];
+        const pid = parts[4];
+        
+        // Only show LISTENING ports
+        if (state === 'LISTENING') {
+          const lastColonIndex = localAddress.lastIndexOf(':');
+          const port = localAddress.substring(lastColonIndex + 1);
+          const protocol = parts[0];
+          
+          const key = `${pid}-${port}`;
+          if (!processMap.has(key)) {
+            processMap.set(key, {
+              pid,
+              port,
+              protocol,
+              command: 'Loading...',
+              user: os.userInfo().username,
+              memory: 'N/A'
+            });
+          }
+        }
+      }
+    });
+
+    // Get process details for each PID
+    const pids = [...new Set([...processMap.values()].map(p => p.pid))];
+    getWindowsProcessDetails(pids, processMap);
+    
+  } else {
+    // Unix-like systems
+    const lines = output.trim().split('\n');
+    
+    lines.forEach((line, index) => {
+      if (index === 0) return; // Skip header
+      
+      const parts = line.trim().split(/\s+/);
+      // COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
+      
+      if (parts.length >= 9) {
+        const command = parts[0];
+        const pid = parts[1];
+        const user = parts[2];
+        const name = parts[parts.length - 1];
+        
+        // Parse port from NAME (e.g., *:3000, 127.0.0.1:8080)
+        const portMatch = name.match(/:(\d+)$/);
+        if (portMatch) {
+          const port = portMatch[1];
+          const protocol = parts[7] === 'TCP' ? 'TCP' : 'UDP';
+          
+          const key = `${pid}-${port}`;
+          if (!processMap.has(key)) {
+            processMap.set(key, {
+              pid,
+              port,
+              protocol,
+              command,
+              user,
+              memory: 'N/A'
+            });
+          }
+        }
+      }
+    });
+  }
+
+  return Array.from(processMap.values()).sort((a, b) => 
+    parseInt(a.port) - parseInt(b.port)
+  );
+}
+
+// Get detailed process info on Windows
+function getWindowsProcessDetails(pids, processMap) {
+  if (pids.length === 0) return;
+  
+  const tasklistCmd = `tasklist /FI "PID eq ${pids.join('" /FI "PID eq ')}" /FO CSV /NH`;
+  
+  exec(tasklistCmd, (error, stdout) => {
+    if (!error && stdout) {
+      const lines = stdout.trim().split('\n');
+      
+      lines.forEach(line => {
+        // "Image Name","PID","Session Name","Session#","Mem Usage"
+        const matches = line.match(/"([^"]+)"/g);
+        if (matches && matches.length >= 5) {
+          const imageName = matches[0].replace(/"/g, '');
+          const pid = matches[1].replace(/"/g, '');
+          const memory = matches[4].replace(/"/g, '');
+          
+          // Update all entries with this PID
+          processMap.forEach(process => {
+            if (process.pid === pid) {
+              process.command = imageName;
+              process.memory = memory;
+            }
+          });
+        }
+      });
+    }
+  });
+}
+
+// Display ports in a formatted table
+function displayPortsTable(processes) {
+  const table = new Table({
+    head: ['Port', 'PID', 'Protocol', 'Command', 'User', 'Memory'],
+    colWidths: [8, 10, 10, 30, 15, 12],
+    style: {
+      head: ['cyan', 'bold'],
+      border: ['gray']
+    }
+  });
+
+  processes.forEach(p => {
+    table.push([
+      p.port,
+      p.pid,
+      p.protocol,
+      p.command.length > 28 ? p.command.substring(0, 25) + '...' : p.command,
+      p.user.length > 13 ? p.user.substring(0, 10) + '...' : p.user,
+      p.memory
+    ]);
+  });
+
+  console.log(table.toString());
+  console.log('');
+}
+
+// Prompt user to select and kill a process
+async function promptKillProcess(processes) {
+  const choices = processes.map(p => ({
+    name: `Port ${p.port} - ${p.command} (PID: ${p.pid})`,
+    value: p.pid
+  }));
+
+  choices.push(new inquirer.Separator());
+  choices.push({ name: 'Cancel', value: null });
+
+  try {
+    const answer = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'pid',
+        message: 'Select a process to kill:',
+        choices,
+        pageSize: 15
+      }
+    ]);
+
+    if (answer.pid) {
+      const selectedProcess = processes.find(p => p.pid === answer.pid);
+      
+      const confirm = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'confirmed',
+          message: `Kill process ${selectedProcess.command} (PID: ${answer.pid}) on port ${selectedProcess.port}?`,
+          default: false
+        }
+      ]);
 
-function nukePort(port) {
+      if (confirm.confirmed) {
+        console.log(`\nNuking process ${answer.pid}...`);
+        killPid(answer.pid);
+      } else {
+        console.log('Cancelled.');
+      }
+    } else {
+      console.log('Cancelled.');
+    }
+  } catch (error) {
+    if (error.isTtyError) {
+      console.error('Interactive mode not supported in this environment.');
+    } else {
+      console.error('Selection cancelled.');
+    }
+  }
+}
+
+// Check if a port is currently in use
+function checkPortInUse(port, callback) {
+  const platform = os.platform();
+  let checkCommand;
+  
+  if (platform === 'win32') {
+    checkCommand = `netstat -ano | findstr :${port}`;
+  } else {
+    checkCommand = `lsof -i :${port} -t`;
+  }
+
+  exec(checkCommand, (error, stdout) => {
+    if (error || !stdout) {
+      // Port is free
+      callback(false);
+      return;
+    }
+
+    // Check if it's the exact port (for Windows)
+    if (platform === 'win32') {
+      const lines = stdout.trim().split('\n');
+      let found = false;
+      
+      lines.forEach(line => {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length > 1) {
+          const localAddress = parts[1];
+          const lastColonIndex = localAddress.lastIndexOf(':');
+          const portFound = localAddress.substring(lastColonIndex + 1);
+          
+          if (portFound === port) {
+            found = true;
+          }
+        }
+      });
+      
+      callback(found);
+    } else {
+      // Unix: lsof -t returns PIDs if port is in use
+      callback(stdout.trim().length > 0);
+    }
+  });
+}
+
+// Poll port until it's free
+function pollPortUntilFree(port, maxWaitSeconds = 30) {
+  console.log(`Waiting for port ${port} to be released...`);
+  
+  const pollInterval = 500; // ms
+  const maxAttempts = (maxWaitSeconds * 1000) / pollInterval;
+  let attempts = 0;
+
+  const interval = setInterval(() => {
+    checkPortInUse(port, (inUse) => {
+      if (!inUse) {
+        clearInterval(interval);
+        console.log(`\nPort ${port} is now free!`);
+        process.exit(0);
+      }
+      
+      attempts++;
+      process.stdout.write('.');
+      
+      if (attempts >= maxAttempts) {
+        clearInterval(interval);
+        console.error(`\nTimeout: Port ${port} is still in use after ${maxWaitSeconds} seconds`);
+        process.exit(1);
+      }
+    });
+  }, pollInterval);
+}
+
+// Original nuke port function
+function nukePort(port, shouldWait = false) {
   const platform = os.platform();
   let findCommand;
   
+  console.log(`Searching for process holding port ${port}...`);
+  
   if (platform === 'win32') {
     findCommand = `netstat -ano | findstr :${port}`;
   } else {
@@ -79,12 +404,19 @@ function nukePort(port) {
 
     pids.forEach(pid => {
       console.log(`Found process with PID: ${pid}. Nuking it...`);
-      killPid(pid);
+      killPid(pid, () => {
+        if (shouldWait) {
+          // Wait a moment for the process to fully terminate
+          setTimeout(() => {
+            pollPortUntilFree(port);
+          }, 1000);
+        }
+      });
     });
   });
 }
 
-function killPid(pid) {
+function killPid(pid, callback) {
   const platform = os.platform();
   let killCommand;
 
@@ -97,10 +429,10 @@ function killPid(pid) {
   exec(killCommand, (error, stdout, stderr) => {
     if (error) {
       console.error(`Failed to kill process ${pid}: ${error.message}`);
+      if (callback) callback(error);
       return;
     }
     console.log(`Successfully nuked process ${pid}.`);
+    if (callback) callback(null);
   });
 }
-
-nukePort(port);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "port-nuker",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A simple CLI utility to kill processes holding a specific port. Solves EADDRINUSE errors instantly.",
   "main": "index.js",
   "bin": {
@@ -27,13 +27,17 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/yourusername/port-nuker.git"
+    "url": "https://github.com/alexgutscher26/Port-Nuker.git"
   },
   "bugs": {
-    "url": "https://github.com/yourusername/port-nuker/issues"
+    "url": "https://github.com/alexgutscher26/port-nuker/issues"
   },
-  "homepage": "https://github.com/yourusername/port-nuker#readme",
+  "homepage": "https://github.com/alexgutscher26/port-nuker#readme",
   "engines": {
     "node": ">=12.0.0"
+  },
+  "dependencies": {
+    "inquirer": "^8.2.6",
+    "cli-table3": "^0.6.3"
   }
 }

package/.agent/skills/.github/CODEOWNERS

@@ -1,8 +0,0 @@
-# Global owners
-* @sickn33
-
-# Skills
-/skills/ @sickn33
-
-# Documentation
-*.md @sickn33

package/.agent/skills/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,33 +0,0 @@
----
-name: Bug Report
-about: Create a report to help us improve the skills
-title: "[BUG] "
-labels: bug
-assignees: sickn33
----
-
-**Describe the bug**
-A clear and concise description of what the bug is.
-
-**To Reproduce**
-Steps to reproduce the behavior:
-
-1. Go to '...'
-2. Click on '...'
-3. Scroll down to '...'
-4. See error
-
-**Expected behavior**
-A clear and concise description of what you expected to happen.
-
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
-
-**Environment (please complete the following information):**
-
-- OS: [e.g. macOS, Windows]
-- Tool: [e.g. Claude Code, Antigravity]
-- Version [if known]
-
-**Additional context**
-Add any other context about the problem here.

package/.agent/skills/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,19 +0,0 @@
----
-name: Skill Request
-about: Suggest a new skill for the collection
-title: "[REQ] "
-labels: enhancement
-assignees: sickn33
----
-
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex: I'm always frustrated when [...]
-
-**Describe the solution you'd like**
-A description of the skill you want. What trigger should it have? What files should it effect?
-
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
-**Additional context**
-Add any other context or screenshots about the feature request here.