portdog 1.0.0

package/README.md

@@ -0,0 +1,43 @@
+# portdog
+
+Your port watchdog. Stop googling `lsof -i :3000`.
+
+## Install
+
+```bash
+npm install -g portdog
+```
+
+## Usage
+
+```bash
+# See all ports in use
+portdog list
+
+# Kill whatever is on port 3000
+portdog kill 3000
+
+# Force kill (SIGKILL)
+portdog kill 3000 --force
+
+# Check if ports are free
+portdog scan 3000 8080 5432
+
+# Get a free port
+portdog free
+
+# Get 5 free ports
+portdog free -n 5
+
+# Detailed info about what's on a port
+portdog who 3000
+```
+
+## Aliases
+
+- `portdog ls` = `portdog list`
+- `portdog k <port>` = `portdog kill <port>`
+
+## License
+
+MIT

package/bin/portdog.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { listPorts, killPort, scanPorts, freePort, whoisPort } = require('../src/commands');
+
+program
+  .name('portdog')
+  .description('🐕 Your port watchdog. Stop googling lsof.')
+  .version('1.0.0');
+
+program
+  .command('list')
+  .alias('ls')
+  .description('Show all ports in use with process info')
+  .option('-p, --port <port>', 'Filter by specific port')
+  .action(listPorts);
+
+program
+  .command('kill <port>')
+  .alias('k')
+  .description('Kill whatever is running on a port')
+  .option('-f, --force', 'Force kill (SIGKILL)', false)
+  .action(killPort);
+
+program
+  .command('scan <ports...>')
+  .description('Check if ports are free (e.g. portdog scan 3000 8080 5432)')
+  .action(scanPorts);
+
+program
+  .command('free')
+  .description('Find and print a random free port')
+  .option('-n, --count <number>', 'Number of free ports to find', '1')
+  .action(freePort);
+
+program
+  .command('who <port>')
+  .description('Detailed info about what is using a port')
+  .action(whoisPort);
+
+program.parse();

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "portdog",
+  "version": "1.0.0",
+  "description": "Your port watchdog. Stop googling lsof.",
+  "main": "index.js",
+  "bin": {
+    "portdog": "./bin/portdog.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["port", "kill", "process", "cli", "devtools", "lsof", "watchdog"],
+  "author": "",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3"
+  }
+}

package/src/commands.js

@@ -0,0 +1,195 @@
+const chalk = require('chalk');
+const Table = require('cli-table3');
+const {
+  getProcessesOnPorts,
+  isPortFree,
+  findFreePorts,
+  killProcess,
+  getDetailedProcessInfo,
+  timeSince,
+} = require('./portUtils');
+
+async function listPorts(options) {
+  const processes = getProcessesOnPorts();
+
+  if (processes.length === 0) {
+    console.log(chalk.green('\n  No ports in use. Your machine is squeaky clean.\n'));
+    return;
+  }
+
+  let filtered = processes;
+  if (options.port) {
+    const targetPort = parseInt(options.port, 10);
+    filtered = processes.filter((p) => p.port === targetPort);
+    if (filtered.length === 0) {
+      console.log(chalk.green(`\n  Port ${targetPort} is free. Nothing there.\n`));
+      return;
+    }
+  }
+
+  // Sort by port number
+  filtered.sort((a, b) => a.port - b.port);
+
+  const table = new Table({
+    head: [
+      chalk.cyan('PORT'),
+      chalk.cyan('PID'),
+      chalk.cyan('PROCESS'),
+      chalk.cyan('USER'),
+      chalk.cyan('MEMORY'),
+      chalk.cyan('RUNNING SINCE'),
+    ],
+    style: { head: [], border: ['gray'] },
+  });
+
+  for (const p of filtered) {
+    const portColor = p.port < 1024 ? chalk.red : chalk.green;
+    table.push([
+      portColor(p.port),
+      chalk.yellow(p.pid),
+      chalk.white(p.command),
+      chalk.gray(p.user),
+      chalk.magenta(p.memory || '-'),
+      chalk.gray(timeSince(p.startTime) || '-'),
+    ]);
+  }
+
+  console.log(`\n  ${chalk.bold(`${filtered.length} port(s) in use`)}\n`);
+  console.log(table.toString());
+  console.log(chalk.gray(`\n  Kill with: ${chalk.white('portdog kill <port>')}\n`));
+}
+
+async function killPort(port, options) {
+  const portNum = parseInt(port, 10);
+  if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+    console.log(chalk.red(`\n  Invalid port: ${port}\n`));
+    process.exit(1);
+  }
+
+  const processes = getProcessesOnPorts().filter((p) => p.port === portNum);
+
+  if (processes.length === 0) {
+    console.log(chalk.green(`\n  Port ${portNum} is already free. Nothing to kill.\n`));
+    return;
+  }
+
+  for (const p of processes) {
+    const method = options.force ? 'SIGKILL' : 'SIGTERM';
+    console.log(
+      chalk.yellow(
+        `\n  Killing ${chalk.white(p.command)} (PID ${p.pid}) on port ${portNum} with ${method}...`
+      )
+    );
+
+    const success = killProcess(p.pid, options.force);
+
+    if (success) {
+      // Verify it's actually dead
+      await new Promise((r) => setTimeout(r, 500));
+      const stillAlive = getProcessesOnPorts().some(
+        (proc) => proc.pid === p.pid && proc.port === portNum
+      );
+
+      if (stillAlive && !options.force) {
+        console.log(
+          chalk.yellow(
+            `  Process didn't die. Try: ${chalk.white(`portdog kill ${portNum} --force`)}`
+          )
+        );
+      } else if (stillAlive) {
+        console.log(chalk.red(`  Process refused to die even with SIGKILL. Check permissions.`));
+      } else {
+        console.log(chalk.green(`  Done. Port ${portNum} is now free.\n`));
+      }
+    } else {
+      console.log(
+        chalk.red(`  Failed to kill PID ${p.pid}. You might need sudo:\n`)
+      );
+      console.log(chalk.gray(`    sudo portdog kill ${portNum}\n`));
+    }
+  }
+}
+
+async function scanPorts(ports) {
+  console.log('');
+  const results = await Promise.all(
+    ports.map(async (p) => {
+      const portNum = parseInt(p, 10);
+      if (isNaN(portNum)) return { port: p, status: 'invalid' };
+      const free = await isPortFree(portNum);
+      return { port: portNum, status: free ? 'free' : 'in-use' };
+    })
+  );
+
+  for (const r of results) {
+    if (r.status === 'invalid') {
+      console.log(chalk.red(`  ${r.port}  invalid port number`));
+    } else if (r.status === 'free') {
+      console.log(chalk.green(`  :${r.port}  free`));
+    } else {
+      const proc = getProcessesOnPorts().find((p) => p.port === r.port);
+      const info = proc ? chalk.gray(` (${proc.command}, PID ${proc.pid})`) : '';
+      console.log(chalk.red(`  :${r.port}  in use${info}`));
+    }
+  }
+  console.log('');
+}
+
+async function freePort(options) {
+  const count = parseInt(options.count, 10) || 1;
+  const ports = await findFreePorts(count);
+
+  if (count === 1) {
+    console.log(`\n  ${chalk.green(ports[0])}\n`);
+  } else {
+    console.log('');
+    for (const p of ports) {
+      console.log(`  ${chalk.green(p)}`);
+    }
+    console.log('');
+  }
+}
+
+async function whoisPort(port) {
+  const portNum = parseInt(port, 10);
+  if (isNaN(portNum) || portNum < 1 || portNum > 65535) {
+    console.log(chalk.red(`\n  Invalid port: ${port}\n`));
+    process.exit(1);
+  }
+
+  const processes = getProcessesOnPorts().filter((p) => p.port === portNum);
+
+  if (processes.length === 0) {
+    console.log(chalk.green(`\n  Port ${portNum} is free. Nobody home.\n`));
+    return;
+  }
+
+  for (const p of processes) {
+    const details = getDetailedProcessInfo(p.pid);
+
+    console.log(`\n  ${chalk.bold.cyan(`Port ${portNum}`)}`);
+    console.log(chalk.gray('  ' + '─'.repeat(40)));
+    console.log(`  ${chalk.gray('Process:')}    ${chalk.white(p.command)}`);
+    console.log(`  ${chalk.gray('PID:')}        ${chalk.yellow(p.pid)}`);
+    console.log(`  ${chalk.gray('User:')}       ${p.user}`);
+    console.log(`  ${chalk.gray('Memory:')}     ${chalk.magenta(p.memory || '-')}`);
+    console.log(`  ${chalk.gray('Started:')}    ${p.startTime || '-'} ${chalk.gray(`(${timeSince(p.startTime)})`)}`);
+
+    if (details) {
+      console.log(`  ${chalk.gray('Full cmd:')}   ${chalk.dim(details.fullCommand)}`);
+      console.log(`  ${chalk.gray('Open files:')} ${details.openFiles}`);
+      console.log(
+        `  ${chalk.gray('Children:')}   ${details.childCount}${
+          details.childPids.length > 0
+            ? chalk.gray(` (PIDs: ${details.childPids.join(', ')})`)
+            : ''
+        }`
+      );
+    }
+
+    console.log(chalk.gray('  ' + '─'.repeat(40)));
+    console.log(chalk.gray(`  Kill it: ${chalk.white(`portdog kill ${portNum}`)}\n`));
+  }
+}
+
+module.exports = { listPorts, killPort, scanPorts, freePort, whoisPort };

package/src/portUtils.js

@@ -0,0 +1,229 @@
+const { execSync } = require('child_process');
+const net = require('net');
+const os = require('os');
+
+function getProcessesOnPorts() {
+  const platform = os.platform();
+  const results = [];
+
+  try {
+    let output;
+    if (platform === 'darwin' || platform === 'linux') {
+      // Get listening TCP ports
+      output = execSync('lsof -iTCP -sTCP:LISTEN -nP 2>/dev/null || true', {
+        encoding: 'utf-8',
+        timeout: 5000,
+      });
+
+      const lines = output.trim().split('\n');
+      if (lines.length <= 1) return results;
+
+      // Skip header
+      for (let i = 1; i < lines.length; i++) {
+        const parts = lines[i].split(/\s+/);
+        if (parts.length < 9) continue;
+
+        const command = parts[0];
+        const pid = parseInt(parts[1], 10);
+        const user = parts[2];
+        const nameField = parts[8]; // e.g. *:3000 or 127.0.0.1:8080
+
+        const portMatch = nameField.match(/:(\d+)$/);
+        if (!portMatch) continue;
+
+        const port = parseInt(portMatch[1], 10);
+
+        // Get process start time and memory
+        let startTime = '';
+        let memory = '';
+        try {
+          const psOut = execSync(`ps -p ${pid} -o lstart=,rss= 2>/dev/null || true`, {
+            encoding: 'utf-8',
+            timeout: 3000,
+          }).trim();
+          if (psOut) {
+            const rssMatch = psOut.match(/(\d+)\s*$/);
+            if (rssMatch) {
+              memory = formatMemory(parseInt(rssMatch[1], 10));
+              startTime = psOut.replace(/\s*\d+\s*$/, '').trim();
+            }
+          }
+        } catch {}
+
+        results.push({ port, pid, command, user, startTime, memory });
+      }
+    } else if (platform === 'win32') {
+      output = execSync('netstat -ano -p TCP | findstr LISTENING', {
+        encoding: 'utf-8',
+        timeout: 5000,
+      });
+
+      const lines = output.trim().split('\n');
+      for (const line of lines) {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length < 5) continue;
+
+        const localAddr = parts[1];
+        const pid = parseInt(parts[4], 10);
+        const portMatch = localAddr.match(/:(\d+)$/);
+        if (!portMatch) continue;
+
+        const port = parseInt(portMatch[1], 10);
+
+        let command = '';
+        try {
+          command = execSync(`tasklist /FI "PID eq ${pid}" /FO CSV /NH 2>nul`, {
+            encoding: 'utf-8',
+            timeout: 3000,
+          }).trim().split(',')[0]?.replace(/"/g, '') || '';
+        } catch {}
+
+        results.push({ port, pid, command, user: '', startTime: '', memory: '' });
+      }
+    }
+  } catch (err) {
+    // Silently handle - will return empty results
+  }
+
+  // Deduplicate by port+pid
+  const seen = new Set();
+  return results.filter((r) => {
+    const key = `${r.port}:${r.pid}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, '0.0.0.0');
+  });
+}
+
+function findFreePorts(count = 1) {
+  return new Promise((resolve) => {
+    const ports = [];
+    let found = 0;
+
+    function findNext() {
+      if (found >= count) return resolve(ports);
+
+      const server = net.createServer();
+      server.listen(0, '0.0.0.0', () => {
+        const port = server.address().port;
+        server.close(() => {
+          ports.push(port);
+          found++;
+          findNext();
+        });
+      });
+    }
+    findNext();
+  });
+}
+
+function killProcess(pid, force = false) {
+  const platform = os.platform();
+  const signal = force ? 'SIGKILL' : 'SIGTERM';
+
+  try {
+    if (platform === 'win32') {
+      execSync(`taskkill ${force ? '/F' : ''} /PID ${pid} 2>nul`, { encoding: 'utf-8' });
+    } else {
+      process.kill(pid, signal);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getDetailedProcessInfo(pid) {
+  const platform = os.platform();
+  if (platform === 'win32') return null;
+
+  try {
+    const psOut = execSync(
+      `ps -p ${pid} -o pid=,ppid=,user=,lstart=,%cpu=,%mem=,rss=,command= 2>/dev/null`,
+      { encoding: 'utf-8', timeout: 3000 }
+    ).trim();
+
+    if (!psOut) return null;
+
+    // Also get the full command with args
+    const cmdOut = execSync(`ps -p ${pid} -o args= 2>/dev/null`, {
+      encoding: 'utf-8',
+      timeout: 3000,
+    }).trim();
+
+    // Get open file count
+    let openFiles = 0;
+    try {
+      const lsofOut = execSync(`lsof -p ${pid} 2>/dev/null | wc -l`, {
+        encoding: 'utf-8',
+        timeout: 3000,
+      }).trim();
+      openFiles = parseInt(lsofOut, 10) || 0;
+    } catch {}
+
+    // Get child process count
+    let children = [];
+    try {
+      const childOut = execSync(`pgrep -P ${pid} 2>/dev/null || true`, {
+        encoding: 'utf-8',
+        timeout: 3000,
+      }).trim();
+      if (childOut) children = childOut.split('\n').filter(Boolean);
+    } catch {}
+
+    return {
+      fullCommand: cmdOut,
+      openFiles,
+      childCount: children.length,
+      childPids: children.map(Number),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function formatMemory(rssKb) {
+  if (rssKb > 1024 * 1024) return `${(rssKb / (1024 * 1024)).toFixed(1)} GB`;
+  if (rssKb > 1024) return `${(rssKb / 1024).toFixed(1)} MB`;
+  return `${rssKb} KB`;
+}
+
+function timeSince(dateStr) {
+  if (!dateStr) return '';
+  try {
+    const start = new Date(dateStr);
+    const now = new Date();
+    const diffMs = now - start;
+    const diffSec = Math.floor(diffMs / 1000);
+    const diffMin = Math.floor(diffSec / 60);
+    const diffHr = Math.floor(diffMin / 60);
+    const diffDay = Math.floor(diffHr / 24);
+
+    if (diffDay > 0) return `${diffDay}d ${diffHr % 24}h ago`;
+    if (diffHr > 0) return `${diffHr}h ${diffMin % 60}m ago`;
+    if (diffMin > 0) return `${diffMin}m ago`;
+    return `${diffSec}s ago`;
+  } catch {
+    return '';
+  }
+}
+
+module.exports = {
+  getProcessesOnPorts,
+  isPortFree,
+  findFreePorts,
+  killProcess,
+  getDetailedProcessInfo,
+  timeSince,
+};