portclean 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tejaswan Kalluri
+
+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

@@ -14,7 +14,7 @@ npm install -g portclean
 portclean [ports...] [options]
 
 Arguments:
-  ports         Port number(s) to target
+  ports         Port number(s) or ranges to target (e.g. 3000 or 3000-3010)
 
 Options:
   --force, -f   Skip confirmation prompt
@@ -38,7 +38,7 @@ Process 12345 (node) is using port 3000. Kill it? (y/N) y
 ### Kill multiple ports
 
 ```bash
-$ portclean 3000 8080
+$ portclean 3000 8080 9000
 Processes on port 3000:
   1. PID 12345 (node)
 Process 12345 (node) is using port 3000. Kill it? (y/N) y
@@ -48,6 +48,11 @@ Processes on port 8080:
   1. PID 54321 (python)
 Process 54321 (python) is using port 8080. Kill it? (y/N) y
 ✓ Killed process 54321 (python)
+
+Processes on port 9000:
+  1. PID 11111 (go)
+Process 11111 (go) is using port 9000. Kill it? (y/N) y
+✓ Killed process 11111 (go)
 ```
 
 ### Kill without confirmation
@@ -59,6 +64,21 @@ Processes on port 3000:
 ✓ Killed process 12345 (node)
 ```
 
+### Kill a port range
+
+```bash
+$ portclean 3000-3010 --force
+Processes on port 3000:
+  1. PID 12345 (node)
+✓ Killed process 12345 (node)
+
+...
+
+Processes on port 3010:
+  1. PID 12399 (go)
+✓ Killed process 12399 (go)
+```
+
 ### Kill all processes using a port
 
 When multiple processes are using the same port:
@@ -78,7 +98,7 @@ Kill all 3 process(es) on port 3000? (y/N) y
 ### Kill all processes without confirmation
 
 ```bash
-$ portclean 3000 8080 --all --force
+$ portclean 3000 8080 9000 --all --force
 Processes on port 3000:
   1. PID 12345 (node)
   2. PID 12346 (node)
@@ -88,20 +108,28 @@ Processes on port 3000:
 Processes on port 8080:
   1. PID 54321 (python)
 ✓ Killed process 54321 (python)
+
+Processes on port 9000:
+  1. PID 11111 (go)
+✓ Killed process 11111 (go)
 ```
 
 ### Kill processes on ports without --all (prompts per process)
 
 ```bash
-$ portclean 3000
+$ portclean 3000-3002
 Processes on port 3000:
   1. PID 12345 (node)
-  2. PID 12346 (node)
-  3. PID 12347 (node)
 Process 12345 (node) is using port 3000. Kill it? (y/N) y
 ✓ Killed process 12345 (node)
-Process 12346 (node) is using port 3000. Kill it? (y/N) n
-Process 12347 (node) is using port 3000. Kill it? (y/N) y
+
+Processes on port 3001:
+  1. PID 12346 (node)
+Process 12346 (node) is using port 3001. Kill it? (y/N) n
+
+Processes on port 3002:
+  1. PID 12347 (node)
+Process 12347 (node) is using port 3002. Kill it? (y/N) y
 ✓ Killed process 12347 (node)
 ```
 
@@ -110,8 +138,9 @@ Process 12347 (node) is using port 3000. Kill it? (y/N) y
 ### macOS/Linux
 
 1. **Primary method**: Uses `lsof -i :<port>` to find processes
-2. **Fallback**: If `lsof` is not available, uses `netstat -anp` and parses the output
-3. **Process names**: Extracted from the command output or via `ps` command
+2. **Fallback (Linux only)**: If `lsof` is not available, uses `netstat -anp` and parses the output (stderr suppressed)
+3. **macOS fallback**: macOS `netstat` lacks PID data, so we skip it and return no processes instead of printing errors
+4. **Process names**: Extracted from the command output or via `ps` command
 
 ### Windows
 

package/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
-import { execSync, exec } from 'child_process';
+import { execSync } from 'child_process';
 import { kill } from 'process';
-import { stdin, stdout, stderr } from 'process';
+import { stdin, stdout } from 'process';
 import parseArgs from 'mri';
 import colors from 'picocolors';
 import * as readline from 'readline';
@@ -10,26 +10,63 @@ import * as readline from 'readline';
 const VERSION = '1.0.0';
 const PLATFORM = process.platform;
 
-// Parse CLI arguments
-const args = parseArgs(process.argv.slice(2), {
-  alias: {
-    h: 'help',
-    v: 'version',
-    f: 'force',
-    a: 'all',
-  },
-});
-
-// Handle help flag
-if (args.help) {
-  console.log(`
+// Parse ports (single numbers or inclusive ranges like 3000-3010)
+function parsePorts(inputs) {
+  const ports = new Set();
+  const errors = [];
+
+  for (const input of inputs) {
+    if (typeof input !== 'string') {
+      errors.push(`Invalid port input: ${input}`);
+      continue;
+    }
+
+    if (input.includes('-')) {
+      const [startStr, endStr] = input.split('-', 2);
+      const start = parseInt(startStr, 10);
+      const end = parseInt(endStr, 10);
+
+      if (Number.isNaN(start) || Number.isNaN(end) || start < 1 || end > 65535 || start > end) {
+        errors.push(`Error: Invalid port range ${input}`);
+        continue;
+      }
+
+      for (let p = start; p <= end; p++) {
+        ports.add(p);
+      }
+      continue;
+    }
+
+    const port = parseInt(input, 10);
+    if (Number.isNaN(port) || port < 1 || port > 65535) {
+      errors.push(`Error: Invalid port ${input}`);
+      continue;
+    }
+    ports.add(port);
+  }
+
+  return { ports: Array.from(ports), errors };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2), {
+    alias: {
+      h: 'help',
+      v: 'version',
+      f: 'force',
+      a: 'all',
+    },
+  });
+
+  if (args.help) {
+    console.log(`
 ${colors.bold('portclean')} - Kill processes using specific ports
 
 ${colors.bold('Usage:')}
   portclean [ports...] [options]
 
 ${colors.bold('Arguments:')}
-  ports         Port number(s) to target
+  ports         Port number(s) or ranges to target (e.g. 3000 or 3000-3010)
 
 ${colors.bold('Options:')}
   --force, -f   Skip confirmation prompt
@@ -39,59 +76,50 @@ ${colors.bold('Options:')}
 
 ${colors.bold('Examples:')}
   portclean 3000                    Kill process on port 3000
-  portclean 3000 8080               Kill processes on ports 3000 and 8080
+  portclean 3000 8080 9000          Kill processes on multiple ports
+  portclean 3000-3010               Kill processes on ports 3000 through 3010
   portclean 3000 --force            Kill port 3000 without confirmation
   portclean 3000 --all              Kill all processes using port 3000
   portclean 3000 8080 --force --all Kill all processes on both ports without confirmation
 `);
-  process.exit(0);
-}
-
-// Handle version flag
-if (args.version) {
-  console.log(`portkill v${VERSION}`);
-  process.exit(0);
-}
+    process.exit(0);
+  }
 
-// Get ports from positional arguments
-const ports = args._;
+  if (args.version) {
+    console.log(`portkill v${VERSION}`);
+    process.exit(0);
+  }
 
-// Validate ports
-if (ports.length === 0) {
-  console.error(colors.red('Error: No ports specified'));
-  process.exit(1);
-}
+  const rawPorts = args._;
 
-const validPorts = ports.filter((p) => {
-  const port = parseInt(p, 10);
-  if (isNaN(port) || port < 1 || port > 65535) {
-    console.error(colors.red(`Error: Invalid port ${p}`));
-    return false;
+  if (rawPorts.length === 0) {
+    console.error(colors.red('Error: No ports specified'));
+    process.exit(1);
   }
-  return true;
-});
 
-if (validPorts.length === 0) {
-  process.exit(1);
-}
+  const { ports, errors: portErrors } = parsePorts(rawPorts);
+  portErrors.forEach((msg) => console.error(colors.red(msg)));
 
-// Main execution
-(async () => {
-  try {
-    for (const port of validPorts) {
-      await handlePort(parseInt(port, 10));
-    }
-    process.exit(0);
-  } catch (error) {
-    console.error(colors.red(`Error: ${error.message}`));
+  if (ports.length === 0) {
     process.exit(1);
   }
-})();
+
+  for (const port of ports) {
+    await handlePort(port, args);
+  }
+
+  process.exit(0);
+}
 
 /**
  * Handle killing processes on a specific port
  */
-async function handlePort(port) {
+async function handlePort(port, args) {
+  if (isNaN(port) || port < 1 || port > 65535) {
+    console.error(colors.red(`Error: Invalid port ${port}`));
+    return;
+  }
+
   try {
     const processes = await getProcessesOnPort(port);
 
@@ -108,14 +136,12 @@ async function handlePort(port) {
     if (args.force || args.all) {
       // If --force or --all, show single confirmation per port (or none with --force)
       if (args.force) {
-        // Kill without confirmation
         for (const proc of processes) {
           await killProcess(proc.pid, proc.command);
         }
       } else if (args.all) {
-        // --all without --force: single confirmation
         const confirmed = await prompt(
-          `Kill all ${processes.length} process(es) on port ${port}? (y/N) `
+          `Kill all ${processes.length} process(es) on port ${port}? (Y/n) `
         );
         if (confirmed) {
           for (const proc of processes) {
@@ -124,10 +150,9 @@ async function handlePort(port) {
         }
       }
     } else {
-      // Without --all: prompt per process
       for (const proc of processes) {
         const confirmed = await prompt(
-          `Process ${proc.pid} (${proc.command}) is using port ${port}. Kill it? (y/N) `
+          `Process ${proc.pid} (${proc.command}) is using port ${port}. Kill it? (Y/n) `
         );
         if (confirmed) {
           await killProcess(proc.pid, proc.command);
@@ -156,18 +181,21 @@ async function getProcessesOnPort(port) {
  * Get processes on macOS/Linux using lsof or netstat
  */
 async function getProcessesPosix(port) {
+  // Suppress stderr from system commands to avoid leaking raw tool logs
+  const execOpts = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] };
+
   try {
-    // Try lsof first
     try {
-      const output = execSync(`lsof -i :${port} -n -P`, { encoding: 'utf8' });
+      const output = execSync(`lsof -i :${port} -n -P`, execOpts);
       return parseLsofOutput(output);
     } catch {
-      // Fallback to netstat
-      const output = execSync('netstat -anp', { encoding: 'utf8' });
-      return parseNetstatOutput(output, port);
+      if (PLATFORM === 'linux') {
+        const output = execSync('netstat -anp', execOpts);
+        return parseNetstatOutput(output, port);
+      }
+      return [];
     }
-  } catch (error) {
-    console.error(colors.red(`Failed to get processes on port ${port}: ${error.message}`));
+  } catch {
     return [];
   }
 }
@@ -176,7 +204,7 @@ async function getProcessesPosix(port) {
  * Parse lsof output
  */
 function parseLsofOutput(output) {
-  const lines = output.trim().split('\n').slice(1); // Skip header
+  const lines = output.trim().split('\n').slice(1);
   const processes = [];
 
   for (const line of lines) {
@@ -186,7 +214,6 @@ function parseLsofOutput(output) {
       const command = parts[0];
 
       if (!isNaN(pid) && pid > 0) {
-        // Check if already added
         if (!processes.find((p) => p.pid === pid)) {
           processes.push({ pid, command });
         }
@@ -201,7 +228,7 @@ function parseLsofOutput(output) {
  * Parse netstat output for a specific port
  */
 function parseNetstatOutput(output, port) {
-  const lines = output.trim().split('\n').slice(1); // Skip header
+  const lines = output.trim().split('\n').slice(1);
   const processes = [];
 
   for (const line of lines) {
@@ -213,19 +240,17 @@ function parseNetstatOutput(output, port) {
 
       if (match && state === 'LISTEN') {
         const pid = parseInt(match[1], 10);
-        const proto = parts[0];
         const addr = parts[3];
         const addrParts = addr.split(':');
         const addrPort = addrParts[addrParts.length - 1];
 
         if (parseInt(addrPort, 10) === port && !isNaN(pid) && pid > 0) {
-          // Get command name
           let command = 'unknown';
           try {
             const psOutput = execSync(`ps -p ${pid} -o comm=`, { encoding: 'utf8' });
             command = psOutput.trim();
           } catch {
-            // Use default
+            // ignore
           }
 
           if (!processes.find((p) => p.pid === pid)) {
@@ -247,7 +272,7 @@ async function getProcessesWindows(port) {
     const netstatOutput = execSync('netstat -ano', { encoding: 'utf8' });
     const pids = new Set();
 
-    const lines = netstatOutput.trim().split('\n').slice(4); // Skip header
+    const lines = netstatOutput.trim().split('\n').slice(4);
     for (const line of lines) {
       const parts = line.trim().split(/\s+/);
       if (parts.length >= 5) {
@@ -279,7 +304,7 @@ async function getProcessesWindows(port) {
           command = taskLine;
         }
       } catch {
-        // Use default
+        // ignore
       }
 
       processes.push({ pid, command });
@@ -300,11 +325,9 @@ async function killProcess(pid, command) {
     if (PLATFORM === 'win32') {
       execSync(`taskkill /PID ${pid} /F`, { encoding: 'utf8' });
     } else {
-      // Try using process.kill first
       try {
         kill(pid, 'SIGKILL');
       } catch {
-        // Fallback to shell command
         execSync(`kill -9 ${pid}`);
       }
     }
@@ -326,7 +349,17 @@ function prompt(question) {
 
     rl.question(question, (answer) => {
       rl.close();
-      resolve(answer.toLowerCase() === 'y');
+      const response = answer.trim().toLowerCase();
+      resolve(response === '' || response === 'y' || response === 'yes');
     });
   });
 }
+
+if (import.meta.url === new URL(process.argv[1], 'file:').href) {
+  main().catch((error) => {
+    console.error(colors.red(`Error: ${error.message}`));
+    process.exit(1);
+  });
+}
+
+export { parsePorts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portclean",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Kill processes using specific ports on macOS, Linux, and Windows",
   "type": "module",
   "main": "cli.js",
@@ -8,7 +8,7 @@
     "portclean": "cli.js"
   },
   "scripts": {
-    "test": "node --test test/*.test.js",
+    "test": "node --test",
     "smoke": "node cli.js --help"
   },
   "keywords": [
@@ -17,8 +17,16 @@
     "kill",
     "process"
   ],
-  "author": "",
+  "author": "Tejaswan Kalluri",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tejaswankalluri/portclean.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tejaswankalluri/portclean/issues"
+  },
+  "homepage": "https://github.com/tejaswankalluri/portclean#readme",
   "dependencies": {
     "mri": "^1.2.0",
     "picocolors": "^1.0.0"